skillrepo 4.0.0 → 4.2.0

package/src/test/e2e/mock-server.mjs

@@ -6,7 +6,8 @@
  *   GET    /api/v1/skill-content                  — legacy skill content
  *   POST   /api/v1/auth/validate                  — credential check (PR2)
  *   GET    /api/v1/library                        — library sync with ETag + since (PR2)
- *   POST   /api/v1/library                        — add to library (PR3a)
+ *   POST   /api/v1/library                        — multipart file-push (#1452)
+ *   POST   /api/v1/library/refs                   — add catalog skill to library (#1451)
  *   DELETE /api/v1/library/[owner]/[name]         — remove from library (PR3a)
  *   GET    /api/v1/skills/[owner]/[name]          — single skill fetch (PR2)
  *   GET    /api/v1/skills/search                  — keyword search (PR2)
@@ -24,8 +25,9 @@
  *   setEtag(etag)                        — what library responses include
  *
  *   (PR3a additions)
- *   setAddResponse(owner, name, resp)    — per-skill response for POST /library
+ *   setAddResponse(owner, name, resp)    — per-skill response for POST /library/refs (#1451)
  *   setRemoveResponse(owner, name, resp) — per-skill response for DELETE /library/<owner>/<name>
+ *   setPushResponse(resp)                — response for POST /library multipart push (#1452)
  *   getLastPostBody()                    — inspect the most recent POST body (JSON-parsed)
  *
  * The slot APIs let unit/integration tests configure each scenario
@@ -85,6 +87,14 @@ export function createMockServer(initialPayload, options = {}) {
   let addResponses = new Map();    // key: "owner/name" or "*" → { status, body }
   let removeResponses = new Map(); // key: "owner/name" or "*" → { status, body }
 
+  // #1452 — POST /api/v1/library (multipart file-push) response slot.
+  // Tests set this with `setPushResponse({ status, body })`; when null,
+  // a default 201 LibraryPushResponse is served. The test server does
+  // not parse multipart bodies — verifying the wire format is the
+  // client's responsibility.
+  /** @type {{ status: number, body: any } | null} */
+  let pushResponse = null;
+
   // Most recent POST body (JSON-parsed) for test inspection.
   //
   // IMPORTANT:
@@ -138,19 +148,25 @@ export function createMockServer(initialPayload, options = {}) {
     // command sends a JSON body to POST /api/v1/library, so we
     // now collect chunks and re-dispatch once the stream ends.
     if (req.method === "POST" || req.method === "DELETE" || req.method === "PUT" || req.method === "PATCH") {
-      let bodyChunks = "";
+      // Buffer as Buffer chunks, not string concatenation. JSON routes
+      // re-interpret as UTF-8; binary multipart bodies (#1452 push) keep
+      // their bytes intact. Concatenating `chunk.toString("utf-8")`
+      // would silently corrupt non-UTF-8 file content.
+      const chunks = [];
       req.on("data", (chunk) => {
-        bodyChunks += chunk.toString("utf-8");
+        chunks.push(chunk);
       });
       req.on("end", () => {
-        if (req.method === "POST" && bodyChunks.length > 0) {
+        const rawBody = Buffer.concat(chunks);
+        const rawBodyText = rawBody.toString("utf-8");
+        if (req.method === "POST" && rawBodyText.length > 0) {
           try {
-            lastPostBody = JSON.parse(bodyChunks);
+            lastPostBody = JSON.parse(rawBodyText);
           } catch {
-            lastPostBody = bodyChunks; // preserve as string for tests
+            lastPostBody = rawBodyText; // preserve as string for tests
           }
         }
-        handleRequest(req, res, bodyChunks);
+        handleRequest(req, res, rawBodyText);
       });
       req.on("error", () => {
         // Connection dropped — nothing to do, client is gone
@@ -189,8 +205,11 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
-    // ── PR3a: POST /api/v1/library (add to library) ─────────────────
-    if (url.pathname === "/api/v1/library" && req.method === "POST") {
+    // ── #1451: POST /api/v1/library/refs (add catalog skill) ───────
+    //
+    // Was at /api/v1/library until #1452 rebound that URL to multipart
+    // file-push. Same handler logic; only the URL moved.
+    if (url.pathname === "/api/v1/library/refs" && req.method === "POST") {
       if (!checkAuth(req, res)) return;
       let body;
       try {
@@ -233,6 +252,61 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
+    // ── #1452: POST /api/v1/library (multipart file-push) ──────────
+    //
+    // Accepts multipart/form-data and returns a synthesized
+    // `LibraryPushResponse` shape. The handler does not actually
+    // parse the multipart body — it just inspects the Content-Type
+    // header to confirm the client sent multipart, and serves either
+    // a `pushResponse` slot value (set via `setPushResponse`) or a
+    // default 201 with `action: "created"` shape.
+    if (url.pathname === "/api/v1/library" && req.method === "POST") {
+      if (!checkAuth(req, res)) return;
+      const contentType = req.headers["content-type"] ?? "";
+      if (!contentType.includes("multipart/form-data")) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error:
+              "Invalid multipart body. Set Content-Type: multipart/form-data.",
+            code: "invalid_multipart",
+          }),
+        );
+        return;
+      }
+      if (pushResponse) {
+        res.writeHead(pushResponse.status, {
+          "Content-Type": "application/json",
+        });
+        res.end(JSON.stringify(pushResponse.body));
+        return;
+      }
+      // Default: 201 with a synthesized SyncSkill response.
+      res.writeHead(201, {
+        "Content-Type": "application/json",
+        Location: "/api/v1/library/mock/test-skill",
+      });
+      res.end(
+        JSON.stringify({
+          action: "created",
+          bump: null,
+          skill: {
+            owner: "mock",
+            name: "test-skill",
+            version: "1.0",
+            description: "mock",
+            keywords: [],
+            updatedAt: new Date().toISOString(),
+            etag: '"mock/test-skill@0"',
+            contextSignals: null,
+            files: [],
+            filesIncomplete: false,
+          },
+        }),
+      );
+      return;
+    }
+
     // ── PR3a: DELETE /api/v1/library/[owner]/[name] (remove) ────────
     {
       const m = url.pathname.match(/^\/api\/v1\/library\/([^\/]+)\/([^\/]+)$/);
@@ -489,6 +563,14 @@ export function createMockServer(initialPayload, options = {}) {
       removeResponses = new Map();
     },
 
+    /**
+     * #1452 — register the next POST /api/v1/library (multipart file-push)
+     * response. Pass `null` to restore the default 201 LibraryPushResponse.
+     */
+    setPushResponse(response) {
+      pushResponse = response;
+    },
+
     /**
      * Return the most recent POST body the server received, or null
      * if no POST has been made yet. Body is JSON-parsed when

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/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");
+    }
+  });
+});