skillrepo 3.0.0 → 3.1.1

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

@@ -0,0 +1,352 @@
+/**
+ * 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,
+} 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";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+  assertHomeIsolated,
+} from "../helpers/sandbox-home.mjs";
+import { installShim, uninstallShim } from "../helpers/skillrepo-shim.mjs";
+
+let sandbox;
+let originalCwd;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+/** @type {ReturnType<typeof installShim> | undefined} */
+let shimHandle;
+let stdout;
+let stderr;
+
+function ASSERT_HOME_ISOLATED() {
+  // Thin wrapper around the shared helper so the call sites in tests
+  // stay short. Checks BOTH HOME and USERPROFILE so Windows is
+  // actually guarded (os.homedir() reads USERPROFILE on Windows).
+  assertHomeIsolated(tmpdir(), "session-sync tests");
+}
+
+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();
+  originalHomeEnv = captureHome();
+  process.chdir(join(sandbox, "project"));
+  setSandboxHome(join(sandbox, "home"));
+
+  // Put a predictable `skillrepo` shim at the front of PATH so
+  // mergeSessionHook's binary resolver finds it. Saves having to
+  // inject a binaryPath at every call site. The shim helper handles
+  // cross-platform differences (POSIX extension-less shell script
+  // vs Windows .cmd file + PATHEXT lookup + PATH delimiter).
+  shimHandle = installShim(process.env.HOME);
+
+  ASSERT_HOME_ISOLATED();
+
+  stdout = createCaptureStream();
+  stderr = createCaptureStream();
+}
+
+function teardown() {
+  process.chdir(originalCwd);
+  uninstallShim(shimHandle);
+  shimHandle = undefined;
+  restoreHome(originalHomeEnv);
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+// ──────────────────────────────────────────────────────────────────
+
+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");
+  });
+});