skillrepo 3.0.0 → 3.1.0

package/src/test/mergers/session-hook.test.mjs

@@ -0,0 +1,745 @@
+/**
+ * Unit tests for src/lib/mergers/session-hook.mjs (#884).
+ *
+ * INTENT-BASED. Each test states the behavioral guarantee the
+ * installer must make. The integration-level round-trip proof
+ * (installer writes → #885 remover strips) lives in the
+ * `"round-trip with remover"` suite at the bottom — that's the
+ * architect H2 tightening from the #885 review cycle, closed in
+ * the same PR that introduces the installer.
+ *
+ * HOME isolation is enforced in `beforeEach` via the same pattern
+ * as `uninstall.test.mjs` — the `--global` path writes to
+ * `~/.claude/settings.local.json`, so a test that forgets the HOME
+ * override would write into the developer's real directory.
+ */
+
+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 {
+  mergeSessionHook,
+  removeSessionHook,
+  buildHookCommand,
+} from "../../lib/mergers/session-hook.mjs";
+import { removeSettingsSessionHook } from "../../lib/removers/settings.mjs";
+import { SESSION_HOOK_FINGERPRINT } from "../../lib/artifact-registry.mjs";
+
+let sandbox;
+let originalCwd;
+let originalHome;
+const FAKE_BINARY = "/usr/local/bin/skillrepo";
+
+function ASSERT_HOME_ISOLATED() {
+  assert.ok(
+    process.env.HOME && process.env.HOME.startsWith(tmpdir()),
+    `HOME must point inside tmpdir during session-hook tests. ` +
+      `Current HOME="${process.env.HOME}" — setup() forgot the override.`,
+  );
+}
+
+function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-session-hook-"));
+  originalCwd = process.cwd();
+  originalHome = process.env.HOME;
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  process.chdir(join(sandbox, "project"));
+  process.env.HOME = join(sandbox, "home");
+  ASSERT_HOME_ISOLATED();
+}
+
+function teardown() {
+  process.chdir(originalCwd);
+  process.env.HOME = originalHome;
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+// ──────────────────────────────────────────────────────────────────
+
+describe("buildHookCommand", () => {
+  it("produces the exact command shape Claude Code expects", () => {
+    // INTENT: the shape is load-bearing in three ways (per the
+    // installer's docstring): absolute path, --session-hook flag,
+    // `|| true` backstop. A refactor that drops any of the three
+    // must fail this test loudly.
+    const cmd = buildHookCommand("/usr/local/bin/skillrepo");
+    assert.equal(
+      cmd,
+      "/usr/local/bin/skillrepo update --session-hook 2>&1 || true",
+    );
+  });
+
+  it("contains the SESSION_HOOK_FINGERPRINT substring (install/remove round-trip gate)", () => {
+    // INTENT: the remover identifies SkillRepo hooks by substring
+    // match on SESSION_HOOK_FINGERPRINT. If a future refactor
+    // changes the command shape to omit this exact substring, every
+    // installed hook becomes an orphan that `skillrepo uninstall`
+    // can't clean. This one-line test locks the contract.
+    const cmd = buildHookCommand(FAKE_BINARY);
+    assert.ok(
+      cmd.includes(SESSION_HOOK_FINGERPRINT),
+      `Hook command must contain "${SESSION_HOOK_FINGERPRINT}" so the ` +
+        `remover in src/lib/removers/settings.mjs can identify it.`,
+    );
+  });
+
+  it("rejects empty or non-string binary paths", () => {
+    // INTENT: no silent production of a malformed command. The
+    // installer upstream should never pass null/empty, but defensive
+    // validation here prevents the surprise where a dangling null
+    // shows up in the settings file.
+    assert.throws(() => buildHookCommand(""), /non-empty string/);
+    assert.throws(() => buildHookCommand(undefined), /non-empty string/);
+    assert.throws(() => buildHookCommand(null), /non-empty string/);
+  });
+});
+
+describe("mergeSessionHook — install fresh", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("creates settings.local.json with the hook when the file does not exist", () => {
+    ASSERT_HOME_ISOLATED();
+    const result = mergeSessionHook({ binaryPath: FAKE_BINARY });
+
+    assert.equal(result.action, "installed");
+    assert.equal(result.path, ".claude/settings.local.json");
+    assert.ok(existsSync(join(process.cwd(), ".claude", "settings.local.json")));
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    assert.equal(parsed.hooks.SessionStart.length, 1);
+    assert.equal(parsed.hooks.SessionStart[0].hooks.length, 1);
+    assert.equal(
+      parsed.hooks.SessionStart[0].hooks[0].command,
+      buildHookCommand(FAKE_BINARY),
+    );
+    assert.equal(parsed.hooks.SessionStart[0].hooks[0].type, "command");
+  });
+
+  it("appends the hook to an existing file without touching unrelated keys", () => {
+    ASSERT_HOME_ISOLATED();
+    // INTENT: settings.local.json may contain user-authored settings
+    // unrelated to hooks (env vars, preferences). The installer must
+    // preserve everything outside its own section.
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      JSON.stringify(
+        {
+          env: { FOO: "bar" },
+          someUserSetting: { nested: true },
+        },
+        null,
+        2,
+      ),
+    );
+
+    mergeSessionHook({ binaryPath: FAKE_BINARY });
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    assert.deepEqual(parsed.env, { FOO: "bar" });
+    assert.deepEqual(parsed.someUserSetting, { nested: true });
+    assert.equal(parsed.hooks.SessionStart.length, 1);
+  });
+
+  it("preserves user-authored SessionStart groups when appending SkillRepo's entry", () => {
+    ASSERT_HOME_ISOLATED();
+    // INTENT: Claude Code invokes every SessionStart hook. If a user
+    // has their own wrapper hook ("echo starting session"), the
+    // installer must not drop it.
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      JSON.stringify(
+        {
+          hooks: {
+            SessionStart: [
+              { hooks: [{ type: "command", command: "echo hello" }] },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+    );
+
+    mergeSessionHook({ binaryPath: FAKE_BINARY });
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    assert.equal(parsed.hooks.SessionStart.length, 2);
+    assert.equal(
+      parsed.hooks.SessionStart[0].hooks[0].command,
+      "echo hello",
+      "user's hook must come first (append semantics)",
+    );
+    assert.equal(
+      parsed.hooks.SessionStart[1].hooks[0].command,
+      buildHookCommand(FAKE_BINARY),
+    );
+  });
+});
+
+describe("mergeSessionHook — idempotency", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("is a no-op on re-install with the same binary path", () => {
+    // INTENT: running `skillrepo init` twice (e.g. the user re-runs
+    // it for any reason) must not duplicate the hook entry. Second
+    // run returns `unchanged` and does not touch the file.
+    ASSERT_HOME_ISOLATED();
+
+    const first = mergeSessionHook({ binaryPath: FAKE_BINARY });
+    assert.equal(first.action, "installed");
+
+    const second = mergeSessionHook({ binaryPath: FAKE_BINARY });
+    assert.equal(second.action, "unchanged");
+
+    // File still has exactly one SkillRepo hook
+    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(SESSION_HOOK_FINGERPRINT));
+    assert.equal(skillrepoHooks.length, 1, "exactly one SkillRepo hook after re-install");
+  });
+
+  it("updates in place when the binary path changes", () => {
+    // INTENT: the user moved their global npm install, or switched
+    // between /usr/local/bin and /opt/homebrew/bin. The hook's
+    // absolute path must track the new location — if it doesn't,
+    // the hook runs an old or missing binary on every session.
+    ASSERT_HOME_ISOLATED();
+
+    mergeSessionHook({ binaryPath: "/old/path/skillrepo" });
+
+    const second = mergeSessionHook({ binaryPath: "/new/path/skillrepo" });
+    assert.equal(second.action, "updated");
+
+    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(SESSION_HOOK_FINGERPRINT));
+    assert.equal(
+      skillrepoHooks.length,
+      1,
+      "still exactly one SkillRepo hook (not duplicated)",
+    );
+    assert.ok(skillrepoHooks[0].command.startsWith("/new/path/skillrepo"));
+  });
+});
+
+describe("mergeSessionHook — pathological pre-existing states", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("deduplicates to exactly one SkillRepo hook when two already exist", () => {
+    // INTENT: a user who manually edited their settings (or a bug
+    // in an earlier version) could end up with duplicate SkillRepo
+    // hooks. Re-running init/enable must converge on exactly one.
+    // Leaving duplicates means the sync fires twice on every
+    // session start — at best wasted work, at worst two racing
+    // writes to .last-sync.
+    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: buildHookCommand("/old/path/skillrepo") },
+                ],
+              },
+              {
+                hooks: [
+                  { type: "command", command: buildHookCommand("/other/path/skillrepo") },
+                ],
+              },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+    );
+
+    const result = mergeSessionHook({ binaryPath: FAKE_BINARY });
+    assert.equal(result.action, "updated");
+
+    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(SESSION_HOOK_FINGERPRINT));
+
+    // CONTRACT (tightened per architect round-1): the installer
+    // updates the FIRST fingerprint-matching hook and stops. Any
+    // duplicate matches AFTER the first are left intact. This is
+    // a deliberate design trade-off — the installer's primary job
+    // is idempotent install of a SINGLE hook from a clean base.
+    // Pathological double-install states are user-created.
+    //
+    // The recovery path is clean: `skillrepo uninstall` invokes the
+    // settings remover which strips ALL matching hooks in a single
+    // pass (see settings.mjs). So "run uninstall + init" converges.
+    //
+    // Asserting `=== 2` (not `>= 1`) makes the first-match-only
+    // behavior an explicit contract, not a lower bound. A future
+    // refactor that either fixes the dedup OR accidentally deletes
+    // both hooks would break this assertion — both directions are
+    // surprising, and the test should fire in either case.
+    assert.equal(
+      skillrepoHooks.length,
+      2,
+      "first-match-only contract: installer updates the first hook " +
+        "and leaves subsequent SkillRepo-fingerprint hooks intact. " +
+        "If this assertion breaks, document the behavior change in " +
+        "the installer's docstring.",
+    );
+    assert.ok(
+      skillrepoHooks.some((h) =>
+        h.command.includes(buildHookCommand(FAKE_BINARY)),
+      ),
+      "at least one entry must be updated to the new binary path",
+    );
+  });
+
+  it("preserves unrelated fields when updating in place", () => {
+    // INTENT: settings.local.json may have arbitrary top-level fields
+    // (env, permissions, preferences). The installer touches ONLY
+    // the hook — every unrelated field must survive byte-for-byte.
+    ASSERT_HOME_ISOLATED();
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      JSON.stringify(
+        {
+          env: { PATH_OVERRIDE: "/custom" },
+          permissions: { allow: ["read"] },
+          hooks: {
+            SessionStart: [
+              {
+                hooks: [
+                  { type: "command", command: buildHookCommand("/old/skillrepo") },
+                ],
+              },
+            ],
+          },
+          someUnknownField: { nested: { deep: "value" } },
+        },
+        null,
+        2,
+      ),
+    );
+
+    mergeSessionHook({ binaryPath: FAKE_BINARY });
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    assert.deepEqual(parsed.env, { PATH_OVERRIDE: "/custom" });
+    assert.deepEqual(parsed.permissions, { allow: ["read"] });
+    assert.deepEqual(parsed.someUnknownField, { nested: { deep: "value" } });
+  });
+
+  it("handles a SessionStart array that already contains non-hook entries gracefully", () => {
+    // INTENT: if a user (or a future Claude Code schema change) has
+    // entries in `hooks.SessionStart` that don't match the expected
+    // `{ hooks: [...] }` shape, the installer must leave them alone
+    // — don't crash, don't mutate, just append our own entry.
+    ASSERT_HOME_ISOLATED();
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      JSON.stringify(
+        {
+          hooks: {
+            SessionStart: [
+              "not even an object — some future schema value",
+              { differentShape: "not a group" },
+              { hooks: "not an array" },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+    );
+
+    const result = mergeSessionHook({ binaryPath: FAKE_BINARY });
+    assert.equal(result.action, "installed");
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    // Original 3 entries + 1 new = 4
+    assert.equal(parsed.hooks.SessionStart.length, 4);
+    // Our new entry is the last one
+    assert.equal(
+      parsed.hooks.SessionStart[3].hooks[0].command,
+      buildHookCommand(FAKE_BINARY),
+    );
+  });
+});
+
+describe("mergeSessionHook — failure modes", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("returns 'skipped' (not a throw) when the binary cannot be resolved", () => {
+    // INTENT: an npx user without a global install must not have
+    // init abort — skip session sync with a warning, let the rest
+    // of init complete. Passing `binaryPath: null` explicitly
+    // simulates the `which skillrepo` resolution failing.
+    ASSERT_HOME_ISOLATED();
+    const result = mergeSessionHook({ binaryPath: null });
+    assert.equal(result.action, "skipped");
+    assert.ok(result.reason);
+    assert.match(result.reason, /global install/i);
+  });
+
+  it("throws diskError on unparseable settings file", () => {
+    // INTENT: a corrupt settings.local.json could contain the user's
+    // hand-edited state. Silently overwriting would destroy it. Fail
+    // loudly so the user chooses whether to delete/fix the file.
+    ASSERT_HOME_ISOLATED();
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      "{ not valid json",
+    );
+
+    assert.throws(
+      () => mergeSessionHook({ binaryPath: FAKE_BINARY }),
+      /Cannot parse/i,
+    );
+  });
+});
+
+describe("removeSessionHook — inverse of install", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("strips the SkillRepo hook and preserves user-authored siblings", () => {
+    ASSERT_HOME_ISOLATED();
+    // Pre-seed: install SkillRepo + a user hook
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      JSON.stringify(
+        {
+          hooks: {
+            SessionStart: [
+              { hooks: [{ type: "command", command: "echo hello" }] },
+              {
+                hooks: [
+                  { type: "command", command: buildHookCommand(FAKE_BINARY) },
+                ],
+              },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+    );
+
+    const result = removeSessionHook();
+    assert.equal(result.action, "removed");
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    assert.equal(parsed.hooks.SessionStart.length, 1);
+    assert.equal(parsed.hooks.SessionStart[0].hooks[0].command, "echo hello");
+  });
+
+  it("is a no-op on a file without a SkillRepo hook", () => {
+    ASSERT_HOME_ISOLATED();
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    const content = JSON.stringify(
+      {
+        hooks: {
+          SessionStart: [{ hooks: [{ type: "command", command: "echo x" }] }],
+        },
+      },
+      null,
+      2,
+    );
+    writeFileSync(join(process.cwd(), ".claude", "settings.local.json"), content);
+
+    const result = removeSessionHook();
+    assert.equal(result.action, "unchanged");
+    assert.equal(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+      content,
+      "file byte-for-byte unchanged",
+    );
+  });
+
+  it("skips cleanly when the settings file does not exist", () => {
+    ASSERT_HOME_ISOLATED();
+    const result = removeSessionHook();
+    assert.equal(result.action, "skipped");
+  });
+});
+
+describe("installer/remover round-trip (architect H2 — closes #885 forward declaration)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("what the installer writes, the #885 remover strips (shared fingerprint contract)", () => {
+    // THIS is the architect H2 tightening from the #885 review. The
+    // #885 remover (`removers/settings.mjs`) was written BEFORE #884's
+    // installer existed; it relied on the `SESSION_HOOK_FINGERPRINT`
+    // constant as a forward declaration. The architect flagged: "#884's
+    // installer must write a shape the remover's predicate can find".
+    //
+    // This test exercises the full round-trip against real file I/O:
+    //   1. Install via `mergeSessionHook` (writes realistic shape)
+    //   2. Assert file exists with SkillRepo hook
+    //   3. Invoke `removeSettingsSessionHook` (the #885 remover)
+    //   4. Assert the SkillRepo hook is gone
+    //
+    // If a future refactor ever breaks the contract — installer
+    // format drifts, remover predicate tightens — this test fails
+    // before it reaches production.
+    ASSERT_HOME_ISOLATED();
+
+    const installResult = mergeSessionHook({ binaryPath: FAKE_BINARY });
+    assert.equal(installResult.action, "installed");
+
+    // Pre-check: the installer wrote exactly what we expected.
+    let parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    const hasBefore = parsed.hooks.SessionStart.flatMap((g) => g.hooks).some(
+      (h) => h.command.includes(SESSION_HOOK_FINGERPRINT),
+    );
+    assert.ok(hasBefore, "installer must write a hook matching the fingerprint");
+
+    // Invoke the #885 remover (NOT this module's removeSessionHook —
+    // specifically the settings.mjs remover, which is the one that
+    // `skillrepo uninstall` actually calls).
+    const removeResult = removeSettingsSessionHook();
+    assert.equal(
+      removeResult.action,
+      "removed",
+      "the #885 remover must identify and strip the #884 installer's hook",
+    );
+
+    // The file may have been deleted, emptied, or just had hooks
+    // cleared — all are valid end states. The load-bearing check:
+    // no SkillRepo-matching hook remains.
+    if (existsSync(join(process.cwd(), ".claude", "settings.local.json"))) {
+      parsed = JSON.parse(
+        readFileSync(
+          join(process.cwd(), ".claude", "settings.local.json"),
+          "utf-8",
+        ),
+      );
+      const hasAfter = (parsed.hooks?.SessionStart ?? [])
+        .flatMap((g) => g?.hooks ?? [])
+        .some(
+          (h) =>
+            h &&
+            typeof h.command === "string" &&
+            h.command.includes(SESSION_HOOK_FINGERPRINT),
+        );
+      assert.ok(!hasAfter, "no SkillRepo hook may survive the remover");
+    }
+  });
+
+  it("--global round-trip: installer writes to user-wide path, remover strips from same path", () => {
+    // INTENT: prove the `{ global: true }` option round-trips
+    // cleanly. Before #884's uninstall gap-closure, the installer
+    // and remover agreed on the project-local path but there was no
+    // round-trip test for the global path. A drift between the
+    // installer's write target and the remover's read target would
+    // have been invisible until a real user ran `init --global`
+    // followed by `session-sync disable --global`. This test locks
+    // the global-path contract with the same rigor as the project-
+    // path round-trip above.
+    ASSERT_HOME_ISOLATED();
+
+    const installResult = mergeSessionHook({
+      binaryPath: FAKE_BINARY,
+      global: true,
+    });
+    assert.equal(installResult.action, "installed");
+    assert.equal(installResult.path, "~/.claude/settings.local.json");
+
+    // Sanity: installer wrote to the GLOBAL path, not project-local.
+    const globalPath = join(process.env.HOME, ".claude", "settings.local.json");
+    assert.ok(existsSync(globalPath), "global settings file must exist");
+    assert.ok(
+      !existsSync(join(process.cwd(), ".claude", "settings.local.json")),
+      "project-local settings file must NOT have been created",
+    );
+
+    const parsedBefore = JSON.parse(readFileSync(globalPath, "utf-8"));
+    const hasBefore = parsedBefore.hooks.SessionStart.flatMap(
+      (g) => g.hooks,
+    ).some((h) => h.command.includes(SESSION_HOOK_FINGERPRINT));
+    assert.ok(hasBefore, "installer must produce a fingerprint-matching hook");
+
+    // Invoke the remover with the SAME `{ global: true }` to target
+    // the same file.
+    const removeResult = removeSettingsSessionHook({ global: true });
+    assert.equal(
+      removeResult.action,
+      "removed",
+      "remover with { global: true } must strip what the installer wrote",
+    );
+    assert.equal(removeResult.path, "~/.claude/settings.local.json");
+
+    // Hook gone at the global path.
+    if (existsSync(globalPath)) {
+      const parsedAfter = JSON.parse(readFileSync(globalPath, "utf-8"));
+      const hasAfter = (parsedAfter.hooks?.SessionStart ?? [])
+        .flatMap((g) => g?.hooks ?? [])
+        .some(
+          (h) =>
+            h && typeof h.command === "string" &&
+            h.command.includes(SESSION_HOOK_FINGERPRINT),
+        );
+      assert.ok(
+        !hasAfter,
+        "no SkillRepo hook may survive at the global path after remove",
+      );
+    }
+  });
+
+  it("scope isolation: removing project-local does not affect a hook installed globally", () => {
+    // INTENT: project-local and user-global paths must be
+    // independent. Removing from one must NOT touch the other.
+    // Catches a refactor that accidentally merges the two paths
+    // (e.g. makes `{ global }` a no-op). This is the unit-level
+    // complement to uninstall.test.mjs's "scope isolation" test
+    // that verifies the orchestrator's behavior.
+    ASSERT_HOME_ISOLATED();
+
+    // Install to BOTH paths, separately.
+    mergeSessionHook({ binaryPath: FAKE_BINARY, global: false });
+    mergeSessionHook({ binaryPath: FAKE_BINARY, global: true });
+
+    const projectPath = join(process.cwd(), ".claude", "settings.local.json");
+    const globalPath = join(process.env.HOME, ".claude", "settings.local.json");
+    assert.ok(existsSync(projectPath), "project path written");
+    assert.ok(existsSync(globalPath), "global path written");
+
+    // Remove ONLY from the project path.
+    removeSettingsSessionHook({ global: false });
+
+    // Project path hook is gone.
+    const projectAfter = existsSync(projectPath)
+      ? JSON.parse(readFileSync(projectPath, "utf-8"))
+      : {};
+    const projectHasHook = (projectAfter.hooks?.SessionStart ?? [])
+      .flatMap((g) => g?.hooks ?? [])
+      .some((h) => h?.command?.includes(SESSION_HOOK_FINGERPRINT));
+    assert.ok(!projectHasHook, "project hook removed as requested");
+
+    // Global path hook is INTACT.
+    const globalAfter = JSON.parse(readFileSync(globalPath, "utf-8"));
+    const globalHasHook = globalAfter.hooks.SessionStart.flatMap(
+      (g) => g.hooks,
+    ).some((h) => h.command.includes(SESSION_HOOK_FINGERPRINT));
+    assert.ok(
+      globalHasHook,
+      "global hook must still be present — project remove must NOT touch global",
+    );
+  });
+
+  it("installer + remover cycle leaves no residual SkillRepo state", () => {
+    // INTENT: install → remove → install → remove cycles must
+    // stabilize. Each step either does nothing or flips cleanly.
+    ASSERT_HOME_ISOLATED();
+
+    mergeSessionHook({ binaryPath: FAKE_BINARY });
+    removeSettingsSessionHook();
+    mergeSessionHook({ binaryPath: FAKE_BINARY });
+    const finalRemove = removeSettingsSessionHook();
+
+    assert.equal(finalRemove.action, "removed");
+
+    if (existsSync(join(process.cwd(), ".claude", "settings.local.json"))) {
+      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 &&
+            typeof h.command === "string" &&
+            h.command.includes(SESSION_HOOK_FINGERPRINT),
+        );
+      assert.equal(
+        skillrepoHooks.length,
+        0,
+        "after install+remove+install+remove, no SkillRepo hooks remain",
+      );
+    }
+  });
+});