@openparachute/vault 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to Parachute Vault are documented here.
 
 This project loosely follows [Keep a Changelog](https://keepachangelog.com) and [Semantic Versioning](https://semver.org).
 
+## [0.2.3] — 2026-04-17
+
+### Fixed
+
+- **OAuth discovery endpoints now served at RFC-compliant path-insertion URLs (`/.well-known/oauth-authorization-server/{path}`) in addition to the existing path-append form.** Restores Claude Code's MCP OAuth SDK compatibility, which follows RFC 8414 §3.1 and RFC 9728 §3 strictly and probes only the path-insertion shape. Before 0.2.3, the SDK's AS-metadata fetch 404'd, leaving it without a `registration_endpoint` and cascading into a 404 on the `/register` fallback. Both scoped forms now work: `/.well-known/oauth-authorization-server/vaults/<name>` and the longer `/.well-known/oauth-authorization-server/vaults/<name>/mcp`; same shapes on `/.well-known/oauth-protected-resource/...`. Path-append routes (`/vaults/<name>/.well-known/<type>`) are unchanged so lax clients keep working.
+
+## [0.2.2] — 2026-04-17
+
+### Fixed
+
+- **`start.sh` daemon wrapper no longer crashes on user shell profiles that reference unbound variables.** The generated wrapper ran `source ~/.zprofile` and `source ~/.zshrc` under `set -u`, so a zsh plugin framework or any conditional profile setup that touched an unset variable would abort the wrapper with exit 1. The `2>/dev/null` redirect swallowed the error, launchd saw repeated exit 1s, and the daemon silently refused to start with an empty `vault.err`. The wrapper now brackets the profile-source lines with `set +u` / `set -u` so -u is only active for code the wrapper owns. Run `parachute vault init` once on 0.2.2 to rewrite `~/.parachute/start.sh` — the rewrite is idempotent.
+
+### Added
+
+- **`parachute --version` / `parachute -v` / `parachute version`** print the installed package version to stdout. Works at the root and with the `vault` prefix (`parachute vault --version`, etc.). Reads from the installed `package.json` at module load, not a hardcoded string.
+
 ## [0.2.1] — 2026-04-17
 
 ### Fixed
@@ -83,5 +99,7 @@ First tagged public release. Ships the auth, backup, and onboarding surface the
 - **`core/src/test-preload.ts`** isolates `PARACHUTE_HOME` for tests so `bun test` never touches a user's real `~/.parachute/`.
 - Test suite at release cut: **538 passing / 0 failing / 3 skipped** across 22 files (541 tests total).
 
+[0.2.3]: https://github.com/ParachuteComputer/parachute-vault/releases/tag/v0.2.3
+[0.2.2]: https://github.com/ParachuteComputer/parachute-vault/releases/tag/v0.2.2
 [0.2.1]: https://github.com/ParachuteComputer/parachute-vault/releases/tag/v0.2.1
 [0.2.0]: https://github.com/ParachuteComputer/parachute-vault/releases/tag/v0.2.0

package/README.md

@@ -172,6 +172,7 @@ parachute vault init                       # one-command setup (idempotent — s
 parachute vault status                     # check what's running
 parachute vault doctor                     # diagnose install/config issues (see Troubleshooting)
 parachute vault url                        # print the local server URL (for scripts)
+parachute --version                        # print the installed version (aliases: -v, version)
 parachute vault uninstall                  # remove daemon + MCP entry; keeps user data
 parachute vault uninstall --wipe           # ...and also remove vaults, .env, config.yaml, logs
 parachute vault uninstall --yes --wipe     # scripted destructive wipe (prints an audit line)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/cli.ts

@@ -19,6 +19,10 @@
 import { resolve } from "path";
 import { homedir } from "os";
 import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from "fs";
+// JSON import — resolved at module load, works for both dev runs
+// (`bun src/cli.ts …`) and the published package (`bunx @openparachute/vault`)
+// because package.json ships at the root next to src/.
+import pkg from "../package.json" with { type: "json" };
 import {
   ensureConfigDirSync,
   readVaultConfig,
@@ -180,6 +184,14 @@ switch (command) {
   case "-h":
     usage();
     break;
+  case "version":
+  case "--version":
+  case "-v":
+    // Intentionally minimal — just the version string on stdout. Scripts
+    // (and `parachute vault doctor` in a future check) rely on this being
+    // a bare-number line; anything else belongs in `vault status`.
+    console.log(pkg.version);
+    break;
   default:
     console.error(`Unknown command: ${command}`);
     usage();
@@ -1976,6 +1988,7 @@ Setup:
                                            config.yaml, and daemon logs (vault.log, vault.err).
                                            --yes skips prompts (DANGEROUS with --wipe: no confirmation).
   parachute vault url                      Print the local server URL (for scripts)
+  parachute --version                      Print the installed version (alias: -v, version)
 
 Vaults:
   parachute vault create <name>            Create a new vault

package/src/daemon.ts

@@ -55,8 +55,17 @@ export function generateWrapper(opts: {
 set -u
 
 # Source user shell profile for PATH (needed for parakeet-mlx, ffmpeg, etc.)
+# Temporarily disable -u around these: user rc files routinely reference
+# unbound variables (zsh plugin frameworks, conditional setups), and a bare
+# \`set -u\` source would crash the wrapper with exit 1 and leave vault.err
+# empty because of the 2>/dev/null below — launchd would respawn silently
+# until it gave up. Keep the stderr redirect so expected "command not found"
+# noise from incomplete setups doesn't fill vault.err; to debug silent
+# wrapper failures, run \`bash -x ~/.parachute/start.sh\` by hand.
+set +u
 [ -f "$HOME/.zprofile" ] && source "$HOME/.zprofile" 2>/dev/null
 [ -f "$HOME/.zshrc" ] && source "$HOME/.zshrc" 2>/dev/null
+set -u
 
 if [ -f "${envPath}" ]; then
   set -a

package/src/launchd.test.ts

@@ -78,6 +78,84 @@ describe("generateWrapper", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  // ---------------------------------------------------------------------------
+  // The incident this guards against (0.2.2): sourcing the user's ~/.zshrc or
+  // ~/.zprofile under `set -u` crashes the wrapper if any line in the rc file
+  // references an unbound variable — which is routine in zsh plugin frameworks
+  // and half-configured setups. The 2>/dev/null redirect swallowed the error
+  // so vault.err stayed empty and launchd silently gave up after repeated
+  // exit 1s. The fix brackets the profile-source lines with `set +u` / `set -u`
+  // so strict-unset-vars only applies to code the wrapper itself owns.
+  // ---------------------------------------------------------------------------
+
+  test("brackets profile sourcing with set +u / set -u to survive user rc files", () => {
+    const wrapper = generateWrapper({ bunPath: "/bin/bun" });
+    // Textual shape check — quickest canary.
+    const lines = wrapper.split("\n");
+    const zprofileIdx = lines.findIndex((l) => l.includes(".zprofile"));
+    const zshrcIdx = lines.findIndex((l) => l.includes(".zshrc"));
+    expect(zprofileIdx).toBeGreaterThan(-1);
+    expect(zshrcIdx).toBeGreaterThan(-1);
+    // Both source lines must be sandwiched between a `set +u` and a `set -u`.
+    // Walk back for `set +u` and forward for `set -u` from whichever source
+    // line comes first / last so ordering stays flexible.
+    const firstIdx = Math.min(zprofileIdx, zshrcIdx);
+    const lastIdx = Math.max(zprofileIdx, zshrcIdx);
+    const preceding = lines.slice(0, firstIdx).reverse().find((l) => l.trim().startsWith("set "));
+    const following = lines.slice(lastIdx + 1).find((l) => l.trim().startsWith("set "));
+    expect(preceding?.trim()).toBe("set +u");
+    expect(following?.trim()).toBe("set -u");
+  });
+
+  test("surviving profile source under set -u: running the generated wrapper with a rc file that trips set -u does not abort before reaching the pointer-file logic", async () => {
+    // The integration proof. Build a fake HOME where ~/.zshrc expands an
+    // unbound variable ($UNSET_IN_TEST), point the wrapper at it via HOME,
+    // and expect the wrapper to exit on the "server path not configured"
+    // path (exit 1 from the explicit check) rather than on the zshrc crash
+    // (exit 1 from set -u). The signal we compare on is the stderr message:
+    // the pointer-missing branch prints a specific error; a set-u crash
+    // prints zsh's own "parameter not set" message and no vault-branded
+    // text at all.
+    //
+    // Skipping stderr here would let a regressed wrapper silently exit 1
+    // and still pass the test, so we assert on the presence of the
+    // pointer-missing message.
+    const dir = mkdtempSync(join(tmpdir(), "vault-wrapper-setu-"));
+    try {
+      const fakeHome = join(dir, "home");
+      writeFileSync(join(dir, "mkdir.marker"), ""); // ensure dir exists
+      await $`mkdir -p ${fakeHome}`.quiet();
+      // A ~/.zshrc that blows up under set -u.
+      writeFileSync(join(fakeHome, ".zshrc"), 'echo "$UNSET_IN_TEST"\n');
+      // Wrapper with explicit env/pointer paths that do NOT exist. We do not
+      // pass PARACHUTE_VAULT_SERVER_PATH either. So the wrapper should take
+      // the "no server path configured" branch and exit 1 with the branded
+      // message — but only if it survives the zshrc source.
+      const wrapper = generateWrapper({
+        bunPath: "/bin/echo", // won't be reached; a safe no-op if it is
+        serverPathFile: join(dir, "nonexistent-pointer"),
+        envPath: join(dir, "nonexistent.env"),
+      });
+      const path = join(dir, "start.sh");
+      writeFileSync(path, wrapper);
+      // Override HOME so the wrapper sources our crafted zshrc.
+      // Clear PARACHUTE_VAULT_SERVER_PATH in case the test runner has it set.
+      const result = await $`HOME=${fakeHome} PARACHUTE_VAULT_SERVER_PATH= bash ${path}`
+        .quiet()
+        .nothrow();
+      const stderr = result.stderr.toString();
+      // Positive: we reached the branded pointer-missing branch.
+      expect(stderr).toMatch(/parachute-vault: server path not configured/);
+      // Negative: we did NOT crash in zshrc with a zsh/bash unbound-variable
+      // message. Catches a future regression where someone drops the
+      // `set +u` bracket.
+      expect(stderr).not.toMatch(/UNSET_IN_TEST: unbound variable/);
+      expect(result.exitCode).toBe(1); // the branded branch
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("generatePlist", () => {

package/src/routing.test.ts

@@ -476,3 +476,186 @@ describe("MCP 401 WWW-Authenticate challenge (RFC 9728)", () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// RFC 8414 §3.1 / RFC 9728 §3 path-insertion discovery.
+//
+// For a resource at `/vaults/<name>/mcp`, the spec-mandated metadata URLs are
+//   /.well-known/oauth-authorization-server/vaults/<name>[/mcp]
+//   /.well-known/oauth-protected-resource/vaults/<name>[/mcp]
+// rather than the path-append form
+//   /vaults/<name>/.well-known/<type>
+// that PR #111 also ships. Strict clients (including Claude Code's MCP OAuth
+// SDK) probe only the path-insertion form; lax clients try path-append. We
+// serve both so any conformant probe hits a live endpoint.
+// ---------------------------------------------------------------------------
+
+describe("path-insertion OAuth discovery (RFC 8414 §3.1 / RFC 9728 §3)", () => {
+  test("/.well-known/oauth-authorization-server/vaults/<name> returns vault-scoped AS metadata", async () => {
+    createVault("journal");
+    const path = "/.well-known/oauth-authorization-server/vaults/journal";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      issuer: string;
+      authorization_endpoint: string;
+      token_endpoint: string;
+      registration_endpoint: string;
+    };
+    // All four endpoints must be vault-scoped — otherwise Claude Code's
+    // registration_endpoint falls back to root `/register` and cascades 404.
+    expect(body.issuer).toBe("http://localhost:1940/vaults/journal");
+    expect(body.authorization_endpoint).toBe("http://localhost:1940/vaults/journal/oauth/authorize");
+    expect(body.token_endpoint).toBe("http://localhost:1940/vaults/journal/oauth/token");
+    expect(body.registration_endpoint).toBe("http://localhost:1940/vaults/journal/oauth/register");
+  });
+
+  test("/.well-known/oauth-authorization-server/vaults/<name>/mcp (longer form) also returns AS metadata", async () => {
+    // Aaron's log shows Claude Code probes this longer form too; cheap to
+    // support since it resolves to the same AS for the same vault.
+    createVault("journal");
+    const path = "/.well-known/oauth-authorization-server/vaults/journal/mcp";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { issuer: string; registration_endpoint: string };
+    expect(body.issuer).toBe("http://localhost:1940/vaults/journal");
+    expect(body.registration_endpoint).toBe("http://localhost:1940/vaults/journal/oauth/register");
+  });
+
+  test("/.well-known/oauth-protected-resource/vaults/<name> returns vault-scoped PRM", async () => {
+    createVault("journal");
+    const path = "/.well-known/oauth-protected-resource/vaults/journal";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { resource: string; authorization_servers: string[] };
+    expect(body.resource).toBe("http://localhost:1940/vaults/journal/mcp");
+    expect(body.authorization_servers).toEqual(["http://localhost:1940/vaults/journal"]);
+  });
+
+  test("/.well-known/oauth-protected-resource/vaults/<name>/mcp (longer form) also returns PRM", async () => {
+    createVault("journal");
+    const path = "/.well-known/oauth-protected-resource/vaults/journal/mcp";
+    const res = await route(new Request(`http://localhost:1940${path}`), path);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { resource: string };
+    expect(body.resource).toBe("http://localhost:1940/vaults/journal/mcp");
+  });
+
+  test("path-insertion and path-append forms return identical metadata", async () => {
+    // The coherence guarantee: a client that follows either spec shape MUST
+    // land on the same AS config. If these drift, a mixed-toolchain deploy
+    // (CLI using one form, daemon using the other) would mint tokens
+    // against inconsistent endpoints.
+    createVault("journal");
+
+    // AS metadata
+    const insertAsPath = "/.well-known/oauth-authorization-server/vaults/journal";
+    const appendAsPath = "/vaults/journal/.well-known/oauth-authorization-server";
+    const insertAsRes = await route(new Request(`http://localhost:1940${insertAsPath}`), insertAsPath);
+    const appendAsRes = await route(new Request(`http://localhost:1940${appendAsPath}`), appendAsPath);
+    expect(await insertAsRes.json()).toEqual(await appendAsRes.json());
+
+    // PRM
+    const insertPrmPath = "/.well-known/oauth-protected-resource/vaults/journal";
+    const appendPrmPath = "/vaults/journal/.well-known/oauth-protected-resource";
+    const insertPrmRes = await route(new Request(`http://localhost:1940${insertPrmPath}`), insertPrmPath);
+    const appendPrmRes = await route(new Request(`http://localhost:1940${appendPrmPath}`), appendPrmPath);
+    expect(await insertPrmRes.json()).toEqual(await appendPrmRes.json());
+  });
+
+  test("unknown vault in path-insertion URL returns 404, not boilerplate metadata", async () => {
+    // Don't leak metadata for phantom vaults. The equivalent path-append
+    // route also 404s when the vault doesn't exist (`readVaultConfig` miss
+    // at the vault-scoped routes branch); path-insertion must match.
+    createVault("journal");
+    for (const path of [
+      "/.well-known/oauth-authorization-server/vaults/nonexistent",
+      "/.well-known/oauth-authorization-server/vaults/nonexistent/mcp",
+      "/.well-known/oauth-protected-resource/vaults/nonexistent",
+      "/.well-known/oauth-protected-resource/vaults/nonexistent/mcp",
+    ]) {
+      const res = await route(new Request(`http://localhost:1940${path}`), path);
+      expect(res.status).toBe(404);
+    }
+  });
+
+  test("x-forwarded-* headers propagate into the generated metadata URLs", async () => {
+    // Same contract as the WWW-Authenticate challenge and the root/append
+    // discovery endpoints: metadata must match the public-facing origin so
+    // a Cloudflare Tunnel / Tailscale Funnel deployment doesn't advertise
+    // internal localhost:1940 URLs.
+    createVault("journal");
+    const path = "/.well-known/oauth-authorization-server/vaults/journal";
+    const res = await route(
+      new Request(`http://127.0.0.1:1940${path}`, {
+        headers: {
+          "x-forwarded-host": "vault.example.com",
+          "x-forwarded-proto": "https",
+        },
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { issuer: string; registration_endpoint: string };
+    expect(body.issuer).toBe("https://vault.example.com/vaults/journal");
+    expect(body.registration_endpoint).toBe(
+      "https://vault.example.com/vaults/journal/oauth/register",
+    );
+  });
+
+  test("end-to-end flow: WWW-Authenticate → PRM → AS metadata → registration_endpoint is live", async () => {
+    // The actual Claude-Code bug: on 401, follow the challenge to the PRM,
+    // then follow PRM.authorization_servers[0] to the AS metadata (via
+    // path-insertion), then hit the `registration_endpoint`. Every hop
+    // must resolve — before the fix, the AS-metadata-via-path-insertion
+    // step 404'd and the SDK fell back to `/register` which also 404'd.
+    createVault("journal");
+
+    // Step 1: unauthenticated MCP → 401 + WWW-Authenticate.
+    const mcpRes = await route(
+      new Request("http://localhost:1940/vaults/journal/mcp"),
+      "/vaults/journal/mcp",
+    );
+    expect(mcpRes.status).toBe(401);
+    const challenge = mcpRes.headers.get("WWW-Authenticate")!;
+    const prmUrl = challenge.match(/resource_metadata="([^"]+)"/)![1];
+
+    // Step 2: fetch PRM. The challenge points at the path-append form, but
+    // a strict client might also try path-insertion — both must work.
+    // Follow the advertised URL (path-append in this case) and note the
+    // authorization_servers pointer.
+    const prmPath = new URL(prmUrl).pathname;
+    const prmRes = await route(new Request(`http://localhost:1940${prmPath}`), prmPath);
+    expect(prmRes.status).toBe(200);
+    const prm = (await prmRes.json()) as { authorization_servers: string[] };
+    const asBase = prm.authorization_servers[0]; // "http://localhost:1940/vaults/journal"
+
+    // Step 3: strict-client path-insertion probe for AS metadata.
+    const asBasePath = new URL(asBase).pathname; // "/vaults/journal"
+    const asInsertPath = `/.well-known/oauth-authorization-server${asBasePath}`;
+    const asRes = await route(
+      new Request(`http://localhost:1940${asInsertPath}`),
+      asInsertPath,
+    );
+    // This was the 404 before the fix — the reason Claude Code's SDK gave
+    // up and cascade-404'd on `/register`.
+    expect(asRes.status).toBe(200);
+    const asMeta = (await asRes.json()) as { registration_endpoint: string };
+
+    // Step 4: the advertised registration_endpoint must be live (POST-only).
+    const regPath = new URL(asMeta.registration_endpoint).pathname;
+    const regRes = await route(
+      new Request(`http://localhost:1940${regPath}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          client_name: "Test",
+          redirect_uris: ["https://example.com/cb"],
+        }),
+      }),
+      regPath,
+    );
+    // Successful DCR is 201; anything but 404 proves the endpoint is wired.
+    expect(regRes.status).toBe(201);
+  });
+});

package/src/routing.ts

@@ -115,7 +115,43 @@ export async function route(
   path: string,
   clientIp?: string,
 ): Promise<Response> {
-  // OAuth discovery endpoints (no auth required)
+  // OAuth discovery endpoints (no auth required).
+  //
+  // RFC 8414 §3.1 and RFC 9728 §3 specify the discovery URL shape when an
+  // authorization server (or protected resource) has a path component `/p`:
+  //
+  //   Path-insertion (spec-mandated):
+  //     <host>/.well-known/<metadata-type>/p
+  //   Path-append (widespread in the wild, shipped in PR #111):
+  //     <host>/p/.well-known/<metadata-type>
+  //
+  // Strict clients — including Claude Code's MCP OAuth SDK — probe only the
+  // path-insertion form. Lax clients try path-append. We serve both so any
+  // conformant probe hits a live endpoint. Unscoped root forms
+  // (`/.well-known/oauth-*`) are the third accepted shape, and the
+  // path-append branch for scoped discovery lives further down alongside the
+  // other `/vaults/{name}/*` routing.
+  const protectedResourceInsert = path.match(
+    /^\/\.well-known\/oauth-protected-resource\/vaults\/([^/]+)(?:\/mcp)?$/,
+  );
+  if (protectedResourceInsert) {
+    const vaultName = protectedResourceInsert[1];
+    if (!readVaultConfig(vaultName)) {
+      return Response.json({ error: "Vault not found", vault: vaultName }, { status: 404 });
+    }
+    return handleProtectedResource(req, `/vaults/${vaultName}/mcp`, `/vaults/${vaultName}`);
+  }
+  const authServerInsert = path.match(
+    /^\/\.well-known\/oauth-authorization-server\/vaults\/([^/]+)(?:\/mcp)?$/,
+  );
+  if (authServerInsert) {
+    const vaultName = authServerInsert[1];
+    if (!readVaultConfig(vaultName)) {
+      return Response.json({ error: "Vault not found", vault: vaultName }, { status: 404 });
+    }
+    return handleAuthorizationServer(req, vaultName);
+  }
+
   if (path === "/.well-known/oauth-protected-resource") {
     return handleProtectedResource(req);
   }

package/src/version.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Integration tests for `parachute --version` and its aliases.
+ *
+ * Spawns the real CLI as a subprocess so the argv-dispatch path is exercised
+ * end-to-end. Every accepted spelling must produce the exact version string
+ * from package.json on stdout, with exit code 0, and nothing else.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { resolve } from "path";
+import pkg from "../package.json" with { type: "json" };
+
+const CLI = resolve(import.meta.dir, "cli.ts");
+
+function runCli(args: string[]): {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+} {
+  const proc = Bun.spawnSync({
+    cmd: ["bun", CLI, ...args],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    exitCode: proc.exitCode ?? -1,
+    stdout: new TextDecoder().decode(proc.stdout),
+    stderr: new TextDecoder().decode(proc.stderr),
+  };
+}
+
+describe("parachute version", () => {
+  // Every spelling must print the package's version and nothing else.
+  // `parachute vault --version` works via the argv parser's existing
+  // `args[0] === "vault"` branch, which shifts "vault" off and treats
+  // `--version` as the command — so the same switch case handles both
+  // root and vault-prefixed invocations.
+  for (const form of [
+    ["--version"],
+    ["-v"],
+    ["version"],
+    ["vault", "--version"],
+    ["vault", "-v"],
+    ["vault", "version"],
+  ]) {
+    test(`parachute ${form.join(" ")} prints the package version`, () => {
+      const { exitCode, stdout, stderr } = runCli(form);
+      expect(exitCode).toBe(0);
+      // Exact match — no banner, no trailing whitespace other than the single
+      // trailing newline from console.log. Scripts will pipe this through
+      // things like `$(parachute --version)`.
+      expect(stdout).toBe(`${pkg.version}\n`);
+      // Stderr must be empty. If the dispatcher drops into the default branch
+      // it would print "Unknown command:" plus the full usage() block to
+      // stderr, which is exactly the regression this test catches.
+      expect(stderr).toBe("");
+    });
+  }
+
+  test("version string looks like semver (sanity check)", () => {
+    // Defense-in-depth: if someone ever replaces the JSON import with a
+    // hardcoded string, a malformed value still won't slip through.
+    expect(pkg.version).toMatch(/^\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?$/);
+  });
+});