skillrepo 3.1.1 → 3.1.3

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

@@ -25,6 +25,7 @@ import {
   setSandboxHome,
   restoreHome,
 } from "../helpers/sandbox-home.mjs";
+import { isolatePathEnv } from "../helpers/path-isolation.mjs";
 
 let sandbox;
 let server;
@@ -890,8 +891,16 @@ describe("runInit — v3.1.1 Next steps prefix (bug 1)", () => {
     ];
 
     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"],
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
       { stdout, stderr },
     );
 
@@ -907,4 +916,674 @@ describe("runInit — v3.1.1 Next steps prefix (bug 1)", () => {
       "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:
+  //   - We control isTransientRunnerInvocation()'s output via
+  //     process.argv[1] and process.env._.
+  //   - We CLEAR PATH so resolveGlobalBinary() genuinely returns
+  //     null (otherwise the developer's locally-installed `skillrepo`
+  //     makes Branch 4 fire when the test expects Branch 6). This
+  //     matters even more in v3.1.3+ which scans PATH directly in
+  //     Node — any pre-existing skillrepo on the dev's PATH would
+  //     be visible to the locator.
+  // Tests that DO want a "global on PATH" scenario explicitly install
+  // a shim via `installShim` in their body (see Branch 4 + idempotency
+  // tests below); the shim helper prepends its own bin dir to PATH
+  // so it survives the cleared baseline.
+  let originalArgv;
+  let originalUnderscore;
+  let originalNpmCommand;
+  let restorePath;
+  let shimSandbox;
+  let shimHandle;
+
+  beforeEach(async () => {
+    await setup();
+    originalArgv = process.argv;
+    originalUnderscore = process.env._;
+    originalNpmCommand = process.env.npm_command;
+    restorePath = isolatePathEnv();
+    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 });
+    // Restore PATH last (after uninstallShim, which restores PATH
+    // to its pre-shim state — usually our cleared baseline). The
+    // outer restore puts the dev's real PATH back for the next
+    // test suite.
+    restorePath();
+    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);
+  });
 });