skillrepo 3.1.0 → 3.1.2

package/src/test/commands/init.test.mjs

@@ -20,12 +20,18 @@ import { readConfig } from "../../lib/config.mjs";
 import { CliError, EXIT_AUTH, EXIT_VALIDATION } from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
 let server;
 let serverUrl;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 let stdout;
 let stderr;
 const VALID_KEY = "sk_live_init_test";
@@ -38,9 +44,9 @@ async function setup() {
   mkdirSync(join(sandbox, "project", ".claude"), { recursive: true });
   mkdirSync(join(sandbox, "home"), { recursive: true });
   originalCwd = process.cwd();
-  originalHome = process.env.HOME;
+  originalHomeEnv = captureHome();
   process.chdir(join(sandbox, "project"));
-  process.env.HOME = join(sandbox, "home");
+  setSandboxHome(join(sandbox, "home"));
   delete process.env.SKILLREPO_ACCESS_KEY;
   delete process.env.SKILLREPO_URL;
 
@@ -55,7 +61,7 @@ async function setup() {
 async function teardown() {
   if (server) await server.stop();
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
   server = null;
 }
@@ -499,25 +505,29 @@ describe("runInit — stale-key handling", () => {
 // init tests verify the ORCHESTRATION: --yes path, --no-session-sync
 // opt-out, --json output shape, and the non-fatal disk-error path.
 
-import { chmodSync as _chmodSync } from "node:fs";
 import { SESSION_HOOK_FINGERPRINT as _FINGERPRINT } from "../../lib/artifact-registry.mjs";
+import { installShim, uninstallShim } from "../helpers/skillrepo-shim.mjs";
+
+/** @type {ReturnType<typeof installShim> | undefined} */
+let _shimHandle;
 
 async function setupWithShim() {
   await setup();
-  // Drop a deterministic `skillrepo` shim into HOME/bin so
-  // `which skillrepo` resolves to it rather than a possibly-missing
-  // global install.
-  const binDir = join(process.env.HOME, "bin");
-  mkdirSync(binDir, { recursive: true });
-  const shim = join(binDir, "skillrepo");
-  writeFileSync(shim, "#!/bin/sh\nexit 0\n");
-  _chmodSync(shim, 0o755);
-  process.env.PATH = `${binDir}:${process.env.PATH}`;
+  // Drop a cross-platform `skillrepo` shim into HOME/bin so the
+  // CLI's binary resolver (which/where) finds it rather than
+  // depending on whether the dev/CI machine has a global install.
+  _shimHandle = installShim(process.env.HOME);
+}
+
+async function teardownWithShim() {
+  uninstallShim(_shimHandle);
+  _shimHandle = undefined;
+  await teardown();
 }
 
 describe("runInit — session sync (#884)", () => {
   beforeEach(setupWithShim);
-  afterEach(teardown);
+  afterEach(teardownWithShim);
 
   it("--yes installs the hook at step 6 by default", async () => {
     // INTENT: the architect-designed default for --yes mode is
@@ -695,3 +705,867 @@ describe("runInit — session sync (#884)", () => {
     assert.equal(json.sessionSync.path, "~/.claude/settings.local.json");
   });
 });
+
+// ── v3.1.1 patch fixes: init UX bugs surfaced by real-world npx use ──
+//
+// Real-user `npx skillrepo@latest init` session surfaced four bugs in
+// the v3.1.0 init output. The tests below lock each fix as a
+// behavioral contract:
+//
+//   1. "Next steps" hardcoded `skillrepo` even under npx — would fail
+//      with "command not found" for users without a global install.
+//   2. Session-sync hook installed under npx with a cache-temporary
+//      path that breaks on cache eviction. (Covered in
+//      session-hook.test.mjs via isNpxInvocation guard test.)
+//   3. Step-7 zero-delta message conflated "empty library" with
+//      "nothing changed since last sync" — lied to users who had
+//      synced skills but no server-side changes since.
+//   4. `--verbose` rejected as Unknown argument by resolveFlags.
+//      (Covered in cli-config.test.mjs.)
+
+describe("runInit — v3.1.1 zero-delta message (bug 3)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("reports 'Library is up to date' when a delta sync returns zero changes", async () => {
+    // Reproduces the real-user bug: a user with an existing
+    // .last-sync from a prior v3.0.0 session runs `skillrepo init`
+    // again. Init's step 7 sends `since=<prior syncedAt>`. Server
+    // returns empty skills[] because nothing changed server-side.
+    // Counters (added/updated/removed) all zero.
+    //
+    // Before the fix: init printed "No skills in library yet"
+    // regardless of whether the library was empty or fully synced.
+    // After: init distinguishes via the new `fullSync` field in
+    // SyncSummary and prints "Library is up to date (no changes
+    // since last sync)" for the delta case.
+    //
+    // Pre-seed a .last-sync file simulating the prior sync state.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      join(process.env.HOME, ".claude", "skillrepo", ".last-sync"),
+      JSON.stringify({
+        schemaVersion: 1,
+        etag: '"old-v300-format-etag"',
+        syncedAt: "2026-04-15T12:00:00.000Z",
+      }),
+    );
+
+    // Server returns empty skills[] (no changes since last sync).
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "2026-04-16T12:00:00.000Z" });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(
+      out,
+      /Library is up to date/,
+      "zero-delta on delta sync must report 'up to date', not 'no skills in library yet'",
+    );
+    assert.doesNotMatch(
+      out,
+      /No skills in library yet/,
+      "the misleading 'no skills' message must NOT fire when .last-sync existed",
+    );
+  });
+
+  it("still reports 'No skills in library yet' on a true first-run full sync with zero skills", async () => {
+    // The other side of bug 3: when there's NO prior .last-sync and
+    // the server returns zero skills, the library IS genuinely
+    // empty. The message should still say so.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "2026-04-16T12:00:00.000Z" });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(out, /No skills in library yet/);
+  });
+
+  it("304 Not Modified reports 'Library is up to date' (neutral phrasing)", async () => {
+    // 304 path: server returned "nothing changed" at the HTTP
+    // level. Definitively up-to-date regardless of whether library
+    // is populated or empty.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      join(process.env.HOME, ".claude", "skillrepo", ".last-sync"),
+      JSON.stringify({
+        schemaVersion: 1,
+        etag: '"match-me"',
+        syncedAt: "2026-04-15T12:00:00.000Z",
+      }),
+    );
+    server.setEtag('"match-me"');
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    assert.match(stdout.text(), /Library is up to date/);
+  });
+});
+
+describe("runInit — v3.1.1 Next steps prefix (bug 1)", () => {
+  // Process-state isolation: the tests below depend on controlling
+  // isNpxInvocation()'s outputs. The test host's shell environment
+  // may have `_` set to some launching command (the enclosing `npm
+  // run check`, `node --test`, etc.). beforeEach force-clears the
+  // two isNpxInvocation signals (argv[1] and `_`) plus the
+  // now-unused `npm_command` — the latter is cleared defensively
+  // because older versions of this codebase treated it as an npx
+  // signal, and belt-and-suspenders cleanup costs nothing.
+  let originalArgv;
+  let originalNpmCommand;
+  let originalUnderscore;
+
+  beforeEach(async () => {
+    await setup();
+    originalArgv = process.argv;
+    originalNpmCommand = process.env.npm_command;
+    originalUnderscore = process.env._;
+    // Non-npx state:
+    process.argv = ["/usr/local/bin/node", "/usr/local/bin/skillrepo"];
+    delete process.env.npm_command;
+    delete process.env._;
+  });
+
+  afterEach(async () => {
+    process.argv = originalArgv;
+    if (originalNpmCommand === undefined) delete process.env.npm_command;
+    else process.env.npm_command = originalNpmCommand;
+    if (originalUnderscore === undefined) delete process.env._;
+    else process.env._ = originalUnderscore;
+    await teardown();
+  });
+
+  it("shows bare `skillrepo` prefix when running from a stable install", async () => {
+    // With all npx signals cleared (beforeEach above), isNpxInvocation
+    // returns false and the bare prefix is used in the Next Steps
+    // block.
+    //
+    // NOTE ON REGEX: "npm install -g skillrepo" appears in TWO places
+    // that look alike but come from different code paths:
+    //
+    //   1. Step 6/7 session-sync skipped message (when the binary
+    //      can't be resolved — in the test environment, `which
+    //      skillrepo` doesn't find anything real).
+    //   2. Next Steps tip (only shown under npx).
+    //
+    // We want to assert only #2 is absent. Match the EXACT "Tip:"
+    // prefix to scope the assertion to Next Steps.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    // The commands in Next Steps are bare, not prefixed.
+    assert.match(out, /^ +• skillrepo list/m);
+    assert.doesNotMatch(
+      out,
+      /npx skillrepo list/,
+      "bare install must NOT show the npx-prefixed hints",
+    );
+    // The "Tip: …" line appears only under npx.
+    assert.doesNotMatch(
+      out,
+      /Tip: `npm install -g skillrepo`/,
+      "bare install must NOT show the npx-mode global-install tip",
+    );
+  });
+
+  it("shows `npx skillrepo` prefix and global-install tip under npx invocation", async () => {
+    // Simulate npx by stuffing argv[1] with an _npx cache path.
+    // isNpxInvocation() returns true and the output changes shape.
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/dc129a78aca3fc9c/node_modules/.bin/skillrepo",
+    ];
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    // v3.1.2: pass --no-session-sync to scope this test to the
+    // Next-Steps prefix/tip behavior (its actual intent). Without
+    // the flag, step 6 would attempt the new auto-install-global
+    // flow, which actually shells out to `npm install -g skillrepo`
+    // (a test pollutant — slow, network-dependent, and could
+    // mutate the developer's global node_modules). Adding
+    // --no-session-sync skips step 6 entirely while leaving the
+    // npx-detection prefix and Tip behaviors fully exercised.
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(
+      out,
+      /npx skillrepo list/,
+      "npx invocation must prefix commands with `npx`",
+    );
+    assert.match(
+      out,
+      /Tip: `npm install -g skillrepo`/,
+      "npx invocation must show the Next-Steps global-install tip",
+    );
+  });
+
+  // ── v3.1.2: per-runner Next-Steps prefix ────────────────────────
+  //
+  // v3.1.1 hardcoded `npx skillrepo` for ALL transient runners. After
+  // extending detection to pnpm dlx / yarn berry dlx / bunx, the
+  // prefix must match the actual runner so the user can copy-paste
+  // the suggested command.
+
+  it("v3.1.2: shows `pnpx skillrepo` prefix when launched via pnpm dlx", async () => {
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.local/share/pnpm/store/dlx-abc/node_modules/.bin/skillrepo",
+    ];
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    // Match the bullet line exactly so we don't accidentally match
+    // `pnpx skillrepo list` while looking for `npx skillrepo list`
+    // (the substring overlap is real — pnpx ends with "npx").
+    assert.match(out, /^ +• pnpx skillrepo list/m);
+    assert.doesNotMatch(
+      out,
+      /^ +• npx skillrepo list/m,
+      "must NOT show bare `npx` prefix when invoked via pnpx",
+    );
+  });
+
+  it("v3.1.2: shows `pnpm add -g` install command in Tip when launched via pnpm dlx", async () => {
+    // Round-3 fix for the architect's NOTE 1: the Tip line was
+    // hardcoded `npm install -g skillrepo` even for pnpx/yarn dlx/
+    // bunx users. This test locks the per-runner Tip behavior.
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.local/share/pnpm/store/dlx-abc/node_modules/.bin/skillrepo",
+    ];
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(
+      out,
+      /Tip: `pnpm add -g skillrepo`/,
+      "pnpx user must see the pnpm install command, not npm",
+    );
+    assert.doesNotMatch(
+      out,
+      /Tip: `npm install -g skillrepo`/,
+      "must NOT show the bare npm command for a pnpx user",
+    );
+  });
+
+  it("v3.1.2: shows `bun add -g` install command in Tip when launched via bunx", async () => {
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.bun/install/cache/skillrepo@3.1.2/node_modules/.bin/skillrepo",
+    ];
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
+      { stdout, stderr },
+    );
+
+    assert.match(stdout.text(), /Tip: `bun add -g skillrepo`/);
+  });
+
+  it("v3.1.2: yarn berry dlx Tip falls back to `npm install -g` (yarn berry has no global add)", async () => {
+    // Yarn berry deliberately ships no `yarn global add` — see the
+    // comment on TRANSIENT_RUNNERS in transient-runners.mjs. Users
+    // who want a persistent global on yarn-berry get the universal
+    // npm fallback.
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/proj/.yarn/berry/cache/skillrepo-npm-3.1.2-abc/node_modules/skillrepo/bin/skillrepo.mjs",
+    ];
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
+      { stdout, stderr },
+    );
+
+    assert.match(stdout.text(), /Tip: `npm install -g skillrepo`/);
+  });
+
+  it("v3.1.2: shows `yarn dlx skillrepo` prefix when launched via yarn berry dlx", async () => {
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/proj/.yarn/berry/cache/skillrepo-npm-3.1.2-abc/node_modules/skillrepo/bin/skillrepo.mjs",
+    ];
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(out, /yarn dlx skillrepo list/);
+  });
+
+  it("v3.1.2: shows `bunx skillrepo` prefix when launched via bunx", async () => {
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.bun/install/cache/skillrepo@3.1.2/node_modules/.bin/skillrepo",
+    ];
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(out, /bunx skillrepo list/);
+  });
+});
+
+// ── v3.1.2 (#894): init step 6 auto-install-global behavior ─────────
+//
+// Six branches in init.mjs step 6 under v3.1.2:
+//
+//   1. --no-session-sync           → opted-out, no install attempted
+//   2. non-Claude target           → not-applicable, no install attempted
+//   3. non-npx, no global on PATH  → mergeSessionHook returns "skipped"
+//      (existing v3.1.1 behavior, preserved)
+//   4. npx + EXISTING global       → use existing path, no auto-install
+//   5. npx + NO global, decline    → "declined", manual instructions printed
+//   6. npx + NO global, accept     → auto-install runs (mocked spawn).
+//                                    On success, hook installed via the
+//                                    explicit binaryPath bypass.
+//
+// All tests mock spawn via the new `deps.spawn` injection point so
+// no test ever shells out to `npm install -g`.
+
+describe("runInit — v3.1.2 step 6 auto-install (npx)", () => {
+  // Process-state isolation: same as the v3.1.1 npx prefix tests
+  // above. We control isNpxInvocation()'s output via process.argv[1]
+  // and process.env._.
+  let originalArgv;
+  let originalUnderscore;
+  let originalNpmCommand;
+  let shimSandbox;
+  let shimHandle;
+
+  beforeEach(async () => {
+    await setup();
+    originalArgv = process.argv;
+    originalUnderscore = process.env._;
+    originalNpmCommand = process.env.npm_command;
+    shimSandbox = null;
+    shimHandle = null;
+  });
+
+  afterEach(async () => {
+    process.argv = originalArgv;
+    if (originalUnderscore === undefined) delete process.env._;
+    else process.env._ = originalUnderscore;
+    if (originalNpmCommand === undefined) delete process.env.npm_command;
+    else process.env.npm_command = originalNpmCommand;
+    if (shimHandle) {
+      const { uninstallShim } = await import("../helpers/skillrepo-shim.mjs");
+      uninstallShim(shimHandle);
+    }
+    if (shimSandbox) rmSync(shimSandbox, { recursive: true, force: true });
+    await teardown();
+  });
+
+  function makeNpxArgv() {
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/dc129a78aca3fc9c/node_modules/.bin/skillrepo",
+    ];
+    delete process.env._;
+    delete process.env.npm_command;
+  }
+
+  // NOTE: the "Branch 5: npx + --json without --yes → declined"
+  // path is defensive code that is unreachable through `runInit`
+  // today. Step 5 (MCP auto-merge) prompts unconditionally
+  // per-vendor when `--yes` is not passed, so a non-interactive
+  // `--json` invocation hangs at step 5 before reaching step 6.
+  // The branch exists so a future refactor that makes step 5
+  // non-interactive under `--json` (e.g. default-yes for MCP merge
+  // under --json) gets the right step 6 semantics for free. Until
+  // that refactor lands, we cannot integration-test the branch
+  // without injecting a `confirmFn` into both step 5 and step 6,
+  // which would be more test scaffolding than the defensive code
+  // is worth. Coverage for the underlying "no install + manual
+  // instructions" semantic is provided by the failure-path tests
+  // below (Branch 6 with mock-failed spawn) which assert the
+  // identical printed message.
+
+  // NOTE: a "Branch 6 success" integration test (npx + --yes +
+  // spawn-success + binary appears on PATH post-install) cannot be
+  // cleanly written through `runInit`. The structural problem: if
+  // we install the shim on PATH BEFORE calling runInit, init's
+  // `resolveGlobalBinary()` finds it during the npx-mode check and
+  // takes Branch 4 (pre-existing global) instead. Installing the
+  // shim AFTER spawn fires would require a callback hook in
+  // mock-spawn that runs in the child's close handler — extra
+  // scaffolding for a path that's already covered by the
+  // composition of:
+  //   - global-install.test.mjs "happy path" (spawn → success →
+  //     resolveGlobalBinary finds shim → success result)
+  //   - session-hook.test.mjs "v3.1.2 bypass" (binaryPath param
+  //     bypasses npx guard → hook installed)
+  //   - init.test.mjs Branch 4 below (when a global exists, init
+  //     uses it directly via the binaryPath parameter)
+  // These three together cover the same end-to-end semantic.
+
+  it("Branch 6 failure: npx + --yes + spawn-fail (npm exit 1) → init exits 0, manual instructions printed", async () => {
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({
+      exitCode: 1,
+      stderrText: "npm ERR! some failure",
+    });
+
+    // No exception thrown — init must continue past auto-install
+    // failure and complete the rest of its steps.
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    // Hook NOT installed.
+    assert.equal(
+      existsSync(join(process.cwd(), ".claude", "settings.local.json")),
+      false,
+    );
+
+    // Output mentions failure + manual instructions + the npm error
+    // snippet for diagnosis.
+    const out = stdout.text();
+    assert.match(out, /Could not install skillrepo globally/);
+    assert.match(out, /npm install -g skillrepo/);
+    // Sync (step 7) still ran — no early abort
+    assert.match(out, /Library is up to date|No skills in library yet/);
+  });
+
+  it("Branch 6 EACCES (--json mode): spawn EACCES → eacces-categorized error in JSON sessionSync block", async () => {
+    // EACCES detection requires stderr capture, which only happens
+    // in --json mode (`outputMode: "silent"`). In non-json/inherit
+    // mode, npm's stderr goes to the user's terminal directly so
+    // we don't capture it — meaning categorization falls back to
+    // generic "npm-nonzero." That asymmetry is intentional: the
+    // user always sees the real npm output one way or another.
+    //
+    // This test exercises the categorization path under --json
+    // where the helper's structured error is the only signal the
+    // (machine) consumer has.
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({
+      exitCode: 243,
+      stderrText: "npm ERR! Error: EACCES: permission denied",
+    });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--json"],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    // In --json mode the human warnings go to stderr, but the
+    // machine-readable JSON on stdout is the contract.
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.sessionSync.action, "skipped");
+    // Init still succeeded overall — the sync block is present and
+    // the JSON parses cleanly.
+    assert.ok(json.sync, "sync block must be present after EACCES failure");
+  });
+
+  it("Branch 6 generic failure (non-json mode, non-EACCES exit code): falls back to generic error message", async () => {
+    // In non-json/inherit mode, stderr is NOT captured (it streams
+    // to the user's terminal directly). The helper categorizes the
+    // failure based ONLY on the exit code in inherit mode:
+    //   - 243 → EACCES (npm's documented permission-error code)
+    //   - any other non-zero → generic "npm-nonzero"
+    // This test exercises the generic path with a non-243 exit
+    // (e.g., a network or registry-side failure). Since the user
+    // already saw the real npm output via inherit, the helper's
+    // human message just confirms the failure happened.
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({
+      exitCode: 1,
+      stderrText: "irrelevant — won't be captured in inherit mode",
+    });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    const out = stdout.text();
+    // Generic categorization message — exit code is mentioned but
+    // no specific category like "EACCES" or "ENOENT".
+    assert.match(out, /Could not install skillrepo globally/);
+    assert.match(out, /exited with code 1/);
+    // Manual-install instructions printed.
+    assert.match(out, /npm install -g skillrepo/);
+    // Init still completed.
+    assert.match(out, /Library is up to date|No skills in library yet/);
+  });
+
+  it("Branch 6 EACCES via exit code 243 (non-json mode): categorized as eacces even without stderr capture", async () => {
+    // The v3.1.2 review surfaced an issue: EACCES detection in
+    // inherit mode was impossible because stderr wasn't captured.
+    // Fix: detect via exit code 243 (npm's documented EACCES exit
+    // code on POSIX). This test locks in that exit-code-based
+    // categorization works in inherit mode.
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({
+      exitCode: 243,
+      // No stderrText — inherit mode wouldn't capture it anyway,
+      // and we're proving the exit-code path works without stderr.
+    });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    const out = stdout.text();
+    // EACCES-categorized message — the actionable hint about sudo
+    // and the npm permissions docs URL must appear.
+    assert.match(out, /permissions error \(EACCES\)/);
+    assert.match(out, /sudo/);
+    assert.match(out, /npmjs.com\/resolving-eacces/);
+    // Init still completed.
+    assert.match(out, /Library is up to date|No skills in library yet/);
+  });
+
+  it("Branch 4: npx + EXISTING global on PATH → no auto-install, hook uses existing", async () => {
+    // Pre-stage a shim that resolveGlobalBinary will find — this
+    // simulates the user already having `npm install -g skillrepo`
+    // done before running `npx skillrepo init`. Init must detect
+    // the pre-existing global, skip the install offer, and use the
+    // existing path for the hook.
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    const { installShim } = await import("../helpers/skillrepo-shim.mjs");
+    shimSandbox = mkdtempSync(join(tmpdir(), "sr-init-preexisting-"));
+    shimHandle = installShim(shimSandbox);
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({ exitCode: 0 });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    // Spawn was NEVER called — pre-existing global was used directly.
+    assert.equal(
+      spawn.calls.length,
+      0,
+      "spawn must NOT be called when a global is already on PATH",
+    );
+
+    // Hook installed.
+    const settingsPath = join(
+      process.cwd(),
+      ".claude",
+      "settings.local.json",
+    );
+    assert.ok(existsSync(settingsPath));
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const hookCmd = settings.hooks.SessionStart[0].hooks[0].command;
+    // The path is now shell-quoted (v3.1.2: see buildHookCommand
+    // docstring for rationale), so it does not appear at position 0
+    // verbatim — it appears after the opening quote character.
+    //
+    // Cross-platform path comparison via the UNIQUE SANDBOX-DIR
+    // BASENAME (e.g. `sr-init-preexisting-XYZ`): on Windows,
+    // `os.tmpdir()` returns the 8.3 short-name form
+    // (`C:\Users\RUNNER~1\AppData\Local\Temp\...`) while `where.exe`
+    // returns the long-name form (`C:\Users\runneradmin\...`) for
+    // the SAME directory. The two strings differ, and `realpathSync`
+    // does NOT expand 8.3 short-names (those are filesystem aliases,
+    // not symlinks). The basename of the sandbox dir, however, is
+    // identical in both forms — it's the random suffix `mkdtempSync`
+    // appended, which doesn't have a short-name alias. Asserting the
+    // basename appears in the hookCmd is robust across platforms
+    // and path-form representations.
+    const { basename } = await import("node:path");
+    const sandboxName = basename(shimSandbox);
+    assert.ok(
+      hookCmd.includes(sandboxName) && hookCmd.includes("skillrepo"),
+      `expected hook command to contain sandbox ${sandboxName} and binary "skillrepo", got: ${hookCmd}`,
+    );
+
+    // Output communicates the action (not silent).
+    const out = stdout.text();
+    assert.match(out, /Found global skillrepo at/);
+  });
+
+  it("Branch 1: npx + --no-session-sync → spawn never called, action = opted-out", async () => {
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({ exitCode: 0 });
+
+    await runInit(
+      [
+        "--key",
+        VALID_KEY,
+        "--url",
+        serverUrl,
+        "--yes",
+        "--no-session-sync",
+        "--json",
+      ],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    assert.equal(spawn.calls.length, 0);
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.sessionSync.action, "opted-out");
+    assert.equal(
+      existsSync(join(process.cwd(), ".claude", "settings.local.json")),
+      false,
+    );
+  });
+
+  it("--json mode: stdout contains ONLY JSON (no npm output mixed in) when auto-install runs", async () => {
+    // Critical regression guard: in --json mode, npm output must
+    // NOT pollute stdout. The `outputMode: "silent"` switch in
+    // installSkillrepoGlobally is what enforces this; the test
+    // proves the wiring is correct.
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    // Use a spawn mock that "writes to stdout" — except since we're
+    // in silent mode, child.stdout is piped (not inherited) and
+    // production code drains it. The mock doesn't actually emit
+    // stdout data, but the test's value is that the entire stdout
+    // stream is parseable JSON regardless.
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({
+      exitCode: 1,
+      stderrText: "noisy npm error output",
+    });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--json"],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    // The entire stdout text must be valid JSON.
+    let parsed;
+    assert.doesNotThrow(() => {
+      parsed = JSON.parse(stdout.text());
+    }, "stdout must be valid JSON");
+    assert.equal(parsed.sessionSync.action, "skipped");
+  });
+
+  it("Branch 2: --ide cursor (non-Claude target) → spawn never called, action = not-applicable", async () => {
+    // QA gap fix: previously had no test for the non-Claude branch.
+    // Even under npx, if the user targets a non-Claude IDE, the
+    // SessionStart hook (Claude-specific) is skipped without an
+    // install offer.
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({ exitCode: 0 });
+
+    await runInit(
+      [
+        "--key",
+        VALID_KEY,
+        "--url",
+        serverUrl,
+        "--yes",
+        "--ide",
+        "cursor",
+        "--json",
+      ],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    assert.equal(spawn.calls.length, 0);
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.sessionSync.action, "not-applicable");
+    assert.equal(json.sessionSync.path, null);
+  });
+
+  it("--json contract: sessionSync.action = 'failed' is reachable when settings.local.json is corrupt", async () => {
+    // QA gap fix (BLOCKING): The "failed" action enum value was
+    // documented in the JSON output block but never exercised by
+    // a --json integration test. Pre-seed a corrupt
+    // settings.local.json before init runs the existing-global
+    // branch. mergeSessionHook throws diskError → init catches →
+    // sessionSyncAction = "failed" → JSON serialization.
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    // Pre-seed a corrupt settings file so mergeSessionHook throws.
+    const claudeDir = join(process.cwd(), ".claude");
+    mkdirSync(claudeDir, { recursive: true });
+    writeFileSync(
+      join(claudeDir, "settings.local.json"),
+      "{ this is not valid JSON",
+    );
+
+    // Pre-existing global on PATH so init takes Branch 4 (which
+    // calls mergeSessionHook directly with binaryPath).
+    const { installShim } = await import("../helpers/skillrepo-shim.mjs");
+    shimSandbox = mkdtempSync(join(tmpdir(), "sr-init-failed-"));
+    shimHandle = installShim(shimSandbox);
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({ exitCode: 0 });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--json"],
+      { stdout, stderr },
+      { spawn },
+    );
+
+    // JSON output is still valid (no unhandled exception aborted
+    // serialization) and reports the "failed" action enum value.
+    const json = JSON.parse(stdout.text());
+    assert.equal(
+      json.sessionSync.action,
+      "failed",
+      "corrupt settings.local.json must surface as action='failed'",
+    );
+    // Sync block still present — failure was non-fatal.
+    assert.ok(json.sync, "sync block must be present after disk error");
+  });
+
+  it("getCliVersion crash recovery: init exits 0 when getCliVersion throws (defensive)", async () => {
+    // QA gap fix (BLOCKING): If the CLI's package.json is corrupt,
+    // getCliVersion throws — but init must not crash. We exercise
+    // the recovery path by stubbing the cli-version module to throw.
+    //
+    // We can't easily mock the import statically, so we use a
+    // dynamic import + property override pattern: import the module,
+    // monkey-patch getCliVersion, run init, restore.
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    // Inject a `getCliVersion` stub via the deps parameter that
+    // throws as if the CLI's package.json were broken. ESM exports
+    // can't be monkey-patched, so deps injection is the only way
+    // to exercise the defensive try/catch.
+    const throwingGetCliVersion = () => {
+      throw new Error("synthetic: package.json missing version");
+    };
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({ exitCode: 0 });
+
+    // Should NOT throw — init's defensive try/catch must catch
+    // the version-read error and continue.
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+      { spawn, getCliVersion: throwingGetCliVersion },
+    );
+
+    const out = stdout.text();
+    assert.match(
+      out,
+      /Could not determine CLI version for global install/,
+      "init must surface the version-read failure with actionable instructions",
+    );
+    assert.match(
+      out,
+      /npm install -g skillrepo/,
+      "fallback message must include manual install hint",
+    );
+    // Spawn must NOT have been called (we never had a version to
+    // pin to).
+    assert.equal(spawn.calls.length, 0);
+    // Init still completed.
+    assert.match(out, /Library is up to date|No skills in library yet/);
+  });
+
+  it("idempotency: re-running init after a successful auto-install does NOT spawn again", async () => {
+    // Simulate the second run: a global skillrepo is already on
+    // PATH from a prior init. resolveGlobalBinary finds it and
+    // init skips the auto-install branch entirely (Branch 4).
+    makeNpxArgv();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+
+    const { installShim } = await import("../helpers/skillrepo-shim.mjs");
+    shimSandbox = mkdtempSync(join(tmpdir(), "sr-init-idempotent-"));
+    shimHandle = installShim(shimSandbox);
+
+    const { makeMockSpawn } = await import("../helpers/mock-spawn.mjs");
+    const spawn = makeMockSpawn({ exitCode: 0 });
+
+    // First run with shim already in place — install branch skipped.
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+      { spawn },
+    );
+    assert.equal(spawn.calls.length, 0, "first run with pre-existing global");
+
+    // Second run — same. Spawn must STILL be 0.
+    const stdout2 = createCaptureStream();
+    const stderr2 = createCaptureStream();
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout: stdout2, stderr: stderr2 },
+      { spawn },
+    );
+    assert.equal(spawn.calls.length, 0, "second run also uses existing global");
+
+    // The hook should be unchanged.
+    const settingsPath = join(
+      process.cwd(),
+      ".claude",
+      "settings.local.json",
+    );
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    // Only one SessionStart group, only one hook in it — no duplicates.
+    assert.equal(settings.hooks.SessionStart.length, 1);
+    assert.equal(settings.hooks.SessionStart[0].hooks.length, 1);
+  });
+});