skillrepo 3.1.1 → 3.1.2

package/src/lib/mergers/session-hook.mjs

@@ -70,8 +70,6 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { execFileSync } from "node:child_process";
-import { isAbsolute } from "node:path";
 import { writeFileAtomic } from "../fs-utils.mjs";
 import { SESSION_HOOK_FINGERPRINT } from "../artifact-registry.mjs";
 import {
@@ -80,7 +78,7 @@ import {
 } from "../paths.mjs";
 import { diskError, validationError } from "../errors.mjs";
 import { removeSettingsSessionHook } from "../removers/settings.mjs";
-import { isNpxInvocation } from "../cli-config.mjs";
+import { resolveBinaryOnPath } from "../binary-locator.mjs";
 import { platformConventions } from "../platform.mjs";
 
 /**
@@ -90,15 +88,31 @@ import { platformConventions } from "../platform.mjs";
  * Shell shape is platform-specific — see `platform.mjs` for the full
  * rationale. Summary:
  *
- *   - **POSIX** (macOS, Linux): `<path> update --session-hook 2>&1 || true`.
+ *   - **POSIX** (macOS, Linux): `'<path>' update --session-hook 2>&1 || true`.
  *     `|| true` catches any non-zero exit at the shell level; primary
  *     defense is the `--session-hook` flag contract in the Node process.
- *   - **Windows** (cmd.exe / PowerShell): `<path> update --session-hook 2>&1`.
+ *   - **Windows** (cmd.exe / PowerShell): `"<path>" update --session-hook 2>&1`.
  *     `|| true` omitted because cmd.exe doesn't know the `true` builtin.
  *     `--session-hook` contract is the only defense; consequences of
  *     binary-vanished scenarios are slightly noisier in Claude Code's
  *     session log but still non-blocking.
  *
+ * Path quoting is mandatory: real-world install paths contain spaces
+ * (`C:\Program Files\nodejs\skillrepo.cmd`, `/Users/First Last/.npm-global/bin/skillrepo`)
+ * and parentheses (`C:\Program Files (x86)\...`). An unquoted path
+ * makes the shell parse the command as multiple arguments and the
+ * hook silently fails on session start.
+ *
+ * The fingerprint constant (`SESSION_HOOK_FINGERPRINT` =
+ * ` update --session-hook` with leading space) MUST appear in the
+ * resulting command for the uninstaller and idempotency walks to
+ * find it. Single/double quotes don't break the fingerprint because
+ * the leading space sits between the closing quote and `update`.
+ * Backward-compat: existing v3.1.0/v3.1.1 hooks with unquoted paths
+ * also match the fingerprint (the space sits between the path and
+ * `update`), so re-running init detects them and updates in place
+ * to the new quoted shape.
+ *
  * The suffix is supplied by `platformConventions().hookShellSuffix` —
  * this function doesn't know which OS it's targeting, it just
  * concatenates the convention's suffix.
@@ -116,69 +130,57 @@ export function buildHookCommand(binaryPath, { platform: platformOverride } = {}
     );
   }
   const conv = platformConventions({ platform: platformOverride });
-  return `${binaryPath} update --session-hook 2>&1${conv.hookShellSuffix}`;
+  const quotedPath = quoteShellPath(binaryPath, conv.family);
+  return `${quotedPath} update --session-hook 2>&1${conv.hookShellSuffix}`;
 }
 
 /**
- * Resolve the absolute path of the `skillrepo` binary via `which`.
- * Returns null if resolution fails (e.g. user ran `npx skillrepo init`
- * without a global install) — the caller should skip hook installation
- * with a clear warning rather than fail init.
+ * Quote a filesystem path for inclusion in a shell command, using the
+ * conventions of the target shell family.
  *
- * @returns {string | null}
+ *   - **POSIX**: wrap in single quotes; escape any embedded single
+ *     quote with the standard `'\''` trick (close quote, escaped
+ *     literal quote, reopen quote). Single quotes suppress ALL shell
+ *     interpretation, so spaces, `$`, `*`, parens, double quotes,
+ *     backticks, and backslashes pass through verbatim.
+ *
+ *   - **Windows** (cmd.exe): wrap in double quotes; escape any
+ *     embedded double quote with `\"`. Backslashes inside the path
+ *     pass through unchanged (cmd.exe does not interpret backslashes
+ *     as escapes inside double quotes). Filesystem rules forbid
+ *     literal `"` in NTFS path components, so the `\"` escape is
+ *     defensive — paths in the wild won't contain it.
+ *
+ * @param {string} path
+ * @param {"posix" | "windows"} family
+ * @returns {string} The quoted path, ready to be interpolated into
+ *          a shell command.
  */
-export function resolveSkillrepoBinary({ platform: platformOverride } = {}) {
-  // npx-invocation guard. Returns null early before any OS-specific
-  // logic runs — npx detection is platform-neutral (argv and env
-  // checks only) so it doesn't need the conventions object.
-  if (isNpxInvocation()) {
-    return null;
+function quoteShellPath(path, family) {
+  if (family === "windows") {
+    return `"${path.replace(/"/g, '\\"')}"`;
   }
+  // POSIX
+  return `'${path.replace(/'/g, "'\\''")}'`;
+}
 
-  // Platform-specific binary locator name comes from the single
-  // source of truth in platform.mjs. Adding a new locator for a
-  // new platform is one edit in platform.mjs, not a scattered
-  // search for `platform() === "win32"` conditionals. See
-  // platform.mjs for the full rationale.
-  const conv = platformConventions({ platform: platformOverride });
-
-  try {
-    // 3-second timeout — `which`/`where` typically return in
-    // milliseconds, but a PATH that includes a network filesystem
-    // or a shell alias that does I/O could hang indefinitely.
-    // Bounding the call ensures `skillrepo init` never stalls on
-    // binary resolution.
-    const raw = execFileSync(conv.binaryLocator, ["skillrepo"], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 3000,
-    });
-    // Windows `where` can return multiple matching paths (one per
-    // PATH entry containing the binary) on separate lines. Take
-    // only the first. `which` always returns a single path but the
-    // split is harmless there. This is the one line where the
-    // platform difference actually leaks through — all platforms
-    // receive potentially-multi-line output that we canonicalize
-    // the same way.
-    const result = raw.split(/\r?\n/)[0].trim();
-    if (!result) return null;
-    // Sanity: the resolved path must be absolute. A relative
-    // result would be meaningless at session-start time because
-    // the Claude Code hook runner's cwd is undefined. `isAbsolute`
-    // handles both POSIX (`/foo/bar`) and Windows (`C:\foo\bar`)
-    // path styles — it's Node's built-in cross-platform check,
-    // not a platform-conditional we need to own.
-    if (!isAbsolute(result)) return null;
-    return result;
-  } catch {
-    // Locator exits non-zero if the binary isn't on PATH, or throws
-    // ENOENT if the locator itself isn't available (e.g. a minimal
-    // container image without `which`, or a Windows system with
-    // `where.exe` missing which is effectively never — but still
-    // safe-handled). Either way: null → caller routes to the
-    // architect-specified "requires stable install" skip message.
-    return null;
-  }
+/**
+ * Resolve the absolute path of the `skillrepo` binary on PATH,
+ * skipping resolution entirely when the current process is itself
+ * a transient-runner invocation (npx, pnpx, yarn dlx, bunx) — those
+ * cache paths must not be baked into the long-lived hook command.
+ *
+ * Thin wrapper over `resolveBinaryOnPath` with the
+ * `skipIfTransient` flag preset. Kept as a named export for
+ * call-site readability and so existing tests keep working.
+ *
+ * @returns {string | null}
+ */
+export function resolveSkillrepoBinary({ platform: platformOverride } = {}) {
+  return resolveBinaryOnPath("skillrepo", {
+    skipIfTransient: true,
+    platform: platformOverride,
+  });
 }
 
 /**
@@ -237,18 +239,28 @@ export function mergeSessionHook({
     //   2. `which skillrepo` returned nothing — no global install
     //      exists at all.
     // Both are the same problem from the hook's perspective: we
-    // can't produce a command that will still work later. The
-    // architect's #884 design specified the same warning text for
-    // both cases.
+    // can't produce a command that will still work later.
+    //
+    // v3.1.2 (#894): `init` bypasses this path under npx by running
+    // `npm install -g skillrepo@<version>` itself and then calling
+    // `mergeSessionHook` with the resulting `binaryPath` explicitly.
+    // The remaining callers that hit this branch are:
+    //   - `skillrepo session-sync enable` invoked under npx (does
+    //     not auto-install — a deliberate, explicit user invocation
+    //     should not silently mutate global package state).
+    //   - The rare bare-install case where `which skillrepo` fails
+    //     even though we're not under npx (PATH misconfiguration).
+    //
+    // Both cases get the same actionable hint pointing the user at
+    // `skillrepo init`, which DOES auto-install under npx.
     return {
       path: displayPath,
       action: "skipped",
       reason:
         "Session sync requires a stable `skillrepo` binary on PATH. " +
-        "Under `npx skillrepo ...` or without a global install, the " +
-        "hook would bind to a transient path that eventually breaks. " +
-        "Install globally with `npm install -g skillrepo` and re-run " +
-        "`skillrepo session-sync enable`.",
+        "Run `npm install -g skillrepo` (or use `skillrepo init`, " +
+        "which offers to install globally for you under npx), then " +
+        "re-run `skillrepo session-sync enable`.",
     };
   }
 

package/src/lib/transient-runners.mjs

@@ -0,0 +1,204 @@
+/**
+ * Transient package-runner detection (#894 / v3.1.2).
+ *
+ * The CLI cares about transient package runners — npx, pnpm dlx,
+ * yarn berry dlx, bunx — in two distinct ways:
+ *
+ *   1. **Detect when the current process IS a transient invocation**
+ *      (`detectTransientRunner` / `isTransientRunnerInvocation`).
+ *      Used by `init` to gate the auto-install-global flow and to
+ *      pick the right runner-prefix in Next-Steps output, and by
+ *      `mergers/session-hook` to refuse baking a transient cache
+ *      path into a long-lived hook command.
+ *
+ *   2. **Detect when a candidate filesystem path is INSIDE a runner's
+ *      transient cache** (`isTransientCachePath`). Used by the binary
+ *      locator (`lib/binary-locator.mjs`) to filter `where`/`which`
+ *      output so a cache-located binary doesn't shadow a real global
+ *      install.
+ *
+ * The substring patterns for each runner's cache are the same data
+ * for both use cases; centralizing here is the single-source-of-truth
+ * fix for the duplication that existed in v3.1.2's first cleanup
+ * pass (cli-config.mjs and global-install.mjs each carried their own
+ * frozen array of the same substrings).
+ *
+ * ## Adding a new runner
+ *
+ * Add an entry to `TRANSIENT_RUNNERS` with:
+ *   - `name`: the canonical runner-command string used in Next-Steps
+ *     output (e.g. `"npx"`, `"pnpx"`, `"yarn dlx"`, `"bunx"`).
+ *   - `cacheSubstrings`: substrings (POSIX and Windows separator
+ *     variants) that uniquely identify the runner's per-invocation
+ *     cache directory inside an absolute path. Both `argv[1]`-style
+ *     paths and `where`/`which` output paths are matched against
+ *     this list.
+ *   - `commandSuffixes`: launcher-binary names that, when set as
+ *     `process.env._` (the shell's "last command" var), uniquely
+ *     identify this runner. Suffix-matched. Empty array if the
+ *     runner has no canonical `_` form (e.g. `yarn dlx` with a
+ *     space — `_` only gets the binary name, not the full command).
+ */
+
+/**
+ * @typedef {Object} TransientRunner
+ * @property {string} name - Display name used in user-facing output
+ *           (also the prefix for `<name> skillrepo list` next-step
+ *           hints).
+ * @property {readonly string[]} cacheSubstrings - Path substrings
+ *           that uniquely identify the runner's cache directory.
+ * @property {readonly string[]} commandSuffixes - `_` env-var
+ *           suffix patterns matching the launcher binary name.
+ * @property {string} globalInstallCommand - The canonical "install
+ *           skillrepo globally with this package manager" command
+ *           we suggest to a user who just ran via this runner.
+ *           Used by init's Next-Steps Tip when no global is yet
+ *           active. Yarn berry uses `npm install -g` because yarn
+ *           berry intentionally has no `yarn global add` equivalent
+ *           (it directs users to `dlx` for one-offs and away from
+ *           globals); npm-installed binaries land on the user's
+ *           PATH the same regardless of which runner they used to
+ *           bootstrap.
+ */
+
+/**
+ * Catalog of supported transient runners. Order matters only for
+ * tie-breaking when multiple runners' substrings match the same
+ * path (extremely unlikely given the specificity of each); the
+ * first match wins.
+ */
+export const TRANSIENT_RUNNERS = Object.freeze([
+  Object.freeze({
+    name: "npx",
+    // npx writes to `~/.npm/_npx/<hash>/...`.
+    cacheSubstrings: Object.freeze(["/_npx/", "\\_npx\\"]),
+    commandSuffixes: Object.freeze(["/npx", "\\npx"]),
+    globalInstallCommand: "npm install -g skillrepo",
+  }),
+  Object.freeze({
+    name: "pnpx",
+    // pnpm dlx writes to `<store>/dlx-<hash>/...`. Both pnpm dlx
+    // and the legacy `pnpx` shim hit this cache.
+    cacheSubstrings: Object.freeze(["/dlx-", "\\dlx-"]),
+    commandSuffixes: Object.freeze(["/pnpx", "\\pnpx"]),
+    globalInstallCommand: "pnpm add -g skillrepo",
+  }),
+  Object.freeze({
+    name: "yarn dlx",
+    // yarn berry dlx caches under `.yarn/berry/cache/...` and
+    // resolves PnP virtuals under `.yarn/$$virtual/...`. The
+    // launcher is `yarn dlx <pkg>` which sets `_` to `yarn`, NOT
+    // `yarn dlx` — so commandSuffixes is empty; argv-path detection
+    // is the only signal.
+    cacheSubstrings: Object.freeze([
+      "/.yarn/berry/",
+      "\\.yarn\\berry\\",
+      "/.yarn/$$virtual/",
+      "\\.yarn\\$$virtual\\",
+    ]),
+    commandSuffixes: Object.freeze([]),
+    // Yarn berry deliberately doesn't ship a `yarn global add`
+    // (the team directs users away from globals toward `yarn dlx`
+    // for one-offs). For users who DO want a persistent global,
+    // `npm install -g` is the universal fallback that works
+    // alongside yarn berry without conflict.
+    globalInstallCommand: "npm install -g skillrepo",
+  }),
+  Object.freeze({
+    name: "bunx",
+    cacheSubstrings: Object.freeze([
+      "/.bun/install/cache/",
+      "\\.bun\\install\\cache\\",
+    ]),
+    commandSuffixes: Object.freeze(["/bunx", "\\bunx"]),
+    globalInstallCommand: "bun add -g skillrepo",
+  }),
+]);
+
+/**
+ * Look up the canonical global-install command for a runner display
+ * name (as returned by `detectTransientRunner`). Returns null when
+ * the name doesn't match any registered runner — caller should fall
+ * back to the universal `npm install -g skillrepo` text.
+ *
+ * @param {string | null} runnerName
+ * @returns {string | null}
+ */
+export function globalInstallCommandFor(runnerName) {
+  if (!runnerName) return null;
+  const runner = TRANSIENT_RUNNERS.find((r) => r.name === runnerName);
+  return runner ? runner.globalInstallCommand : null;
+}
+
+/**
+ * Identify the transient runner that launched the current process,
+ * if any.
+ *
+ * Detection signals (first match wins):
+ *   1. `process.argv[1]` contains one of the runner's
+ *      `cacheSubstrings`. The executable's path itself names the
+ *      runner's cache directory.
+ *   2. `process.env._` ends with one of the runner's
+ *      `commandSuffixes`. Defensive against shim layouts where
+ *      `argv[1]` has been symlinked through a path that doesn't
+ *      contain the cache substring.
+ *
+ * Why NOT `process.env.npm_command === "exec"`: that signal also
+ * fires for stable-install users running `npm exec skillrepo ...`
+ * directly or via a `package.json` lifecycle script. Adding it
+ * trades a minor coverage gain for a real false-positive surface
+ * affecting users with a real global install.
+ *
+ * @param {object} [options]
+ * @param {string[]} [options.argv=process.argv] - Test override.
+ * @param {NodeJS.ProcessEnv} [options.env=process.env] - Test override.
+ * @returns {string | null} The runner's display name, or `null` if
+ *          the process is NOT a transient invocation.
+ */
+export function detectTransientRunner({
+  argv = process.argv,
+  env = process.env,
+} = {}) {
+  const execPath = argv[1] ?? "";
+  for (const runner of TRANSIENT_RUNNERS) {
+    for (const substring of runner.cacheSubstrings) {
+      if (execPath.includes(substring)) return runner.name;
+    }
+  }
+  const underscore = env._ ?? "";
+  for (const runner of TRANSIENT_RUNNERS) {
+    for (const suffix of runner.commandSuffixes) {
+      if (underscore.endsWith(suffix)) return runner.name;
+    }
+  }
+  return null;
+}
+
+/**
+ * Boolean shortcut over `detectTransientRunner`. Use when a caller
+ * only needs to know "is this a transient invocation at all?" and
+ * doesn't care which runner.
+ *
+ * @returns {boolean}
+ */
+export function isTransientRunnerInvocation() {
+  return detectTransientRunner() !== null;
+}
+
+/**
+ * True when `absPath` is inside any registered runner's transient
+ * cache directory. Used by the binary locator to filter
+ * `where`/`which` output so a cache-located binary doesn't get
+ * baked into a long-lived hook command.
+ *
+ * @param {string} absPath - An absolute filesystem path.
+ * @returns {boolean}
+ */
+export function isTransientCachePath(absPath) {
+  for (const runner of TRANSIENT_RUNNERS) {
+    for (const substring of runner.cacheSubstrings) {
+      if (absPath.includes(substring)) return true;
+    }
+  }
+  return false;
+}