skillrepo 3.0.0 → 3.1.1

package/src/test/commands/update.test.mjs

@@ -16,12 +16,18 @@ import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { CliError, EXIT_AUTH, 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";
 
@@ -49,9 +55,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;
 
@@ -65,7 +71,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;
 }
@@ -162,3 +168,161 @@ describe("runUpdate — flag handling", () => {
     assert.ok(existsSync(dir));
   });
 });
+
+// ── --session-hook mode (#884) ────────────────────────────────────────
+//
+// Session-hook mode is what the Claude Code SessionStart hook #884's
+// installer writes invokes: `skillrepo update --session-hook`. The
+// contract: exit 0 on ALL errors, silent on 304, one-line summary on
+// changes, one-line failure message on error. A sync failure must
+// NEVER block a session start.
+//
+// Architect pre-flight review flagged the flag-acceptance bug as
+// "most likely silent-failure bug" — if `resolveFlags` rejects the
+// flag before the exit-0 contract activates, every session-start
+// hook silently fails with a symptom indistinguishable from 304.
+// Tests in this suite specifically guard against that.
+
+describe("runUpdate — --session-hook contract", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("accepts the --session-hook flag without throwing a validation error", async () => {
+    // THE architect-flagged regression guard. If a future refactor
+    // removes the acceptPositional callback from update.mjs,
+    // resolveFlags throws `Unknown argument: --session-hook` before
+    // the exit-0 contract has a chance to fire. The `|| true` shell
+    // backstop would catch it, but the user would lose the failure
+    // message AND every sync would silently no-op. This test makes
+    // that class of regression fail loudly at unit-test time.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+          { stdout },
+        ),
+      "update --session-hook must NOT throw Unknown argument",
+    );
+  });
+
+  it("is silent on 304 / up-to-date (no 'Syncing' output every session)", async () => {
+    // INTENT: 304 means nothing changed. Printing "Syncing..." on
+    // every session start with no value to show would clutter the
+    // system-message surface. The contract is SILENCE on 304.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.equal(
+      stdout.text(),
+      "",
+      "session-hook mode must emit zero output when there's nothing to sync",
+    );
+  });
+
+  it("prints one line on successful sync with changes", async () => {
+    // INTENT: when content CHANGES, surface exactly one actionable
+    // line so the user knows their library updated. No banners, no
+    // multi-line output — a single line the hook runner can render
+    // as a system message.
+    server.setLibraryResponse({
+      skills: [makeSkill("sync-hook-test")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    const out = stdout.text();
+    assert.match(out, /^\[SkillRepo\] Library synced: \d+ added, \d+ updated, \d+ removed\.\n$/);
+  });
+
+  it("exits 0 with a failure message on a server error instead of throwing", async () => {
+    // THE load-bearing contract. A sync failure must NEVER block a
+    // session start. runUpdate called with --session-hook against an
+    // unreachable server must return normally (no throw) and emit a
+    // one-line failure message.
+    //
+    // We simulate an unreachable server by pointing at an invalid
+    // port. Without the exit-0 contract, this would throw
+    // networkError from runSync; WITH the contract, the catch block
+    // swallows it and prints a failure message.
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", "http://127.0.0.1:1", "--session-hook"],
+          { stdout },
+        ),
+      "session-hook mode must NEVER throw — session start must proceed",
+    );
+    const out = stdout.text();
+    assert.match(out, /^\[SkillRepo\] Sync failed: .+\n$/);
+  });
+
+  it("exits 0 with a failure message on auth error (invalid key)", async () => {
+    // Auth error is non-retryable AND non-blocking for session start.
+    // If the user's key was rotated, we want them to see "access key
+    // invalid" in their session system message, but the session must
+    // still open normally.
+    server.setForcedStatus(401, { error: "Invalid access key" });
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+          { stdout },
+        ),
+    );
+    const out = stdout.text();
+    assert.match(out, /Sync failed/);
+  });
+
+  it("exits 0 with a failure message when no access key is configured", async () => {
+    // INTENT: the VERY first session after installing skillrepo, if
+    // init hasn't run yet, has no key. The hook must not block the
+    // session. This is a genuine first-run scenario, not a synthetic
+    // edge case — users who set up Claude Code before running
+    // `skillrepo init` will hit exactly this.
+    //
+    // No --key flag, no cached config, no env var. resolveFlags
+    // normally throws authError in this case. Session-hook mode
+    // must catch that and exit 0 anyway.
+    await assert.doesNotReject(
+      () =>
+        runUpdate(["--url", serverUrl, "--session-hook"], { stdout }),
+      "session-hook mode with no key must NEVER throw",
+    );
+    const out = stdout.text();
+    assert.match(out, /Sync failed/, "failure message must still surface");
+  });
+
+  it("exits 0 when the --session-hook flag appears after other flags", async () => {
+    // INTENT: flag ordering is not part of the contract. The installer
+    // writes a specific order today, but a user hand-editing their
+    // settings (or a future refactor moving flags around) must not
+    // break the exit-0 behavior.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await assert.doesNotReject(
+      () =>
+        runUpdate(
+          ["--session-hook", "--key", VALID_KEY, "--url", serverUrl],
+          { stdout },
+        ),
+    );
+    assert.equal(stdout.text(), "", "still silent on 304 regardless of flag order");
+  });
+
+  it("exits 0 silently when the server returns zero deltas (empty success, not 304)", async () => {
+    // INTENT: 304 isn't the only silent-success case. A 200 response
+    // with zero added/updated/removed (a fresh sync that happened to
+    // produce no work) is also silent — same UX reasoning as 304.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.equal(stdout.text(), "", "zero-delta 200 is silent");
+  });
+});

package/src/test/helpers/sandbox-home.mjs

@@ -0,0 +1,161 @@
+/**
+ * Cross-platform sandbox HOME isolation for CLI tests.
+ *
+ * Problem this solves
+ * -------------------
+ * Every CLI test that touches the filesystem runs in a temp-dir sandbox and
+ * redirects "home" so writes under `~/.claude/` or `~/.claude/skills/` land
+ * inside the sandbox instead of polluting the developer's real home.
+ *
+ * The pre-v3.1.1 pattern set `process.env.HOME` and relied on `os.homedir()`
+ * reading from HOME. That works on POSIX — `homedir()` reads HOME first —
+ * but it silently fails on Windows. On Windows, `homedir()` reads
+ * `USERPROFILE` (NOT HOME), so the tests' HOME redirect is a no-op: the
+ * CLI writes to `C:\Users\<runner>\.claude\` (the real user home) instead
+ * of the sandbox, and the post-assert `dir.startsWith(process.env.HOME)`
+ * fails because the string paths don't match.
+ *
+ * This surfaced the first time `.github/workflows/ci.yml` gained a
+ * `windows-latest` runner in PR #892 — 99 tests failed, none of them real
+ * CLI regressions, all because the sandbox isolation wasn't cross-platform.
+ *
+ * The contract
+ * ------------
+ * `captureHome()` snapshots BOTH env vars before you overwrite them. The
+ * snapshot correctly distinguishes "was undefined" from "was empty
+ * string" so `restoreHome()` can `delete` the var rather than set it to
+ * the literal string `"undefined"` (which `process.env.X = undefined`
+ * would do in Node — verified on Node 20).
+ *
+ * `setSandboxHome(path)` sets BOTH HOME and USERPROFILE to the same
+ * sandbox path. Setting both guarantees `homedir()` lands in the sandbox
+ * on every platform without the caller having to know which env var the
+ * current platform prefers.
+ *
+ * `restoreHome(snapshot)` restores the original state, with the delete-
+ * on-undefined pattern.
+ *
+ * Usage
+ * -----
+ *   import { captureHome, setSandboxHome, restoreHome } from "../helpers/sandbox-home.mjs";
+ *
+ *   let originalHomeEnv;
+ *   function setup() {
+ *     sandbox = mkdtempSync(join(tmpdir(), "cli-foo-"));
+ *     originalHomeEnv = captureHome();
+ *     setSandboxHome(join(sandbox, "home"));
+ *   }
+ *   function teardown() {
+ *     restoreHome(originalHomeEnv);
+ *     rmSync(sandbox, { recursive: true, force: true });
+ *   }
+ */
+
+/**
+ * @typedef {Object} HomeEnvSnapshot
+ * @property {string | undefined} HOME
+ * @property {string | undefined} USERPROFILE
+ */
+
+/**
+ * Snapshot HOME and USERPROFILE as they exist right now. Call before
+ * any `setSandboxHome` so `restoreHome` has something to put back.
+ *
+ * @returns {HomeEnvSnapshot}
+ */
+export function captureHome() {
+  return {
+    HOME: process.env.HOME,
+    USERPROFILE: process.env.USERPROFILE,
+  };
+}
+
+/**
+ * Set both HOME and USERPROFILE to the sandbox path. After this call,
+ * `os.homedir()` will resolve to `path` on every supported platform.
+ *
+ * @param {string} path - Absolute path to the sandbox "home" directory.
+ *        Caller is responsible for creating the directory if needed.
+ */
+export function setSandboxHome(path) {
+  if (typeof path !== "string" || path.length === 0) {
+    throw new Error("setSandboxHome: path must be a non-empty string");
+  }
+  process.env.HOME = path;
+  process.env.USERPROFILE = path;
+}
+
+/**
+ * Restore HOME and USERPROFILE to whatever they were at the time of
+ * `captureHome()`. Deletes the env var when the snapshot value was
+ * `undefined` — setting `process.env.X = undefined` in Node produces
+ * the literal string `"undefined"`, which would corrupt subsequent
+ * tests that read the env var.
+ *
+ * @param {HomeEnvSnapshot} snapshot - Return value of `captureHome()`.
+ */
+export function restoreHome(snapshot) {
+  if (!snapshot || typeof snapshot !== "object") {
+    throw new Error("restoreHome: snapshot must be the object from captureHome()");
+  }
+  if (snapshot.HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = snapshot.HOME;
+  if (snapshot.USERPROFILE === undefined) delete process.env.USERPROFILE;
+  else process.env.USERPROFILE = snapshot.USERPROFILE;
+}
+
+/**
+ * Assert both HOME and USERPROFILE point inside a sandbox rooted at
+ * `tmpdirRoot` (typically `os.tmpdir()`). This is the integrity check
+ * that prevents a test from accidentally writing into the developer's
+ * real home when `setSandboxHome()` was forgotten or bypassed.
+ *
+ * BOTH env vars are checked because `os.homedir()` reads `HOME` on
+ * POSIX and `USERPROFILE` on Windows. An assertion that checks only
+ * `HOME` would pass on Windows even when USERPROFILE still points at
+ * the real user home — defeating the purpose of the guard. The
+ * guards migrated from `session-sync.test.mjs`, `uninstall.test.mjs`,
+ * and `session-hook.test.mjs` into this helper after a review-round-4
+ * finding spotted the USERPROFILE gap.
+ *
+ * `USERPROFILE` is checked only when it's defined — on POSIX it's
+ * typically absent and `setSandboxHome()` does set it alongside
+ * HOME so it should be defined under the isolation contract, but we
+ * tolerate the "not set at all" state as well since that's
+ * equivalent to "can't leak outside the sandbox via it."
+ *
+ * @param {string} tmpdirRoot - Root path the HOME/USERPROFILE must
+ *        be inside. Typically `os.tmpdir()`.
+ * @param {string} [contextMessage] - Optional context to include in
+ *        the assertion failure message so the developer can tell
+ *        which test suite's setup forgot the override.
+ * @throws {AssertionError} If either env var is set but falls
+ *         outside `tmpdirRoot`.
+ */
+export function assertHomeIsolated(tmpdirRoot, contextMessage = "") {
+  if (typeof tmpdirRoot !== "string" || tmpdirRoot.length === 0) {
+    throw new Error(
+      "assertHomeIsolated: tmpdirRoot must be a non-empty string " +
+        "(usually os.tmpdir())",
+    );
+  }
+  const context = contextMessage ? ` (${contextMessage})` : "";
+  if (!process.env.HOME || !process.env.HOME.startsWith(tmpdirRoot)) {
+    throw new Error(
+      `HOME must point inside "${tmpdirRoot}"${context}. ` +
+        `Current HOME="${process.env.HOME}" — setup() forgot setSandboxHome() ` +
+        `or something else overwrote it.`,
+    );
+  }
+  if (
+    process.env.USERPROFILE !== undefined &&
+    !process.env.USERPROFILE.startsWith(tmpdirRoot)
+  ) {
+    throw new Error(
+      `USERPROFILE must point inside "${tmpdirRoot}"${context} ` +
+        `when defined. Current USERPROFILE="${process.env.USERPROFILE}" — ` +
+        `on Windows, os.homedir() reads USERPROFILE, so a stray real-host ` +
+        `value leaks tests into the real user home.`,
+    );
+  }
+}

package/src/test/helpers/skillrepo-shim.mjs

@@ -0,0 +1,133 @@
+/**
+ * Cross-platform `skillrepo` binary shim for CLI tests.
+ *
+ * Why this exists
+ * ---------------
+ * Several tests (init session-sync, session-sync command) invoke
+ * `runInit` or `runSessionSync`, which internally call
+ * `resolveSkillrepoBinary()` → `execFileSync("which" or "where",
+ * ["skillrepo"])`. For those calls to succeed deterministically —
+ * regardless of whether the developer has a global `skillrepo`
+ * install on PATH — the tests drop a fake `skillrepo` binary into
+ * a sandbox bin dir and prepend that dir to PATH.
+ *
+ * The original pattern was POSIX-only. On Windows it failed two ways:
+ *   1. The shim was created as a bash script (`#!/bin/sh\nexit 0\n`)
+ *      which `where.exe` won't match — `where` only resolves files
+ *      whose extension is in PATHEXT (.CMD by default), not
+ *      extension-less shell scripts.
+ *   2. PATH was joined with `:` which is the POSIX separator;
+ *      Windows uses `;`.
+ *
+ * This helper produces shims correctly for both families.
+ *
+ * Usage
+ * -----
+ *   import { installShim, uninstallShim } from "../helpers/skillrepo-shim.mjs";
+ *
+ *   let shim;
+ *   function setup() {
+ *     // ...sandbox + HOME/USERPROFILE setup...
+ *     shim = installShim(join(sandbox, "home"));
+ *   }
+ *   function teardown() {
+ *     uninstallShim(shim);
+ *     // ...HOME/USERPROFILE restore + sandbox cleanup...
+ *   }
+ *
+ * `installShim(homePath)` returns a `ShimHandle` carrying the path
+ * prepended to PATH and the original PATH value — pass it back to
+ * `uninstallShim` for restoration.
+ */
+
+import { mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { join, delimiter } from "node:path";
+import { platformConventions } from "../../lib/platform.mjs";
+
+/**
+ * @typedef {Object} ShimHandle
+ * @property {string} binDir - The directory we created and prepended.
+ * @property {string | undefined} originalPath - PATH as it was before
+ *        we prepended. Distinguishes "was undefined" from "was empty
+ *        string" so `uninstallShim` can `delete` rather than set the
+ *        env var to the literal string `"undefined"` (Node 20
+ *        coerces `env.X = undefined` to that string, verified).
+ */
+
+/**
+ * Drop a `skillrepo` shim into `<homePath>/bin` and prepend that dir
+ * to PATH so the CLI's binary resolver finds it on both POSIX and
+ * Windows.
+ *
+ * @param {string} homePath - Absolute path to the sandbox home dir.
+ *        Must already exist (caller typically just ran `mkdirSync`).
+ * @returns {ShimHandle}
+ */
+export function installShim(homePath) {
+  if (typeof homePath !== "string" || homePath.length === 0) {
+    throw new Error("installShim: homePath must be a non-empty string");
+  }
+  const conv = platformConventions();
+  const binDir = join(homePath, "bin");
+  mkdirSync(binDir, { recursive: true });
+
+  if (conv.family === "windows") {
+    // On Windows we create BOTH a `.cmd` and an extension-less shim.
+    // `where.exe skillrepo` matches anything whose extension is in
+    // PATHEXT (.CMD is default, empty extension is NOT in default
+    // PATHEXT) — so the `.cmd` is what production `resolveSkillrepoBinary`
+    // finds. The extension-less shim is a courtesy so any test that
+    // happens to invoke `bash -c './bin/skillrepo'` directly gets a
+    // working file — hence the POSIX shebang content, NOT cmd.exe
+    // syntax. (An earlier revision wrote `@exit 0` to both files; the
+    // round-3c review caught that the extension-less file with
+    // cmd.exe syntax would fail under bash. The `.cmd` gets cmd.exe
+    // syntax; the bare file gets POSIX shebang syntax.)
+    const cmdShim = join(binDir, "skillrepo.cmd");
+    writeFileSync(cmdShim, "@exit 0\r\n");
+    const bareShim = join(binDir, "skillrepo");
+    writeFileSync(bareShim, "#!/bin/sh\nexit 0\n");
+    // On Windows file-system permissions don't gate executability,
+    // but chmodSync is a no-op on Windows anyway so we skip it to
+    // avoid any platform-conditional chmod paths. Production uses
+    // `platformConventions().supportsPosixPermissions` for the same
+    // reason in `fs-utils.mjs`.
+  } else {
+    // POSIX shim — bash script + executable bit.
+    const shim = join(binDir, "skillrepo");
+    writeFileSync(shim, "#!/bin/sh\nexit 0\n");
+    chmodSync(shim, 0o755);
+  }
+
+  // Capture PATH as-is, including the `undefined` case. `??
+  // ""` would coalesce to empty string, but then `uninstallShim`
+  // can't tell "PATH was undefined" from "PATH was empty" — the
+  // restore would then write `""` into an env that had no PATH set,
+  // potentially breaking subsequent subprocess spawns that inherit
+  // env.
+  const originalPath = process.env.PATH;
+  // `path.delimiter` is `:` on POSIX, `;` on Windows — the correct
+  // separator for whichever platform we're running on.
+  process.env.PATH = `${binDir}${delimiter}${originalPath ?? ""}`;
+  return { binDir, originalPath };
+}
+
+/**
+ * Restore PATH to what it was before `installShim` was called.
+ * Deletes the env var if PATH was undefined at capture time —
+ * setting `process.env.PATH = undefined` produces the literal
+ * string `"undefined"` in Node, which would silently break
+ * binary lookups in subsequent tests.
+ *
+ * @param {ShimHandle | null | undefined} handle - Return value of
+ *        `installShim`, or null/undefined for a safe no-op on tests
+ *        that bailed before install ran.
+ */
+export function uninstallShim(handle) {
+  if (!handle) return;
+  if (handle.originalPath === undefined) {
+    delete process.env.PATH;
+  } else {
+    process.env.PATH = handle.originalPath;
+  }
+}

package/src/test/integration/file-write.integration.test.mjs

@@ -33,24 +33,30 @@ import {
   cleanupOrphans,
   resolvePlacementDir,
 } from "../../lib/file-write.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 
 function setupSandbox() {
   sandbox = mkdtempSync(join(tmpdir(), "cli-fw-int-"));
   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"));
 }
 
 function teardownSandbox() {
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
 }