skillrepo 3.1.0 → 3.1.2

package/src/test/lib/platform.test.mjs

@@ -0,0 +1,135 @@
+/**
+ * Unit tests for src/lib/platform.mjs (v3.1.1).
+ *
+ * INTENT-BASED. The platform module is the single source of truth
+ * for every platform-specific difference the CLI honors. These
+ * tests lock in the contract that consumers (session-hook merger,
+ * future vendors) depend on. If a future refactor adds a new
+ * convention or changes an existing one, these tests must be
+ * updated — the data flow through this module is load-bearing.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { platform as osPlatform } from "node:os";
+
+import { platformConventions, isWindows } from "../../lib/platform.mjs";
+
+describe("platformConventions", () => {
+  it("returns POSIX conventions on macOS (darwin)", () => {
+    // INTENT: macOS is a POSIX family platform. `which` is the
+    // binary locator; shell supports `|| true` backstop; chmod
+    // works meaningfully; atomic directory rename works. A refactor
+    // that treats macOS as a special case would break every
+    // developer on the team.
+    const conv = platformConventions({ platform: "darwin" });
+    assert.equal(conv.family, "posix");
+    assert.equal(conv.binaryLocator, "which");
+    assert.equal(conv.hookShellSuffix, " || true");
+    assert.equal(conv.supportsPosixPermissions, true);
+    assert.equal(conv.supportsAtomicDirectoryRename, true);
+  });
+
+  it("returns POSIX conventions on Linux", () => {
+    const conv = platformConventions({ platform: "linux" });
+    assert.equal(conv.family, "posix");
+    assert.equal(conv.binaryLocator, "which");
+    assert.equal(conv.hookShellSuffix, " || true");
+    assert.equal(conv.supportsPosixPermissions, true);
+    assert.equal(conv.supportsAtomicDirectoryRename, true);
+  });
+
+  it("returns Windows conventions on win32", () => {
+    // INTENT: Windows has four material differences that can't be
+    // abstracted away:
+    //   1. `where.exe` instead of `which` (no shell binary lookup)
+    //   2. no `|| true` (cmd.exe doesn't know the `true` builtin)
+    //   3. chmod mode bits don't map to the ACL model — applying
+    //      0o600 on Windows looks like it worked but doesn't
+    //      restrict access the way a POSIX 0600 does
+    //   4. renameSync fails on existing directory targets, so
+    //      directory replacement needs a remove-then-rename dance
+    //      with a small non-atomic window
+    // This test locks all four values for Windows — a refactor
+    // that breaks any one of them breaks every Windows user.
+    const conv = platformConventions({ platform: "win32" });
+    assert.equal(conv.family, "windows");
+    assert.equal(conv.binaryLocator, "where");
+    assert.equal(conv.hookShellSuffix, "");
+    assert.equal(conv.supportsPosixPermissions, false);
+    assert.equal(conv.supportsAtomicDirectoryRename, false);
+  });
+
+  it("treats unknown platforms as POSIX (conservative default)", () => {
+    // INTENT: Node supports aix, freebsd, openbsd, sunos, netbsd,
+    // android — all POSIX-family. A newly-released `NodeJS.Platform`
+    // value we've never seen must NOT crash the CLI. Falling back
+    // to POSIX is correct for every non-Windows Node target and
+    // matches how `node:path` / `node:fs` handle the same cases.
+    const conv = platformConventions({ platform: "aix" });
+    assert.equal(conv.family, "posix");
+    assert.equal(conv.binaryLocator, "which");
+  });
+
+  it("uses os.platform() when called without an override", () => {
+    // INTENT: production callers let the override default. Verify
+    // the default correctly reflects the current runtime, so a
+    // CI run on Linux sees POSIX conventions without the test
+    // needing to know the specific platform.
+    const conv = platformConventions();
+    const actualPlatform = osPlatform();
+    if (actualPlatform === "win32") {
+      assert.equal(conv.family, "windows");
+    } else {
+      assert.equal(conv.family, "posix");
+    }
+  });
+
+  it("returns a frozen object — callers cannot mutate conventions at runtime", () => {
+    // INTENT: the whole point of the single-source-of-truth design
+    // is that nobody gets to reach in and rewrite the rules. If a
+    // caller mutated the returned object, the next caller would
+    // see unexpected values. Freezing guarantees isolation.
+    const conv = platformConventions({ platform: "linux" });
+    assert.ok(Object.isFrozen(conv), "conventions object must be frozen");
+    assert.throws(
+      () => {
+        conv.binaryLocator = "pwned";
+      },
+      /Cannot assign to read only property/,
+      "attempting to mutate a frozen convention must throw in strict mode",
+    );
+  });
+
+  it("returns the SAME frozen instance across calls for the same platform", () => {
+    // INTENT: identity guarantee. Two calls with the same platform
+    // return the same object — callers can cache without worrying
+    // about subtle drift between invocations.
+    const a = platformConventions({ platform: "darwin" });
+    const b = platformConventions({ platform: "darwin" });
+    assert.strictEqual(a, b);
+
+    const c = platformConventions({ platform: "win32" });
+    const d = platformConventions({ platform: "win32" });
+    assert.strictEqual(c, d);
+
+    // And of course, two different platforms don't collide:
+    assert.notStrictEqual(a, c);
+  });
+});
+
+describe("isWindows", () => {
+  it("returns true only when platform is win32", () => {
+    assert.equal(isWindows({ platform: "win32" }), true);
+    assert.equal(isWindows({ platform: "darwin" }), false);
+    assert.equal(isWindows({ platform: "linux" }), false);
+    assert.equal(isWindows({ platform: "aix" }), false);
+  });
+
+  it("defaults to os.platform() when called without an override", () => {
+    // INTENT: same default as platformConventions — production
+    // callers get the right answer for their runtime platform.
+    const actual = osPlatform();
+    assert.equal(isWindows(), actual === "win32");
+  });
+});

package/src/test/lib/sync.test.mjs

@@ -39,10 +39,16 @@ import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { globalLastSyncPath } from "../../lib/paths.mjs";
 import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.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 server;
 let serverUrl;
 const VALID_KEY = "sk_live_test123";
@@ -71,9 +77,9 @@ async function setupServer() {
   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"));
 
   server = createMockServer({});
   const port = await server.start();
@@ -83,7 +89,7 @@ async function setupServer() {
 async function teardownServer() {
   if (server) await server.stop();
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
   server = null;
 }
@@ -146,6 +152,10 @@ describe("runSync — empty library", () => {
     assert.equal(result.updated, 0);
     assert.equal(result.removed, 0);
     assert.equal(result.notModified, false);
+    // v3.1.1: no prior .last-sync state → this was a full sync.
+    // init.mjs distinguishes full vs delta to render accurate
+    // zero-counters messages (empty library vs up to date).
+    assert.equal(result.fullSync, true, "no last-sync state means fullSync:true");
   });
 });
 
@@ -338,6 +348,12 @@ describe("runSync — ETag round-trip", () => {
     assert.equal(second.added, 0);
     assert.equal(second.updated, 0);
     assert.equal(second.removed, 0);
+    // v3.1.1: first sync had no prior state → fullSync:true. Second
+    // sync had the first's .last-sync written → fullSync:false.
+    // init.mjs uses this to distinguish the "empty library" vs
+    // "nothing changed since last sync" cases when counters are all 0.
+    assert.equal(first.fullSync, true, "first sync must report fullSync:true");
+    assert.equal(second.fullSync, false, "304 after prior sync must report fullSync:false");
   });
 
   it("304 short-circuit does not delete or modify on-disk skills", async () => {

package/src/test/lib/transient-runners.test.mjs

@@ -0,0 +1,270 @@
+/**
+ * Unit tests for src/lib/transient-runners.mjs (#894 / v3.1.2).
+ *
+ * Covers the three exports:
+ *   - detectTransientRunner — returns the runner's display NAME
+ *     (npx / pnpx / yarn dlx / bunx) or null. Used by init.mjs's
+ *     Next-Steps prefix.
+ *   - isTransientRunnerInvocation — boolean shortcut. Used as the
+ *     gate for auto-install and the npx-guard in mergers/session-hook.
+ *   - isTransientCachePath — boolean for filtering `where`/`which`
+ *     output. Used by the binary locator.
+ *
+ * The boolean shortcut's behavior is also covered transitively by
+ * `cli-config.test.mjs` (which re-exports it). This file specifically
+ * locks in:
+ *   - The runner-NAME return contract (v3.1.2 added this so init's
+ *     Next-Steps shows `pnpx skillrepo list` for pnpm dlx users
+ *     instead of always `npx skillrepo list`).
+ *   - The `isTransientCachePath` filter behavior the binary locator
+ *     depends on.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  detectTransientRunner,
+  isTransientRunnerInvocation,
+  isTransientCachePath,
+  globalInstallCommandFor,
+} from "../../lib/transient-runners.mjs";
+
+// ── detectTransientRunner — returns the runner display name ────────
+
+describe("detectTransientRunner", () => {
+  it("returns null for a vanilla stable-install argv", () => {
+    const result = detectTransientRunner({
+      argv: ["/usr/local/bin/node", "/usr/local/bin/skillrepo"],
+      env: {},
+    });
+    assert.equal(result, null);
+  });
+
+  it("returns 'npx' for an npm npx invocation", () => {
+    const result = detectTransientRunner({
+      argv: [
+        "/usr/local/bin/node",
+        "/Users/alice/.npm/_npx/abc123/node_modules/.bin/skillrepo",
+      ],
+      env: {},
+    });
+    assert.equal(result, "npx");
+  });
+
+  it("returns 'pnpx' for a pnpm dlx invocation (cache substring)", () => {
+    const result = detectTransientRunner({
+      argv: [
+        "/usr/local/bin/node",
+        "/Users/alice/.local/share/pnpm/store/dlx-abc123/node_modules/.bin/skillrepo",
+      ],
+      env: {},
+    });
+    assert.equal(result, "pnpx");
+  });
+
+  it("returns 'yarn dlx' for a yarn berry dlx invocation", () => {
+    const result = detectTransientRunner({
+      argv: [
+        "/usr/local/bin/node",
+        "/Users/alice/project/.yarn/berry/cache/skillrepo-npm-3.1.2-abc/node_modules/skillrepo/bin/skillrepo.mjs",
+      ],
+      env: {},
+    });
+    assert.equal(result, "yarn dlx");
+  });
+
+  it("returns 'bunx' for a bun bunx invocation (cache substring)", () => {
+    const result = detectTransientRunner({
+      argv: [
+        "/usr/local/bin/node",
+        "/Users/alice/.bun/install/cache/skillrepo@3.1.2/node_modules/.bin/skillrepo",
+      ],
+      env: {},
+    });
+    assert.equal(result, "bunx");
+  });
+
+  it("returns 'npx' from `_` env-var fallback when argv path doesn't match", () => {
+    // E.g., a wrapper script symlinks the npx binary somewhere
+    // outside the npx cache. The `_` signal still identifies the
+    // launcher.
+    const result = detectTransientRunner({
+      argv: ["/usr/local/bin/node", "/somewhere/bin/skillrepo"],
+      env: { _: "/usr/local/bin/npx" },
+    });
+    assert.equal(result, "npx");
+  });
+
+  it("returns 'pnpx' from `_` env-var fallback", () => {
+    const result = detectTransientRunner({
+      argv: ["/usr/local/bin/node", "/somewhere/bin/skillrepo"],
+      env: { _: "/usr/local/bin/pnpx" },
+    });
+    assert.equal(result, "pnpx");
+  });
+
+  it("returns 'bunx' from `_` env-var fallback", () => {
+    const result = detectTransientRunner({
+      argv: ["/usr/local/bin/node", "/somewhere/bin/skillrepo"],
+      env: { _: "/Users/alice/.bun/bin/bunx" },
+    });
+    assert.equal(result, "bunx");
+  });
+
+  it("argv signal beats `_` env-var (first-match wins on argv)", () => {
+    // If both signal a runner, argv wins. Realistically these would
+    // signal the SAME runner (npx invocation sets argv to the npx
+    // cache AND `_` to the npx binary), but the test pins the
+    // priority for the rare disagreement case.
+    const result = detectTransientRunner({
+      argv: [
+        "/usr/local/bin/node",
+        "/Users/alice/.bun/install/cache/skillrepo@3.1.2/node_modules/.bin/skillrepo",
+      ],
+      env: { _: "/usr/local/bin/npx" },
+    });
+    // bunx wins because argv is checked first.
+    assert.equal(result, "bunx");
+  });
+
+  it("does not false-positive on a directory named 'dlx-utils' (substring not in pnpm cache)", () => {
+    // Defensive: `/dlx-` is the substring, but a user-named directory
+    // like `/Users/alice/utility-dlx/` doesn't trigger because the
+    // substring requires a leading `/` separator before `dlx-`.
+    const result = detectTransientRunner({
+      argv: ["/usr/local/bin/node", "/Users/alice/utility-dlx/bin/skillrepo"],
+      env: {},
+    });
+    assert.equal(result, null);
+  });
+
+  it("does not false-positive on an `npx`-named user dir without the _npx cache pattern", () => {
+    const result = detectTransientRunner({
+      argv: ["/usr/local/bin/node", "/opt/npxtools/bin/skillrepo"],
+      env: {},
+    });
+    assert.equal(result, null);
+  });
+});
+
+// ── isTransientRunnerInvocation — boolean shortcut ──────────────────
+
+describe("isTransientRunnerInvocation (boolean shortcut)", () => {
+  // The boolean version reads from process.argv / process.env directly
+  // (no override hook for this convenience wrapper). The full table
+  // of detection cases is covered above via detectTransientRunner;
+  // these tests just verify the boolean shape.
+  let originalArgv;
+  let originalUnderscore;
+
+  function setup() {
+    originalArgv = process.argv;
+    originalUnderscore = process.env._;
+    delete process.env._;
+  }
+  function teardown() {
+    process.argv = originalArgv;
+    if (originalUnderscore === undefined) delete process.env._;
+    else process.env._ = originalUnderscore;
+  }
+
+  it("returns true when argv signals a transient runner", () => {
+    setup();
+    try {
+      process.argv = [
+        "/usr/local/bin/node",
+        "/Users/alice/.npm/_npx/abc/skillrepo",
+      ];
+      assert.equal(isTransientRunnerInvocation(), true);
+    } finally {
+      teardown();
+    }
+  });
+
+  it("returns false for a stable-install argv", () => {
+    setup();
+    try {
+      process.argv = ["/usr/local/bin/node", "/usr/local/bin/skillrepo"];
+      assert.equal(isTransientRunnerInvocation(), false);
+    } finally {
+      teardown();
+    }
+  });
+});
+
+// ── isTransientCachePath — used by binary locator ──────────────────
+
+describe("isTransientCachePath", () => {
+  it("identifies an npx cache path", () => {
+    assert.equal(
+      isTransientCachePath("/Users/alice/.npm/_npx/abc/node_modules/.bin/skillrepo"),
+      true,
+    );
+  });
+
+  it("identifies a pnpm dlx cache path", () => {
+    assert.equal(
+      isTransientCachePath("/Users/alice/.local/share/pnpm/store/dlx-abc/node_modules/.bin/skillrepo"),
+      true,
+    );
+  });
+
+  it("identifies a yarn berry cache path", () => {
+    assert.equal(
+      isTransientCachePath(
+        "/Users/alice/proj/.yarn/berry/cache/skillrepo-npm-3.1.2-abc/...",
+      ),
+      true,
+    );
+  });
+
+  it("identifies a bun cache path", () => {
+    assert.equal(
+      isTransientCachePath("/Users/alice/.bun/install/cache/skillrepo@3.1.2/bin/skillrepo"),
+      true,
+    );
+  });
+
+  it("identifies a Windows-style npx cache path", () => {
+    assert.equal(
+      isTransientCachePath(
+        "C:\\Users\\alice\\.npm\\_npx\\abc\\node_modules\\.bin\\skillrepo.cmd",
+      ),
+      true,
+    );
+  });
+
+  it("returns false for a stable global path", () => {
+    assert.equal(isTransientCachePath("/usr/local/bin/skillrepo"), false);
+    assert.equal(isTransientCachePath("/opt/homebrew/bin/skillrepo"), false);
+    assert.equal(
+      isTransientCachePath("C:\\Program Files\\nodejs\\skillrepo.cmd"),
+      false,
+    );
+    assert.equal(
+      isTransientCachePath("/Users/alice/.npm-global/bin/skillrepo"),
+      false,
+    );
+  });
+});
+
+// ── globalInstallCommandFor — per-runner install hint ──────────────
+
+describe("globalInstallCommandFor", () => {
+  it("returns the right install command for each known runner", () => {
+    assert.equal(globalInstallCommandFor("npx"), "npm install -g skillrepo");
+    assert.equal(globalInstallCommandFor("pnpx"), "pnpm add -g skillrepo");
+    // yarn berry has no `yarn global add`; falls back to npm
+    // (documented in the TRANSIENT_RUNNERS comment).
+    assert.equal(globalInstallCommandFor("yarn dlx"), "npm install -g skillrepo");
+    assert.equal(globalInstallCommandFor("bunx"), "bun add -g skillrepo");
+  });
+
+  it("returns null for unknown / null runner names so callers can fall back", () => {
+    assert.equal(globalInstallCommandFor(null), null);
+    assert.equal(globalInstallCommandFor(undefined), null);
+    assert.equal(globalInstallCommandFor(""), null);
+    assert.equal(globalInstallCommandFor("not-a-real-runner"), null);
+  });
+});