skillrepo 3.1.0 → 3.1.2

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

package/src/test/lib/cli-config.test.mjs

@@ -18,28 +18,35 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { resolveFlags, effectiveVendors } from "../../lib/cli-config.mjs";
+import { isTransientRunnerInvocation } from "../../lib/transient-runners.mjs";
 import { CliError, EXIT_AUTH, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 let originalEnv;
 
 function setupSandbox() {
   sandbox = mkdtempSync(join(tmpdir(), "cli-config-"));
   mkdirSync(join(sandbox, "home", ".claude", "skillrepo"), { recursive: true });
-  originalHome = process.env.HOME;
+  originalHomeEnv = captureHome();
   // Snapshot the env vars we mutate so tests don't bleed into each other
   originalEnv = {
     SKILLREPO_ACCESS_KEY: process.env.SKILLREPO_ACCESS_KEY,
     SKILLREPO_URL: process.env.SKILLREPO_URL,
   };
-  process.env.HOME = join(sandbox, "home");
+  setSandboxHome(join(sandbox, "home"));
   delete process.env.SKILLREPO_ACCESS_KEY;
   delete process.env.SKILLREPO_URL;
 }
 
 function teardownSandbox() {
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (originalEnv.SKILLREPO_ACCESS_KEY === undefined) {
     delete process.env.SKILLREPO_ACCESS_KEY;
   } else {
@@ -405,3 +412,174 @@ describe("effectiveVendors", () => {
     );
   });
 });
+
+// ── isTransientRunnerInvocation ───────────────────────────────────────────────────
+//
+// The helper detects whether the CLI was launched via `npx skillrepo`
+// vs. a stable global install. v3.1.0 shipped a bug where the session-
+// hook installer's `which skillrepo` check treated the npx cache path
+// as a stable install location — this helper is the fix mechanism.
+// Three independent signals are checked; any one is sufficient.
+
+describe("isTransientRunnerInvocation", () => {
+  let originalArgv;
+  let originalNpmCommand;
+  let originalUnderscore;
+
+  beforeEach(() => {
+    originalArgv = process.argv;
+    originalNpmCommand = process.env.npm_command;
+    originalUnderscore = process.env._;
+    delete process.env.npm_command;
+    delete process.env._;
+  });
+
+  afterEach(() => {
+    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;
+  });
+
+  it("returns false for a vanilla node invocation", () => {
+    process.argv = ["/usr/local/bin/node", "/usr/local/bin/skillrepo"];
+    assert.equal(isTransientRunnerInvocation(), false);
+  });
+
+  it("detects npx via the argv[1] _npx cache path", () => {
+    // Primary signal — the executable's path literally lives inside
+    // ~/.npm/_npx/<hash>/. Most reliable.
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/dc129a78aca3fc9c/node_modules/.bin/skillrepo",
+    ];
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("does NOT treat npm_command=exec as an npx signal (false-positive guard)", () => {
+    // v3.1.1 review rejected `npm_command === "exec"` as an npx
+    // signal because it also fires when a stable-install user runs
+    // `skillrepo` from a package.json lifecycle script (e.g.
+    // `"postinstall": "skillrepo init --yes"`) or via `npm exec
+    // skillrepo ...`. Those users have a real global install and
+    // should NOT see session-sync skipped or `npx skillrepo` in
+    // Next Steps. The argv[1] _npx-path signal already catches
+    // real npx invocations unambiguously.
+    //
+    // This test locks the decision: even with `npm_command=exec`
+    // set, without an `_npx` path in argv[1] or an `/npx` `_` env
+    // var, the invocation must be treated as a stable install.
+    process.argv = ["/usr/local/bin/node", "/some/other/path/skillrepo"];
+    process.env.npm_command = "exec";
+    assert.equal(isTransientRunnerInvocation(), false);
+  });
+
+  it("detects npx via the _ env var ending in /npx (legacy fallback)", () => {
+    process.argv = ["/usr/local/bin/node", "/path/skillrepo"];
+    process.env._ = "/usr/local/bin/npx";
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("handles Windows _npx path separator", () => {
+    process.argv = [
+      "C:\\Program Files\\nodejs\\node.exe",
+      "C:\\Users\\alice\\.npm\\_npx\\abc123\\node_modules\\.bin\\skillrepo",
+    ];
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("does NOT false-positive on a path containing 'npx' substring but not in _npx cache", () => {
+    // E.g., a user installs into /opt/npxtools/bin/skillrepo. The
+    // check matches `/_npx/` specifically (with leading slash), not
+    // substring "npx", so this should be safely negative.
+    process.argv = ["/usr/local/bin/node", "/opt/npxtools/bin/skillrepo"];
+    assert.equal(isTransientRunnerInvocation(), false);
+  });
+
+  // ── v3.1.2: extended detection for pnpx, yarn dlx, bunx ──────────
+
+  it("detects pnpm dlx invocation via cache substring '/dlx-'", () => {
+    // pnpm dlx caches in `<store>/dlx-<hash>/...` per-invocation.
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.local/share/pnpm/store/dlx-abc123/node_modules/.bin/skillrepo",
+    ];
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("detects pnpm dlx invocation on Windows", () => {
+    process.argv = [
+      "C:\\Program Files\\nodejs\\node.exe",
+      "C:\\Users\\alice\\AppData\\Local\\pnpm\\store\\dlx-abc123\\node_modules\\.bin\\skillrepo.cmd",
+    ];
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("detects yarn berry dlx invocation via '/.yarn/berry/' cache substring", () => {
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/project/.yarn/berry/cache/skillrepo-npm-3.1.2-abc/node_modules/skillrepo/bin/skillrepo.mjs",
+    ];
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("detects bunx invocation via '/.bun/install/cache/' cache substring", () => {
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.bun/install/cache/skillrepo@3.1.2/node_modules/.bin/skillrepo",
+    ];
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("detects pnpx via process.env._ suffix", () => {
+    process.argv = ["/usr/local/bin/node", "/somewhere/skillrepo"];
+    process.env._ = "/usr/local/bin/pnpx";
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("detects bunx via process.env._ suffix", () => {
+    process.argv = ["/usr/local/bin/node", "/somewhere/skillrepo"];
+    process.env._ = "/Users/alice/.bun/bin/bunx";
+    assert.equal(isTransientRunnerInvocation(), true);
+  });
+
+  it("does NOT false-positive on a directory name containing 'dlx' that is not pnpm dlx", () => {
+    // E.g. `/Users/alice/dlx-utils/bin/skillrepo` — the substring is
+    // present but it's not in a pnpm cache. The fingerprint requires
+    // a leading separator so `/dlx-` matches a path SEGMENT named
+    // `dlx-...`, which a user-named directory wouldn't typically be.
+    process.argv = ["/usr/local/bin/node", "/Users/alice/utility-dlx/bin/skillrepo"];
+    assert.equal(isTransientRunnerInvocation(), false);
+  });
+});
+
+// ── resolveFlags accepts --verbose ───────────────────────────────────
+
+describe("resolveFlags — --verbose flag (bug 4 fix)", () => {
+  beforeEach(setupSandbox);
+  afterEach(teardownSandbox);
+
+  it("accepts --verbose without throwing Unknown argument", () => {
+    // Before this fix: commands passing argv through resolveFlags
+    // rejected --verbose as unknown, despite the flag being documented
+    // in the top-level --help. The dispatcher reads
+    // process.argv.includes("--verbose") to set SKILLREPO_VERBOSE=1
+    // but doesn't strip it from argv — so resolveFlags saw the raw
+    // flag and threw validationError.
+    //
+    // Locks the fix: resolveFlags ignores --verbose (the dispatcher
+    // already consumed its effect via the env var).
+    process.env.SKILLREPO_ACCESS_KEY = "sk_live_x";
+    assert.doesNotThrow(() =>
+      resolveFlags(["--verbose", "--json"]),
+    );
+  });
+
+  it("--verbose anywhere in argv — not just at a specific position", () => {
+    process.env.SKILLREPO_ACCESS_KEY = "sk_live_x";
+    assert.doesNotThrow(() =>
+      resolveFlags(["--json", "--verbose", "--global"]),
+    );
+  });
+});

package/src/test/lib/cli-version.test.mjs

@@ -0,0 +1,47 @@
+/**
+ * Unit tests for src/lib/cli-version.mjs (#894 / v3.1.2).
+ *
+ * Tiny module, tiny suite — but the cases below lock in the
+ * contract that `installSkillrepoGlobally({ version })` depends on.
+ * If the version read silently regressed (returned undefined,
+ * stale, or threw on a valid tarball), every npx user's
+ * auto-install would silently fail or pin to garbage.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+import { getCliVersion } from "../../lib/cli-version.mjs";
+
+describe("getCliVersion", () => {
+  it("returns the version string from the CLI's own package.json", () => {
+    // FACT-based: read the package.json the same way the SUT does,
+    // then compare. If the version field changes (e.g. v3.1.3
+    // bump), this test passes automatically — it's not a literal
+    // assertion against "3.1.2", which would create churn on every
+    // version bump.
+    const pkgUrl = new URL(
+      "../../../package.json",
+      import.meta.url,
+    );
+    const pkg = JSON.parse(readFileSync(pkgUrl, "utf-8"));
+    assert.equal(getCliVersion(), pkg.version);
+  });
+
+  it("returns a valid semver-shaped string (X.Y.Z)", () => {
+    // Defense against a future regression where the package.json
+    // version is corrupted to a non-string (boolean, number,
+    // object). The CLI install command would silently produce
+    // garbage like `npm install -g skillrepo@true` without this
+    // shape check.
+    const v = getCliVersion();
+    assert.equal(typeof v, "string");
+    assert.match(v, /^\d+\.\d+\.\d+/);
+  });
+
+  it("returns a non-empty string", () => {
+    const v = getCliVersion();
+    assert.ok(v.length > 0, "version must be non-empty");
+  });
+});

package/src/test/lib/config.test.mjs

@@ -25,19 +25,25 @@ import {
 } from "../../lib/config.mjs";
 import { globalConfigPath } from "../../lib/paths.mjs";
 import { CliError, EXIT_VALIDATION, EXIT_DISK } from "../../lib/errors.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 
 function setupSandbox() {
   sandbox = mkdtempSync(join(tmpdir(), "cli-config-mjs-"));
   mkdirSync(join(sandbox, "home"), { recursive: true });
-  originalHome = process.env.HOME;
-  process.env.HOME = join(sandbox, "home");
+  originalHomeEnv = captureHome();
+  setSandboxHome(join(sandbox, "home"));
 }
 
 function teardownSandbox() {
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
 }