CLI: --version reports the npm package version (#731)

* CLI: --version reports the npm package version

npx impeccable --version printed 3.6.0 after the 4.0.0 release because
the shim handed every argument to the engine, whose baked-in
CLI_VERSION still said 3.6.0. The shim now answers --version and -v
from its own package.json, as docs/CLI-CONTRACT.md specifies, without
locating or downloading a binary; a test covers both flags. The
engine's CLI_VERSION moves to 4.0.0 for the next engine release, with
the cli-version golden re-recorded and the delta noted.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vau2X53xGTjjTCXWMVBoNY

* CLI shim: --version wins whenever it leads, trailing arguments or not

Co-Authored-By: Claude Code <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vau2X53xGTjjTCXWMVBoNY

---------

Co-authored-by: Claude Code <noreply@anthropic.com>

cli/bin/cli.js

@@ -68,6 +68,14 @@ async function locate() {
   return download().catch((err) => { process.stderr.write(`impeccable: ${err.message}\n`); return null; });
 }
 
+// `--version` / `-v` is answered by the shim itself: the number users mean
+// is this npm package's version, not the engine's (docs/CLI-CONTRACT.md).
+const argv = process.argv.slice(2);
+if (argv[0] === '--version' || argv[0] === '-v') {
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+
 const bin = await locate();
 if (!bin) {
   process.stderr.write(
@@ -76,7 +84,7 @@ if (!bin) {
   );
   process.exit(127);
 }
-const result = spawnSync(bin, process.argv.slice(2), {
+const result = spawnSync(bin, argv, {
   stdio: 'inherit',
   env: { IMPECCABLE_SELF: 'npx impeccable', ...process.env },
 });

crates/cli/src/main.rs

@@ -108,7 +108,7 @@ fn run(args: &[String], io: &mut Io) -> i32 {
 
 /// The npm `impeccable` package version `cli.js --version` prints (its
 /// `package.json`), tracked separately from the crate version.
-pub const CLI_VERSION: &str = "3.6.0";
+pub const CLI_VERSION: &str = "4.0.0";
 
 /// The engines wired into `impeccable detect`: the static HTML engine
 /// (crates/html). The browser engine (crates/browser) plugs in here once it

tests/cli-shim.test.mjs

@@ -174,6 +174,17 @@ describe('npm shim download verification', { skip: process.platform === 'win32'
     assert.deepEqual(cacheEntries(res.home), []);
   });
 
+  it('answers --version and -v from its own package.json without touching a binary', async () => {
+    const expected = JSON.parse(fs.readFileSync(PKG_PATH, 'utf-8')).version;
+    for (const args of [['--version'], ['-v'], ['--version', 'extra']]) {
+      const flag = args.join(' ');
+      const res = await runShim(args);
+      assert.equal(res.status, 0, `${flag} exits 0`);
+      assert.equal(res.stdout, `${expected}\n`);
+      assert.deepEqual(requests, [], 'no download was attempted');
+    }
+  });
+
   it('prefers IMPECCABLE_BIN and never downloads', async () => {
     sidecar = { status: 404, body: '' };
     const { dir, shim } = stageShim();

tests/oracle/DELTAS.md

@@ -155,3 +155,12 @@ file, the file set, or the printed lines differs from the JS.
 
 - `pin-opencode-project`, `pin-opencode-user-scope`, `pin-opencode-skips-foreign-command`, `pin-opencode-then-unpin`, `pin-opencode-unpin-skips-foreign`.
 
+
+## Recorded 2026-09-04: `--version` follows the npm package to 4.0.0
+
+The npm shim answers `--version` / `-v` itself from its own `package.json`
+(docs/CLI-CONTRACT.md), so the number users see tracks the package they
+installed. The binary's `CLI_VERSION` moves from `3.6.0` to `4.0.0` with the
+CLI 4.0.0 release; it is what the binary prints when run directly.
+
+- `cli-version`.

tests/oracle/golden/cli-version.json

@@ -1,5 +1,5 @@
 {
-  "stdout": "3.6.0\n",
+  "stdout": "4.0.0\n",
   "stderr": "",
   "exit": 0,
   "signal": null,