skillrepo 3.1.0 → 3.1.2

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

@@ -45,26 +45,32 @@ import {
   BLOCKED_EXTENSIONS,
 } from "../../lib/file-write.mjs";
 import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
 
 // ── Test sandbox helpers ────────────────────────────────────────────────
 
 let sandbox;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 
 function setupSandbox() {
   sandbox = mkdtempSync(join(tmpdir(), "cli-fw-"));
   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 });
 }
 
@@ -262,14 +268,18 @@ describe("resolvePlacementDir", () => {
 
   it("resolves claudeProject under cwd", () => {
     const dir = resolvePlacementDir("claudeProject", "pdf-helper");
-    assert.ok(dir.endsWith("/.claude/skills/pdf-helper"));
-    assert.ok(dir.startsWith(process.cwd()));
+    // Use join() for the expected suffix so the platform-native
+    // separator is compared (backslash on Windows, forward slash
+    // on POSIX). Hardcoding "/" would silently fail on Windows.
+    assert.equal(dir, join(process.cwd(), ".claude", "skills", "pdf-helper"));
   });
 
   it("resolves claudeGlobal under HOME", () => {
     const dir = resolvePlacementDir("claudeGlobal", "pdf-helper");
-    assert.ok(dir.endsWith("/.claude/skills/pdf-helper"));
-    assert.ok(dir.startsWith(process.env.HOME));
+    assert.equal(
+      dir,
+      join(process.env.HOME, ".claude", "skills", "pdf-helper"),
+    );
   });
 
   it("resolves projectFallback under cwd /skills/", () => {
@@ -456,8 +466,12 @@ describe("writeSkillDir — happy path", () => {
     const skill = minimalSkill();
     const result = writeSkillDir(skill, { vendors: ["cursor"] });
     assert.equal(result.written.length, 1);
-    assert.ok(result.written[0].includes("/skills/pdf-helper"));
-    // .gitignore should now contain /skills/
+    // Use join() for the expected fragment so Windows's "\" separator
+    // matches. The forward-slash literal would fail on windows-latest.
+    assert.ok(result.written[0].includes(join("skills", "pdf-helper")));
+    // .gitignore should now contain /skills/ (that literal — it's the
+    // gitignore pattern, not a filesystem path — and gitignore uses
+    // forward slashes even on Windows, per git's own conventions).
     const gi = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
     assert.match(gi, /\/skills\//);
     assert.match(gi, /SkillRepo/);

package/src/test/lib/global-install.test.mjs

@@ -0,0 +1,424 @@
+/**
+ * Unit tests for src/lib/global-install.mjs (#894 / v3.1.2).
+ *
+ * These cover the auto-install-global helper that init.mjs step 6
+ * uses under npx. The spawn function is injected via the `spawn`
+ * option so no test ever shells out to npm.
+ *
+ * Categories:
+ *   1. Spawn invocation shape (POSIX vs Windows command name,
+ *      args, stdio).
+ *   2. Version pinning (always `skillrepo@<version>`).
+ *   3. Result enum coverage:
+ *        success | eacces | enoent-npm | npm-nonzero | timeout |
+ *        path-not-updated.
+ *   4. Output mode: inherit vs silent (stdio shape differs).
+ *   5. resolveGlobalBinary: filters _npx cache paths.
+ *   6. Programmer-error throws (missing version arg).
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  installSkillrepoGlobally,
+  resolveGlobalBinary,
+} from "../../lib/global-install.mjs";
+import { makeMockSpawn } from "../helpers/mock-spawn.mjs";
+
+// ── installSkillrepoGlobally — spawn invocation shape ────────────
+
+describe("installSkillrepoGlobally — spawn shape", () => {
+  it("invokes `npm install -g skillrepo@<version>` on POSIX", async () => {
+    const spawn = makeMockSpawn({ exitCode: 0 });
+    // Pass platform: "linux" to force POSIX shape regardless of host.
+    await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+    });
+    assert.equal(spawn.calls.length, 1);
+    assert.equal(spawn.calls[0].cmd, "npm");
+    assert.deepEqual(spawn.calls[0].args, [
+      "install",
+      "-g",
+      "skillrepo@3.1.2",
+    ]);
+  });
+
+  it("invokes `npm.cmd install -g skillrepo@<version>` on Windows", async () => {
+    // The Windows code path must use `npm.cmd` because npm on
+    // Windows is a batch script, not a native binary. spawn() with
+    // `shell: false` requires the literal name on disk. This test
+    // is the regression guard for that platform branch.
+    const spawn = makeMockSpawn({ exitCode: 0 });
+    await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "win32",
+    });
+    assert.equal(spawn.calls[0].cmd, "npm.cmd");
+    assert.deepEqual(spawn.calls[0].args, [
+      "install",
+      "-g",
+      "skillrepo@3.1.2",
+    ]);
+  });
+
+  it("uses stdio: 'inherit' by default so npm output streams to terminal", async () => {
+    const spawn = makeMockSpawn({ exitCode: 0 });
+    await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+    });
+    assert.equal(spawn.calls[0].opts.stdio, "inherit");
+  });
+
+  it("uses stdio: ['ignore','pipe','pipe'] when outputMode is 'silent'", async () => {
+    // Silent mode is for --json: npm output must NOT touch the
+    // process stdout (which is reserved for the JSON blob), but
+    // stderr is captured for failure-message extraction.
+    const spawn = makeMockSpawn({ exitCode: 0 });
+    await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+      outputMode: "silent",
+    });
+    assert.deepEqual(spawn.calls[0].opts.stdio, ["ignore", "pipe", "pipe"]);
+  });
+
+  it("pins the version exactly — no extra suffixes or flags", async () => {
+    // Lock in that the spawn args are exactly what we expect, with
+    // no future drift to e.g. `--save-exact` or `--no-fund` slipping
+    // in. The npm command is intentionally minimal.
+    const spawn = makeMockSpawn({ exitCode: 0 });
+    await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+    });
+    assert.deepEqual(spawn.calls[0].args, [
+      "install",
+      "-g",
+      "skillrepo@3.1.2",
+    ]);
+  });
+
+  it("uses the version arg verbatim (no normalization)", async () => {
+    // Defense: a future caller passing a version like "3.1.2-rc.1"
+    // or "next" must get exactly that string in the npm spec, not
+    // a normalized form. This is the contract: caller controls the
+    // version string; the helper just embeds it.
+    const spawn = makeMockSpawn({ exitCode: 0 });
+    await installSkillrepoGlobally({
+      version: "3.2.0-rc.1",
+      spawn,
+      platform: "linux",
+    });
+    assert.equal(spawn.calls[0].args[2], "skillrepo@3.2.0-rc.1");
+  });
+});
+
+// ── installSkillrepoGlobally — programmer error throws ──────────
+
+describe("installSkillrepoGlobally — programmer errors", () => {
+  it("throws when version is missing", async () => {
+    await assert.rejects(
+      () => installSkillrepoGlobally({ spawn: makeMockSpawn() }),
+      /version.*non-empty string/,
+    );
+  });
+
+  it("throws when version is an empty string", async () => {
+    await assert.rejects(
+      () => installSkillrepoGlobally({ version: "", spawn: makeMockSpawn() }),
+      /version.*non-empty string/,
+    );
+  });
+
+  it("throws when version is not a string", async () => {
+    await assert.rejects(
+      () =>
+        installSkillrepoGlobally({
+          version: 312,
+          spawn: makeMockSpawn(),
+        }),
+      /version.*non-empty string/,
+    );
+  });
+});
+
+// ── installSkillrepoGlobally — result enum ──────────────────────
+//
+// resolveGlobalBinary is called by installSkillrepoGlobally on the
+// success path to verify the binary actually landed on PATH. In
+// these tests we DON'T have a real `skillrepo` to find — so the
+// "happy" tests below assert errorCode === "path-not-updated"
+// rather than success === true. The integration tests in
+// init.test.mjs exercise the full happy path with a shim on PATH.
+
+describe("installSkillrepoGlobally — failure categorization", () => {
+  it("returns errorCode='eacces' when stderr contains EACCES", async () => {
+    const spawn = makeMockSpawn({
+      exitCode: 243,
+      stderrText:
+        "npm ERR! code EACCES\nnpm ERR! Error: EACCES: permission denied",
+    });
+    const result = await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+      outputMode: "silent",
+    });
+    assert.equal(result.success, false);
+    assert.equal(result.errorCode, "eacces");
+    assert.match(result.error, /permissions/i);
+    assert.match(result.error, /sudo/i);
+  });
+
+  it("returns errorCode='enoent-npm' when spawn fires error with code ENOENT", async () => {
+    const enoent = Object.assign(new Error("spawn npm ENOENT"), {
+      code: "ENOENT",
+    });
+    const spawn = makeMockSpawn({ error: enoent });
+    const result = await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+    });
+    assert.equal(result.success, false);
+    assert.equal(result.errorCode, "enoent-npm");
+    assert.match(result.error, /npm.*not found/i);
+  });
+
+  it("returns errorCode='npm-nonzero' for generic non-zero exits", async () => {
+    const spawn = makeMockSpawn({
+      exitCode: 1,
+      stderrText: "npm ERR! 404 Not Found - GET https://registry...",
+    });
+    const result = await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+      outputMode: "silent",
+    });
+    assert.equal(result.success, false);
+    assert.equal(result.errorCode, "npm-nonzero");
+    assert.match(result.error, /exited with code 1/);
+    // First ~200 chars of stderr should be included for diagnosis.
+    assert.match(result.error, /404 Not Found/);
+  });
+
+  it("includes stderr snippet when in silent mode", async () => {
+    const spawn = makeMockSpawn({
+      exitCode: 1,
+      stderrText: "specific-failure-marker-12345",
+    });
+    const result = await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+      outputMode: "silent",
+    });
+    assert.match(result.error, /specific-failure-marker-12345/);
+  });
+
+  it("returns errorCode='timeout' when child does not complete in time", async () => {
+    // Use a hanging spawn + a very short timeout. The result must
+    // come back within ~100ms to keep the suite fast.
+    const spawn = makeMockSpawn({ hang: true });
+    const result = await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+      platform: "linux",
+      timeoutMs: 50,
+    });
+    assert.equal(result.success, false);
+    assert.equal(result.errorCode, "timeout");
+    assert.match(result.error, /did not complete/i);
+    // The mock's kill should have been invoked.
+    assert.equal(spawn.killed, true);
+  });
+
+  it("returns errorCode='path-not-updated' when npm exits 0 but no binary on PATH", async () => {
+    // No shim on PATH → resolveGlobalBinary returns null → the
+    // helper categorizes as path-not-updated. This is the nvm-
+    // misconfiguration case: install succeeded, but the user's
+    // npm prefix bin dir isn't on PATH so the binary is invisible
+    // to the hook runner.
+    const spawn = makeMockSpawn({ exitCode: 0 });
+    // Save and clear PATH so resolveGlobalBinary genuinely finds
+    // nothing — even if the developer happens to have a global
+    // skillrepo installed.
+    const originalPath = process.env.PATH;
+    process.env.PATH = "/nonexistent/dir";
+    try {
+      const result = await installSkillrepoGlobally({
+        version: "3.1.2",
+        spawn,
+        platform: "linux",
+      });
+      assert.equal(result.success, false);
+      assert.equal(result.errorCode, "path-not-updated");
+      assert.match(result.error, /not found on PATH/);
+    } finally {
+      if (originalPath === undefined) {
+        delete process.env.PATH;
+      } else {
+        process.env.PATH = originalPath;
+      }
+    }
+  });
+
+  it("never throws on user-recoverable failures", async () => {
+    // Defensive: every failure path must return a result, not
+    // throw. The init flow depends on this — a thrown exception
+    // here would abort init, which is the wrong behavior because
+    // the rest of init succeeded.
+    const cases = [
+      { exitCode: 1 },
+      {
+        error: Object.assign(new Error("ENOENT"), { code: "ENOENT" }),
+      },
+      { exitCode: 243, stderrText: "EACCES" },
+      { hang: true },
+    ];
+    for (const opts of cases) {
+      const spawn = makeMockSpawn(opts);
+      const result = await installSkillrepoGlobally({
+        version: "3.1.2",
+        spawn,
+        platform: "linux",
+        timeoutMs: 50,
+        outputMode: "silent",
+      });
+      assert.equal(typeof result, "object");
+      assert.equal(result.success, false);
+      assert.ok(result.errorCode, `errorCode set for ${JSON.stringify(opts)}`);
+      assert.ok(result.error, `error set for ${JSON.stringify(opts)}`);
+    }
+  });
+});
+
+// ── installSkillrepoGlobally — happy path with binary on PATH ──
+
+describe("installSkillrepoGlobally — happy path", () => {
+  // Use installShim from skillrepo-shim helper to put a fake
+  // skillrepo on PATH. After the mock spawn succeeds,
+  // resolveGlobalBinary should find the shim and return success.
+  // (PATH is restored by uninstallShim — no separate originalPath
+  // capture needed.)
+
+  let shim;
+
+  beforeEach(async () => {
+    const { installShim } = await import("../helpers/skillrepo-shim.mjs");
+    const { mkdtempSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const sandbox = mkdtempSync(join(tmpdir(), "sr-globalinstall-"));
+    shim = installShim(sandbox);
+    // Save the sandbox for cleanup
+    shim.sandbox = sandbox;
+  });
+
+  afterEach(async () => {
+    const { uninstallShim } = await import("../helpers/skillrepo-shim.mjs");
+    const { rmSync } = await import("node:fs");
+    uninstallShim(shim);
+    if (shim?.sandbox) rmSync(shim.sandbox, { recursive: true, force: true });
+  });
+
+  it("returns success with binaryPath when npm exits 0 and binary is on PATH", async () => {
+    const spawn = makeMockSpawn({ exitCode: 0 });
+    const result = await installSkillrepoGlobally({
+      version: "3.1.2",
+      spawn,
+    });
+    assert.equal(result.success, true, `expected success, got ${JSON.stringify(result)}`);
+    assert.ok(
+      result.binaryPath,
+      "binaryPath must be set on success",
+    );
+    // The resolved path should be under our sandbox. We check the
+    // sandbox's UNIQUE BASENAME (e.g. `sr-globalinstall-XYZ`)
+    // rather than `.startsWith(shim.binDir)` because Windows can
+    // hand back two different forms of the SAME directory: 8.3
+    // short-name (`C:\Users\RUNNER~1\...`) from `os.tmpdir()` vs
+    // long-name (`C:\Users\runneradmin\...`) from `where.exe`.
+    // The basename is invariant — `mkdtempSync`'s random suffix
+    // doesn't have a short-name alias.
+    const { basename } = await import("node:path");
+    const sandboxName = basename(shim.sandbox);
+    assert.ok(
+      result.binaryPath.includes(sandboxName) &&
+        result.binaryPath.includes("skillrepo"),
+      `expected binaryPath to contain sandbox ${sandboxName} and "skillrepo", got ${result.binaryPath}`,
+    );
+  });
+});
+
+// ── resolveGlobalBinary — npx-cache filtering ───────────────────
+
+describe("resolveGlobalBinary — transient-cache filtering", () => {
+  // The cache-filter logic is integration-tested via the production
+  // path (`installSkillrepoGlobally` happy-path test below confirms
+  // a stable shim is found through the filter). This describe block
+  // covers the negative case: when only transient cache binaries
+  // are on PATH, return null.
+
+  let originalPath;
+  beforeEach(() => {
+    originalPath = process.env.PATH;
+    process.env.PATH = "/nonexistent/dir";
+  });
+  afterEach(() => {
+    if (originalPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalPath;
+  });
+
+  it("returns null when no skillrepo is on PATH", () => {
+    assert.equal(resolveGlobalBinary(), null);
+  });
+});
+
+// ── resolveGlobalBinary — happy path with shim ─────────────────
+
+describe("resolveGlobalBinary — happy path", () => {
+  // PATH is restored by uninstallShim in afterEach — no separate
+  // originalPath capture needed.
+  let shim;
+  let sandbox;
+
+  beforeEach(async () => {
+    const { installShim } = await import("../helpers/skillrepo-shim.mjs");
+    const { mkdtempSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    sandbox = mkdtempSync(join(tmpdir(), "sr-resolveglobal-"));
+    shim = installShim(sandbox);
+  });
+
+  afterEach(async () => {
+    const { uninstallShim } = await import("../helpers/skillrepo-shim.mjs");
+    const { rmSync } = await import("node:fs");
+    uninstallShim(shim);
+    if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  it("finds a stable global binary on PATH and returns its absolute path", async () => {
+    const result = resolveGlobalBinary();
+    assert.ok(result, "expected non-null binary path");
+    // Same Windows 8.3-vs-long-name reasoning as the
+    // `installSkillrepoGlobally — happy path` test above. Compare
+    // by the unique random sandbox basename rather than the full
+    // path prefix.
+    const { basename } = await import("node:path");
+    const sandboxName = basename(sandbox);
+    assert.ok(
+      result.includes(sandboxName) && result.includes("skillrepo"),
+      `expected resolved path to contain sandbox ${sandboxName} and "skillrepo", got ${result}`,
+    );
+  });
+});

package/src/test/lib/mcp-merge.test.mjs

@@ -21,10 +21,16 @@ import { tmpdir } from "node:os";
 
 import { mergeMcpForVendors, printManualMcpInstructions } from "../../lib/mcp-merge.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.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;
 let stdout;
 let stderr;
 
@@ -48,16 +54,16 @@ function setupSandbox() {
   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"));
   stdout = createCaptureStream();
   stderr = createCaptureStream();
 }
 
 function teardownSandbox() {
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
 }
 
@@ -194,7 +200,7 @@ describe("mergeMcpForVendors — user declined", () => {
       mcpUrl: "https://x.com/mcp",
       yes: false, // NOT --yes — will call confirmFn
       io: { stdout, stderr },
-      confirmFn,
+      deps: { confirmFn },
     });
 
     assert.equal(results[0].outcome, "skipped");
@@ -210,7 +216,7 @@ describe("mergeMcpForVendors — user declined", () => {
       mcpUrl: "https://x.com/mcp",
       yes: false,
       io: { stdout, stderr },
-      confirmFn,
+      deps: { confirmFn },
     });
     assert.equal(results[0].outcome, "merged");
     assert.equal(results[1].outcome, "skipped");
@@ -276,7 +282,7 @@ describe("mergeMcpForVendors — failure handling", () => {
       mcpUrl: "https://x.com/mcp",
       yes: false,
       io: { stdout, stderr },
-      confirmFn,
+      deps: { confirmFn },
     });
 
     assert.equal(results.length, 3);

package/src/test/lib/paths.test.mjs

@@ -21,24 +21,30 @@ import {
   claudeSkillsGlobalRoot,
   gitignorePath,
 } from "../../lib/paths.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-paths-"));
   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 });
 }