nodejs/cli.rs
1//! Command-line interface for the `node` binary.
2
3use clap::Parser;
4
5#[derive(Parser, Debug)]
6#[command(
7 name = "node",
8 version,
9 about = "JavaScript on fusevm — a compiled JS runtime (bytecode VM + Cranelift JIT)",
10 long_about = None,
11)]
12pub struct Cli {
13 /// Evaluate a one-liner instead of a file (`node -e 'console.log(1+1)'`).
14 #[arg(short = 'e', long = "eval", value_name = "SRC")]
15 pub eval: Option<String>,
16
17 /// Evaluate a one-liner and print its result (`node -p '1+1'` → `2`).
18 #[arg(short = 'p', long = "print", value_name = "SRC")]
19 pub print: Option<String>,
20
21 /// Start the interactive REPL.
22 #[arg(long = "repl")]
23 pub repl: bool,
24
25 /// Speak the Language Server Protocol over stdio.
26 #[arg(long = "lsp")]
27 pub lsp: bool,
28
29 /// Speak the Debug Adapter Protocol over stdio.
30 #[arg(long = "dap")]
31 pub dap: bool,
32
33 /// Ahead-of-time compile the script to a standalone native executable.
34 #[arg(long = "build")]
35 pub build: bool,
36
37 /// Print the compiled fusevm bytecode for the script and exit.
38 #[arg(long = "dump-bytecode")]
39 pub dump_bytecode: bool,
40
41 /// Print the lexer token stream for the script and exit.
42 #[arg(long = "dump-tokens")]
43 pub dump_tokens: bool,
44
45 /// Print the parsed AST for the script and exit.
46 #[arg(long = "dump-ast")]
47 pub dump_ast: bool,
48
49 /// Print a fusevm bytecode disassembly listing for the script and exit.
50 #[arg(long = "disasm")]
51 pub disasm: bool,
52
53 /// Run the script, then report which fusevm tiers took each of its chunks.
54 #[arg(long = "tiers")]
55 pub tiers: bool,
56
57 /// Silence all `process.emitWarning` output (Node's `--no-warnings`).
58 #[arg(long = "no-warnings")]
59 pub no_warnings: bool,
60
61 /// Silence DeprecationWarnings only (Node's `--no-deprecation`).
62 #[arg(long = "no-deprecation")]
63 pub no_deprecation: bool,
64
65 /// Suppress the one-time "(Use `node --trace-warnings ...`)" hint on warnings.
66 #[arg(long = "trace-warnings")]
67 pub trace_warnings: bool,
68
69 /// Suppress that hint for DeprecationWarnings (Node's `--trace-deprecation`).
70 #[arg(long = "trace-deprecation")]
71 pub trace_deprecation: bool,
72
73 /// The `.js` script to run (omit with --repl / --lsp / --dap / -e).
74 #[arg(value_name = "FILE")]
75 pub file: Option<String>,
76
77 /// Arguments passed through to the JS program.
78 #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
79 pub argv: Vec<String>,
80}
81
82/// Parse the process arguments.
83///
84/// Only the runtime's own part of the command line reaches clap: node stops
85/// reading its options at the entry script, so `node args.js -p 8080` hands
86/// `-p 8080` to the program rather than evaluating `8080`. [`split_argv`] finds
87/// that boundary; the entry script is passed behind `--` so a name that starts
88/// with a dash is still a file.
89pub fn parse() -> Cli {
90 let argv0 = std::env::args()
91 .next()
92 .unwrap_or_else(|| "node".to_string());
93 Cli::parse_from(runtime_args(argv0, split_argv(std::env::args())))
94}
95
96/// The arguments clap should see: `argv0`, the runtime flags, and the entry
97/// script (behind `--`), but none of the program's own arguments.
98fn runtime_args(argv0: String, split: Argv) -> Vec<String> {
99 let mut out = vec![argv0];
100 out.extend(split.exec);
101 if let Some(script) = split.script {
102 out.push("--".to_string());
103 out.push(script);
104 }
105 out
106}
107
108/// How Node divides the command line, which is NOT the raw `argv` the OS handed
109/// over: the flags the RUNTIME consumed go to `process.execArgv`, and
110/// `process.argv` is `[execPath, entryScript, ...userArgs]` with those flags
111/// removed. The split is entry-point dependent and observably so —
112/// `node -e 'src' z` reports `execArgv = ["-e","src"]` and `argv = [exec,"z"]`,
113/// with NO `argv[1]`, while `node s.js z` reports `execArgv = []` and
114/// `argv = [exec, "/abs/s.js", "z"]`. Measured on node v26.7.0.
115pub struct Argv {
116 /// Runtime flags, including `-e`/`--eval` and its source.
117 pub exec: Vec<String>,
118 /// The entry script as given, or `None` for `-e` and for stdin.
119 pub script: Option<String>,
120 /// Everything after the entry point, passed through to the program.
121 pub user: Vec<String>,
122 /// Whether the program came from `-e`/`--eval`/`-p`/`--print`.
123 pub eval: bool,
124}
125
126/// Compute [`Argv`] from the raw command line.
127///
128/// This walks the raw arguments rather than reading the parsed [`Cli`], because
129/// clap assigns the FIRST positional to `file` even under `-e`, where that
130/// positional is really the program's own first argument.
131pub fn split_argv<I: IntoIterator<Item = String>>(raw: I) -> Argv {
132 let mut out = Argv {
133 exec: Vec::new(),
134 script: None,
135 user: Vec::new(),
136 eval: false,
137 };
138 let mut it = raw.into_iter().skip(1);
139 let mut eval_seen = false;
140 while let Some(a) = it.next() {
141 if a == "-e" || a == "--eval" || a == "-p" || a == "--print" {
142 out.exec.push(a);
143 if let Some(src) = it.next() {
144 out.exec.push(src);
145 }
146 eval_seen = true;
147 out.eval = true;
148 } else if a == "--" {
149 // `--` ends the runtime's options and is in neither list: what
150 // follows is the entry script (unless `-e` supplied the program)
151 // and then the program's own arguments, dashes and all.
152 if !eval_seen {
153 out.script = it.next();
154 }
155 out.user.extend(it);
156 break;
157 } else if a.starts_with('-') && a != "-" {
158 // `-` is Node's "read stdin" entry point, not a flag.
159 out.exec.push(a);
160 } else {
161 // The first non-flag ends the runtime's own arguments. Under `-e`
162 // there is no entry script, so it is already a program argument.
163 if !eval_seen {
164 out.script = Some(a);
165 } else {
166 out.user.push(a);
167 }
168 out.user.extend(it);
169 break;
170 }
171 }
172 out
173}