skillrepo 4.0.0 → 4.2.0

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

@@ -0,0 +1,519 @@
+/**
+ * SessionStart-hook installer/uninstaller for the claude-shape vendors:
+ * Gemini CLI, Codex CLI, and VS Code + Copilot (#1240).
+ *
+ * Each of these vendors accepts the nested-array hook config Anthropic
+ * documents for Claude Code, with vendor-specific extras layered on:
+ *
+ *   {
+ *     "hooks": {
+ *       "<EventName>": [
+ *         {
+ *           ...groupFields,                 // e.g. Gemini's `matcher: "*"`
+ *           "hooks": [
+ *             { ...entryFields,             // e.g. Gemini's `name`,
+ *                                           //      Codex's `timeout: 60`
+ *               "command": "<canonical>" }
+ *           ]
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * "<EventName>" is per-vendor (`SessionStart` for Gemini and Codex,
+ * lowercase `sessionStart` for VS Code + Copilot) and comes from the
+ * agent registry's `agentHook.eventName` field. The inner per-hook
+ * entry is built by merging the universal `command`
+ * (`AGENT_HOOK_COMMAND` from artifact-registry.mjs) with the vendor's
+ * `agentHook.entryFields`. The OUTER group object spreads the vendor's
+ * `agentHook.groupFields` on fresh install AND when upgrading from a
+ * Phase-0-era group that lacks them — the latter is the upgrade-path
+ * gate for Gemini's `matcher: "*"` (without it Gemini silently filters
+ * out the group and the hook never fires).
+ *
+ * ## Why a separate module from session-hook.mjs
+ *
+ * The legacy `session-hook.mjs` is Claude-Code-specific:
+ *   - Resolves an absolute `binaryPath` via PATH lookup (Claude doesn't
+ *     load PATH at hook time)
+ *   - Wraps the command in shell-specific quoting + `|| true` backstop
+ *   - Writes to `.claude/settings.local.json`
+ *   - Honors `--session-hook`'s exit-0-on-error contract
+ *
+ * The cohort hooks have NONE of these concerns:
+ *   - `npx --yes skillrepo update --silent` is the universal command;
+ *     no binaryPath resolution
+ *   - Cohort vendors invoke hooks through the user's normal shell, so
+ *     no shell-quoting is needed
+ *   - Each vendor has its own user-scope hook config file
+ *   - `--silent` exits non-zero on real failure (the cohort vendors
+ *     don't block session start on hook failure the way Claude does)
+ *
+ * Forking the merger is cheaper than a single function with a "claude
+ * legacy mode vs cohort mode" branch: the two flows share almost no
+ * logic — only the basic JSON-walk-by-fingerprint pattern, which is
+ * tightly coupled to the per-shape schema anyway.
+ *
+ * ## Idempotency contract (mirrors session-hook.mjs)
+ *
+ * `mergeClaudeShapeAgentHook` is safe to re-run:
+ *   - First run: no SkillRepo entry present → installs, returns "installed"
+ *   - Re-run with same command: no-op, returns "unchanged"
+ *   - Re-run after manual edit (e.g. extension-only change): replaces
+ *     the SkillRepo entry in place, returns "updated"
+ *   - Other tools' entries are NEVER touched. The walk filters by
+ *     `AGENT_HOOK_FINGERPRINT` substring on the `command` field.
+ *
+ * ## Atomic writes
+ *
+ * The hook config files are read by their respective agents at session
+ * start. A half-written JSON would break every subsequent session.
+ * `writeFileAtomic` (temp file + rename + unlink-on-failure) is the
+ * mandatory write path.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import {
+  AGENT_HOOK_COMMAND,
+  AGENT_HOOK_FINGERPRINT,
+} from "../artifact-registry.mjs";
+import { getAgentByKey } from "../agent-registry.mjs";
+import { diskError, validationError } from "../errors.mjs";
+
+/**
+ * Build the per-hook entry the merger writes. The `entryFields` from
+ * the agent registry's `agentHook.entryFields` (e.g. Gemini's
+ * `{ type: "command", timeout: 60000 }`) are spread BEFORE `command`
+ * so the user can NEVER override the command via a registry typo —
+ * the explicit assignment of `command: AGENT_HOOK_COMMAND` wins.
+ *
+ * Exported so tests can assert the exact JSON-serializable shape.
+ *
+ * @param {object} entryFields - Vendor-specific extras from the agent
+ *        registry. Treated as JSON-serializable; non-serializable keys
+ *        will surface at write time as a JSON.stringify error and are
+ *        the registry author's problem, not this function's.
+ * @returns {Record<string, unknown>}
+ */
+export function buildClaudeShapeEntry(entryFields = {}) {
+  return {
+    ...entryFields,
+    command: AGENT_HOOK_COMMAND,
+  };
+}
+
+/**
+ * Install (or refresh) the cohort SessionStart hook in a claude-shape
+ * vendor's hook config file. Creates the file if it doesn't exist.
+ *
+ * @param {object} options
+ * @param {string} options.vendorKey - Canonical key from the agent
+ *        registry. Must be a registry entry whose `agentHook.shape`
+ *        is `"claude-shape"`. Other shapes throw a validation error.
+ * @returns {{
+ *   path: string;
+ *   action: "installed" | "updated" | "unchanged";
+ *   command: string;
+ * }}
+ *   Action values:
+ *     - `"installed"` — no prior SkillRepo hook, we added one
+ *     - `"updated"` — prior SkillRepo hook existed but the entry differed,
+ *       replaced in place
+ *     - `"unchanged"` — exact entry already present; no-op
+ */
+export function mergeClaudeShapeAgentHook({ vendorKey }) {
+  const { hookSpec } = resolveAgent(vendorKey);
+  const filePath = hookSpec.pathFn();
+  const eventName = hookSpec.eventName;
+  const desiredEntry = buildClaudeShapeEntry(hookSpec.entryFields);
+
+  const config = readConfigOrEmpty(filePath, hookSpec.displayPath);
+
+  if (!config.hooks || typeof config.hooks !== "object") {
+    config.hooks = {};
+  }
+  if (!Array.isArray(config.hooks[eventName])) {
+    config.hooks[eventName] = [];
+  }
+
+  // Walk `hooks.<EventName>[i].hooks[j]` exhaustively for entries
+  // whose `command` matches the SkillRepo fingerprint. The walk MUST
+  // mirror the remover's filter in `removers/agent-hooks.mjs`; both
+  // sides use `AGENT_HOOK_FINGERPRINT` as the single source of truth
+  // so they can't drift.
+  //
+  // Exhaustive walk (not break-on-first) is the symmetric installer
+  // counterpart to the remover's exhaustive filter: the remover
+  // strips ALL matching entries, so the installer also has to handle
+  // ALL matching entries. Without this, a prior-run double-install
+  // (or manual edit, or a future code path that produces two entries
+  // by mistake) leaves a ghost the installer doesn't see. Fixing on
+  // every install is cheap and means the post-install invariant
+  // "exactly one SkillRepo entry per cohort hook config" holds even
+  // through bug-recovery scenarios.
+  let primaryHandled = false;     // tracks whether we've already replaced/preserved one
+  let foundChanged = false;        // any actual mutation (updated or stripped duplicate)
+  let foundUnchangedExact = false; // first match was already byte-equal to desired
+  let groupsToCompact = false;     // a group's hooks array became empty during walk
+
+  for (const group of config.hooks[eventName]) {
+    if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
+      continue;
+    }
+    const survivingInGroup = [];
+    let groupMutated = false;
+    for (const inner of group.hooks) {
+      if (
+        inner &&
+        typeof inner === "object" &&
+        typeof inner.command === "string" &&
+        inner.command.includes(AGENT_HOOK_FINGERPRINT)
+      ) {
+        if (!primaryHandled) {
+          primaryHandled = true;
+          if (entriesEqual(inner, desiredEntry)) {
+            foundUnchangedExact = true;
+            survivingInGroup.push(inner);
+          } else {
+            foundChanged = true;
+            groupMutated = true; // in-place replacement at the same index
+            survivingInGroup.push(desiredEntry);
+          }
+        } else {
+          // Duplicate SkillRepo entry from a prior buggy run or
+          // manual edit. Drop it; the primary slot above carries
+          // the canonical entry.
+          foundChanged = true;
+          groupMutated = true; // length-changing drop
+        }
+        continue;
+      }
+      survivingInGroup.push(inner);
+    }
+    // Write back if we replaced (same length, different content) OR
+    // dropped duplicates (smaller length). Length-only equality is
+    // not sufficient — an in-place replacement leaves length
+    // unchanged but the content needs to be written. Round-2
+    // reviewer caught this gap.
+    if (groupMutated) {
+      group.hooks = survivingInGroup;
+      if (group.hooks.length === 0) groupsToCompact = true;
+    }
+  }
+
+  // Drop fully-emptied groups so the file doesn't accumulate
+  // structurally-empty husks across multiple install/uninstall
+  // cycles. Mirrors the remover's empty-container collapse.
+  if (groupsToCompact) {
+    config.hooks[eventName] = config.hooks[eventName].filter((g) => {
+      if (!g || typeof g !== "object" || !Array.isArray(g.hooks)) return true;
+      return g.hooks.length > 0;
+    });
+  }
+
+  // Vendor-specific group-level fields (#1242 Gemini). When the
+  // registry declares `groupFields` (e.g. `{ matcher: "*" }` for
+  // Gemini), every group that contains our entry MUST carry them.
+  // This handles two scenarios:
+  //
+  //   - **Fresh install** (no primaryHandled match): the append at
+  //     the bottom of this function spreads `groupFields` into the
+  //     new group.
+  //   - **Phase-0-era upgrade** (entry exists but in a group lacking
+  //     `matcher`): the loop below adds the missing fields to the
+  //     group containing our entry. Without this, a Phase-0-installed
+  //     Gemini hook stays silently broken after the upgrade — the
+  //     entry is correct but Gemini's matcher filter rejects the
+  //     group, so the hook never fires.
+  //
+  // **Always-re-add contract**: a user who deliberately deletes a
+  // required `groupFields` value (e.g. removes `matcher: "*"` from
+  // their Gemini config) will have it re-added on the next install.
+  // The `=== undefined` guard means we never overwrite a user-set
+  // value (e.g. `matcher: "narrower-pattern"`) — but a missing field
+  // is treated as "broken state to repair," not "user choice to
+  // honor." This is intentional: `groupFields` are required for the
+  // hook to fire at all, so silent self-repair is the right default
+  // for a deletion that would otherwise leave the hook dead. Falsy
+  // non-undefined values (`""`, `null`, `false`) are NOT re-written —
+  // we trust those as deliberate user input even though they may
+  // produce a broken hook. A user who accidentally types
+  // `matcher: ""` is making an explicit choice we won't second-guess;
+  // a user who didn't set the field at all is in unrepaired upgrade
+  // state. (Alternative-considered: widen to "fix any falsy value"
+  // would clobber a future user setting `matcher: false` to
+  // intentionally disable the hook for a session — different bug,
+  // worse class.)
+  //
+  // Idempotent: if the field is already present (any value, falsy or
+  // truthy) we don't touch it, and the merger only reports `updated`
+  // when something actually changed.
+  if (hookSpec.groupFields && primaryHandled) {
+    for (const group of config.hooks[eventName]) {
+      if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
+        continue;
+      }
+      const containsOurs = group.hooks.some(
+        (h) =>
+          h &&
+          typeof h.command === "string" &&
+          h.command.includes(AGENT_HOOK_FINGERPRINT),
+      );
+      if (!containsOurs) continue;
+      for (const [k, v] of Object.entries(hookSpec.groupFields)) {
+        if (group[k] === undefined) {
+          group[k] = v;
+          foundChanged = true;
+        }
+      }
+    }
+  }
+
+  let matchedAction;
+  if (!primaryHandled) {
+    // No prior entry — append a new group with a single hook. We
+    // append (not prepend) so user-authored groups retain their
+    // relative order. All known claude-shape vendors fire all
+    // groups in sequence.
+    //
+    // Spread `groupFields` (e.g. Gemini's `matcher: "*"`) BEFORE
+    // `hooks` so a registry typo can't override the canonical
+    // `hooks` array. Same pattern as `entryFields` in
+    // `buildClaudeShapeEntry`.
+    const newGroup = {
+      ...(hookSpec.groupFields ?? {}),
+      hooks: [desiredEntry],
+    };
+    config.hooks[eventName].push(newGroup);
+    matchedAction = "installed";
+  } else if (foundChanged) {
+    matchedAction = "updated";
+  } else if (foundUnchangedExact) {
+    matchedAction = "unchanged";
+  } else {
+    // Defensive: unreachable. primaryHandled implies one of the two
+    // outcomes above. Leaving an explicit branch makes the future
+    // refactor's failure obvious.
+    matchedAction = "updated";
+  }
+
+  if (matchedAction === "unchanged") {
+    return {
+      path: hookSpec.displayPath,
+      action: "unchanged",
+      command: AGENT_HOOK_COMMAND,
+    };
+  }
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+
+  return {
+    path: hookSpec.displayPath,
+    action: matchedAction,
+    command: AGENT_HOOK_COMMAND,
+  };
+}
+
+/**
+ * Strip the SkillRepo cohort hook from a claude-shape vendor's hook
+ * config. Idempotent and safe under concurrent edits — non-SkillRepo
+ * hooks and unrelated event-arrays are never touched.
+ *
+ * @param {object} options
+ * @param {string} options.vendorKey
+ * @param {boolean} [options.dryRun=false]
+ * @returns {{
+ *   path: string;
+ *   action: "removed" | "would-remove" | "skipped" | "unchanged";
+ *   error?: string;
+ * }}
+ *   Action values:
+ *     - `"removed"`     — at least one matching entry stripped
+ *     - `"would-remove"`— dryRun and a matching entry exists
+ *     - `"skipped"`    — file does not exist OR is unparseable
+ *     - `"unchanged"`  — file exists, parseable, no matching entry
+ */
+export function unmergeClaudeShapeAgentHook({ vendorKey, dryRun = false }) {
+  const { hookSpec } = resolveAgent(vendorKey);
+  const filePath = hookSpec.pathFn();
+  const eventName = hookSpec.eventName;
+
+  if (!existsSync(filePath)) {
+    return { path: hookSpec.displayPath, action: "skipped" };
+  }
+
+  const raw = readFileSync(filePath, "utf-8");
+  if (raw.trim().length === 0) {
+    return { path: hookSpec.displayPath, action: "unchanged" };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    return {
+      path: hookSpec.displayPath,
+      action: "skipped",
+      error: `Cannot parse ${hookSpec.displayPath}: ${err.message}. Fix or delete the file and re-run.`,
+    };
+  }
+
+  if (
+    !config ||
+    typeof config !== "object" ||
+    !config.hooks ||
+    typeof config.hooks !== "object" ||
+    !Array.isArray(config.hooks[eventName])
+  ) {
+    return { path: hookSpec.displayPath, action: "unchanged" };
+  }
+
+  const originalGroups = config.hooks[eventName];
+  let anyRemoved = false;
+
+  const newGroups = originalGroups
+    .map((group) => {
+      if (!group || typeof group !== "object" || !Array.isArray(group.hooks)) {
+        return group;
+      }
+      const beforeCount = group.hooks.length;
+      const survivingHooks = group.hooks.filter((h) => {
+        if (!h || typeof h !== "object" || typeof h.command !== "string") {
+          return true;
+        }
+        const matches = h.command.includes(AGENT_HOOK_FINGERPRINT);
+        if (matches) {
+          anyRemoved = true;
+          return false;
+        }
+        return true;
+      });
+      if (survivingHooks.length !== beforeCount && survivingHooks.length === 0) {
+        // Whole group was ours — drop it.
+        return null;
+      }
+      if (survivingHooks.length !== beforeCount) {
+        return { ...group, hooks: survivingHooks };
+      }
+      return group;
+    })
+    .filter((g) => g !== null);
+
+  if (!anyRemoved) {
+    return { path: hookSpec.displayPath, action: "unchanged" };
+  }
+
+  if (dryRun) {
+    return { path: hookSpec.displayPath, action: "would-remove" };
+  }
+
+  // Clean up empty containers so the file doesn't accumulate dead
+  // structure: empty event-array → drop the key; empty `hooks`
+  // object → drop the key. Mirrors `removers/settings.mjs`.
+  if (newGroups.length === 0) {
+    delete config.hooks[eventName];
+  } else {
+    config.hooks[eventName] = newGroups;
+  }
+  if (Object.keys(config.hooks).length === 0) {
+    delete config.hooks;
+  }
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+  return { path: hookSpec.displayPath, action: "removed" };
+}
+
+// ── Internal helpers ───────────────────────────────────────────────
+
+/**
+ * Look up the registry entry and validate it's a claude-shape vendor.
+ * Throws `validationError` on unknown key or wrong shape — both are
+ * caller bugs the dispatcher should never produce.
+ *
+ * @param {string} vendorKey
+ * @returns {{ entry: import("../agent-registry.mjs").AgentEntry, hookSpec: import("../agent-registry.mjs").AgentHookSpec }}
+ */
+function resolveAgent(vendorKey) {
+  const entry = getAgentByKey(vendorKey);
+  if (!entry) {
+    throw validationError(
+      `Unknown agent key: ${vendorKey}. Add it to AGENT_REGISTRY.`,
+    );
+  }
+  if (!entry.agentHook) {
+    throw validationError(
+      `Agent "${vendorKey}" has no agentHook spec — cannot install a SessionStart hook.`,
+    );
+  }
+  if (entry.agentHook.shape !== "claude-shape") {
+    throw validationError(
+      `Agent "${vendorKey}" has shape "${entry.agentHook.shape}", expected "claude-shape".`,
+      {
+        hint: "Use the matching shape merger (e.g. mergeCursorShapeAgentHook).",
+      },
+    );
+  }
+  return { entry, hookSpec: entry.agentHook };
+}
+
+/**
+ * Read an existing JSON config or return an empty object. Throws a
+ * `diskError` for an unparseable non-empty file — silently overwriting
+ * a corrupt file would destroy any user-authored hooks we can't read.
+ *
+ * @param {string} filePath
+ * @param {string} displayPath - For the error message; never the
+ *        absolute path (leaks the user's home).
+ */
+function readConfigOrEmpty(filePath, displayPath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, "utf-8");
+  if (raw.trim().length === 0) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw diskError(
+      `Cannot parse ${displayPath}: ${err.message}. Fix or delete the file, then re-run.`,
+      { cause: err },
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw diskError(
+      `${displayPath} must be a JSON object at the top level.`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Deep-equal-by-JSON for two plain objects. Used to detect "identical
+ * entry already present" without imposing an order on keys (a key
+ * order change should NOT trigger an "updated" return — JSON object
+ * key order is not load-bearing for any of the target agents).
+ *
+ * The implementation re-serializes with a stable key order: this is
+ * cheap (entries are small — a `command` string plus 0–2 metadata
+ * fields) and avoids the cyclic-reference / Date / RegExp pitfalls of
+ * a recursive deep-equal. Callers must only pass JSON-safe values,
+ * which `buildClaudeShapeEntry` guarantees.
+ *
+ * @param {object} a
+ * @param {object} b
+ * @returns {boolean}
+ */
+function entriesEqual(a, b) {
+  return stableJson(a) === stableJson(b);
+}
+
+function stableJson(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  const sortedKeys = Object.keys(value).sort();
+  const parts = sortedKeys.map(
+    (k) => `${JSON.stringify(k)}:${stableJson(value[k])}`,
+  );
+  return `{${parts.join(",")}}`;
+}