skillrepo 3.1.0 → 3.1.2

package/src/lib/platform.mjs

@@ -0,0 +1,124 @@
+/**
+ * Platform conventions — single source of truth for OS-specific
+ * differences the CLI has to honor.
+ *
+ * The CLI runs on POSIX systems (macOS, Linux) and Windows. Most
+ * code paths are platform-neutral via Node built-ins (path.join,
+ * os.homedir, fs.rmSync, etc.) — but a handful of surfaces have
+ * real platform differences that can't be abstracted away at the
+ * Node level:
+ *
+ *   1. **Binary-locator command**. POSIX provides `which`; Windows
+ *      provides `where.exe`. `execFileSync` doesn't spawn a shell,
+ *      so the literal name must exist on disk.
+ *
+ *   2. **Hook shell backstop suffix**. The SessionStart hook command
+ *      relies on a shell-level fallback (`|| true`) to guarantee
+ *      exit 0 even if the binary vanishes. POSIX shells support it;
+ *      cmd.exe doesn't know the `true` builtin and would emit a
+ *      confusing error. The `--session-hook` flag's exit-0 contract
+ *      inside the Node process is the primary defense regardless of
+ *      platform; the shell backstop is belt-and-suspenders that we
+ *      lose on Windows.
+ *
+ *   3. **POSIX file permissions**. `chmodSync(0o600)` silently
+ *      succeeds on Windows but doesn't produce the intended effect —
+ *      Windows's ACL model doesn't map to the Unix mode bits. Any
+ *      call meant to restrict permissions on credential files must
+ *      be guarded so Windows users aren't misled into thinking their
+ *      files are access-controlled when they aren't.
+ *
+ *   4. **Atomic directory replacement semantics**. POSIX's
+ *      `renameSync` over an existing directory is atomic on the same
+ *      filesystem — the swap is instantaneous from the perspective
+ *      of any concurrent reader. Windows fails with EEXIST/EPERM if
+ *      the target exists; the replacement must be done as a
+ *      remove-then-rename sequence with a small window where the
+ *      target is missing. Callers that write skills have to know
+ *      which strategy applies so they can surface a meaningful
+ *      recovery hint if the Windows path fails mid-sequence.
+ *
+ * This module exposes a single `platformConventions()` function that
+ * returns a frozen object with every platform-specific value the
+ * CLI needs. New platform-specific surfaces should be added here
+ * rather than spreading ad-hoc `platform() === "win32"` checks
+ * across the codebase. This is a convention, not an enforced rule —
+ * it's documentation plus a consumer pattern, not a linter.
+ *
+ * The `platform` parameter is an optional override for tests —
+ * production callers let it default to `os.platform()`.
+ */
+
+import { platform as osPlatform } from "node:os";
+
+/**
+ * @typedef {Object} PlatformConventions
+ * @property {"posix" | "windows"} family - High-level family name.
+ * @property {string} binaryLocator - Command used to resolve a
+ *           binary's absolute path from PATH. `"which"` on POSIX,
+ *           `"where"` on Windows.
+ * @property {string} hookShellSuffix - Suffix appended to hook
+ *           commands to guarantee exit 0 at the shell level. `" || true"`
+ *           on POSIX (appended to the base command), empty string on
+ *           Windows (the `--session-hook` flag's exit-0 contract is
+ *           the only defense).
+ * @property {boolean} supportsPosixPermissions - True when
+ *           `chmodSync(mode)` produces the intended POSIX mode-bit
+ *           effect. False on Windows, where the call nominally
+ *           succeeds but doesn't restrict ACLs the way a 0600 bit
+ *           would on Unix. Callers use this to skip chmod on
+ *           Windows rather than leave misleading "perms applied"
+ *           success paths that don't actually restrict access.
+ * @property {boolean} supportsAtomicDirectoryRename - True when
+ *           `renameSync` over an existing directory is atomic.
+ *           POSIX: true. Windows: false — callers must implement
+ *           remove-then-rename, accepting the small non-atomic
+ *           window where the target doesn't exist. The Windows
+ *           code path MUST produce a recoverable failure state if
+ *           the rename step fails (i.e. leave the `.tmp/` dir on
+ *           disk so the user can rename it manually).
+ */
+
+const POSIX = Object.freeze({
+  family: "posix",
+  binaryLocator: "which",
+  hookShellSuffix: " || true",
+  supportsPosixPermissions: true,
+  supportsAtomicDirectoryRename: true,
+});
+
+const WINDOWS = Object.freeze({
+  family: "windows",
+  binaryLocator: "where",
+  hookShellSuffix: "",
+  supportsPosixPermissions: false,
+  supportsAtomicDirectoryRename: false,
+});
+
+/**
+ * Return the platform-specific convention set for the current
+ * platform, or an override.
+ *
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform] - Override for testing.
+ *        Production callers should let this default to the real
+ *        runtime platform.
+ * @returns {PlatformConventions}
+ */
+export function platformConventions({ platform: platformOverride } = {}) {
+  const plat = platformOverride ?? osPlatform();
+  return plat === "win32" ? WINDOWS : POSIX;
+}
+
+/**
+ * True if the current (or overridden) platform is Windows.
+ * Convenience wrapper — prefer `platformConventions().family ===
+ * "windows"` in call sites that already hold a conventions object.
+ *
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform]
+ * @returns {boolean}
+ */
+export function isWindows({ platform: platformOverride } = {}) {
+  return platformConventions({ platform: platformOverride }).family === "windows";
+}

package/src/lib/sync.mjs

@@ -27,6 +27,22 @@
  * @property {number} updated     - Skills overwritten on disk
  * @property {number} removed     - Tombstones applied
  * @property {boolean} notModified - True if 304 short-circuit fired
+ * @property {boolean | null} fullSync - True if this was a full (non-delta)
+ *                                   sync — i.e. no prior `.last-sync` state
+ *                                   existed so no `since` was sent. False if
+ *                                   this was a delta sync. `null` only ever
+ *                                   appears in SYNTHESIZED failure summaries
+ *                                   (e.g. `init.mjs` when runSync threw) to
+ *                                   mark the state as genuinely unknown —
+ *                                   consumers should never see `null` from
+ *                                   runSync itself. A full sync returning
+ *                                   zero skills genuinely means "empty
+ *                                   library"; a delta sync returning zero
+ *                                   means "nothing changed since last sync".
+ *                                   Consumers must distinguish these to
+ *                                   render accurate user messages (see
+ *                                   init.mjs step 7).
+ * @property {string} [syncedAt]
  * @property {string} syncedAt    - ISO timestamp from the server response
  *
  * @typedef {Object} SyncStateFile
@@ -182,6 +198,14 @@ export async function runSync(options) {
   if (lastSync?.etag) opts.ifNoneMatch = lastSync.etag;
   if (lastSync?.syncedAt) opts.since = lastSync.syncedAt;
 
+  // Track whether this is a full or delta sync BEFORE the network
+  // call, for the returned summary's `fullSync` field. A "full" sync
+  // is one where no `since` was sent — which is exactly when no
+  // prior last-sync state existed. The distinction matters to
+  // consumers (init.mjs) that need to tell "empty library" from
+  // "nothing changed since last sync" in the zero-counters case.
+  const fullSync = !lastSync?.syncedAt;
+
   const result = await getLibrary(serverUrl, apiKey, opts);
 
   // Step 4: 304 short-circuit
@@ -191,6 +215,7 @@ export async function runSync(options) {
       updated: 0,
       removed: 0,
       notModified: true,
+      fullSync,
       syncedAt: lastSync?.syncedAt ?? new Date().toISOString(),
     };
   }
@@ -201,6 +226,7 @@ export async function runSync(options) {
     updated: 0,
     removed: 0,
     notModified: false,
+    fullSync,
     syncedAt: result.syncedAt,
   };
 

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;
+}

package/src/test/commands/add.test.mjs

@@ -13,12 +13,18 @@ import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { CliError, EXIT_VALIDATION, EXIT_AUTH, EXIT_SCOPE } from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
 let server;
 let serverUrl;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 let stdout;
 const VALID_KEY = "sk_live_test";
 
@@ -46,9 +52,9 @@ async function setup() {
   mkdirSync(join(sandbox, "project"), { recursive: true });
   mkdirSync(join(sandbox, "home"), { recursive: true });
   originalCwd = process.cwd();
-  originalHome = process.env.HOME;
+  originalHomeEnv = captureHome();
   process.chdir(join(sandbox, "project"));
-  process.env.HOME = join(sandbox, "home");
+  setSandboxHome(join(sandbox, "home"));
   delete process.env.SKILLREPO_ACCESS_KEY;
 
   server = createMockServer({});
@@ -61,7 +67,7 @@ async function setup() {
 async function teardown() {
   if (server) await server.stop();
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
   server = null;
 }

package/src/test/commands/get.test.mjs

@@ -13,12 +13,18 @@ import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
 let server;
 let serverUrl;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 let stdout;
 const VALID_KEY = "sk_live_test";
 
@@ -53,9 +59,9 @@ async function setup() {
   mkdirSync(join(sandbox, "project"), { recursive: true });
   mkdirSync(join(sandbox, "home"), { recursive: true });
   originalCwd = process.cwd();
-  originalHome = process.env.HOME;
+  originalHomeEnv = captureHome();
   process.chdir(join(sandbox, "project"));
-  process.env.HOME = join(sandbox, "home");
+  setSandboxHome(join(sandbox, "home"));
   delete process.env.SKILLREPO_ACCESS_KEY;
   delete process.env.SKILLREPO_URL;
 
@@ -69,7 +75,7 @@ async function setup() {
 async function teardown() {
   if (server) await server.stop();
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
   server = null;
 }