skillrepo 3.1.0 → 3.1.2

package/src/commands/session-sync-actions.mjs

@@ -0,0 +1,92 @@
+/**
+ * Single source of truth for the `sessionSync.action` enum surfaced
+ * by `skillrepo init` (#894 / v3.1.2).
+ *
+ * The enum appears in three places that MUST stay in sync:
+ *   - the `--json` output's `sessionSync.action` field (consumer
+ *     contract for CI scripts and programmatic callers)
+ *   - the human-readable summary at the end of init
+ *   - the README's `init` flag table
+ *
+ * Before this module existed, the values were declared inline in a
+ * JSDoc comment block and re-typed as string literals at every
+ * assignment site — drift risk. Centralizing here means adding a
+ * new value is one edit (this file + the consumer that needs it),
+ * not a grep-and-pray pass across init.mjs.
+ *
+ * The enum is `Object.freeze`d so callers can't mutate it. JS
+ * doesn't have first-class enums; this is the standard idiom.
+ */
+
+/**
+ * @typedef {"installed" | "updated" | "unchanged" | "opted-out" | "declined" | "not-applicable" | "skipped" | "failed"} SessionSyncActionValue
+ */
+
+/**
+ * Action enum constants. Use these instead of string literals at
+ * assignment sites. Values:
+ *
+ *   - `Installed`     — fresh hook write
+ *   - `Updated`       — existing hook found, command differed,
+ *                       replaced in place (e.g. binary path changed)
+ *   - `Unchanged`     — identical hook already present, no write
+ *   - `OptedOut`      — `--no-session-sync` was passed
+ *   - `Declined`      — user said no at the prompt
+ *   - `NotApplicable` — Claude Code wasn't a vendor target (the hook
+ *                       is Claude-specific, would never fire)
+ *   - `Skipped`       — install offer was accepted but the install
+ *                       failed (npm error, version-read error,
+ *                       prerequisite missing). Distinct from
+ *                       `OptedOut` (user explicit) and `Declined`
+ *                       (user said no).
+ *   - `Failed`        — disk error while writing the settings file
+ *                       (corrupt JSON, permissions, etc.)
+ */
+export const SessionSyncAction = Object.freeze({
+  Installed: "installed",
+  Updated: "updated",
+  Unchanged: "unchanged",
+  OptedOut: "opted-out",
+  Declined: "declined",
+  NotApplicable: "not-applicable",
+  Skipped: "skipped",
+  Failed: "failed",
+});
+
+/**
+ * True when the action represents a state where the SessionStart
+ * hook is currently in place on disk (and therefore the global
+ * `skillrepo` binary referenced by the hook is also active on PATH,
+ * because `mergeSessionHook` only emits these actions when it
+ * successfully wrote/found a working hook).
+ *
+ * Used by `init` to suppress the now-stale "install globally"
+ * Next-Steps tip after step 6 has put a hook in place.
+ *
+ * @param {string} action
+ * @returns {boolean}
+ */
+export function isHookActive(action) {
+  return (
+    action === SessionSyncAction.Installed ||
+    action === SessionSyncAction.Updated ||
+    action === SessionSyncAction.Unchanged
+  );
+}
+
+/**
+ * Frozen array of all valid `sessionSync.action` string values.
+ * Useful for runtime validation in tests and for the JSON-schema-
+ * style documentation generator.
+ *
+ * Built from `Object.values(SessionSyncAction)` so it stays in sync
+ * automatically. We use a frozen array (rather than a Set) because
+ * `Object.freeze` on a Set does NOT prevent `.add()` from mutating
+ * the internal storage — JS frozen-Set semantics are surprising.
+ * Frozen arrays ARE immutable end-to-end. Membership checks are
+ * `.includes()` instead of `.has()`; the values list is small (8)
+ * so the linear scan is irrelevant.
+ */
+export const SESSION_SYNC_ACTION_VALUES = Object.freeze(
+  Object.values(SessionSyncAction),
+);

package/src/lib/artifact-registry.mjs

@@ -88,8 +88,48 @@ export const VSCODE_INPUT_ID = "skillrepo-api-key";
 /**
  * Substring that identifies a SessionStart hook command entry as
  * SkillRepo-owned. The #884 installer writes a hook whose `command`
- * field contains `skillrepo update --session-hook`; any entry whose
- * command contains this substring is removed by the uninstall path.
+ * field ends with `<binary-path> update --session-hook ...`; any
+ * entry whose command contains ` update --session-hook` (with the
+ * leading space) is removed by the uninstall path.
+ *
+ * The leading space is a lightweight word boundary — it requires
+ * that `update` is preceded by whitespace (i.e. it's an argv token
+ * after the binary path), not a suffix of a longer identifier like
+ * `toolupdate` or `postupdate`. Without the space, a hypothetical
+ * binary at `/usr/local/bin/myapp-update` invoked with
+ * `--session-hook` as `/usr/local/bin/myapp-update --session-hook`
+ * would NOT match (because the substring would be `-update
+ * --session-hook`, not ` update --session-hook`), whereas a naive
+ * `update --session-hook` fingerprint would have.
+ *
+ * The leading space does NOT eliminate all false-positive classes.
+ * A command like `brew update --session-hook` DOES match the
+ * fingerprint — the space between `brew` and `update` is exactly
+ * what we key on. The primary protection against real-world false
+ * positives is the specificity of the two-token combination
+ * `update --session-hook` itself: `--session-hook` is not a
+ * conventional flag name used by tools other than SkillRepo, so the
+ * chance of a coincidental match is astronomically low. The test
+ * at `session-hook.test.mjs` "the fingerprint is specific enough
+ * that innocuous user hooks do NOT match it" enumerates plausible
+ * user-hook commands and confirms none trip the predicate.
+ *
+ * The fingerprint is also deliberately platform-neutral. Earlier
+ * versions matched the longer `skillrepo update --session-hook`
+ * substring, but that pattern silently fails to match Windows hook
+ * commands because npm installs the CLI as a `.cmd` shim — the
+ * absolute path on Windows ends `...\skillrepo.cmd`, which puts the
+ * `.cmd` extension between `skillrepo` and `update` in the command
+ * string. The shorter ` update --session-hook` substring is present
+ * on both:
+ *   POSIX:   `/usr/local/bin/skillrepo update --session-hook 2>&1 || true`
+ *   Windows: `C:\path\skillrepo.cmd update --session-hook 2>&1`
+ *
+ * Backward-compat: any v3.1.0 hook contains
+ * `skillrepo update --session-hook`, which is a strict superset of
+ * ` update --session-hook` (the space between `skillrepo` and `update`
+ * is the space we're matching). So upgrades still correctly identify
+ * and update the old entry in place.
  *
  * Exported so #884's installer can import and use the same constant —
  * this is the module boundary that makes #884 depend on #885 rather
@@ -97,7 +137,7 @@ export const VSCODE_INPUT_ID = "skillrepo-api-key";
  * 5.3) notes the bidirectional-fingerprint requirement; centralizing
  * it here enforces it at the language level.
  */
-export const SESSION_HOOK_FINGERPRINT = "skillrepo update --session-hook";
+export const SESSION_HOOK_FINGERPRINT = " update --session-hook";
 
 // ── Artifact descriptors ────────────────────────────────────────────
 

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

@@ -8,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";
@@ -85,6 +89,15 @@ export function resolveFlags(argv, opts = {}) {
     } else if (arg === "--help" || arg === "-h") {
       // Dispatcher should have intercepted this. Defensive no-op.
       continue;
+    } else if (arg === "--verbose") {
+      // Global flag set by the dispatcher into SKILLREPO_VERBOSE=1
+      // so http.mjs's retry logger can honor it. It's a first-class
+      // flag, not an unknown arg — accept it silently in every
+      // command that passes through resolveFlags. Before this
+      // branch existed, any command that consumed argv via
+      // resolveFlags rejected `--verbose` with "Unknown argument",
+      // breaking the flag documented in the top-level --help.
+      continue;
     } else {
       // Allow the caller to consume a positional arg before we treat
       // it as unknown. This is how `get @owner/name` and

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/config.mjs

@@ -43,10 +43,10 @@ import {
   unlinkSync,
 } from "node:fs";
 import { dirname } from "node:path";
-import { platform } from "node:os";
 
 import { globalConfigPath } from "./paths.mjs";
 import { diskError, validationError } from "./errors.mjs";
+import { platformConventions } from "./platform.mjs";
 
 /**
  * Current schema version. Bump this on any structural change.
@@ -187,8 +187,11 @@ export function writeConfig(config) {
 
   // chmod the temp file before renaming so the destination never
   // exists with world-readable perms (which would be a brief
-  // credential leak window on a shared system).
-  if (platform() !== "win32") {
+  // credential leak window on a shared system). Windows callers
+  // route through platformConventions().supportsPosixPermissions —
+  // see platform.mjs for why we skip chmod there instead of pretend-
+  // applying it.
+  if (platformConventions().supportsPosixPermissions) {
     try {
       chmodSync(tmpPath, 0o600);
     } catch {

package/src/lib/file-write.mjs

@@ -50,7 +50,6 @@ import {
   statSync,
 } from "node:fs";
 import { dirname, join, isAbsolute, relative } from "node:path";
-import { platform } from "node:os";
 
 import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
 import {
@@ -63,6 +62,7 @@ import {
   gitignorePath,
 } from "./paths.mjs";
 import { CliError, validationError, diskError } from "./errors.mjs";
+import { platformConventions } from "./platform.mjs";
 
 // ── Constants (mirror the server-side validators in src/lib/skills/) ────
 
@@ -562,8 +562,13 @@ function writeSkillToDir(skill, targetDir) {
     }
   }
 
-  // 2 + 3 + 4: rename dance (POSIX atomic on same filesystem; best-effort on Windows)
-  if (platform() === "win32") {
+  // 2 + 3 + 4: rename dance. POSIX is atomic on the same filesystem;
+  // Windows has to do remove-then-rename because renameSync fails on
+  // existing directory targets. The split is named via
+  // platformConventions().supportsAtomicDirectoryRename so the intent
+  // reads as a capability check, not a platform check. See
+  // platform.mjs for the rationale.
+  if (!platformConventions().supportsAtomicDirectoryRename) {
     // Windows: rename fails on existing destinations and locked files,
     // so we fall back to remove-then-rename. There is a window where
     // the live target is gone but the rename has not yet completed.

package/src/lib/fs-utils.mjs

@@ -14,6 +14,7 @@ import {
   unlinkSync,
 } from "node:fs";
 import { dirname } from "node:path";
+import { platformConventions } from "./platform.mjs";
 
 /**
  * Read a file as UTF-8, returning null if it doesn't exist.
@@ -44,15 +45,6 @@ export function writeFileSafe(filePath, content) {
   writeFileSync(filePath, content, "utf-8");
 }
 
-/**
- * Write a file and mark it executable (0o755).
- * Used for the Cursor session hook which is invoked directly via shebang.
- */
-export function writeExecutable(filePath, content) {
-  writeFileSafe(filePath, content);
-  chmodSync(filePath, 0o755);
-}
-
 /**
  * Check if a path exists (file or directory).
  */
@@ -105,7 +97,7 @@ export function writeFileAtomic(filePath, content, { mode } = {}) {
     throw new Error(`Cannot write ${tmpPath}: ${err.message}`, { cause: err });
   }
 
-  if (mode !== undefined && process.platform !== "win32") {
+  if (mode !== undefined && platformConventions().supportsPosixPermissions) {
     try {
       chmodSync(tmpPath, mode);
     } catch {
@@ -115,6 +107,13 @@ export function writeFileAtomic(filePath, content, { mode } = {}) {
       // file after the write.
     }
   }
+  // On Windows we deliberately skip chmod entirely. Node lets the call
+  // succeed on Windows but the mode bits don't map to anything the
+  // ACL layer enforces, so a "success" return would mislead the caller
+  // into thinking the credential file is access-restricted when it
+  // isn't. Windows users needing per-user protection should rely on
+  // %APPDATA%'s inherited ACLs (which default to the current user) or
+  // apply DACL restrictions at the OS level — outside this CLI's scope.
 
   try {
     renameSync(tmpPath, filePath);