skillrepo 3.1.0 → 3.1.2

package/src/test/commands/list.test.mjs

@@ -12,12 +12,18 @@ import { runList } from "../../commands/list.mjs";
 import { CliError, EXIT_AUTH } 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";
 
@@ -37,9 +43,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({});
@@ -52,7 +58,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/remove.test.mjs

@@ -13,12 +13,18 @@ import { writeSkillDir, 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/search.test.mjs

@@ -12,12 +12,18 @@ import { runSearch } from "../../commands/search.mjs";
 import { CliError, EXIT_VALIDATION, EXIT_AUTH } 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;
 let stderr;
 const VALID_KEY = "sk_live_test";
@@ -42,9 +48,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({});
@@ -58,7 +64,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/session-sync-actions.test.mjs

@@ -0,0 +1,74 @@
+/**
+ * Unit tests for src/commands/session-sync-actions.mjs (#894 / v3.1.2).
+ *
+ * The action-enum module is tiny but it's the SINGLE SOURCE OF TRUTH
+ * for the `sessionSync.action` JSON field. Downstream consumers
+ * (CI scripts, programmatic callers) parse this enum. The tests
+ * below lock in:
+ *   1. The enum's keys (programmer-facing names) and values
+ *      (consumer-facing strings) are stable.
+ *   2. The set of valid values reflects all 8 documented actions.
+ *   3. The frozen object can't be silently mutated at runtime.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  SessionSyncAction,
+  SESSION_SYNC_ACTION_VALUES,
+} from "../../commands/session-sync-actions.mjs";
+
+describe("SessionSyncAction enum", () => {
+  it("exposes all 8 documented action values with the exact wire strings", () => {
+    // Wire strings are what downstream consumers rely on; changing
+    // them is a breaking change. This test fails loudly on any
+    // accidental rename.
+    assert.equal(SessionSyncAction.Installed, "installed");
+    assert.equal(SessionSyncAction.Updated, "updated");
+    assert.equal(SessionSyncAction.Unchanged, "unchanged");
+    assert.equal(SessionSyncAction.OptedOut, "opted-out");
+    assert.equal(SessionSyncAction.Declined, "declined");
+    assert.equal(SessionSyncAction.NotApplicable, "not-applicable");
+    assert.equal(SessionSyncAction.Skipped, "skipped");
+    assert.equal(SessionSyncAction.Failed, "failed");
+  });
+
+  it("is frozen (cannot be mutated at runtime)", () => {
+    // Without the freeze, a runtime monkey-patch could change the
+    // wire value of an action and silently break downstream consumers.
+    assert.throws(
+      () => {
+        SessionSyncAction.Installed = "different";
+      },
+      TypeError,
+      "SessionSyncAction must be frozen",
+    );
+  });
+
+  it("SESSION_SYNC_ACTION_VALUES contains all 8 wire strings", () => {
+    assert.equal(SESSION_SYNC_ACTION_VALUES.length, 8);
+    for (const value of [
+      "installed",
+      "updated",
+      "unchanged",
+      "opted-out",
+      "declined",
+      "not-applicable",
+      "skipped",
+      "failed",
+    ]) {
+      assert.ok(
+        SESSION_SYNC_ACTION_VALUES.includes(value),
+        `expected SESSION_SYNC_ACTION_VALUES to contain "${value}"`,
+      );
+    }
+  });
+
+  it("SESSION_SYNC_ACTION_VALUES is frozen (cannot push, pop, or splice)", () => {
+    assert.throws(
+      () => SESSION_SYNC_ACTION_VALUES.push("new-action"),
+      /frozen|mutate|read-?only|extensible/i,
+    );
+  });
+});

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

@@ -22,7 +22,6 @@ import {
   readFileSync,
   writeFileSync,
   existsSync,
-  chmodSync,
 } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -32,18 +31,28 @@ import { buildHookCommand } from "../../lib/mergers/session-hook.mjs";
 import { SESSION_HOOK_FINGERPRINT } from "../../lib/artifact-registry.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
 import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+  assertHomeIsolated,
+} from "../helpers/sandbox-home.mjs";
+import { installShim, uninstallShim } from "../helpers/skillrepo-shim.mjs";
 
 let sandbox;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+/** @type {ReturnType<typeof installShim> | undefined} */
+let shimHandle;
 let stdout;
 let stderr;
 
 function ASSERT_HOME_ISOLATED() {
-  assert.ok(
-    process.env.HOME && process.env.HOME.startsWith(tmpdir()),
-    `HOME must point inside tmpdir. Current HOME="${process.env.HOME}"`,
-  );
+  // Thin wrapper around the shared helper so the call sites in tests
+  // stay short. Checks BOTH HOME and USERPROFILE so Windows is
+  // actually guarded (os.homedir() reads USERPROFILE on Windows).
+  assertHomeIsolated(tmpdir(), "session-sync tests");
 }
 
 function setup() {
@@ -51,19 +60,16 @@ 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"));
 
   // Put a predictable `skillrepo` shim at the front of PATH so
-  // mergeSessionHook's `which skillrepo` resolves to it. Saves having
-  // to inject a binaryPath at every call site.
-  const binDir = join(process.env.HOME, "bin");
-  mkdirSync(binDir, { recursive: true });
-  const shim = join(binDir, "skillrepo");
-  writeFileSync(shim, "#!/bin/sh\nexit 0\n");
-  chmodSync(shim, 0o755);
-  process.env.PATH = `${binDir}:${process.env.PATH}`;
+  // mergeSessionHook's binary resolver finds it. Saves having to
+  // inject a binaryPath at every call site. The shim helper handles
+  // cross-platform differences (POSIX extension-less shell script
+  // vs Windows .cmd file + PATHEXT lookup + PATH delimiter).
+  shimHandle = installShim(process.env.HOME);
 
   ASSERT_HOME_ISOLATED();
 
@@ -73,14 +79,10 @@ function setup() {
 
 function teardown() {
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  uninstallShim(shimHandle);
+  shimHandle = undefined;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
-  // Strip the prepended bin dir from PATH to keep subsequent tests clean
-  if (process.env.PATH?.startsWith(join(sandbox ?? "", "home", "bin"))) {
-    process.env.PATH = process.env.PATH.slice(
-      join(sandbox, "home", "bin").length + 1,
-    );
-  }
 }
 
 // ──────────────────────────────────────────────────────────────────

package/src/test/commands/uninstall.test.mjs

@@ -36,13 +36,21 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { runUninstall } from "../../commands/uninstall.mjs";
+import { SESSION_HOOK_FINGERPRINT } from "../../lib/artifact-registry.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+  assertHomeIsolated,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
 let projectDir;
 let homeDir;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 let stdout;
 let stderr;
 
@@ -54,11 +62,11 @@ let stderr;
  * architect tightening #2 asked for.
  */
 function ASSERT_HOME_ISOLATED() {
-  assert.ok(
-    process.env.HOME && process.env.HOME.startsWith(tmpdir()),
-    `HOME must point inside os.tmpdir() during uninstall tests. ` +
-      `Current HOME="${process.env.HOME}" — setup() forgot the override.`,
-  );
+  // Thin wrapper around the shared helper. Checks BOTH HOME and
+  // USERPROFILE so Windows is actually guarded — `os.homedir()`
+  // reads USERPROFILE on Windows, and an assertion that checked
+  // only HOME would pass while real user state was at risk.
+  assertHomeIsolated(tmpdir(), "uninstall tests");
 }
 
 function setup() {
@@ -69,9 +77,9 @@ function setup() {
   mkdirSync(homeDir, { recursive: true });
 
   originalCwd = process.cwd();
-  originalHome = process.env.HOME;
+  originalHomeEnv = captureHome();
   process.chdir(projectDir);
-  process.env.HOME = homeDir;
+  setSandboxHome(homeDir);
 
   ASSERT_HOME_ISOLATED();
 
@@ -81,7 +89,7 @@ function setup() {
 
 function teardown() {
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
 }
 
@@ -404,7 +412,7 @@ describe("runUninstall — --global", () => {
       "user-authored hook must survive uninstall",
     );
     assert.ok(
-      !allCommands.some((c) => c.includes("skillrepo update --session-hook")),
+      !allCommands.some((c) => c.includes(SESSION_HOOK_FINGERPRINT)),
       "SkillRepo hook must be gone",
     );
   });
@@ -487,7 +495,7 @@ describe("runUninstall — --global", () => {
       .flatMap((group) => group?.hooks ?? [])
       .map((h) => h?.command);
     assert.ok(
-      !allCommands.some((c) => c?.includes("skillrepo update --session-hook")),
+      !allCommands.some((c) => c?.includes(SESSION_HOOK_FINGERPRINT)),
       "global SkillRepo hook must be gone after uninstall --global",
     );
     assert.deepEqual(
@@ -552,9 +560,7 @@ describe("runUninstall — --global", () => {
       .flatMap((g) => g?.hooks ?? [])
       .map((h) => h?.command);
     assert.ok(
-      !projectCommands.some((c) =>
-        c?.includes("skillrepo update --session-hook"),
-      ),
+      !projectCommands.some((c) => c?.includes(SESSION_HOOK_FINGERPRINT)),
       "project-local hook still gets cleaned up",
     );
   });

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

package/src/test/helpers/mock-spawn.mjs

@@ -0,0 +1,121 @@
+/**
+ * Mock spawn factory for v3.1.2 global-install tests.
+ *
+ * `installSkillrepoGlobally` accepts an injected `spawn` so tests
+ * never actually shell out to npm. This helper produces spawn stubs
+ * that mimic `child_process.spawn`'s event-emitter shape:
+ *
+ *   {
+ *     stdout: EventEmitter | undefined,
+ *     stderr: EventEmitter | undefined,
+ *     on: (event, cb) => this,
+ *     kill: () => void,
+ *   }
+ *
+ * The factory returns the spawn function directly. A `.calls` array
+ * is attached as a side property so tests can assert how spawn was
+ * invoked (cmd name, args, options).
+ *
+ * Behavioral knobs:
+ *   - exitCode (number)        : the close event fires with this code.
+ *   - error (Error)            : if set, fires the `error` event
+ *                                instead of `close`. Use for ENOENT
+ *                                tests (`{ code: "ENOENT" }`).
+ *   - stderrText (string)      : emitted as a single Buffer chunk on
+ *                                the child's stderr stream. Used by
+ *                                EACCES + npm-nonzero categorization
+ *                                tests.
+ *   - hang (boolean)           : never fires `close` or `error`.
+ *                                Used for timeout tests.
+ *   - asyncDelayMs (number)    : delay before firing close/error.
+ *                                Default 0 (uses process.nextTick).
+ *
+ * Tests do NOT use `child_process.spawn` directly — they import this
+ * helper and pass its return value as `spawn` to
+ * `installSkillrepoGlobally({ spawn })`.
+ */
+
+import { EventEmitter } from "node:events";
+
+/**
+ * @typedef {Object} MockSpawnOptions
+ * @property {number} [exitCode=0]
+ * @property {Error & {code?: string}} [error]
+ * @property {string} [stderrText]
+ * @property {boolean} [hang]
+ * @property {number} [asyncDelayMs=0]
+ */
+
+/**
+ * Build a spawn stub. The returned function has shape:
+ *   (cmd: string, args: string[], opts: object) => ChildProcessMock
+ *
+ * @param {MockSpawnOptions} [options]
+ * @returns {Function & { calls: Array<{cmd: string, args: string[], opts: object}>, killed: boolean }}
+ */
+export function makeMockSpawn(options = {}) {
+  const {
+    exitCode = 0,
+    error = null,
+    stderrText = "",
+    hang = false,
+    asyncDelayMs = 0,
+  } = options;
+
+  const calls = [];
+
+  function mockSpawn(cmd, args, opts) {
+    calls.push({ cmd, args, opts });
+
+    // Mimic child_process.ChildProcess shape via plain EventEmitter.
+    // We create the streams unconditionally so the production code's
+    // `if (child.stderr)` checks work consistently.
+    const stdout = new EventEmitter();
+    const stderr = new EventEmitter();
+    const child = new EventEmitter();
+    child.stdout = stdout;
+    child.stderr = stderr;
+    child.kill = () => {
+      mockSpawn.killed = true;
+    };
+    // (`mockSpawn.killed` is initialized to `false` once on the
+    // outer factory below — we deliberately do NOT re-initialize
+    // here because re-initializing on every spawn call would
+    // overwrite `true` if the same spawn instance were called
+    // twice and the first call's kill had already fired.)
+
+    if (hang) {
+      // Never emit close or error. Caller's timeout will fire.
+      return child;
+    }
+
+    const fire = () => {
+      // Emit stderr data BEFORE close so production code sees the
+      // text in the buffer when categorizing the failure.
+      if (stderrText) {
+        stderr.emit("data", Buffer.from(stderrText, "utf-8"));
+      }
+      if (error) {
+        child.emit("error", error);
+      } else {
+        child.emit("close", exitCode);
+      }
+    };
+
+    if (asyncDelayMs > 0) {
+      setTimeout(fire, asyncDelayMs);
+    } else {
+      // process.nextTick mimics spawn's "events fire on next tick"
+      // contract — production code's `child.on("close", ...)`
+      // attaches listeners synchronously after spawn returns, and
+      // the events arrive on the next tick. setImmediate also works
+      // but is one tick later than necessary.
+      process.nextTick(fire);
+    }
+    return child;
+  }
+
+  mockSpawn.calls = calls;
+  mockSpawn.killed = false;
+  return mockSpawn;
+}