skillrepo 3.1.0 → 3.1.1

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

package/src/test/commands/init.test.mjs

@@ -20,12 +20,18 @@ import { readConfig } from "../../lib/config.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;
 let stderr;
 const VALID_KEY = "sk_live_init_test";
@@ -38,9 +44,9 @@ async function setup() {
   mkdirSync(join(sandbox, "project", ".claude"), { 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;
 
@@ -55,7 +61,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;
 }
@@ -499,25 +505,29 @@ describe("runInit — stale-key handling", () => {
 // init tests verify the ORCHESTRATION: --yes path, --no-session-sync
 // opt-out, --json output shape, and the non-fatal disk-error path.
 
-import { chmodSync as _chmodSync } from "node:fs";
 import { SESSION_HOOK_FINGERPRINT as _FINGERPRINT } from "../../lib/artifact-registry.mjs";
+import { installShim, uninstallShim } from "../helpers/skillrepo-shim.mjs";
+
+/** @type {ReturnType<typeof installShim> | undefined} */
+let _shimHandle;
 
 async function setupWithShim() {
   await setup();
-  // Drop a deterministic `skillrepo` shim into HOME/bin so
-  // `which skillrepo` resolves to it rather than a possibly-missing
-  // global install.
-  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}`;
+  // Drop a cross-platform `skillrepo` shim into HOME/bin so the
+  // CLI's binary resolver (which/where) finds it rather than
+  // depending on whether the dev/CI machine has a global install.
+  _shimHandle = installShim(process.env.HOME);
+}
+
+async function teardownWithShim() {
+  uninstallShim(_shimHandle);
+  _shimHandle = undefined;
+  await teardown();
 }
 
 describe("runInit — session sync (#884)", () => {
   beforeEach(setupWithShim);
-  afterEach(teardown);
+  afterEach(teardownWithShim);
 
   it("--yes installs the hook at step 6 by default", async () => {
     // INTENT: the architect-designed default for --yes mode is
@@ -695,3 +705,206 @@ describe("runInit — session sync (#884)", () => {
     assert.equal(json.sessionSync.path, "~/.claude/settings.local.json");
   });
 });
+
+// ── v3.1.1 patch fixes: init UX bugs surfaced by real-world npx use ──
+//
+// Real-user `npx skillrepo@latest init` session surfaced four bugs in
+// the v3.1.0 init output. The tests below lock each fix as a
+// behavioral contract:
+//
+//   1. "Next steps" hardcoded `skillrepo` even under npx — would fail
+//      with "command not found" for users without a global install.
+//   2. Session-sync hook installed under npx with a cache-temporary
+//      path that breaks on cache eviction. (Covered in
+//      session-hook.test.mjs via isNpxInvocation guard test.)
+//   3. Step-7 zero-delta message conflated "empty library" with
+//      "nothing changed since last sync" — lied to users who had
+//      synced skills but no server-side changes since.
+//   4. `--verbose` rejected as Unknown argument by resolveFlags.
+//      (Covered in cli-config.test.mjs.)
+
+describe("runInit — v3.1.1 zero-delta message (bug 3)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("reports 'Library is up to date' when a delta sync returns zero changes", async () => {
+    // Reproduces the real-user bug: a user with an existing
+    // .last-sync from a prior v3.0.0 session runs `skillrepo init`
+    // again. Init's step 7 sends `since=<prior syncedAt>`. Server
+    // returns empty skills[] because nothing changed server-side.
+    // Counters (added/updated/removed) all zero.
+    //
+    // Before the fix: init printed "No skills in library yet"
+    // regardless of whether the library was empty or fully synced.
+    // After: init distinguishes via the new `fullSync` field in
+    // SyncSummary and prints "Library is up to date (no changes
+    // since last sync)" for the delta case.
+    //
+    // Pre-seed a .last-sync file simulating the prior sync state.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      join(process.env.HOME, ".claude", "skillrepo", ".last-sync"),
+      JSON.stringify({
+        schemaVersion: 1,
+        etag: '"old-v300-format-etag"',
+        syncedAt: "2026-04-15T12:00:00.000Z",
+      }),
+    );
+
+    // Server returns empty skills[] (no changes since last sync).
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "2026-04-16T12:00:00.000Z" });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(
+      out,
+      /Library is up to date/,
+      "zero-delta on delta sync must report 'up to date', not 'no skills in library yet'",
+    );
+    assert.doesNotMatch(
+      out,
+      /No skills in library yet/,
+      "the misleading 'no skills' message must NOT fire when .last-sync existed",
+    );
+  });
+
+  it("still reports 'No skills in library yet' on a true first-run full sync with zero skills", async () => {
+    // The other side of bug 3: when there's NO prior .last-sync and
+    // the server returns zero skills, the library IS genuinely
+    // empty. The message should still say so.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "2026-04-16T12:00:00.000Z" });
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(out, /No skills in library yet/);
+  });
+
+  it("304 Not Modified reports 'Library is up to date' (neutral phrasing)", async () => {
+    // 304 path: server returned "nothing changed" at the HTTP
+    // level. Definitively up-to-date regardless of whether library
+    // is populated or empty.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      join(process.env.HOME, ".claude", "skillrepo", ".last-sync"),
+      JSON.stringify({
+        schemaVersion: 1,
+        etag: '"match-me"',
+        syncedAt: "2026-04-15T12:00:00.000Z",
+      }),
+    );
+    server.setEtag('"match-me"');
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    assert.match(stdout.text(), /Library is up to date/);
+  });
+});
+
+describe("runInit — v3.1.1 Next steps prefix (bug 1)", () => {
+  // Process-state isolation: the tests below depend on controlling
+  // isNpxInvocation()'s outputs. The test host's shell environment
+  // may have `_` set to some launching command (the enclosing `npm
+  // run check`, `node --test`, etc.). beforeEach force-clears the
+  // two isNpxInvocation signals (argv[1] and `_`) plus the
+  // now-unused `npm_command` — the latter is cleared defensively
+  // because older versions of this codebase treated it as an npx
+  // signal, and belt-and-suspenders cleanup costs nothing.
+  let originalArgv;
+  let originalNpmCommand;
+  let originalUnderscore;
+
+  beforeEach(async () => {
+    await setup();
+    originalArgv = process.argv;
+    originalNpmCommand = process.env.npm_command;
+    originalUnderscore = process.env._;
+    // Non-npx state:
+    process.argv = ["/usr/local/bin/node", "/usr/local/bin/skillrepo"];
+    delete process.env.npm_command;
+    delete process.env._;
+  });
+
+  afterEach(async () => {
+    process.argv = originalArgv;
+    if (originalNpmCommand === undefined) delete process.env.npm_command;
+    else process.env.npm_command = originalNpmCommand;
+    if (originalUnderscore === undefined) delete process.env._;
+    else process.env._ = originalUnderscore;
+    await teardown();
+  });
+
+  it("shows bare `skillrepo` prefix when running from a stable install", async () => {
+    // With all npx signals cleared (beforeEach above), isNpxInvocation
+    // returns false and the bare prefix is used in the Next Steps
+    // block.
+    //
+    // NOTE ON REGEX: "npm install -g skillrepo" appears in TWO places
+    // that look alike but come from different code paths:
+    //
+    //   1. Step 6/7 session-sync skipped message (when the binary
+    //      can't be resolved — in the test environment, `which
+    //      skillrepo` doesn't find anything real).
+    //   2. Next Steps tip (only shown under npx).
+    //
+    // We want to assert only #2 is absent. Match the EXACT "Tip:"
+    // prefix to scope the assertion to Next Steps.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    // The commands in Next Steps are bare, not prefixed.
+    assert.match(out, /^ +• skillrepo list/m);
+    assert.doesNotMatch(
+      out,
+      /npx skillrepo list/,
+      "bare install must NOT show the npx-prefixed hints",
+    );
+    // The "Tip: …" line appears only under npx.
+    assert.doesNotMatch(
+      out,
+      /Tip: `npm install -g skillrepo`/,
+      "bare install must NOT show the npx-mode global-install tip",
+    );
+  });
+
+  it("shows `npx skillrepo` prefix and global-install tip under npx invocation", async () => {
+    // Simulate npx by stuffing argv[1] with an _npx cache path.
+    // isNpxInvocation() returns true and the output changes shape.
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/dc129a78aca3fc9c/node_modules/.bin/skillrepo",
+    ];
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const out = stdout.text();
+    assert.match(
+      out,
+      /npx skillrepo list/,
+      "npx invocation must prefix commands with `npx`",
+    );
+    assert.match(
+      out,
+      /Tip: `npm install -g skillrepo`/,
+      "npx invocation must show the Next-Steps global-install tip",
+    );
+  });
+});

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