skillrepo 3.1.1 → 3.1.2

package/src/lib/binary-locator.mjs

@@ -0,0 +1,99 @@
+/**
+ * Cross-platform binary locator with optional transient-runner
+ * filtering (#894 / v3.1.2).
+ *
+ * Wraps `where` (Windows) / `which` (POSIX) to find a named binary
+ * on PATH and returns its absolute path. The two flag knobs
+ * `skipIfTransient` and `filterTransient` were extracted from the
+ * v3.1.2 first cleanup pass: previously two near-identical functions
+ * (`resolveSkillrepoBinary` in `mergers/session-hook.mjs`,
+ * `resolveGlobalBinary` in `lib/global-install.mjs`) duplicated this
+ * logic with the only differences being:
+ *
+ *   - `resolveSkillrepoBinary` had an early-return guard against
+ *     `isNpxInvocation()` (now `isTransientRunnerInvocation`) — the
+ *     `skipIfTransient` flag captures that.
+ *
+ *   - `resolveGlobalBinary` filtered `_npx`-cache results from the
+ *     locator output — the `filterTransient` flag (powered by
+ *     `isTransientCachePath` from `lib/transient-runners.mjs`)
+ *     captures that and extends it to all package runners (pnpm
+ *     dlx, yarn berry dlx, bunx).
+ *
+ * Both flags default to false so the function behaves like a plain
+ * `which`/`where` wrapper unless the caller opts into the extra
+ * semantics.
+ */
+
+import { execFileSync } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { platformConventions } from "./platform.mjs";
+import {
+  isTransientCachePath,
+  isTransientRunnerInvocation,
+} from "./transient-runners.mjs";
+
+/**
+ * Resolve the absolute path of `binaryName` on PATH.
+ *
+ * @param {string} binaryName - The bare command name (e.g.
+ *        `"skillrepo"`). Resolved via the platform's binary locator
+ *        (`which` on POSIX, `where` on Windows).
+ * @param {object} [options]
+ * @param {boolean} [options.skipIfTransient=false] - When true,
+ *        return `null` immediately if the current process is itself
+ *        a transient-runner invocation. Used by callers that bake
+ *        the resolved path into long-lived state (e.g. a SessionStart
+ *        hook command) and must not bind to a transient cache path.
+ * @param {boolean} [options.filterTransient=false] - When true,
+ *        ignore locator output lines that point inside a transient
+ *        runner's cache directory. Used by callers that explicitly
+ *        want a STABLE global install at a non-cache path.
+ * @param {NodeJS.Platform} [options.platform] - Override for tests.
+ *        Production callers leave unset.
+ * @returns {string | null} The absolute path of the first matching
+ *        non-filtered locator output line, or `null` if no match.
+ */
+export function resolveBinaryOnPath(
+  binaryName,
+  { skipIfTransient = false, filterTransient = false, platform: platformOverride } = {},
+) {
+  if (skipIfTransient && isTransientRunnerInvocation()) {
+    return null;
+  }
+
+  const conv = platformConventions({ platform: platformOverride });
+
+  let raw;
+  try {
+    // 3-second cap — `which`/`where` typically return in
+    // milliseconds, but a pathological PATH (network filesystem,
+    // hung shell alias) could otherwise stall the whole CLI.
+    raw = execFileSync(conv.binaryLocator, [binaryName], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    });
+  } catch {
+    // Locator exits non-zero when the binary isn't on PATH, OR
+    // throws ENOENT when the locator itself doesn't exist (rare —
+    // a Windows install missing `where.exe`, or a minimal POSIX
+    // image without `which`). Both collapse to "binary not
+    // resolvable" from the caller's perspective.
+    return null;
+  }
+
+  // Windows `where.exe` returns one match per line; POSIX `which`
+  // returns a single line. Take the first match that survives the
+  // absolute-path and (optional) transient-cache filters.
+  const lines = raw
+    .split(/\r?\n/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+  for (const line of lines) {
+    if (!isAbsolute(line)) continue;
+    if (filterTransient && isTransientCachePath(line)) continue;
+    return line;
+  }
+  return null;
+}

package/src/lib/cli-config.mjs

@@ -1,11 +1,6 @@
 /**
  * Shared credential + flag resolution for command modules.
  *
- * Also houses process-environment helpers that multiple command
- * modules need — specifically `isNpxInvocation()` which several
- * surfaces use to decide whether the user has a stable global
- * install or is running a transient npx download.
- *
  * Every command needs to:
  *   1. Resolve `--key`/`--url`/`--ide`/`--global`/`--json` flags
  *   2. Fall back to ~/.claude/skillrepo/config.json
@@ -13,9 +8,13 @@
  *   4. Hard-error with an actionable hint pointing at `init` if no
  *      key is configured
  *
- * Centralizing this here keeps the four command modules thin and
- * means a future change to credential resolution (e.g., adding a
- * keychain backend) is a single edit instead of four.
+ * Centralizing this here keeps the command modules thin and means
+ * a future change to credential resolution (e.g., adding a keychain
+ * backend) is a single edit instead of N.
+ *
+ * Process-environment helpers for transient package-runner detection
+ * (npx, pnpm dlx, yarn dlx, bunx) live in `lib/transient-runners.mjs`
+ * and `lib/binary-locator.mjs` — import from there directly.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -26,70 +25,6 @@ import { authError, validationError } from "./errors.mjs";
 const VALID_VENDORS = new Set(["claudeCode", "cursor", "windsurf", "vscode"]);
 const VENDOR_ALIASES = { claude: "claudeCode" };
 
-/**
- * True when the current process was launched via `npx skillrepo ...`
- * rather than from a stable global install.
- *
- * Why this matters:
- *
- *   - `npx skillrepo init` downloads the package into `~/.npm/_npx/<hash>/`
- *     and exposes its `.bin/skillrepo` on PATH for the subprocess only.
- *     `execFileSync("which", ["skillrepo"])` DOES find that path, but it
- *     is a transient cache location. npm eviction, a version bump, or
- *     `npm cache clean` later invalidates the absolute path, so any
- *     on-disk reference to it (e.g. a SessionStart hook command baked
- *     in at install time) silently breaks.
- *
- *   - The architect design for #884 explicitly specified that npx
- *     users should skip the session-sync step with a "requires a global
- *     install" warning. The `which`-based resolver in
- *     `mergers/session-hook.mjs` alone is too permissive — it finds the
- *     npx cache path and treats it as stable. This helper closes that
- *     gap by detecting npx unambiguously.
- *
- *   - `init`'s "Next steps" output also needs to know: under npx, the
- *     right hint is `npx skillrepo list` (or "install globally first"),
- *     not bare `skillrepo list` (which would fail for the user).
- *
- * Detection uses two signals, either one sufficient:
- *
- *   1. `process.argv[1]` contains `/_npx/` (or Windows `\_npx\`) —
- *      the primary signal. npx-launched scripts literally live inside
- *      `~/.npm/_npx/<hash>/node_modules/.bin/...` so the executable
- *      path itself names the cache directory. Highest reliability,
- *      no false-positive surface.
- *
- *   2. `process.env._` ends with `/npx` (or `\npx` on Windows) —
- *      legacy fallback for shells that set `_` to the launched
- *      command. Defensive against shim layouts where argv[1] has
- *      been symlinked through a path that doesn't contain `_npx`.
- *
- * Why NOT `process.env.npm_command === "exec"`: this signal was
- * considered but rejected in v3.1.1 review. `npm_command=exec` is
- * also set when a stable-install user runs `skillrepo init` from a
- * `package.json` lifecycle script (e.g. `"postinstall": "skillrepo
- * init --yes"`) or invokes `npm exec skillrepo ...` directly. In
- * those cases the user has a real global install and should NOT
- * have session-sync skipped or see `npx skillrepo` in Next Steps.
- * The argv[1] signal already catches real npx invocations
- * unambiguously; adding npm_command trades a minor coverage gain
- * (shim layouts) for a false-positive surface that affects real
- * users. See v3.1.1 PR review cycle for the full discussion.
- *
- * @returns {boolean}
- */
-export function isNpxInvocation() {
-  const execPath = process.argv[1] ?? "";
-  if (execPath.includes("/_npx/") || execPath.includes("\\_npx\\")) {
-    return true;
-  }
-  const underscore = process.env._ ?? "";
-  if (underscore.endsWith("/npx") || underscore.endsWith("\\npx")) {
-    return true;
-  }
-  return false;
-}
-
 /**
  * @typedef {Object} ResolvedFlags
  * @property {string} serverUrl

package/src/lib/cli-version.mjs

@@ -0,0 +1,56 @@
+/**
+ * Read the running CLI's own version from the package.json that ships
+ * with the tarball.
+ *
+ * Why a dedicated module
+ * ----------------------
+ * v3.1.2's init auto-install feature needs to run
+ * `npm install -g skillrepo@<version>` with the SAME version as the
+ * CLI currently running init. Pinning is what keeps the fresh global
+ * install in lockstep with the npx-cache copy that just executed init,
+ * so there's no silent version drift between the two.
+ *
+ * `process.env.npm_package_version` is NOT reliable here — it's only
+ * set when npm itself spawns the process (e.g. `npm run`), not under
+ * a plain `npx skillrepo ...` or `node ./bin/skillrepo.mjs` run. So
+ * we read the package.json off disk.
+ *
+ * The read is relative to `import.meta.url`, which resolves to this
+ * module's own file URL. From `src/lib/cli-version.mjs`, two levels
+ * up is the package root — the `"files"` array in package.json
+ * includes `bin/` and `src/` alongside the package.json itself, so
+ * the file is always present in the shipped tarball.
+ *
+ * A failed read is a programming error (missing or malformed
+ * package.json in a shipped tarball means the build pipeline broke
+ * invariants). The function throws rather than soft-handling; there
+ * is no meaningful user recovery path.
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * Return the CLI's own semver version as a string (e.g. "3.1.2").
+ *
+ * @returns {string}
+ * @throws {Error} if the package.json cannot be read or parsed, or
+ *         if the `version` field is missing or not a string.
+ */
+export function getCliVersion() {
+  // Resolve `../../package.json` relative to THIS file. This module
+  // lives at `packages/cli/src/lib/cli-version.mjs`, so two `..`
+  // segments land at the package root. Using `import.meta.url` means
+  // the resolution is invariant under tarball/symlink layout — it
+  // always points to where THIS source file actually lives on disk
+  // at runtime.
+  const pkgUrl = new URL("../../package.json", import.meta.url);
+  const raw = readFileSync(pkgUrl, "utf-8");
+  const pkg = JSON.parse(raw);
+  if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+    throw new Error(
+      "cli-version: package.json has no valid `version` string. " +
+        "This indicates a broken build/publish pipeline.",
+    );
+  }
+  return pkg.version;
+}

package/src/lib/global-install.mjs

@@ -0,0 +1,387 @@
+/**
+ * `npm install -g skillrepo@<version>` wrapper for v3.1.2 init's
+ * auto-install-global feature (#894).
+ *
+ * Why this exists
+ * ---------------
+ * Under `npx skillrepo init`, the v3.1.0/v3.1.1 SessionStart hook
+ * design fails because the npx cache path is transient and unsuitable
+ * for a long-lived hook command. v3.1.1 worked around this by
+ * skipping the hook with a "install globally first" warning — the
+ * prompt-then-fail UX bug that v3.1.2 fixes.
+ *
+ * v3.1.2 fixes it by having init OFFER to run the global install
+ * itself when invoked under npx. This module is the spawn wrapper
+ * that runs `npm install -g skillrepo@<version>` and reports a
+ * structured result.
+ *
+ * Design constraints
+ * ------------------
+ *   1. **No new runtime dependencies.** The CLI's only dep is
+ *      `cli-table3`. This module uses Node built-ins (`child_process`,
+ *      `path`) only.
+ *
+ *   2. **Spawn is injectable.** Tests pass a stub spawn so they
+ *      never actually shell out to npm. Production callers leave
+ *      `spawn` unset and get the real `child_process.spawn`.
+ *
+ *   3. **Cross-platform spawn shape.** On Windows, `npm` is a
+ *      `.cmd` script, not a native binary. `spawn("npm", ...)` on
+ *      Windows without `shell: true` throws ENOENT. The locator
+ *      name comes from `platformConventions()` so we don't sprinkle
+ *      `process.platform === "win32"` checks across the codebase.
+ *      We use `shell: false` on both platforms — it sidesteps the
+ *      argument-quoting surprises `shell: true` introduces on Windows
+ *      and is unnecessary because we control all spawn args.
+ *
+ *   4. **`stdio` mode is caller-controlled.** Default is `inherit`
+ *      so npm's progress output streams to the user's terminal during
+ *      the install (the install can take 10-30 seconds — silent would
+ *      look hung). `--json` mode passes `outputMode: "silent"` to
+ *      suppress npm output that would otherwise pollute the JSON
+ *      stdout.
+ *
+ *   5. **Always returns a result, never throws on user-recoverable
+ *      failure.** Init must continue past auto-install failures —
+ *      the rest of init (config, MCP, first sync) succeeded and the
+ *      user's library is on disk. Throwing here would abort init.
+ *      Programmer errors (e.g. missing version arg) DO throw.
+ *
+ *   6. **5-minute timeout.** Slow registries and corporate proxies
+ *      can take longer than the typical 10-30 seconds. 5 minutes is
+ *      well past any reasonable network worst-case but bounds the
+ *      hang time so init can never wait forever.
+ *
+ *   7. **Verify success post-install.** A 0 exit code from npm is
+ *      necessary but not sufficient — the user's npm prefix bin
+ *      directory might not be on PATH (a common nvm misconfiguration).
+ *      We re-resolve the binary via `where`/`which`, filtering out
+ *      `_npx` cache paths, to confirm the install actually produced
+ *      a usable binary at a stable location.
+ *
+ * Result enum
+ * -----------
+ *   - `success: true` — npm exited 0 AND the resulting binary is at
+ *     a stable absolute path. `binaryPath` is set.
+ *   - `errorCode: "eacces"` — permission denied on the npm prefix.
+ *     User needs sudo (or to fix npm prefix). `error` carries the
+ *     actionable message.
+ *   - `errorCode: "enoent-npm"` — `npm` itself not found on PATH.
+ *     User needs to install Node or fix PATH.
+ *   - `errorCode: "npm-nonzero"` — npm ran but exited non-zero for
+ *     some other reason (network, registry 500, package not found).
+ *     `error` includes the first ~200 chars of stderr.
+ *   - `errorCode: "timeout"` — exceeded the 5-minute deadline. We
+ *     killed the child.
+ *   - `errorCode: "path-not-updated"` — npm exited 0 but the binary
+ *     isn't on PATH at a stable location. Either the install actually
+ *     failed silently or the user's npm prefix bin dir isn't on PATH.
+ */
+
+import { spawn as defaultSpawn } from "node:child_process";
+import { platformConventions } from "./platform.mjs";
+import { resolveBinaryOnPath } from "./binary-locator.mjs";
+
+/**
+ * @typedef {Object} GlobalInstallResult
+ * @property {boolean} success
+ * @property {string | null} binaryPath - Absolute path to the resulting
+ *           global `skillrepo` binary on success; null on failure.
+ * @property {string} [error] - Human-readable failure reason. Set
+ *           when `success` is false.
+ * @property {"eacces" | "enoent-npm" | "npm-nonzero" | "timeout" | "path-not-updated"} [errorCode]
+ *           Categorized failure code. Set when `success` is false.
+ */
+
+/**
+ * Default timeout for `npm install -g`. 5 minutes covers the worst
+ * case of slow registries, corporate proxies, or first-time cache
+ * population without letting init hang indefinitely.
+ */
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Run `npm install -g skillrepo@<version>` and return a structured
+ * result. Never throws on user-recoverable failure (npm exit codes,
+ * permission errors, missing npm) — those are reported via the
+ * `errorCode` field. Programmer errors (missing args) DO throw.
+ *
+ * @param {object} options
+ * @param {string} options.version - Semver string to pin
+ *        (e.g. "3.1.2"). Required.
+ * @param {"inherit" | "silent"} [options.outputMode="inherit"] -
+ *        How to handle npm's stdout/stderr.
+ *          - "inherit": stream npm output through this process's
+ *            stdio (the user sees install progress in real time).
+ *          - "silent": capture and discard. Used in `--json` mode
+ *            so npm output doesn't pollute the JSON stdout.
+ * @param {Function} [options.spawn] - Injected for tests. Defaults
+ *        to the real `child_process.spawn`. Tests pass a stub so the
+ *        suite never actually shells out to npm.
+ * @param {NodeJS.Platform} [options.platform] - Override for tests
+ *        that need to exercise Windows spawn semantics on a non-Windows
+ *        host. Production callers leave this unset.
+ * @param {number} [options.timeoutMs=300000] - Maximum time to wait
+ *        before killing the child and returning `errorCode: "timeout"`.
+ * @returns {Promise<GlobalInstallResult>}
+ */
+export async function installSkillrepoGlobally({
+  version,
+  outputMode = "inherit",
+  spawn = defaultSpawn,
+  platform: platformOverride,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  if (typeof version !== "string" || version.length === 0) {
+    // Programmer error — no recovery, throw.
+    throw new Error(
+      "installSkillrepoGlobally: `version` must be a non-empty string.",
+    );
+  }
+
+  const conv = platformConventions({ platform: platformOverride });
+  // Windows `npm` ships as `npm.cmd` — a batch script. spawn() with
+  // `shell: false` requires the literal name on disk, which is
+  // `npm.cmd` on Windows and `npm` everywhere else. Same pattern as
+  // `binaryLocator` ("which" vs "where").
+  const npmCmd = conv.family === "windows" ? "npm.cmd" : "npm";
+  const args = ["install", "-g", `skillrepo@${version}`];
+
+  // stdio mapping:
+  //   - inherit: npm output streams to user's terminal in real time.
+  //   - silent (--json mode): pipe stdout/stderr so we can capture
+  //     them for error categorization, but don't let them touch the
+  //     terminal. The captured stderr is useful for the
+  //     "first 200 chars of stderr" failure message.
+  const stdio = outputMode === "silent"
+    ? ["ignore", "pipe", "pipe"]
+    : "inherit";
+
+  // ── Spawn the child ─────────────────────────────────────────────
+  // We use `shell: false` (the spawn default) on both platforms.
+  // shell: true on Windows introduces argument-quoting surprises
+  // (cmd.exe quoting rules differ from POSIX shells in subtle ways);
+  // we control all args, so we don't need shell expansion.
+  let child;
+  try {
+    child = spawn(npmCmd, args, { stdio });
+  } catch (err) {
+    // Synchronous spawn failure (rare; some Node versions surface
+    // ENOENT this way instead of via the `error` event). Treat
+    // identically to the async ENOENT path.
+    if (err && err.code === "ENOENT") {
+      return {
+        success: false,
+        binaryPath: null,
+        errorCode: "enoent-npm",
+        error:
+          "`npm` was not found on PATH. Install Node.js " +
+          "(which bundles npm) or ensure npm is on your PATH, " +
+          "then re-run init.",
+      };
+    }
+    // Any other synchronous spawn failure is unexpected — surface
+    // as npm-nonzero with the message.
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "npm-nonzero",
+      error: `Failed to spawn npm: ${err?.message ?? String(err)}`,
+    };
+  }
+
+  // ── Capture output (silent mode) ───────────────────────────────
+  // Buffer stderr for failure-message extraction. stdout is captured
+  // too in case we need it later, but we don't currently use it.
+  let stderrChunks = [];
+  if (outputMode === "silent") {
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    }
+    if (child.stdout) {
+      // Drain to prevent backpressure; we don't actually need the
+      // content. Discarding is the goal of silent mode.
+      child.stdout.on("data", () => {});
+    }
+  }
+
+  // ── Wait for completion or timeout ─────────────────────────────
+  const result = await new Promise((resolve) => {
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => {
+      // The `kill()` may not immediately stop a child that's
+      // doing network I/O on a slow socket. We don't await child
+      // exit after kill — the timeout result is what we report;
+      // the OS reaps the child whenever it actually exits.
+      try {
+        child.kill();
+      } catch {
+        // Already exited — fine.
+      }
+      settle({ kind: "timeout" });
+    }, timeoutMs);
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      // Async spawn errors. ENOENT here means `npm` not on PATH.
+      if (err && err.code === "ENOENT") {
+        settle({ kind: "enoent-npm" });
+        return;
+      }
+      // EACCES at spawn time (rare, usually surfaces in npm output
+      // instead). Treat as npm-nonzero with the error message.
+      settle({ kind: "spawn-error", message: err?.message ?? String(err) });
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      settle({ kind: "exit", code });
+    });
+  });
+
+  if (result.kind === "timeout") {
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "timeout",
+      error:
+        `npm install -g skillrepo@${version} did not complete within ` +
+        `${Math.round(timeoutMs / 1000)} seconds. Check your network ` +
+        "connection or npm registry status, then re-run init.",
+    };
+  }
+
+  if (result.kind === "enoent-npm") {
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "enoent-npm",
+      error:
+        "`npm` was not found on PATH. Install Node.js " +
+        "(which bundles npm) or ensure npm is on your PATH, " +
+        "then re-run init.",
+    };
+  }
+
+  if (result.kind === "spawn-error") {
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "npm-nonzero",
+      error: `Failed to run npm: ${result.message}`,
+    };
+  }
+
+  // result.kind === "exit"
+  const exitCode = result.code;
+  // Only build the stderr string when we actually captured it
+  // (silent mode). In inherit mode, `stderrChunks` is always empty
+  // because the stream wasn't piped to us.
+  const stderrText =
+    outputMode === "silent"
+      ? Buffer.concat(stderrChunks).toString("utf-8")
+      : "";
+
+  if (exitCode !== 0) {
+    // EACCES is a common case worth distinguishing — the actionable
+    // remediation differs (sudo or fix prefix vs check the npm
+    // output). We have two signals available:
+    //   1. stderr text contains "EACCES" — only available in silent
+    //      mode (`--json`) where we capture stderr.
+    //   2. exit code 243 — npm's exit code for EACCES on POSIX.
+    //      Documented in npm's source as the dedicated permission-
+    //      error code. Available in BOTH inherit and silent modes
+    //      because exit code is always observable.
+    // Trying both gives the user a categorized error in both modes.
+    if (stderrText.includes("EACCES") || exitCode === 243) {
+      return {
+        success: false,
+        binaryPath: null,
+        errorCode: "eacces",
+        error:
+          "npm reported a permissions error (EACCES). Run with sudo " +
+          "or fix npm's prefix to a writable location: " +
+          "https://docs.npmjs.com/resolving-eacces-permissions-errors",
+      };
+    }
+    // Generic npm failure. In silent mode (--json) we have stderr
+    // text and include the first 200 chars for diagnosis. In inherit
+    // mode the user already saw npm's real output stream past, so
+    // we add a short hint pointing at the two most common
+    // remediations (permissions, network) without trying to guess
+    // which applies.
+    const trimmedStderr =
+      stderrText.length > 0 ? ` ${stderrText.slice(0, 200).trim()}` : "";
+    const inheritHint =
+      stderrText.length === 0
+        ? " Common causes: permissions (try sudo, or fix npm's prefix) " +
+          "or network/registry issues (check your internet connection)."
+        : "";
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "npm-nonzero",
+      error: `npm install -g exited with code ${exitCode}.${trimmedStderr}${inheritHint}`,
+    };
+  }
+
+  // ── Verify the install actually produced a usable binary ──────
+  const binaryPath = resolveGlobalBinary({ platform: platformOverride });
+  if (!binaryPath) {
+    const isWindows = conv.family === "windows";
+    // Windows-specific addendum: PATH changes from `npm install -g`
+    // are NOT visible in the current terminal session — the user
+    // has to open a new terminal for the change to propagate. POSIX
+    // shells inherit the new PATH naturally because npm writes to
+    // a directory the user's shell already has on PATH.
+    const platformAddendum = isWindows
+      ? " On Windows, `npm install -g` does not refresh PATH in the " +
+        "current terminal. Open a new PowerShell or cmd.exe window, " +
+        "then run `skillrepo session-sync enable`."
+      : "";
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "path-not-updated",
+      error:
+        "npm install -g succeeded but `skillrepo` was not found on " +
+        "PATH. Your npm prefix bin directory may not be on PATH. " +
+        "Run `npm config get prefix` and add `<prefix>/bin` to PATH, " +
+        "then run `skillrepo session-sync enable`." +
+        platformAddendum,
+    };
+  }
+
+  return {
+    success: true,
+    binaryPath,
+  };
+}
+
+/**
+ * Resolve the absolute path of a STABLE (non-cache) `skillrepo`
+ * binary on PATH. Used after `npm install -g` to confirm the install
+ * produced a usable binary at a path safe to bake into the
+ * SessionStart hook command.
+ *
+ * Thin wrapper over `resolveBinaryOnPath` with `filterTransient: true`
+ * preset. The `skipIfTransient` flag is intentionally false — we
+ * WANT to find the newly-installed global even when we're running
+ * under a transient runner ourselves.
+ *
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform] - Override for tests.
+ * @returns {string | null}
+ */
+export function resolveGlobalBinary({ platform: platformOverride } = {}) {
+  return resolveBinaryOnPath("skillrepo", {
+    filterTransient: true,
+    platform: platformOverride,
+  });
+}

package/src/lib/mcp-merge.mjs

@@ -75,16 +75,27 @@ import { validationError } from "./errors.mjs";
  * @param {object} [options.io] - Injected streams for testability
  * @param {NodeJS.WritableStream} [options.io.stdout=process.stdout]
  * @param {NodeJS.WritableStream} [options.io.stderr=process.stderr]
- * @param {(prompt: string, defaultYes?: boolean) => Promise<boolean>} [options.confirmFn]
+ * @param {object} [options.deps] - Test-only dependency injection.
+ *        Production callers leave this empty. Standardized name
+ *        across CLI commands (init, init-session-sync, etc.) so all
+ *        injection points live under a single `deps` namespace.
+ * @param {(prompt: string, defaultYes?: boolean) => Promise<boolean>} [options.deps.confirmFn]
  *        Optional injection point for the y/n prompt. Defaults to
  *        the real `confirm` from prompt.mjs. Tests pass a stub to
- *        avoid spawning a readline interface. This dependency is
- *        injected rather than monkey-patched because ESM module
- *        exports are frozen and cannot be reassigned.
+ *        avoid spawning a readline interface. ESM module exports
+ *        are frozen and cannot be reassigned, so dependency
+ *        injection is the only clean way to substitute.
  * @returns {Promise<McpMergeResult[]>}
  */
 export async function mergeMcpForVendors(options) {
-  const { vendors, mcpUrl, yes = false, io = {}, confirmFn = realConfirm } = options;
+  const {
+    vendors,
+    mcpUrl,
+    yes = false,
+    io = {},
+    deps = {},
+  } = options;
+  const confirmFn = deps.confirmFn ?? realConfirm;
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;