refactor(cli): parse JS command arguments with clap

[fengmk2]

Move argument parsing for the staged, config, hooks, migrate, and create commands from JavaScript to Rust. Each NAPI parser uses clap for strict validation and returns a typed result to JavaScript.

Call graph

process.argv
    |
    v
local Node.js CLI
packages/cli/src/bin.ts
    |
    | raw arguments for one JavaScript command
    v
NAPI parser function
packages/cli/binding/src/js_command_args/
    |
    v
clap command grammar
    |
    +-- checks aliases and option boundaries
    +-- converts values
    +-- checks explicit negation
    +-- rejects unknown options
    +-- rejects invalid positional arguments
    |
    v
validated Rust arguments
    |
    v
typed NAPI parse outcome
    |
    v
JavaScript command operations

JavaScript sends raw arguments to one NAPI parser. JavaScript does not parse the returned values again.

The Rust parsers print command help through the shared vp_cli_help formatter. The global and local CLI paths use the same help format. The create parser keeps all template arguments after the separator in their original order.

This change removes duplicate JavaScript option data and the direct mri dependency. The RFC defines the parser rules, help synchronization, NAPI result types, and command ownership.

Compatibility

Argument parsing is now strict. The CLI rejects unknown options and extra positional arguments. It rejects unsupported negative string options and repeated scalar options.

The staged command rejects invalid concurrency values. It also rejects empty --cwd, --diff, and --diff-filter values before JavaScript runs.

The create command rejects --all and invalid package-manager values. These inputs could pass through mri or fail later in JavaScript.

Performance

The benchmark compares the base commit 45acff9b4 with this branch. It ran on macOS ARM64 with Node.js 22.22.0.

Each CLI result used 25 to 30 alternating paired runs after four warm-up pairs. A negative change is faster.

The parser-only test used vp staged --allow-empty --concurrent=2 --diff-filter ACMR --no-stash.

Case	Base mean	PR mean	Change
Staged parser only	1.20 µs	6.33 µs	+5.13 µs
vp --version control	133.2 ms	133.4 ms	+0.2 ms
vp staged --help	136.1 ms	133.9 ms	-2.2 ms
vp config --help	149.4 ms	144.7 ms	-4.7 ms
vp hooks --help	134.4 ms	132.9 ms	-1.5 ms
vp migrate --help	155.8 ms	150.0 ms	-5.8 ms
vp create --help	154.5 ms	150.1 ms	-4.5 ms
vp staged --cwd	135.2 ms	134.5 ms	-0.7 ms
vp hooks unknown	131.7 ms	132.0 ms	+0.3 ms
vp config --hooks-dir	165.3 ms	144.6 ms	-20.7 ms

The clap/NAPI parser is 5.3 times slower in isolation. This adds about 5 µs to a CLI process that takes 130 to 155 ms.

The CLI calls the parser one time. The complete CLI path has no measurable regression. Help is 1% to 4% faster.

vp config --hooks-dir is not a parser-only comparison. The base command starts hooks validation. The PR rejects the missing value first.

Unknown-option timings are not comparable. The base parser can accept an unknown option and start command work. The PR rejects it during parsing.

[netlify]

✅ Deploy Preview for viteplus-preview canceled.

Name	Link
🔨 Latest commit	6ea10b8
🔍 Latest deploy log	https://app.netlify.com/projects/viteplus-preview/deploys/6a8a84f0b8aea300084360e8

[github-actions]

CLI artifact sizes (6ea10b8)

Final release artifacts built by the canonical build-upstream and build-windows-cli actions.
The dist rows use the Linux build. The core total excludes .node files to match the release artifact.

Artifact	Format	Base	PR	Change
packages/cli/dist	Directory total	1.61 MiB	1.59 MiB	-18.84 KiB (-1.14%)
packages/core/dist	Directory total	3.91 MiB	3.91 MiB	0 B (0.00%)
Combined package dist	Directory total	5.52 MiB	5.50 MiB	-18.84 KiB (-0.33%)
vp (Linux x64)	Binary	10.74 MiB	10.74 MiB	+8.00 KiB (+0.07%)
vp (Linux x64)	gzip -9	4.65 MiB	4.65 MiB	+5.46 KiB (+0.11%)
NAPI (Linux x64)	Binary	32.20 MiB	32.39 MiB	+188.00 KiB (+0.57%)
NAPI (Linux x64)	gzip -9	12.69 MiB	12.76 MiB	+68.63 KiB (+0.53%)
vp (macOS ARM64)	Binary	8.03 MiB	8.03 MiB	+16 B (+0.00%)
vp (macOS ARM64)	gzip -9	4.05 MiB	4.06 MiB	+4.81 KiB (+0.12%)
NAPI (macOS ARM64)	Binary	39.80 MiB	39.93 MiB	+129.14 KiB (+0.32%)
NAPI (macOS ARM64)	gzip -9	16.98 MiB	17.05 MiB	+67.52 KiB (+0.39%)
vp (Windows x64)	Binary	8.63 MiB	8.64 MiB	+7.50 KiB (+0.08%)
vp (Windows x64)	gzip -9	3.77 MiB	3.77 MiB	+4.91 KiB (+0.13%)
NAPI (Windows x64)	Binary	27.03 MiB	27.20 MiB	+172.50 KiB (+0.62%)
NAPI (Windows x64)	gzip -9	10.75 MiB	10.82 MiB	+66.38 KiB (+0.60%)
Trampoline (Windows x64)	Binary	214.00 KiB	214.00 KiB	0 B (0.00%)
Trampoline (Windows x64)	gzip -9	103.20 KiB	103.20 KiB	0 B (0.00%)
Installer (Windows x64)	Binary	4.50 MiB	4.50 MiB	0 B (0.00%)
Installer (Windows x64)	gzip -9	2.11 MiB	2.11 MiB	0 B (0.00%)

[fengmk2]

Should command implementation code be placed in a separate directory for better management?