skillrepo 3.0.0 → 3.1.0

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

@@ -484,3 +484,214 @@ 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 { chmodSync as _chmodSync } from "node:fs";
+import { SESSION_HOOK_FINGERPRINT as _FINGERPRINT } from "../../lib/artifact-registry.mjs";
+
+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}`;
+}
+
+describe("runInit — session sync (#884)", () => {
+  beforeEach(setupWithShim);
+  afterEach(teardown);
+
+  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");
+  });
+});

package/src/test/commands/session-sync.test.mjs

@@ -0,0 +1,350 @@
+/**
+ * Unit tests for src/commands/session-sync.mjs (#884).
+ *
+ * INTENT-based coverage of the `skillrepo session-sync enable|disable`
+ * command surface. Lower-level installer correctness (fingerprint,
+ * atomic writes, round-trip with #885 remover) is covered in
+ * `session-hook.test.mjs` — these tests verify the COMMAND wrapper's
+ * behavior: subcommand parsing, flag handling, JSON output, error
+ * propagation.
+ *
+ * HOME isolation enforced in every test. --global paths write to
+ * `~/.claude/settings.local.json` and this guard is the only thing
+ * preventing a misconfigured test from nuking real user state.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  chmodSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runSessionSync } from "../../commands/session-sync.mjs";
+import { buildHookCommand } from "../../lib/mergers/session-hook.mjs";
+import { SESSION_HOOK_FINGERPRINT } from "../../lib/artifact-registry.mjs";
+import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+
+let sandbox;
+let originalCwd;
+let originalHome;
+let stdout;
+let stderr;
+
+function ASSERT_HOME_ISOLATED() {
+  assert.ok(
+    process.env.HOME && process.env.HOME.startsWith(tmpdir()),
+    `HOME must point inside tmpdir. Current HOME="${process.env.HOME}"`,
+  );
+}
+
+function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-cmd-session-sync-"));
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHome = process.env.HOME;
+  process.chdir(join(sandbox, "project"));
+  process.env.HOME = join(sandbox, "home");
+
+  // Put a predictable `skillrepo` shim at the front of PATH so
+  // mergeSessionHook's `which skillrepo` resolves to it. Saves having
+  // to inject a binaryPath at every call site.
+  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}`;
+
+  ASSERT_HOME_ISOLATED();
+
+  stdout = createCaptureStream();
+  stderr = createCaptureStream();
+}
+
+function teardown() {
+  process.chdir(originalCwd);
+  process.env.HOME = originalHome;
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  // Strip the prepended bin dir from PATH to keep subsequent tests clean
+  if (process.env.PATH?.startsWith(join(sandbox ?? "", "home", "bin"))) {
+    process.env.PATH = process.env.PATH.slice(
+      join(sandbox, "home", "bin").length + 1,
+    );
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────
+
+describe("session-sync — subcommand parsing", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("rejects invocation without a subcommand", async () => {
+    // INTENT: ambiguous invocations must fail loudly with guidance,
+    // not silently do nothing. A user who types `skillrepo
+    // session-sync` expects some clear response.
+    await assert.rejects(
+      () => runSessionSync([], { stdout, stderr }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /subcommand/i.test(err.message),
+    );
+  });
+
+  it("rejects unknown subcommands", async () => {
+    await assert.rejects(
+      () => runSessionSync(["status"], { stdout, stderr }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("rejects two subcommands passed together", async () => {
+    await assert.rejects(
+      () => runSessionSync(["enable", "disable"], { stdout, stderr }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /exactly one/i.test(err.message),
+    );
+  });
+});
+
+describe("session-sync enable", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("installs the hook and reports success", async () => {
+    // INTENT: the primary success path — user types `session-sync
+    // enable`, the hook lands, message confirms.
+    ASSERT_HOME_ISOLATED();
+    await runSessionSync(["enable"], { stdout, stderr });
+
+    assert.match(stdout.text(), /installed/i);
+    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(SESSION_HOOK_FINGERPRINT),
+    );
+    assert.ok(hasHook, "SkillRepo hook must be present");
+  });
+
+  it("is idempotent — second enable returns 'unchanged'", async () => {
+    // INTENT: users re-running `session-sync enable` must get a clear
+    // "nothing to do" response, not a duplicate hook.
+    ASSERT_HOME_ISOLATED();
+    await runSessionSync(["enable"], { stdout, stderr });
+    stdout.clear();
+
+    await runSessionSync(["enable"], { stdout, stderr });
+    assert.match(stdout.text(), /already installed/i);
+  });
+
+  it("--json emits structured output with action + command + path", async () => {
+    // INTENT: automation scripts need a deterministic output format.
+    // No ambiguity, no ANSI codes, no surrounding prose.
+    ASSERT_HOME_ISOLATED();
+    await runSessionSync(["enable", "--json"], { stdout, stderr });
+
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.action, "installed");
+    assert.equal(json.path, ".claude/settings.local.json");
+    assert.ok(typeof json.command === "string");
+    assert.ok(json.command.includes(SESSION_HOOK_FINGERPRINT));
+  });
+
+  it("--global writes to the user-wide settings file", async () => {
+    // INTENT: `--global` installs the hook at ~/.claude/settings.local.json
+    // so it fires in EVERY Claude Code session (not just this project).
+    // Used by users who want SkillRepo integration machine-wide.
+    ASSERT_HOME_ISOLATED();
+    await runSessionSync(["enable", "--global"], { stdout, stderr });
+
+    const globalSettings = join(
+      process.env.HOME,
+      ".claude",
+      "settings.local.json",
+    );
+    assert.ok(existsSync(globalSettings));
+    // Project-local file must NOT be touched
+    assert.ok(
+      !existsSync(join(process.cwd(), ".claude", "settings.local.json")),
+      "--global must only touch the user-wide file",
+    );
+  });
+});
+
+describe("session-sync disable", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("removes the hook and reports success", async () => {
+    // INTENT: users disabling the hook must see it gone from the
+    // file immediately, with a clear success message.
+    ASSERT_HOME_ISOLATED();
+    await runSessionSync(["enable"], { stdout, stderr });
+    stdout.clear();
+
+    await runSessionSync(["disable"], { stdout, stderr });
+
+    const settingsPath = join(
+      process.cwd(),
+      ".claude",
+      "settings.local.json",
+    );
+    if (existsSync(settingsPath)) {
+      const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      const hasHook = (parsed.hooks?.SessionStart ?? [])
+        .flatMap((g) => g?.hooks ?? [])
+        .some((h) => h?.command?.includes(SESSION_HOOK_FINGERPRINT));
+      assert.ok(!hasHook, "SkillRepo hook must be gone after disable");
+    }
+    assert.match(stdout.text(), /removed/i);
+  });
+
+  it("reports cleanly when disable runs on a file without the hook", async () => {
+    // INTENT: a user running `session-sync disable` when the hook
+    // isn't installed must get a clear "nothing to do" response, not
+    // an error. This is how automation scripts confirm the final
+    // state is "disabled" regardless of prior state.
+    ASSERT_HOME_ISOLATED();
+    await runSessionSync(["disable"], { stdout, stderr });
+    assert.match(stdout.text(), /not enabled|not installed|nothing to do/i);
+  });
+
+  it("preserves user-authored hooks in the same settings file", async () => {
+    // INTENT: disable must only strip SkillRepo's entry — everything
+    // the user added must survive.
+    ASSERT_HOME_ISOLATED();
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      JSON.stringify(
+        {
+          hooks: {
+            SessionStart: [
+              { hooks: [{ type: "command", command: "echo user-hook" }] },
+              {
+                hooks: [
+                  {
+                    type: "command",
+                    command: buildHookCommand("/some/skillrepo"),
+                  },
+                ],
+              },
+            ],
+          },
+          env: { USER_VAR: "value" },
+        },
+        null,
+        2,
+      ),
+    );
+
+    await runSessionSync(["disable"], { stdout, stderr });
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    // User's hook survives
+    assert.equal(parsed.hooks.SessionStart.length, 1);
+    assert.equal(
+      parsed.hooks.SessionStart[0].hooks[0].command,
+      "echo user-hook",
+    );
+    // User's env survives
+    assert.deepEqual(parsed.env, { USER_VAR: "value" });
+  });
+
+  it("--json emits structured output for the removed case", async () => {
+    ASSERT_HOME_ISOLATED();
+    await runSessionSync(["enable"], { stdout, stderr });
+    stdout.clear();
+
+    await runSessionSync(["disable", "--json"], { stdout, stderr });
+
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.action, "removed");
+    assert.equal(json.path, ".claude/settings.local.json");
+  });
+
+  it("surfaces the parse error in human output when settings.local.json is corrupt", async () => {
+    // Round-2 review gap (both architect + code-reviewer): before
+    // this branch, the corrupt-file path silently misdiagnosed a
+    // broken settings file as "session sync not enabled." Users
+    // had no way to tell from the human output that their file
+    // was the problem. The --json path already surfaced the error;
+    // this test locks the fix for the human output.
+    ASSERT_HOME_ISOLATED();
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      "{ not valid json",
+    );
+
+    await runSessionSync(["disable"], { stdout, stderr });
+
+    const out = stdout.text();
+    assert.match(
+      out,
+      /Cannot parse/i,
+      "corrupt file must produce a visible 'Cannot parse' message, not the generic 'not enabled' message",
+    );
+    assert.doesNotMatch(
+      out,
+      /not enabled/i,
+      "must NOT show the 'not enabled' fallback when the file exists but is corrupt",
+    );
+  });
+
+  it("still emits the parse error via --json for automation consumers", async () => {
+    // Confirms the --json path also surfaces the error (was
+    // already working — this locks the contract in).
+    ASSERT_HOME_ISOLATED();
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      "{ broken",
+    );
+
+    await runSessionSync(["disable", "--json"], { stdout, stderr });
+
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.action, "skipped");
+    assert.ok(json.error, "error field must be present in JSON output");
+    assert.match(json.error, /parse/i);
+  });
+});
+
+describe("session-sync — flag ordering tolerance", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("accepts flags before the subcommand", async () => {
+    // INTENT: users who type `--json enable` vs `enable --json`
+    // expect both to work. Neither the command nor the script it
+    // generates should care about order.
+    ASSERT_HOME_ISOLATED();
+    await runSessionSync(["--json", "enable"], { stdout, stderr });
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.action, "installed");
+  });
+});