@coworker-jp/aidr 0.0.1

package/src/fs-utils.mjs

@@ -0,0 +1,247 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+// Backup path: `<target>.backup-<ISO-timestamp>`.
+// Millisecond timestamp is enough for human-facing uniqueness; parallel-install
+// races within the same ms are out of scope (single-user install tool).
+export function backupPathFor(target) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return `${target}.backup-${stamp}`;
+}
+
+// Strip UTF-8 BOM and parse JSON. Prototype-pollution-safe: removes
+// "__proto__" / "constructor" / "prototype" keys at every level of the parsed
+// object so a hand-edited user config can't inject into Object.prototype when
+// later spread/merged.
+const POISON_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function sanitize(o) {
+  if (o === null || typeof o !== "object") return o;
+  if (Array.isArray(o)) { for (let i = 0; i < o.length; i++) o[i] = sanitize(o[i]); return o; }
+  for (const k of Object.keys(o)) {
+    if (POISON_KEYS.has(k)) { delete o[k]; continue; }
+    o[k] = sanitize(o[k]);
+  }
+  return o;
+}
+
+function parseJsonSafe(text, target) {
+  const stripped = text.replace(/^\uFEFF/, "");
+  if (stripped.trim() === "") return null;
+  if (/^\s*(?:\/\/|\/\*)/m.test(stripped)) {
+    throw new Error(
+      `${target} contains JS-style comments (JSONC). ` +
+      `Standard JSON doesn't allow comments — remove them and re-run.`
+    );
+  }
+  let parsed;
+  try { parsed = JSON.parse(stripped); }
+  catch (e) {
+    throw new Error(
+      `${target} is not valid JSON (${e.message}). ` +
+      `aidr refuses to overwrite a malformed config. ` +
+      `Please fix or delete the file and re-run.`
+    );
+  }
+  return sanitize(parsed);
+}
+
+// Idempotent-aware write with backup contract:
+// - missing file         → write
+// - same content present → noop (no backup, no write)
+// - different content + force   → backup existing then write (no user data lost)
+// - different content + !force  → throw (refuse to overwrite without --force)
+// - symlink               → throw (don't follow user's intentional indirection)
+//
+// Pass `backup: false` to skip backup creation entirely — use this for
+// deterministic, installer-regenerated files (shell scripts, templated
+// wrappers) that don't need to be preserved. User-owned JSON/TOML configs
+// should keep the default (backup: true).
+export async function writeFileSafe(target, content, {
+  dryRun = false,
+  force = false,
+  backup = true,
+  mode = 0o644,
+  stderr = process.stderr,
+} = {}) {
+  let stat = null;
+  try { stat = await fsp.lstat(target); }
+  catch (e) { if (e.code !== "ENOENT") throw e; }
+
+  if (stat && stat.isSymbolicLink()) {
+    throw new Error(
+      `${target} is a symlink. Refusing to overwrite. ` +
+      `Remove the symlink and re-run, or edit the target file manually.`
+    );
+  }
+
+  let backupPath = null;
+  if (stat) {
+    const existing = await fsp.readFile(target, "utf8");
+    if (existing === content) {
+      return { written: false, path: target, backupPath: null, unchanged: true };
+    }
+    if (!force) {
+      throw new Error(`refusing to overwrite ${target} (use --force)`);
+    }
+    if (backup && !dryRun) {
+      backupPath = backupPathFor(target);
+      await fsp.copyFile(target, backupPath);
+    }
+    if (backup) {
+      stderr.write(
+        `WARNING: ${target} already exists. ` +
+        `${dryRun ? "(dry-run: would back up)" : `Backed up to ${backupPath}.`}\n`
+      );
+    }
+  }
+
+  if (dryRun) {
+    process.stdout.write(`\n--- [dry-run] ${target} (${content.length} bytes) ---\n${content}\n--- end ---\n`);
+    return { written: false, path: target, backupPath: null };
+  }
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+  await fsp.writeFile(target, content, { mode });
+  await fsp.chmod(target, mode);
+  return { written: true, path: target, backupPath };
+}
+
+export async function ensureDir(p) {
+  await fsp.mkdir(p, { recursive: true });
+}
+
+export function existsSync(p) {
+  try { fs.statSync(p); return true; } catch { return false; }
+}
+
+export async function removeIfExists(p) {
+  try { await fsp.rm(p, { recursive: true, force: true }); return true; } catch { return false; }
+}
+
+// Merge ourObject into existing JSON at `target` using `mergeFn(existing, ours)`.
+// - Missing file:  writes ourObject (merged with {}).
+// - Existing file: backs up to target.backup-<ISO>, then writes merged result.
+// - Symlink:       refuses (would break the user's intentional indirection).
+// - Malformed:     refuses (don't silently discard user data).
+export async function writeJsonMerge(target, ourObject, mergeFn, {
+  dryRun = false,
+  mode = 0o644,
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  let existing = null;
+  let backupPath = null;
+
+  let stat = null;
+  try { stat = await fsp.lstat(target); }
+  catch (e) { if (e.code !== "ENOENT") throw e; }
+
+  let existingText = null;
+  if (stat) {
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `${target} is a symlink. Refusing to overwrite. ` +
+        `Remove the symlink and re-run, or edit the target file manually.`
+      );
+    }
+    existingText = await fsp.readFile(target, "utf8");
+    existing = parseJsonSafe(existingText, target) ?? {};
+  }
+
+  const merged = mergeFn(existing, ourObject);
+  const content = JSON.stringify(merged, null, 2) + "\n";
+
+  // Idempotent short-circuit: if the merge output matches the existing file
+  // byte-for-byte, skip both the backup and the write. Without this guard
+  // every rerun drops a new settings.json.backup-* file even though nothing
+  // changed, polluting the user's config dir on repeated installs.
+  if (existingText !== null && existingText === content) {
+    return { written: false, path: target, backupPath: null, unchanged: true };
+  }
+
+  if (stat && !dryRun) {
+    backupPath = backupPathFor(target);
+    await fsp.copyFile(target, backupPath);
+  }
+  if (stat) {
+    stderr.write(
+      `WARNING: ${target} already exists. ` +
+      `${dryRun ? "(dry-run: would back up)" : `Backed up to ${backupPath}.`}\n` +
+      `Merging ai-scanner env/hooks; your other settings are preserved.\n`
+    );
+  }
+
+  if (dryRun) {
+    stdout.write(
+      `\n--- [dry-run] ${target} (merged, ${content.length} bytes) ---\n${content}\n--- end ---\n`
+    );
+    return { written: false, path: target, backupPath: null };
+  }
+
+  await fsp.mkdir(path.dirname(target), { recursive: true });
+  const tmp = `${target}.aidr-tmp-${crypto.randomUUID()}`;
+  await fsp.writeFile(tmp, content, { mode });
+  await fsp.chmod(tmp, mode);
+  await fsp.rename(tmp, target);
+  return { written: true, path: target, backupPath };
+}
+
+// Reverse of writeJsonMerge: strip ai-scanner entries from existing JSON using
+// unmergeFn(existing) -> { result, empty }.
+// - File missing: no-op, returns { action: "none" }.
+// - Malformed JSON or symlink: throws (same fail-closed policy as writeJsonMerge).
+// - empty=true after unmerge: delete the file.
+// - empty=false: back up then write the stripped result.
+export async function unmergeJsonFile(target, unmergeFn, {
+  dryRun = false,
+  mode = 0o644,
+} = {}) {
+  let stat = null;
+  try { stat = await fsp.lstat(target); }
+  catch (e) { if (e.code !== "ENOENT") throw e; }
+  if (!stat) return { action: "none", path: target };
+
+  if (stat.isSymbolicLink()) {
+    throw new Error(
+      `${target} is a symlink. Refusing to modify. ` +
+      `Remove the symlink and re-run, or edit the target file manually.`
+    );
+  }
+  const text = await fsp.readFile(target, "utf8");
+  const existing = parseJsonSafe(text, target);
+
+  const { result, empty } = unmergeFn(existing);
+
+  if (dryRun) {
+    return {
+      action: empty ? "delete" : "modify",
+      path: target,
+      preview: empty ? null : (JSON.stringify(result, null, 2) + "\n"),
+    };
+  }
+
+  const backupPath = backupPathFor(target);
+  await fsp.copyFile(target, backupPath);
+
+  if (empty) {
+    await fsp.rm(target, { force: true });
+    return { action: "delete", path: target, backupPath };
+  }
+  const content = JSON.stringify(result, null, 2) + "\n";
+  const tmp = `${target}.aidr-tmp-${crypto.randomUUID()}`;
+  await fsp.writeFile(tmp, content, { mode });
+  await fsp.chmod(tmp, mode);
+  await fsp.rename(tmp, target);
+  return { action: "modify", path: target, backupPath };
+}
+
+export async function pathExists(p) {
+  try { await fsp.access(p); return true; } catch { return false; }
+}
+
+// Remove a directory only if it has become empty (rmdir errors otherwise).
+export async function rmdirIfEmpty(p) {
+  try { await fsp.rmdir(p); return true; }
+  catch { return false; }
+}

package/src/merge.mjs

@@ -0,0 +1,412 @@
+// Build-and-merge for agent settings/hooks JSON files.
+// Keeps ai-scanner's env/hooks fresh while preserving every other user key.
+//
+// Agents that merge into shared settings.json:
+//   - Claude Code (~/.claude/settings.json)
+//   - Gemini CLI  (~/.gemini/settings.json)
+//
+// Agents that merge into shared hooks.json (event → hook-entry array):
+//   - Cursor    (~/.cursor/hooks.json or <repo>/.cursor/hooks.json)
+//   - Windsurf  (~/.windsurf/hooks.json or <repo>/.windsurf/hooks.json)
+//   - Codex CLI (~/.codex/hooks.json   or <repo>/.codex/hooks.json)
+//
+// Kiro writes to a dedicated file (agents/ai-scanner.json) owned entirely by
+// aidr, so no merge is needed.
+
+// Our hook commands are identified by command-string regex rather than a
+// "_managedBy" marker field, because those marker fields aren't part of the
+// agent's official schema and could be stripped by future agent upgrades.
+
+// Anchored to the path prefix we generate in templates.mjs — either
+// `"$CLAUDE_PROJECT_DIR"`, `$CLAUDE_PROJECT_DIR`, `"$HOME"`, or `$HOME` —
+// so a user's unrelated hook at /home/u/project/.claude/coworker-ai/scan_foo.sh
+// does NOT get clobbered on uninstall.
+export const CLAUDE_OUR_COMMAND_RE =
+  /^(?:"\$(?:CLAUDE_PROJECT_DIR|HOME)"|\$(?:CLAUDE_PROJECT_DIR|HOME))\/\.claude\/coworker-ai\/(?:start_scanner|stop_scanner|scan_[a-z_]+|log_web_urls)\.sh(?:\s|$|"|')/;
+
+export const GEMINI_OUR_COMMAND_RE =
+  /ai-scanner["']?\s+scan\s+hook-gemini\b/;
+
+// Matches our Codex hook wrappers whether installed at the repo root
+// (.codex/coworker-ai/pre_shell.sh) or absolute user-scope path
+// (/home/u/.codex/coworker-ai/pre_shell.sh).
+export const CODEX_OUR_COMMAND_RE =
+  /\.codex\/coworker-ai\/(?:session_init|pre_shell|post_shell)\.sh(?:\s|$|"|')/;
+
+export const CURSOR_OUR_COMMAND_RE =
+  /\.cursor\/coworker-ai\/(?:session-init|pre_shell|pre_read|pre_edit|post_shell|post_read|post_write)\.sh(?:\s|$|"|')/;
+
+export const WINDSURF_OUR_COMMAND_RE =
+  /\.windsurf\/coworker-ai\/(?:pre_command|pre_read|pre_write|post_read|post_write)\.sh(?:\s|$|"|')/;
+
+const CLAUDE_EVENTS = ["SessionStart", "PreToolUse", "PostToolUse"];
+const GEMINI_EVENTS = ["BeforeTool", "AfterTool"];
+const CODEX_EVENTS  = ["SessionStart", "PreToolUse", "PostToolUse"];
+const CURSOR_EVENTS   = ["sessionStart", "preToolUse", "postToolUse"];
+const WINDSURF_EVENTS = [
+  "pre_run_command", "pre_read_code", "pre_write_code",
+  "post_read_code",  "post_write_code",
+];
+
+// ── Build (object form of the template) ─────────────────────────────
+
+export function buildClaudeSettings(accessKey, scope = "project") {
+  const dir = scope === "user" ? '"$HOME"' : '"$CLAUDE_PROJECT_DIR"';
+  return {
+    env: {
+      AI_SCANNER_BIN: "",
+      AI_SCANNER_EXCLUDE_DIRS: "",
+      AI_SCANNER_QUARANTINE_DAYS: "3",
+      AI_SCANNER_QUARANTINE_MODE: "scan",
+      AI_SCANNER_EXFIL_MODE: "on",
+      AI_SCANNER_WEBFETCH_YARA_THRESHOLD: "50",
+      AI_SCANNER_ACCESS_KEY: accessKey,
+      AI_SCANNER_LEVEL: "high",
+    },
+    hooks: {
+      SessionStart: [
+        { hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/start_scanner.sh`, timeout: 60 }] },
+      ],
+      PreToolUse: [
+        { matcher: "WebFetch", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/scan_webfetch.sh`, timeout: 20 }] },
+        { matcher: "Edit|MultiEdit|Write", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/scan_edit.sh`, timeout: 15 }] },
+        { matcher: "Bash", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/scan_bash_input.sh`, timeout: 15 }] },
+        { matcher: "Read", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/scan_read_input.sh`, timeout: 15 }] },
+      ],
+      PostToolUse: [
+        { matcher: "WebSearch|WebFetch", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/log_web_urls.sh`, timeout: 10 }] },
+        { matcher: "Read", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/scan_read.sh`, timeout: 15 }] },
+        { matcher: "Bash", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/scan_bash.sh`, timeout: 15 }] },
+        { matcher: "Edit|MultiEdit|Write", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/scan_edit_output.sh`, timeout: 15 }] },
+        { matcher: "WebSearch", hooks: [{ type: "command", command: `${dir}/.claude/coworker-ai/scan_websearch.sh`, timeout: 15 }] },
+      ],
+    },
+  };
+}
+
+// Codex CLI hooks.json uses the same nested structure as Claude's settings.hooks:
+//   event: [{ matcher?, hooks: [{ type: "command", command, ... }] }]
+// Only Bash tool hooks are emitted today (Codex runtime limitation).
+export function buildCodexHooksJson(scope = "project", absHome = "") {
+  const p = scope === "user" ? `${absHome}/.codex/coworker-ai` : ".codex/coworker-ai";
+  // timeout is in seconds. Codex's documented default is 600s (10 min) — far
+  // too long for an inline scan hook. Cap at 15s here so the editor kills
+  // a runaway scanner well before the user notices a stalled tool call;
+  // the in-script `run_scanner` shell timeout (12s) trips first under
+  // normal conditions.
+  return {
+    hooks: {
+      SessionStart: [
+        {
+          matcher: "startup|resume",
+          hooks: [{ type: "command", command: `bash ${p}/session_init.sh`, timeout: 30 }],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: "Bash",
+          hooks: [{
+            type: "command",
+            command: `bash ${p}/pre_shell.sh`,
+            timeout: 15,
+            statusMessage: "AIDR scan",
+          }],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: "Bash",
+          hooks: [{
+            type: "command",
+            command: `bash ${p}/post_shell.sh`,
+            timeout: 15,
+            statusMessage: "AIDR review",
+          }],
+        },
+      ],
+    },
+  };
+}
+
+// Cursor hooks.json — flat entries, each event has [{ matcher?, command, timeout? }].
+export function buildCursorHooksJson(scope = "project", absHome = "") {
+  const p = scope === "user" ? `${absHome}/.cursor/coworker-ai` : ".cursor/coworker-ai";
+  return {
+    version: 1,
+    hooks: {
+      sessionStart: [{ command: `${p}/session-init.sh`, timeout: 60 }],
+      preToolUse: [
+        { matcher: "Shell", command: `${p}/pre_shell.sh`, timeout: 15 },
+        { matcher: "Read",  command: `${p}/pre_read.sh`,  timeout: 15 },
+        { matcher: "Write", command: `${p}/pre_edit.sh`,  timeout: 15 },
+      ],
+      postToolUse: [
+        { matcher: "Shell", command: `${p}/post_shell.sh`, timeout: 15 },
+        { matcher: "Read",  command: `${p}/post_read.sh`,  timeout: 15 },
+        { matcher: "Write", command: `${p}/post_write.sh`, timeout: 15 },
+      ],
+    },
+  };
+}
+
+// Windsurf hooks.json — flat entries, one command per event (no matcher).
+export function buildWindsurfHooksJson(scope = "project", absHome = "") {
+  const p = scope === "user" ? `${absHome}/.windsurf/coworker-ai` : ".windsurf/coworker-ai";
+  return {
+    hooks: {
+      pre_run_command: [{ command: `${p}/pre_command.sh` }],
+      pre_read_code:   [{ command: `${p}/pre_read.sh` }],
+      pre_write_code:  [{ command: `${p}/pre_write.sh` }],
+      post_read_code:  [{ command: `${p}/post_read.sh` }],
+      post_write_code: [{ command: `${p}/post_write.sh` }],
+    },
+  };
+}
+
+export function buildGeminiSettings(accessKey, binary) {
+  // timeout is in milliseconds (Gemini convention). Default 60000 (1 min)
+  // is too long for an inline hook — cap at 15000 so the editor kills a
+  // hung scanner cleanly. The shell-side run_scanner cap fires first under
+  // normal conditions.
+  return {
+    env: {
+      AI_SCANNER_ACCESS_KEY: accessKey,
+      AI_SCANNER_LEVEL: "high",
+    },
+    hooks: {
+      BeforeTool: [
+        { hooks: [{ type: "command", command: `"${binary}" scan hook-gemini --stage pre`, timeout: 15000 }] },
+      ],
+      AfterTool: [
+        { hooks: [{ type: "command", command: `"${binary}" scan hook-gemini --stage post`, timeout: 15000 }] },
+      ],
+    },
+  };
+}
+
+// ── Hook identity checks ────────────────────────────────────────────
+
+export function isOurClaudeHook(hook) {
+  return !!hook
+    && hook.type === "command"
+    && typeof hook.command === "string"
+    && CLAUDE_OUR_COMMAND_RE.test(hook.command);
+}
+
+export function isOurGeminiHook(hook) {
+  return !!hook
+    && hook.type === "command"
+    && typeof hook.command === "string"
+    && GEMINI_OUR_COMMAND_RE.test(hook.command);
+}
+
+// Codex hooks live inside nested .hooks arrays (same shape as Claude).
+export function isOurCodexHook(hook) {
+  return !!hook
+    && hook.type === "command"
+    && typeof hook.command === "string"
+    && CODEX_OUR_COMMAND_RE.test(hook.command);
+}
+
+// Cursor / Windsurf entries are flat — no inner "hooks" array, the command
+// lives directly on the entry itself.
+export function isOurCursorEntry(entry) {
+  return !!entry
+    && typeof entry.command === "string"
+    && CURSOR_OUR_COMMAND_RE.test(entry.command);
+}
+
+export function isOurWindsurfEntry(entry) {
+  return !!entry
+    && typeof entry.command === "string"
+    && WINDSURF_OUR_COMMAND_RE.test(entry.command);
+}
+
+// ── Merge ───────────────────────────────────────────────────────────
+
+function mergeHooksForEvents(existingHooks, ourHooks, events, isOurHook) {
+  const merged = { ...(existingHooks && typeof existingHooks === "object" ? existingHooks : {}) };
+  for (const event of events) {
+    const cleaned = Array.isArray(merged[event])
+      ? merged[event]
+          .map((entry) => {
+            const filtered = Array.isArray(entry?.hooks)
+              ? entry.hooks.filter((h) => !isOurHook(h))
+              : [];
+            return { ...entry, hooks: filtered };
+          })
+          .filter((entry) => entry.hooks.length > 0)
+      : [];
+    merged[event] = [...cleaned, ...(ourHooks[event] || [])];
+  }
+  return merged;
+}
+
+function mergeSettings(existing, ours, events, isOurHook) {
+  // structuredClone preserves every user top-level key untouched (permissions,
+  // statusLine, model, mcpServers, apiKeyHelper, enableAllProjectMcpServers,
+  // …). We only overwrite env / hooks selectively below.
+  const merged = existing && typeof existing === "object"
+    ? structuredClone(existing)
+    : {};
+
+  merged.env = {
+    ...(merged.env && typeof merged.env === "object" ? merged.env : {}),
+    ...ours.env,
+  };
+
+  merged.hooks = mergeHooksForEvents(merged.hooks, ours.hooks, events, isOurHook);
+
+  return merged;
+}
+
+export function mergeClaudeSettings(existing, ours) {
+  return mergeSettings(existing, ours, CLAUDE_EVENTS, isOurClaudeHook);
+}
+
+export function mergeGeminiSettings(existing, ours) {
+  return mergeSettings(existing, ours, GEMINI_EVENTS, isOurGeminiHook);
+}
+
+// ── Unmerge (for uninstall) ─────────────────────────────────────────
+// Strip ai-scanner's env keys + our hooks from an existing settings object.
+// Returns { result, empty } — empty=true means the settings are now effectively
+// blank so the file can be deleted entirely.
+
+function stripAiScannerEnv(env) {
+  if (!env || typeof env !== "object") return env;
+  const next = { ...env };
+  for (const key of Object.keys(next)) {
+    if (key.startsWith("AI_SCANNER_")) delete next[key];
+  }
+  return next;
+}
+
+function stripOurHooks(hooks, events, isOurHook) {
+  if (!hooks || typeof hooks !== "object") return hooks;
+  const next = { ...hooks };
+  for (const event of events) {
+    if (!Array.isArray(next[event])) continue;
+    const cleaned = next[event]
+      .map((entry) => ({
+        ...entry,
+        hooks: Array.isArray(entry?.hooks)
+          ? entry.hooks.filter((h) => !isOurHook(h))
+          : [],
+      }))
+      .filter((entry) => entry.hooks.length > 0);
+    if (cleaned.length === 0) delete next[event];
+    else next[event] = cleaned;
+  }
+  return next;
+}
+
+function unmergeSettings(existing, events, isOurHook) {
+  if (!existing || typeof existing !== "object") return { result: null, empty: true };
+  const next = structuredClone(existing);
+
+  if (next.env) {
+    next.env = stripAiScannerEnv(next.env);
+    if (Object.keys(next.env).length === 0) delete next.env;
+  }
+
+  if (next.hooks) {
+    next.hooks = stripOurHooks(next.hooks, events, isOurHook);
+    if (Object.keys(next.hooks).length === 0) delete next.hooks;
+  }
+
+  const empty = Object.keys(next).length === 0;
+  return { result: empty ? null : next, empty };
+}
+
+export function unmergeClaudeSettings(existing) {
+  return unmergeSettings(existing, CLAUDE_EVENTS, isOurClaudeHook);
+}
+
+export function unmergeGeminiSettings(existing) {
+  return unmergeSettings(existing, GEMINI_EVENTS, isOurGeminiHook);
+}
+
+// ── Codex / Cursor / Windsurf hooks.json ────────────────────────────
+// Top-level shape: { hooks: { <event>: [entry, ...], ... }, ...otherUserKeys }.
+// Codex event entries wrap a nested .hooks[] array (reuse nested merger).
+// Cursor + Windsurf event entries are flat ({ matcher?, command }).
+
+function mergeHooksFlatForEvents(existingHooks, ourHooks, events, isOurEntry) {
+  const merged = { ...(existingHooks && typeof existingHooks === "object" ? existingHooks : {}) };
+  for (const event of events) {
+    const cleaned = Array.isArray(merged[event])
+      ? merged[event].filter((entry) => !isOurEntry(entry))
+      : [];
+    merged[event] = [...cleaned, ...(ourHooks[event] || [])];
+  }
+  return merged;
+}
+
+function mergeHooksTopLevel(existing, ours, events, mergeFn) {
+  const merged = existing && typeof existing === "object"
+    ? structuredClone(existing)
+    : {};
+  merged.hooks = mergeFn(merged.hooks, ours.hooks, events);
+  // Preserve user top-level keys (version, etc.). Copy non-reserved keys from ours.
+  for (const key of Object.keys(ours)) {
+    if (key === "hooks") continue;
+    if (merged[key] === undefined) merged[key] = ours[key];
+  }
+  return merged;
+}
+
+export function mergeCodexHooksJson(existing, ours) {
+  return mergeHooksTopLevel(existing, ours, CODEX_EVENTS,
+    (e, o, ev) => mergeHooksForEvents(e, o, ev, isOurCodexHook));
+}
+
+export function mergeCursorHooksJson(existing, ours) {
+  return mergeHooksTopLevel(existing, ours, CURSOR_EVENTS,
+    (e, o, ev) => mergeHooksFlatForEvents(e, o, ev, isOurCursorEntry));
+}
+
+export function mergeWindsurfHooksJson(existing, ours) {
+  return mergeHooksTopLevel(existing, ours, WINDSURF_EVENTS,
+    (e, o, ev) => mergeHooksFlatForEvents(e, o, ev, isOurWindsurfEntry));
+}
+
+// ── Unmerge for hooks.json variants ─────────────────────────────────
+
+function stripOurFlatHooks(hooks, events, isOurEntry) {
+  if (!hooks || typeof hooks !== "object") return hooks;
+  const next = { ...hooks };
+  for (const event of events) {
+    if (!Array.isArray(next[event])) continue;
+    const cleaned = next[event].filter((entry) => !isOurEntry(entry));
+    if (cleaned.length === 0) delete next[event];
+    else next[event] = cleaned;
+  }
+  return next;
+}
+
+function unmergeHooksJson(existing, stripFn) {
+  if (!existing || typeof existing !== "object") return { result: null, empty: true };
+  const next = structuredClone(existing);
+  if (next.hooks) {
+    next.hooks = stripFn(next.hooks);
+    if (Object.keys(next.hooks).length === 0) delete next.hooks;
+  }
+  const empty = Object.keys(next).length === 0;
+  return { result: empty ? null : next, empty };
+}
+
+export function unmergeCodexHooksJson(existing) {
+  return unmergeHooksJson(existing,
+    (h) => stripOurHooks(h, CODEX_EVENTS, isOurCodexHook));
+}
+
+export function unmergeCursorHooksJson(existing) {
+  return unmergeHooksJson(existing,
+    (h) => stripOurFlatHooks(h, CURSOR_EVENTS, isOurCursorEntry));
+}
+
+export function unmergeWindsurfHooksJson(existing) {
+  return unmergeHooksJson(existing,
+    (h) => stripOurFlatHooks(h, WINDSURF_EVENTS, isOurWindsurfEntry));
+}