skillrepo 3.2.0 → 4.1.0

package/src/test/integration/agent-hooks.integration.test.mjs

@@ -0,0 +1,340 @@
+/**
+ * Integration tests for the cohort SessionStart hook framework (#1240).
+ *
+ * Differs from the per-shape merger unit tests in that we exercise
+ * the FULL installer-through-uninstaller round trip across all four
+ * cohort vendors against a real temp filesystem, in a multi-tool
+ * merge surface where the agent-hooks framework is one of N writers
+ * extending the same JSON files.
+ *
+ * Five scenarios per vendor:
+ *
+ *   1. Fresh install → file at the right path, correct shape
+ *   2. Idempotent re-install → no duplicate entries, action="unchanged"
+ *   3. Multi-tool surface preservation → install with pre-existing
+ *      "other tool" entries → SkillRepo entry adjacent, others intact
+ *   4. Round-trip via the public dispatcher API → install via
+ *      `installAgentHookFor`, uninstall via batch remover
+ *   5. Repeated uninstall → idempotent (skipped/unchanged after the
+ *      first remove)
+ *
+ * No network, no mock server, no spawned binary — pure filesystem +
+ * dispatcher composition.
+ */
+
+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 {
+  installAgentHookFor,
+  uninstallAgentHookFor,
+} from "../../lib/agent-hook-merge.mjs";
+import { removeAllAgentHooks } from "../../lib/removers/agent-hooks.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-hooks-int-"));
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalHomeEnv = captureHome();
+  setSandboxHome(join(sandbox, "home"));
+  assertHomeIsolated(tmpdir(), "agent-hooks integration tests");
+}
+
+function teardown() {
+  restoreHome(originalHomeEnv);
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+const COHORT_VENDORS = ["cursor", "gemini", "codex", "copilot"];
+
+/**
+ * Per-vendor pre-existing "other tool" content. Mirrors realistic
+ * shapes the cohort installer has to coexist with:
+ *   - Cursor: 1Password / Snyk / Apiiro flat sessionStart entries
+ *   - Gemini: theme + a UserPromptSubmit hook the user wrote
+ *   - Codex: a different pre-installed claude-shape SessionStart hook
+ *   - Copilot: per-tool file (no merge concerns) — fresh install only
+ */
+const PRE_EXISTING = {
+  cursor: {
+    version: 1,
+    hooks: {
+      sessionStart: [
+        { command: "1password-agent-helper" },
+        { command: "snyk auth-check" },
+      ],
+      beforePromptSubmit: [{ command: "apiiro-scan" }],
+    },
+  },
+  gemini: {
+    theme: "dark",
+    hooks: {
+      SessionStart: [
+        { hooks: [{ type: "command", command: "user-script.sh" }] },
+      ],
+      UserPromptSubmit: [
+        { hooks: [{ type: "command", command: "another.sh" }] },
+      ],
+    },
+  },
+  codex: {
+    hooks: {
+      SessionStart: [
+        { hooks: [{ type: "command", command: "user-codex-hook.sh" }] },
+      ],
+    },
+  },
+  copilot: null, // per-tool file — no merge concerns
+};
+
+/**
+ * Find the SkillRepo entry's `command` field in the parsed config,
+ * shape-aware. Returns null if not present.
+ */
+function findSkillrepoCommand(parsed, vendorKey) {
+  const entry = getAgentByKey(vendorKey);
+  const eventName = entry.agentHook.eventName;
+  const arr = parsed?.hooks?.[eventName];
+  if (!Array.isArray(arr)) return null;
+  if (entry.agentHook.shape === "cursor-shape") {
+    const found = arr.find(
+      (h) => typeof h?.command === "string" && h.command.includes(AGENT_HOOK_FINGERPRINT),
+    );
+    return found?.command ?? null;
+  }
+  // claude-shape
+  for (const group of arr) {
+    if (!Array.isArray(group?.hooks)) continue;
+    for (const h of group.hooks) {
+      if (typeof h?.command === "string" && h.command.includes(AGENT_HOOK_FINGERPRINT)) {
+        return h.command;
+      }
+    }
+  }
+  return null;
+}
+
+// ──────────────────────────────────────────────────────────────────
+
+describe("agent-hooks integration: end-to-end per-vendor round trip", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  for (const vendorKey of COHORT_VENDORS) {
+    it(`${vendorKey}: 1) fresh install writes correct shape`, () => {
+      const r = installAgentHookFor(vendorKey);
+      assert.equal(r.action, "installed");
+
+      const entry = getAgentByKey(vendorKey);
+      const filePath = entry.agentHook.pathFn();
+      assert.ok(existsSync(filePath), `${vendorKey} hook file must exist`);
+
+      const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+      const cmd = findSkillrepoCommand(parsed, vendorKey);
+      assert.equal(
+        cmd,
+        AGENT_HOOK_COMMAND,
+        `${vendorKey} command must equal AGENT_HOOK_COMMAND`,
+      );
+    });
+
+    it(`${vendorKey}: 2) re-install is idempotent (action: "unchanged", no duplicates)`, () => {
+      installAgentHookFor(vendorKey);
+      const r2 = installAgentHookFor(vendorKey);
+      assert.equal(r2.action, "unchanged");
+
+      const entry = getAgentByKey(vendorKey);
+      const filePath = entry.agentHook.pathFn();
+      const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+
+      // Count SkillRepo entries — must be exactly 1
+      const eventName = entry.agentHook.eventName;
+      let count = 0;
+      const arr = parsed?.hooks?.[eventName] ?? [];
+      if (entry.agentHook.shape === "cursor-shape") {
+        count = arr.filter(
+          (h) => typeof h?.command === "string" && h.command.includes(AGENT_HOOK_FINGERPRINT),
+        ).length;
+      } else {
+        for (const group of arr) {
+          if (!Array.isArray(group?.hooks)) continue;
+          count += group.hooks.filter(
+            (h) =>
+              typeof h?.command === "string" &&
+              h.command.includes(AGENT_HOOK_FINGERPRINT),
+          ).length;
+        }
+      }
+      assert.equal(count, 1, `exactly one SkillRepo hook entry for ${vendorKey}`);
+    });
+
+    it(`${vendorKey}: 3) preserves pre-existing other-tool entries (multi-tool merge surface)`, () => {
+      const entry = getAgentByKey(vendorKey);
+      const filePath = entry.agentHook.pathFn();
+      const pre = PRE_EXISTING[vendorKey];
+      if (pre !== null) {
+        mkdirSync(join(filePath, ".."), { recursive: true });
+        writeFileSync(filePath, JSON.stringify(pre, null, 2));
+      }
+
+      installAgentHookFor(vendorKey);
+      const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+
+      if (vendorKey === "cursor") {
+        // Other tools' sessionStart entries preserved
+        assert.deepEqual(
+          parsed.hooks.sessionStart
+            .map((h) => h.command)
+            .filter((c) => c !== AGENT_HOOK_COMMAND),
+          ["1password-agent-helper", "snyk auth-check"],
+        );
+        // Different-event array untouched
+        assert.deepEqual(parsed.hooks.beforePromptSubmit, [
+          { command: "apiiro-scan" },
+        ]);
+      } else if (vendorKey === "gemini") {
+        // Top-level user setting preserved
+        assert.equal(parsed.theme, "dark");
+        // Different-event hook untouched
+        assert.equal(
+          parsed.hooks.UserPromptSubmit[0].hooks[0].command,
+          "another.sh",
+        );
+        // SessionStart has the user's group AND the SkillRepo group
+        const cmds = parsed.hooks.SessionStart.flatMap((g) =>
+          (g.hooks ?? []).map((h) => h.command),
+        );
+        assert.ok(cmds.includes("user-script.sh"));
+        assert.ok(cmds.includes(AGENT_HOOK_COMMAND));
+      } else if (vendorKey === "codex") {
+        const cmds = parsed.hooks.SessionStart.flatMap((g) =>
+          (g.hooks ?? []).map((h) => h.command),
+        );
+        assert.ok(cmds.includes("user-codex-hook.sh"));
+        assert.ok(cmds.includes(AGENT_HOOK_COMMAND));
+      } else if (vendorKey === "copilot") {
+        // Per-tool file: no pre-existing content. Just sanity-check
+        // the SkillRepo entry is present.
+        const cmd = findSkillrepoCommand(parsed, vendorKey);
+        assert.equal(cmd, AGENT_HOOK_COMMAND);
+      }
+    });
+
+    it(`${vendorKey}: 4) round-trip via batch remover removes only SkillRepo`, () => {
+      const entry = getAgentByKey(vendorKey);
+      const filePath = entry.agentHook.pathFn();
+      const pre = PRE_EXISTING[vendorKey];
+      if (pre !== null) {
+        mkdirSync(join(filePath, ".."), { recursive: true });
+        writeFileSync(filePath, JSON.stringify(pre, null, 2));
+      }
+
+      installAgentHookFor(vendorKey);
+      const removed = removeAllAgentHooks();
+      const myResult = removed.find((r) => r.id === `agent-hook-${vendorKey}`);
+      assert.equal(myResult.action, "removed");
+
+      // File still has the OTHER tools' entries (where applicable)
+      if (existsSync(filePath)) {
+        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+        const cmd = findSkillrepoCommand(parsed, vendorKey);
+        assert.equal(cmd, null, `SkillRepo command must be gone for ${vendorKey}`);
+      }
+    });
+
+    it(`${vendorKey}: 5) repeated uninstall is idempotent`, () => {
+      installAgentHookFor(vendorKey);
+      uninstallAgentHookFor(vendorKey);
+      const r2 = uninstallAgentHookFor(vendorKey);
+      assert.ok(
+        r2.action === "skipped" || r2.action === "unchanged",
+        `expected skipped|unchanged on second uninstall, got ${r2.action}`,
+      );
+    });
+  }
+});
+
+describe("agent-hooks integration: multi-vendor batch operations", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("installing all four vendors in one pass produces four files", () => {
+    for (const v of COHORT_VENDORS) installAgentHookFor(v);
+    assert.ok(existsSync(join(homedir(), ".cursor", "hooks.json")));
+    assert.ok(existsSync(join(homedir(), ".gemini", "settings.json")));
+    assert.ok(existsSync(join(homedir(), ".codex", "hooks.json")));
+    assert.ok(
+      existsSync(join(homedir(), ".copilot", "hooks", "skillrepo-update.json")),
+    );
+  });
+
+  it("removeAllAgentHooks tears down every installed cohort vendor in one pass", () => {
+    for (const v of COHORT_VENDORS) installAgentHookFor(v);
+    const results = removeAllAgentHooks();
+    const removedCount = results.filter((r) => r.action === "removed").length;
+    assert.equal(removedCount, 4);
+  });
+
+  it("cross-vendor state isolation: installing for one vendor does NOT touch any other vendor's file (#1239 QA)", () => {
+    // INTENT: a user runs `skillrepo init --agent cursor`, then later
+    // re-runs with `--agent gemini`. The second run must not corrupt,
+    // remove, or otherwise touch the file the first run wrote. The
+    // dispatcher's per-vendor scoping is correct today; this test
+    // locks the contract so a future widening of the eligible filter
+    // or fan-out logic doesn't silently regress it.
+    installAgentHookFor("cursor");
+    const cursorPath = join(homedir(), ".cursor", "hooks.json");
+    const cursorBefore = readFileSync(cursorPath, "utf-8");
+
+    // Now install Gemini only — Cursor's file must be byte-identical
+    // afterward.
+    installAgentHookFor("gemini");
+    assert.equal(
+      readFileSync(cursorPath, "utf-8"),
+      cursorBefore,
+      "Cursor file must NOT change when installing for Gemini",
+    );
+
+    // Inverse: install Codex now, ensure Gemini's file is also
+    // byte-stable.
+    const geminiPath = join(homedir(), ".gemini", "settings.json");
+    const geminiBefore = readFileSync(geminiPath, "utf-8");
+    installAgentHookFor("codex");
+    assert.equal(
+      readFileSync(geminiPath, "utf-8"),
+      geminiBefore,
+      "Gemini file must NOT change when installing for Codex",
+    );
+
+    // Uninstall one vendor; the other two must survive intact.
+    uninstallAgentHookFor("cursor");
+    assert.equal(
+      readFileSync(geminiPath, "utf-8"),
+      geminiBefore,
+      "Gemini file must NOT change when uninstalling Cursor",
+    );
+  });
+});

package/src/test/integration/file-write.integration.test.mjs

@@ -108,9 +108,12 @@ describe("file-write.mjs integration — round-trip", () => {
     }
   });
 
-  it("writes to global dir under HOME with --global", () => {
+  it("writes to global dir under HOME with --global --agent claudeCode", () => {
     const skill = multiFileSkill();
-    const result = writeSkillDir(skill, { global: true });
+    const result = writeSkillDir(skill, {
+      global: true,
+      vendors: ["claudeCode"],
+    });
     assert.equal(result.written.length, 1);
     const dir = result.written[0];
     assert.ok(dir.startsWith(process.env.HOME), "should write under HOME");
@@ -190,13 +193,13 @@ describe("file-write.mjs integration — orphan recovery", () => {
 
   it("cleanupOrphans removes injected .tmp/ (with live siblings) and .old/ across all roots", () => {
     // Inject orphans in claudeProject root, claudeGlobal root, and
-    // projectFallback root. .tmp/ entries need a live sibling so the
+    // agentsProject root. .tmp/ entries need a live sibling so the
     // safety invariant doesn't preserve them as recoverable.
     const claudeProjectRoot = join(process.cwd(), ".claude", "skills");
-    const fallbackRoot = join(process.cwd(), "skills");
+    const agentsRoot = join(process.cwd(), ".agents", "skills");
     const globalRoot = join(process.env.HOME, ".claude", "skills");
     mkdirSync(claudeProjectRoot, { recursive: true });
-    mkdirSync(fallbackRoot, { recursive: true });
+    mkdirSync(agentsRoot, { recursive: true });
     mkdirSync(globalRoot, { recursive: true });
 
     // ghost-1: live sibling + .tmp + .old (.tmp gets cleaned because live exists)
@@ -205,8 +208,8 @@ describe("file-write.mjs integration — orphan recovery", () => {
     mkdirSync(join(claudeProjectRoot, "ghost-1.old"));
     writeFileSync(join(claudeProjectRoot, "ghost-1.tmp", "garbage.txt"), "leftover");
 
-    // ghost-2: just a .old/ in the fallback root (.old has no invariant)
-    mkdirSync(join(fallbackRoot, "ghost-2.old"));
+    // ghost-2: just a .old/ in the agents cohort root (.old has no invariant)
+    mkdirSync(join(agentsRoot, "ghost-2.old"));
 
     // ghost-3: live sibling + .tmp in the global root
     mkdirSync(join(globalRoot, "ghost-3"));
@@ -217,7 +220,7 @@ describe("file-write.mjs integration — orphan recovery", () => {
 
     assert.ok(!existsSync(join(claudeProjectRoot, "ghost-1.tmp")));
     assert.ok(!existsSync(join(claudeProjectRoot, "ghost-1.old")));
-    assert.ok(!existsSync(join(fallbackRoot, "ghost-2.old")));
+    assert.ok(!existsSync(join(agentsRoot, "ghost-2.old")));
     assert.ok(!existsSync(join(globalRoot, "ghost-3.tmp")));
     // Live siblings preserved
     assert.ok(existsSync(join(claudeProjectRoot, "ghost-1")));
@@ -272,14 +275,32 @@ describe("file-write.mjs integration — remove + .gitignore", () => {
     }
   });
 
-  it("write to fallback creates .gitignore entry; remove does not delete it", () => {
+  it("write to .agents/skills/ creates .gitignore entry; remove does not delete it", () => {
     writeSkillDir(multiFileSkill(), { vendors: ["cursor"] });
     const giBefore = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
-    assert.match(giBefore, /\/skills\//);
+    assert.match(giBefore, /\.agents\/skills\//);
 
     removeSkillDir("pdf-helper", { vendors: ["cursor"] });
     const giAfter = readFileSync(join(process.cwd(), ".gitignore"), "utf-8");
     // remove should not touch .gitignore
     assert.equal(giAfter, giBefore);
   });
+
+  it("cohort dedupe end-to-end: vendors=[cursor, windsurf] writes ONE skill", () => {
+    const skill = multiFileSkill();
+    const result = writeSkillDir(skill, { vendors: ["cursor", "windsurf"] });
+    assert.equal(
+      result.written.length,
+      1,
+      "cohort vendors must collapse to a single write",
+    );
+    const dir = result.written[0];
+    assert.ok(
+      dir.includes(join(".agents", "skills", "pdf-helper")),
+      `expected dir under .agents/skills/, got ${dir}`,
+    );
+    for (const file of skill.files) {
+      assert.ok(existsSync(join(dir, file.path)));
+    }
+  });
 });

package/src/test/lib/agent-hook-merge.test.mjs

@@ -0,0 +1,172 @@
+/**
+ * Unit tests for `lib/agent-hook-merge.mjs` (#1240).
+ *
+ * The dispatcher's job is small but load-bearing: route a vendor key
+ * to the right per-shape merger, and aggregate per-vendor results
+ * for fan-out without letting one failure abort siblings.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  readFileSync,
+  existsSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir, homedir } from "node:os";
+
+import {
+  installAgentHookFor,
+  uninstallAgentHookFor,
+  installAgentHooksForVendors,
+} from "../../lib/agent-hook-merge.mjs";
+import { AGENT_HOOK_COMMAND } from "../../lib/artifact-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-dispatch-"));
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalHomeEnv = captureHome();
+  setSandboxHome(join(sandbox, "home"));
+  assertHomeIsolated(tmpdir(), "agent-hook dispatcher tests");
+}
+
+function teardown() {
+  restoreHome(originalHomeEnv);
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+}
+
+// ──────────────────────────────────────────────────────────────────
+
+describe("installAgentHookFor — single vendor dispatch", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("routes cursor to cursor-shape merger (writes ~/.cursor/hooks.json)", () => {
+    const r = installAgentHookFor("cursor");
+    assert.equal(r.action, "installed");
+    assert.equal(r.path, "~/.cursor/hooks.json");
+    assert.equal(r.command, AGENT_HOOK_COMMAND);
+    assert.ok(existsSync(join(homedir(), ".cursor", "hooks.json")));
+  });
+
+  it("routes gemini/codex/copilot to claude-shape merger (each writes its own file)", () => {
+    for (const vendorKey of ["gemini", "codex", "copilot"]) {
+      const r = installAgentHookFor(vendorKey);
+      assert.equal(r.action, "installed", `expected install for ${vendorKey}`);
+    }
+    assert.ok(existsSync(join(homedir(), ".gemini", "settings.json")));
+    assert.ok(existsSync(join(homedir(), ".codex", "hooks.json")));
+    assert.ok(
+      existsSync(join(homedir(), ".copilot", "hooks", "skillrepo-update.json")),
+    );
+  });
+
+  it("rejects vendors with null agentHook (claudeCode, windsurf, cline)", () => {
+    for (const vendorKey of ["claudeCode", "windsurf", "cline"]) {
+      assert.throws(
+        () => installAgentHookFor(vendorKey),
+        /no agentHook spec/,
+        `${vendorKey} should not have an agentHook spec`,
+      );
+    }
+  });
+
+  it("rejects unknown vendor keys", () => {
+    assert.throws(() => installAgentHookFor("doesnotexist"), /unknown agent/);
+  });
+});
+
+describe("uninstallAgentHookFor", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("routes by shape and removes the hook (round trip with installAgentHookFor)", () => {
+    installAgentHookFor("gemini");
+    const r = uninstallAgentHookFor("gemini");
+    assert.equal(r.action, "removed");
+  });
+
+  it("dryRun returns 'would-remove' without writing", () => {
+    installAgentHookFor("cursor");
+    const filePath = join(homedir(), ".cursor", "hooks.json");
+    const before = readFileSync(filePath, "utf-8");
+    const r = uninstallAgentHookFor("cursor", { dryRun: true });
+    assert.equal(r.action, "would-remove");
+    assert.equal(readFileSync(filePath, "utf-8"), before);
+  });
+});
+
+describe("installAgentHooksForVendors — fan-out + failure isolation", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("installs hooks for every cohort vendor in the input list", () => {
+    const results = installAgentHooksForVendors({
+      vendors: ["cursor", "gemini", "codex", "copilot"],
+    });
+    assert.equal(results.length, 4);
+    for (const r of results) {
+      assert.equal(r.action, "installed", `expected install for ${r.vendorKey}`);
+    }
+  });
+
+  it("silently skips vendors with null agentHook (claudeCode, windsurf, cline)", () => {
+    // Mixed input — claudeCode + cursor in one call. The cohort
+    // installer must NOT install for claudeCode (it has its own
+    // mechanism), only for cursor.
+    const results = installAgentHooksForVendors({
+      vendors: ["claudeCode", "windsurf", "cline", "cursor"],
+    });
+    assert.equal(results.length, 1);
+    assert.equal(results[0].vendorKey, "cursor");
+    assert.equal(results[0].action, "installed");
+  });
+
+  it("dedupes the input list", () => {
+    const results = installAgentHooksForVendors({
+      vendors: ["gemini", "gemini", "gemini"],
+    });
+    assert.equal(results.length, 1);
+  });
+
+  it("surfaces unknown vendor keys as failed (does not silently skip — typos must be visible)", () => {
+    const results = installAgentHooksForVendors({
+      vendors: ["cursor", "fake-vendor"],
+    });
+    const fakeResult = results.find((r) => r.vendorKey === "fake-vendor");
+    assert.equal(fakeResult.action, "failed");
+    assert.match(fakeResult.reason, /Unknown agent key/);
+    // Cursor's entry still installed despite the sibling failure
+    const cursorResult = results.find((r) => r.vendorKey === "cursor");
+    assert.equal(cursorResult.action, "installed");
+  });
+
+  it("rejects non-array input loudly (catches dispatcher bugs at the boundary)", () => {
+    assert.throws(
+      () => installAgentHooksForVendors({ vendors: "cursor" }),
+      /must be an array/,
+    );
+  });
+
+  it("returns idempotent 'unchanged' when re-run after a successful install", () => {
+    installAgentHooksForVendors({ vendors: ["cursor", "gemini"] });
+    const second = installAgentHooksForVendors({
+      vendors: ["cursor", "gemini"],
+    });
+    for (const r of second) {
+      assert.equal(r.action, "unchanged");
+    }
+  });
+});