skillrepo 4.0.0 → 4.2.0

package/src/test/mergers/agent-hook-claude-shape.test.mjs

@@ -0,0 +1,518 @@
+/**
+ * Unit tests for `lib/mergers/agent-hook-claude-shape.mjs` (#1240).
+ *
+ * INTENT-BASED. Each test states the behavioral guarantee the
+ * installer or uninstaller must make. Round-trip preservation under
+ * concurrent multi-tool merges is the load-bearing safety property
+ * (Gemini's settings.json, Codex's hooks.json, and the per-tool
+ * Copilot file are all surfaces other extensions extend).
+ *
+ * HOME isolation enforced in `beforeEach` via the shared sandbox-home
+ * helper — every cohort hook config lives under `os.homedir()`, so a
+ * test that forgets the override would write into the developer's
+ * real home.
+ */
+
+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, homedir } from "node:os";
+
+import {
+  buildClaudeShapeEntry,
+  mergeClaudeShapeAgentHook,
+  unmergeClaudeShapeAgentHook,
+} from "../../lib/mergers/agent-hook-claude-shape.mjs";
+import {
+  AGENT_HOOK_COMMAND,
+  AGENT_HOOK_FINGERPRINT,
+} from "../../lib/artifact-registry.mjs";
+import { getAgentByKey } from "../../lib/agent-registry.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+  assertHomeIsolated,
+} from "../helpers/sandbox-home.mjs";
+
+let sandbox;
+let originalHomeEnv;
+
+function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-agent-hook-claude-"));
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalHomeEnv = captureHome();
+  setSandboxHome(join(sandbox, "home"));
+  assertHomeIsolated(tmpdir(), "agent-hook-claude-shape tests");
+}
+
+function teardown() {
+  restoreHome(originalHomeEnv);
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+// ──────────────────────────────────────────────────────────────────
+
+describe("buildClaudeShapeEntry", () => {
+  it("merges entryFields with the canonical command (command always wins)", () => {
+    // INTENT: a registry author who accidentally sets `command:
+    // "wrong"` in entryFields cannot override the AGENT_HOOK_COMMAND.
+    // The explicit assignment in buildClaudeShapeEntry is the gate.
+    const entry = buildClaudeShapeEntry({
+      type: "command",
+      timeout: 60000,
+      command: "this-must-be-overridden",
+    });
+    assert.equal(entry.command, AGENT_HOOK_COMMAND);
+    assert.equal(entry.type, "command");
+    assert.equal(entry.timeout, 60000);
+  });
+
+  it("works with no entryFields argument (Cursor never passes any)", () => {
+    const entry = buildClaudeShapeEntry();
+    assert.deepEqual(entry, { command: AGENT_HOOK_COMMAND });
+  });
+
+  it("contains AGENT_HOOK_FINGERPRINT in the command (round-trip gate)", () => {
+    // INTENT: the remover identifies SkillRepo entries by fingerprint
+    // substring. If a future refactor changes the command without
+    // preserving the fingerprint, every installed hook becomes an
+    // orphan that uninstall can't clean.
+    const entry = buildClaudeShapeEntry({ type: "command" });
+    assert.ok(
+      entry.command.includes(AGENT_HOOK_FINGERPRINT),
+      `Hook command "${entry.command}" must contain AGENT_HOOK_FINGERPRINT "${AGENT_HOOK_FINGERPRINT}"`,
+    );
+  });
+});
+
+describe("mergeClaudeShapeAgentHook (gemini)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("first install creates the file with claude-shape JSON including matcher and name (#1242)", () => {
+    const r = mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "installed");
+    assert.equal(r.path, "~/.gemini/settings.json");
+
+    const filePath = join(homedir(), ".gemini", "settings.json");
+    assert.ok(existsSync(filePath));
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    assert.deepEqual(parsed, {
+      hooks: {
+        SessionStart: [
+          {
+            // Gemini-specific group field: matcher "*" required for
+            // the hook to fire.
+            matcher: "*",
+            hooks: [
+              {
+                name: "skillrepo-update",
+                type: "command",
+                timeout: 60000,
+                command: AGENT_HOOK_COMMAND,
+              },
+            ],
+          },
+        ],
+      },
+    });
+  });
+
+  it("re-running on a fresh install returns 'unchanged' (idempotent)", () => {
+    mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    const r2 = mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r2.action, "unchanged");
+  });
+
+  it("preserves user-authored OTHER hook entries (multi-tool merge surface)", () => {
+    // Real-world: Gemini's settings.json is also where users put
+    // their own hook configurations, including hooks for OTHER
+    // events. The merger must not touch anything outside its own
+    // SkillRepo entry.
+    const filePath = join(homedir(), ".gemini", "settings.json");
+    mkdirSync(join(homedir(), ".gemini"), { recursive: true });
+    writeFileSync(
+      filePath,
+      JSON.stringify(
+        {
+          // Top-level user setting unrelated to hooks
+          theme: "dark",
+          hooks: {
+            // Existing user-authored hook on the SAME event
+            SessionStart: [
+              {
+                hooks: [
+                  { type: "command", command: "user-script.sh" },
+                ],
+              },
+            ],
+            // User-authored hook on a DIFFERENT event
+            UserPromptSubmit: [
+              { hooks: [{ type: "command", command: "another-script.sh" }] },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+    );
+
+    const r = mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "installed");
+
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    // Top-level user setting preserved
+    assert.equal(parsed.theme, "dark");
+    // Different-event hook untouched
+    assert.deepEqual(parsed.hooks.UserPromptSubmit, [
+      { hooks: [{ type: "command", command: "another-script.sh" }] },
+    ]);
+    // SessionStart now has BOTH the user's group AND the SkillRepo group
+    assert.equal(parsed.hooks.SessionStart.length, 2);
+    assert.equal(
+      parsed.hooks.SessionStart[0].hooks[0].command,
+      "user-script.sh",
+    );
+    // SkillRepo group includes Gemini's required `matcher: "*"` (#1242)
+    assert.equal(parsed.hooks.SessionStart[1].matcher, "*");
+    assert.equal(
+      parsed.hooks.SessionStart[1].hooks[0].command,
+      AGENT_HOOK_COMMAND,
+    );
+  });
+
+  it("dedupes prior duplicate SkillRepo entries on re-install (exhaustive walk)", () => {
+    // INTENT: the symmetric installer-remover invariant. The remover
+    // strips ALL fingerprint-matching entries; the installer must
+    // also handle ALL of them. If a prior buggy run (or a manual
+    // edit) left two SkillRepo entries, re-running install must
+    // collapse them to exactly one.
+    const filePath = join(homedir(), ".gemini", "settings.json");
+    mkdirSync(join(homedir(), ".gemini"), { recursive: true });
+    writeFileSync(
+      filePath,
+      JSON.stringify({
+        hooks: {
+          SessionStart: [
+            {
+              hooks: [
+                { type: "command", timeout: 60000, command: AGENT_HOOK_COMMAND },
+                // Duplicate from a prior buggy run, in the same group
+                { type: "command", timeout: 30000, command: AGENT_HOOK_COMMAND },
+              ],
+            },
+            {
+              // Another duplicate, in a different group
+              hooks: [
+                { type: "command", command: AGENT_HOOK_COMMAND },
+              ],
+            },
+          ],
+        },
+      }),
+    );
+
+    const r = mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "updated");
+
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    // Walk all groups, count fingerprint-matching entries
+    let count = 0;
+    for (const group of parsed.hooks.SessionStart) {
+      for (const h of group.hooks ?? []) {
+        if (typeof h?.command === "string" && h.command.includes("skillrepo update --silent")) {
+          count += 1;
+        }
+      }
+    }
+    assert.equal(count, 1, "exactly one SkillRepo entry must remain after dedupe");
+  });
+
+  it("Phase-0-era upgrade path: adds matcher to a group missing it (#1242)", () => {
+    // INTENT: a hook installed under Phase 0 has the entry but NOT
+    // the group-level `matcher: "*"` field. On the first run after
+    // the Phase 2 upgrade, the merger must detect the missing field
+    // and add it — otherwise Gemini silently filters out the group
+    // and the hook never fires post-upgrade.
+    //
+    // Construct a Phase-0-shaped file (entry has Phase 0's
+    // `{ type, timeout, command }` only, no `name`; group has no
+    // `matcher`).
+    const filePath = join(homedir(), ".gemini", "settings.json");
+    mkdirSync(join(homedir(), ".gemini"), { recursive: true });
+    writeFileSync(
+      filePath,
+      JSON.stringify({
+        hooks: {
+          SessionStart: [
+            {
+              // No matcher — Phase 0 era
+              hooks: [
+                {
+                  type: "command",
+                  timeout: 60000,
+                  command: AGENT_HOOK_COMMAND,
+                },
+              ],
+            },
+          ],
+        },
+      }),
+    );
+
+    const r = mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "updated");
+
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    // Two-sided assertion: BOTH the group-level field add AND the
+    // entry-level replacement must happen on the upgrade. A regression
+    // that drops one side (e.g. adds matcher but doesn't update the
+    // entry to the Phase-2 shape) would otherwise pass with only one
+    // assertion. QA round-2 (#1239) flagged this gap.
+    const group = parsed.hooks.SessionStart[0];
+    const entry = group.hooks[0];
+    // Group-level: matcher added by the upgrade-path loop
+    assert.equal(group.matcher, "*");
+    // Entry-level: full Phase-2 entry shape (name is the new field)
+    assert.equal(entry.name, "skillrepo-update");
+    assert.equal(entry.type, "command");
+    assert.equal(entry.timeout, 60000);
+    assert.equal(entry.command, AGENT_HOOK_COMMAND);
+  });
+
+  it("updates the SkillRepo entry in place when the timeout changes", () => {
+    // Simulate a future registry update where Gemini's timeout
+    // moves from 60000 to 120000. Re-running install should REPLACE
+    // the existing entry rather than append a duplicate.
+    const filePath = join(homedir(), ".gemini", "settings.json");
+    mkdirSync(join(homedir(), ".gemini"), { recursive: true });
+    writeFileSync(
+      filePath,
+      JSON.stringify({
+        hooks: {
+          SessionStart: [
+            {
+              hooks: [
+                {
+                  type: "command",
+                  timeout: 30000, // OLD value
+                  command: AGENT_HOOK_COMMAND,
+                },
+              ],
+            },
+          ],
+        },
+      }),
+    );
+
+    const r = mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "updated");
+
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    assert.equal(parsed.hooks.SessionStart.length, 1);
+    assert.equal(parsed.hooks.SessionStart[0].hooks[0].timeout, 60000);
+  });
+
+  it("rejects vendors with the wrong shape", () => {
+    // Calling claude-shape merger with cursor-shape vendor is a
+    // dispatcher bug; surface it.
+    assert.throws(
+      () => mergeClaudeShapeAgentHook({ vendorKey: "cursor" }),
+      /shape "cursor-shape", expected "claude-shape"/,
+    );
+  });
+
+  it("rejects unknown vendor keys", () => {
+    assert.throws(
+      () => mergeClaudeShapeAgentHook({ vendorKey: "doesnotexist" }),
+      /Unknown agent key/,
+    );
+  });
+
+  it("rejects vendors whose agentHook is null (e.g. claudeCode)", () => {
+    assert.throws(
+      () => mergeClaudeShapeAgentHook({ vendorKey: "claudeCode" }),
+      /no agentHook spec/,
+    );
+  });
+
+  it("throws diskError on a corrupt existing JSON file (does not silently overwrite)", () => {
+    const filePath = join(homedir(), ".gemini", "settings.json");
+    mkdirSync(join(homedir(), ".gemini"), { recursive: true });
+    writeFileSync(filePath, "{not valid json");
+    assert.throws(
+      () => mergeClaudeShapeAgentHook({ vendorKey: "gemini" }),
+      /Cannot parse/,
+    );
+  });
+});
+
+describe("mergeClaudeShapeAgentHook (codex / copilot)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("codex installer writes to ~/.codex/hooks.json with timeout: 60 seconds (#1243)", () => {
+    // Codex's timeout is in SECONDS (distinct from Gemini's
+    // milliseconds). Verified against the Codex hooks source.
+    mergeClaudeShapeAgentHook({ vendorKey: "codex" });
+    const parsed = JSON.parse(
+      readFileSync(join(homedir(), ".codex", "hooks.json"), "utf-8"),
+    );
+    const inner = parsed.hooks.SessionStart[0].hooks[0];
+    assert.equal(inner.type, "command");
+    assert.equal(inner.timeout, 60);
+    assert.equal(inner.command, AGENT_HOOK_COMMAND);
+    // No groupFields for Codex — matcher is Gemini-specific
+    assert.equal(parsed.hooks.SessionStart[0].matcher, undefined);
+  });
+
+  it("copilot installer writes to ~/.copilot/hooks/skillrepo-update.json with lowercase sessionStart event (#1244)", () => {
+    // Copilot's spec uses lowercase `sessionStart` — distinct from
+    // Gemini and Codex's uppercase. Path includes a nested `hooks/`
+    // directory; the installer must mkdirp the parents.
+    mergeClaudeShapeAgentHook({ vendorKey: "copilot" });
+    const filePath = join(
+      homedir(),
+      ".copilot",
+      "hooks",
+      "skillrepo-update.json",
+    );
+    assert.ok(existsSync(filePath));
+    const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+    // Lowercase event name (Phase 4 fix)
+    assert.ok(Array.isArray(parsed.hooks.sessionStart));
+    assert.equal(parsed.hooks.SessionStart, undefined);
+    const inner = parsed.hooks.sessionStart[0].hooks[0];
+    assert.equal(inner.command, AGENT_HOOK_COMMAND);
+    assert.equal(inner.type, "command");
+    assert.equal(inner.timeout, 60);
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+
+describe("unmergeClaudeShapeAgentHook", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("returns 'skipped' when the file does not exist", () => {
+    const r = unmergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "skipped");
+  });
+
+  it("returns 'unchanged' when the file exists but has no SkillRepo entry", () => {
+    mkdirSync(join(homedir(), ".gemini"), { recursive: true });
+    writeFileSync(
+      join(homedir(), ".gemini", "settings.json"),
+      JSON.stringify({ theme: "dark", hooks: {} }),
+    );
+    const r = unmergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "unchanged");
+  });
+
+  it("removes ONLY the SkillRepo entry, preserving everything else", () => {
+    // Multi-tool surface: install SkillRepo + a user hook on the same
+    // event, then verify the remover surgically extracts ours.
+    mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    const filePath = join(homedir(), ".gemini", "settings.json");
+    const before = JSON.parse(readFileSync(filePath, "utf-8"));
+    // Insert an unrelated entry
+    before.hooks.SessionStart.unshift({
+      hooks: [{ type: "command", command: "user-keep.sh" }],
+    });
+    before.theme = "dark";
+    writeFileSync(filePath, JSON.stringify(before, null, 2));
+
+    const r = unmergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "removed");
+
+    const after = JSON.parse(readFileSync(filePath, "utf-8"));
+    assert.equal(after.theme, "dark");
+    assert.equal(after.hooks.SessionStart.length, 1);
+    assert.equal(
+      after.hooks.SessionStart[0].hooks[0].command,
+      "user-keep.sh",
+    );
+  });
+
+  it("dryRun returns 'would-remove' without writing", () => {
+    mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    const filePath = join(homedir(), ".gemini", "settings.json");
+    const before = readFileSync(filePath, "utf-8");
+
+    const r = unmergeClaudeShapeAgentHook({ vendorKey: "gemini", dryRun: true });
+    assert.equal(r.action, "would-remove");
+
+    // File on disk must be unchanged
+    assert.equal(readFileSync(filePath, "utf-8"), before);
+  });
+
+  it("collapses empty containers — fully empty file becomes {} after removal", () => {
+    mergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    unmergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    const parsed = JSON.parse(
+      readFileSync(join(homedir(), ".gemini", "settings.json"), "utf-8"),
+    );
+    // hooks.SessionStart is empty → key removed; hooks empty → key removed
+    assert.deepEqual(parsed, {});
+  });
+
+  it("returns 'skipped' with an error message on a corrupt file (does not throw)", () => {
+    // Uninstall must be lenient — a corrupt file should not block
+    // the rest of the uninstall pass. Same contract as
+    // removeSettingsSessionHook.
+    mkdirSync(join(homedir(), ".gemini"), { recursive: true });
+    writeFileSync(join(homedir(), ".gemini", "settings.json"), "{not valid");
+    const r = unmergeClaudeShapeAgentHook({ vendorKey: "gemini" });
+    assert.equal(r.action, "skipped");
+    assert.match(r.error, /Cannot parse/);
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────
+
+describe("install/uninstall round trip (gemini, codex, copilot)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  for (const vendorKey of ["gemini", "codex", "copilot"]) {
+    it(`${vendorKey}: install → unchanged-on-rerun → removed → unchanged-on-rerun`, () => {
+      const entry = getAgentByKey(vendorKey);
+      assert.ok(entry.agentHook, `${vendorKey} must have an agentHook spec`);
+
+      // 1. Fresh install
+      const r1 = mergeClaudeShapeAgentHook({ vendorKey });
+      assert.equal(r1.action, "installed");
+      assert.ok(existsSync(entry.agentHook.pathFn()));
+
+      // 2. Idempotent re-run
+      const r2 = mergeClaudeShapeAgentHook({ vendorKey });
+      assert.equal(r2.action, "unchanged");
+
+      // 3. Remove
+      const r3 = unmergeClaudeShapeAgentHook({ vendorKey });
+      assert.equal(r3.action, "removed");
+
+      // 4. Idempotent un-rerun
+      const r4 = unmergeClaudeShapeAgentHook({ vendorKey });
+      // After removal, the file may or may not exist depending on
+      // whether the JSON walked down to {} — both are valid
+      // post-remove states. "skipped" (file gone) and "unchanged"
+      // (file exists, no SkillRepo entry) both signal "nothing
+      // more to do."
+      assert.ok(
+        r4.action === "skipped" || r4.action === "unchanged",
+        `expected skipped|unchanged after second uninstall, got ${r4.action}`,
+      );
+    });
+  }
+});