skillrepo 3.0.0 → 3.1.1

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;
 }
@@ -484,3 +490,421 @@ describe("runInit — stale-key handling", () => {
     );
   });
 });
+
+// ── Session-sync step 6 (#884) ────────────────────────────────────────
+//
+// INTENT-based coverage of the new step 6 added in v3.1.0. Tests use
+// the PATH-shim trick from session-sync.test.mjs to make
+// `which skillrepo` resolve deterministically: a fake `skillrepo`
+// executable is dropped into `$HOME/bin` and prepended to PATH.
+// Without this, the behavior of these tests would depend on whether
+// a global install exists on the developer's machine.
+//
+// Lower-level installer correctness (hook shape, idempotency,
+// round-trip with remover) is covered in session-hook.test.mjs. These
+// init tests verify the ORCHESTRATION: --yes path, --no-session-sync
+// opt-out, --json output shape, and the non-fatal disk-error path.
+
+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 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(teardownWithShim);
+
+  it("--yes installs the hook at step 6 by default", async () => {
+    // INTENT: the architect-designed default for --yes mode is
+    // "install the hook." CI/onboarding scripts passing --yes should
+    // get a fully-configured project including session sync.
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const settingsPath = join(process.cwd(), ".claude", "settings.local.json");
+    assert.ok(existsSync(settingsPath), "settings.local.json must exist");
+
+    const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    const hasHook = parsed.hooks.SessionStart.flatMap((g) => g.hooks).some(
+      (h) => h.command.includes(_FINGERPRINT),
+    );
+    assert.ok(hasHook, "SkillRepo SessionStart hook must be installed");
+    assert.match(stdout.text(), /SessionStart hook installed/);
+  });
+
+  it("--no-session-sync skips the hook install even with --yes", async () => {
+    // INTENT: the only way CI scripts that bootstrap a project
+    // without starting Claude Code sessions can opt out. Must work
+    // alongside --yes (otherwise --yes would force hook install).
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--no-session-sync"],
+      { stdout, stderr },
+    );
+
+    const settingsPath = join(process.cwd(), ".claude", "settings.local.json");
+    assert.ok(
+      !existsSync(settingsPath),
+      "settings.local.json must NOT be written under --no-session-sync",
+    );
+    assert.match(stdout.text(), /Session sync skipped \(--no-session-sync\)/);
+  });
+
+  it("re-running init is idempotent — exactly one hook entry", async () => {
+    // INTENT: users re-run init for many reasons (switching keys,
+    // updating the config). A duplicate hook would fire sync twice
+    // per session — waste at best, race at worst.
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+    stdout.clear();
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    const skillrepoHooks = parsed.hooks.SessionStart.flatMap(
+      (g) => g.hooks,
+    ).filter((h) => h.command.includes(_FINGERPRINT));
+    assert.equal(skillrepoHooks.length, 1, "exactly one SkillRepo hook");
+  });
+
+  it("--json includes a sessionSync block with action + path", async () => {
+    // INTENT: automation scripts need to know whether session sync
+    // was installed, opted out, or failed. The JSON contract is the
+    // machine-readable channel for that.
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes", "--json"],
+      { stdout, stderr },
+    );
+    const json = JSON.parse(stdout.text());
+    assert.ok(json.sessionSync, "sessionSync must be in --json output");
+    assert.equal(json.sessionSync.action, "installed");
+    assert.equal(json.sessionSync.path, ".claude/settings.local.json");
+  });
+
+  it("--json with --no-session-sync reports action: 'opted-out'", async () => {
+    await runInit(
+      [
+        "--key",
+        VALID_KEY,
+        "--url",
+        serverUrl,
+        "--yes",
+        "--no-session-sync",
+        "--json",
+      ],
+      { stdout, stderr },
+    );
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.sessionSync.action, "opted-out");
+    assert.equal(json.sessionSync.path, null);
+  });
+
+  it("skips session sync entirely when only non-Claude-Code IDEs are targeted (cross-PR review fix)", async () => {
+    // Cross-PR review flagged: before this guard, a user running
+    // `skillrepo init --ide cursor` would get a Claude Code-specific
+    // SessionStart hook written to `.claude/settings.local.json`.
+    // Cursor never reads that file, so the hook was silent useless
+    // state that `skillrepo uninstall` later had to clean up.
+    //
+    // The guard in init.mjs step 6 now skips the install when
+    // `claudeCode` is not in the resolved vendors list AND
+    // `--global` is not passed. This test proves the skip fires.
+    //
+    // Use --ide cursor to force vendors = ["cursor"]. Bypass the
+    // .claude/ auto-detection by creating .cursor/ instead.
+    mkdirSync(join(process.cwd(), ".cursor"), { recursive: true });
+    rmSync(join(process.cwd(), ".claude"), { recursive: true, force: true });
+
+    await runInit(
+      [
+        "--key",
+        VALID_KEY,
+        "--url",
+        serverUrl,
+        "--yes",
+        "--ide",
+        "cursor",
+        "--json",
+      ],
+      { stdout, stderr },
+    );
+
+    const json = JSON.parse(stdout.text());
+    assert.equal(
+      json.sessionSync.action,
+      "not-applicable",
+      "session sync must report 'not-applicable' for non-Claude-Code targets",
+    );
+    assert.equal(json.sessionSync.path, null);
+    // Critical: the settings.local.json file must NOT have been
+    // written. A Cursor user should never see this Claude-specific
+    // file materialize from `skillrepo init`.
+    assert.ok(
+      !existsSync(join(process.cwd(), ".claude", "settings.local.json")),
+      ".claude/settings.local.json must NOT be written for Cursor-only init",
+    );
+  });
+
+  it("still installs session sync under --global even without claudeCode in vendors", async () => {
+    // INTENT: `--global` writes to `~/.claude/settings.local.json`,
+    // which IS Claude Code's user-wide settings path. A user who
+    // runs `skillrepo init --global` (even without `--ide claude`)
+    // is implicitly targeting Claude Code. The guard must allow
+    // this path so `--global` users still get auto-sync.
+    //
+    // Note: the setup() helper already creates `.claude/` in the
+    // project, which would normally push vendors to include
+    // claudeCode. Force vendors = ["cursor"] via --ide to exercise
+    // the "--global overrides vendors" branch.
+    await runInit(
+      [
+        "--key",
+        VALID_KEY,
+        "--url",
+        serverUrl,
+        "--yes",
+        "--global",
+        "--ide",
+        "cursor",
+        "--json",
+      ],
+      { stdout, stderr },
+    );
+
+    const json = JSON.parse(stdout.text());
+    assert.equal(
+      json.sessionSync.action,
+      "installed",
+      "--global must install the hook even when vendors doesn't include claudeCode",
+    );
+    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;
 }