baldart 3.19.0 → 3.21.2

package/src/utils/hooks.js

@@ -1,28 +1,105 @@
 /**
  * Consumer-side hook registration for `.claude/settings.json`.
  *
- * BALDART ships a Claude Code PreToolUse hook (`framework-edit-gate`) that
- * intercepts Edit / Write / MultiEdit calls targeting files inside
- * `.framework/` and blocks them with an informative reason if the new
- * content contains project-specific tokens (Neo-Brutalism, merchant,
- * Recharts, secrets, hardcoded paths, …).
+ * BALDART ships one or more Claude Code hooks (PreToolUse, Stop, SessionStart,
+ * …) that are auto-registered in the consumer's `.claude/settings.json` on
+ * `baldart add` and re-checked on `baldart update` / `baldart doctor`.
  *
- * Registration is auto-handled by `baldart add` and re-checked by
- * `baldart update` / `baldart doctor`. The user can remove the entry from
- * `.claude/settings.json` if they want to disable it.
+ * **Multi-hook architecture (since v3.18.0)**
  *
- * Schema: the hook config under `hooks.PreToolUse[]` follows Claude Code's
- * documented hook format. Each entry has a `matcher` (tool name regex) and
- * an inner `hooks[]` array of `{ type: "command", command: <shell> }`.
+ * Hook definitions live in `HOOK_REGISTRY` below — adding a hook is a matter
+ * of appending one entry. Every register/unregister/status operation iterates
+ * the registry, so call sites don't change when we ship a new hook.
+ *
+ * Each hook entry carries:
+ *   - `id`          stable marker stored in settings.json under `hooks[].id`
+ *   - `event`       Claude Code event (`PreToolUse`, `Stop`, `SessionStart`, …)
+ *   - `matcher`     tool-name regex (use '*' for events that don't take one)
+ *   - `command`     shell command Claude Code runs
+ *   - `order`       sort key when this hook coexists with other BALDART hooks
+ *                   on the same event (lower runs first)
+ *   - `legacyMatch` (optional) substring that identifies pre-v3.18 entries
+ *                   when migrating consumers from the single-hook layout
+ *
+ * **Drift policy**
+ *
+ * When an existing entry matches our `id` but its `command` differs, we don't
+ * silently rewrite it — that would obliterate user customizations. Instead we
+ * call back to `onDrift({ id, event, matcher, expected, actual })` and expect
+ * `'keep'` or `'replace'`. Callers wire `onDrift` to an inquirer prompt
+ * (with a `'diff'` option that shows the diff and re-prompts). The default
+ * when `onDrift` is not provided is `'keep'` — safe for non-interactive runs.
+ *
+ * **Failure isolation**
+ *
+ * Claude Code's runtime executes hooks on the same event in array order and
+ * isolates failures itself (a non-zero exit from a Stop/SessionStart hook
+ * does not block the others). Our only responsibility is to never corrupt
+ * the array of hooks the user has set up themselves — entries we don't own
+ * (no `id` of ours, no `legacyMatch` of ours) are preserved verbatim and
+ * stay in their original position.
  */
 
 const fs = require('fs');
 const path = require('path');
 
 const SETTINGS_FILE = path.join('.claude', 'settings.json');
-const HOOK_ID = 'baldart-framework-edit-gate';
-const HOOK_COMMAND = 'node .framework/framework/.claude/hooks/framework-edit-gate.js';
-const HOOK_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+
+/** @typedef {Object} HookDef
+ *  @property {string} id
+ *  @property {string} event       Claude Code event name
+ *  @property {string} matcher     tool-name regex, or '*' for matcherless events
+ *  @property {string} command     shell command
+ *  @property {number} order       ascending sort key among BALDART hooks on same event
+ *  @property {string} [legacyMatch] substring marker for pre-v3.18 entries to migrate
+ */
+
+/** @type {HookDef[]} */
+const HOOK_REGISTRY = [
+  {
+    id: 'baldart-framework-edit-gate',
+    event: 'PreToolUse',
+    matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+    command: 'node .framework/framework/.claude/hooks/framework-edit-gate.js',
+    order: 100,
+    legacyMatch: 'framework-edit-gate.js',
+  },
+  {
+    // Denies `Agent` tool calls whose subagent_type matches a BALDART agent
+    // name but the consumer's .claude/agents/<name>.md is missing or its
+    // symlink is broken. Mitigates anthropics/claude-code#56869 (silent
+    // sub-agent fallback) and #20931 (broken file-based discovery) for the
+    // filesystem-detectable subset.
+    id: 'baldart-agent-discovery-gate',
+    event: 'PreToolUse',
+    matcher: 'Agent',
+    command: 'node .framework/framework/.claude/hooks/agent-discovery-gate.js',
+    order: 200,
+  },
+  {
+    // Injects an additionalContext warning at session start listing BALDART
+    // agents whose .claude/agents/<name>.md is missing. Best-effort early
+    // signal (Claude Code #10373 may suppress injection on new
+    // conversations) — the blocking counterpart is agent-discovery-gate.
+    id: 'baldart-agent-discovery-info',
+    event: 'SessionStart',
+    matcher: '*',
+    command: 'bash .framework/framework/.claude/hooks/agent-discovery-info.sh',
+    order: 100,
+  },
+  // Future hooks (T1.3, T1.4, T2.3) will be appended here, e.g.:
+  // {
+  //   id: 'baldart-capture-detect',
+  //   event: 'Stop',
+  //   matcher: '*',
+  //   command: 'bash .framework/framework/.claude/hooks/capture-detect.sh',
+  //   order: 100,
+  // },
+];
+
+// ---------------------------------------------------------------------------
+// settings.json I/O
+// ---------------------------------------------------------------------------
 
 function readSettings(cwd = process.cwd()) {
   const full = path.join(cwd, SETTINGS_FILE);
@@ -41,112 +118,306 @@ function writeSettings(settingsPath, settings) {
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
 }
 
+// ---------------------------------------------------------------------------
+// Internal: locate an entry that owns a given hook definition
+// ---------------------------------------------------------------------------
+
 /**
- * Returns true iff the framework-edit-gate hook is already registered in
- * `.claude/settings.json` (matching either by command string or by the
- * HOOK_ID marker we plant in a sibling property).
+ * Walks `settings.hooks[event]` and returns the first entry/hook pair whose
+ * `id` matches, or whose `command` contains `legacyMatch` (pre-v3.18 layout).
+ * Returns `null` when the hook is not yet registered.
  */
-function isRegistered(cwd = process.cwd()) {
-  const { settings } = readSettings(cwd);
-  if (!settings || !settings.hooks || !Array.isArray(settings.hooks.PreToolUse)) return false;
-  for (const entry of settings.hooks.PreToolUse) {
+function findOwnedEntry(eventList, def) {
+  if (!Array.isArray(eventList)) return null;
+  for (let i = 0; i < eventList.length; i++) {
+    const entry = eventList[i];
     if (!entry || !Array.isArray(entry.hooks)) continue;
-    for (const h of entry.hooks) {
+    for (let j = 0; j < entry.hooks.length; j++) {
+      const h = entry.hooks[j];
       if (!h) continue;
-      if (h.id === HOOK_ID) return true;
-      if (h.type === 'command' && typeof h.command === 'string') {
-        if (h.command.includes('framework-edit-gate.js')) return true;
+      if (h.id === def.id) return { entryIdx: i, hookIdx: j, entry, hook: h, byLegacy: false };
+      if (def.legacyMatch && h.type === 'command'
+          && typeof h.command === 'string' && h.command.includes(def.legacyMatch)) {
+        return { entryIdx: i, hookIdx: j, entry, hook: h, byLegacy: true };
       }
     }
   }
-  return false;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Status — read-only inspection of every hook in the registry
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} HookStatus
+ * @property {string} id
+ * @property {string} event
+ * @property {boolean} registered  hook with this id exists in settings.json
+ * @property {boolean} drift       registered but command differs from expected
+ * @property {boolean} legacy      matched only by legacyMatch (id is missing)
+ * @property {string} expected     command BALDART wants
+ * @property {string} [actual]     command currently in settings.json (when registered)
+ */
+
+/**
+ * Returns the status of every hook in the registry. Pure read; never writes.
+ *
+ * @param {string} cwd
+ * @returns {{ malformed: boolean, path: string, hooks: HookStatus[] }}
+ */
+function getStatus(cwd = process.cwd()) {
+  const { path: settingsPath, settings, malformed } = readSettings(cwd);
+  if (malformed) {
+    return { malformed: true, path: settingsPath, hooks: [] };
+  }
+  const allHooks = (settings && settings.hooks) || {};
+  const hooks = HOOK_REGISTRY.map((def) => {
+    const found = findOwnedEntry(allHooks[def.event], def);
+    if (!found) {
+      return {
+        id: def.id, event: def.event,
+        registered: false, drift: false, legacy: false,
+        expected: def.command,
+      };
+    }
+    const actual = found.hook.command;
+    return {
+      id: def.id, event: def.event,
+      registered: true,
+      drift: actual !== def.command,
+      legacy: found.byLegacy,
+      expected: def.command,
+      actual,
+    };
+  });
+  return { malformed: false, path: settingsPath, hooks };
 }
 
+// ---------------------------------------------------------------------------
+// Register — write path with drift callback
+// ---------------------------------------------------------------------------
+
 /**
- * Register the hook idempotently. Returns:
- *   { status: 'created', path }     — settings.json created from scratch
- *   { status: 'updated', path }     — existing settings.json merged
- *   { status: 'already', path }     — hook was already registered, no-op
- *   { status: 'malformed', path }   — existing settings.json is invalid JSON
+ * Idempotently register every hook in the registry.
+ *
+ * @param {string} [cwd]
+ * @param {Object} [options]
+ * @param {(info: { id: string, event: string, matcher: string,
+ *                  expected: string, actual: string })
+ *           => Promise<'keep'|'replace'>|('keep'|'replace')} [options.onDrift]
+ *        Called when a hook with our `id` exists but command differs.
+ *        Default: `'keep'` (safe for non-interactive / CI).
+ * @returns {Promise<{ malformed: boolean, path: string,
+ *                     created: boolean, updated: boolean,
+ *                     results: Array<{ id: string, status:
+ *                       'created'|'already'|'drift-replaced'|'drift-kept'|'legacy-migrated',
+ *                       previousCommand?: string }> }>}
  */
-function register(cwd = process.cwd()) {
+async function registerAll(cwd = process.cwd(), options = {}) {
+  const onDrift = typeof options.onDrift === 'function'
+    ? options.onDrift
+    : () => 'keep';
+
   const { path: settingsPath, settings: existing, malformed } = readSettings(cwd);
-  if (malformed) return { status: 'malformed', path: settingsPath };
+  if (malformed) {
+    return { malformed: true, path: settingsPath, created: false, updated: false, results: [] };
+  }
 
-  const settings = existing && typeof existing === 'object' ? { ...existing } : {};
+  const wasNew = !existing;
+  const settings = existing && typeof existing === 'object' ? structuredClone(existing) : {};
   settings.hooks = settings.hooks && typeof settings.hooks === 'object'
-    ? { ...settings.hooks }
+    ? settings.hooks
     : {};
 
-  const list = Array.isArray(settings.hooks.PreToolUse) ? [...settings.hooks.PreToolUse] : [];
+  const results = [];
+  let modified = false;
 
-  // Already present?
-  for (const entry of list) {
-    if (!entry || !Array.isArray(entry.hooks)) continue;
-    for (const h of entry.hooks) {
-      if (!h) continue;
-      if (h.id === HOOK_ID) return { status: 'already', path: settingsPath };
-      if (h.type === 'command' && typeof h.command === 'string'
-          && h.command.includes('framework-edit-gate.js')) {
-        return { status: 'already', path: settingsPath };
-      }
+  for (const def of HOOK_REGISTRY) {
+    const list = Array.isArray(settings.hooks[def.event])
+      ? settings.hooks[def.event]
+      : [];
+
+    const found = findOwnedEntry(list, def);
+
+    if (!found) {
+      list.push({
+        matcher: def.matcher,
+        hooks: [{ id: def.id, type: 'command', command: def.command }],
+      });
+      settings.hooks[def.event] = list;
+      results.push({ id: def.id, status: 'created' });
+      modified = true;
+      continue;
+    }
+
+    if (found.byLegacy) {
+      // Pre-v3.18 entry: stamp our id on it and align the command.
+      const previousCommand = found.hook.command;
+      found.hook.id = def.id;
+      found.hook.command = def.command;
+      results.push({ id: def.id, status: 'legacy-migrated', previousCommand });
+      modified = true;
+      continue;
+    }
+
+    if (found.hook.command === def.command) {
+      results.push({ id: def.id, status: 'already' });
+      continue;
+    }
+
+    // Drift: same id, different command. Ask the caller.
+    const decision = await onDrift({
+      id: def.id,
+      event: def.event,
+      matcher: def.matcher,
+      expected: def.command,
+      actual: found.hook.command,
+    });
+
+    if (decision === 'replace') {
+      const previousCommand = found.hook.command;
+      found.hook.command = def.command;
+      results.push({ id: def.id, status: 'drift-replaced', previousCommand });
+      modified = true;
+    } else {
+      results.push({
+        id: def.id, status: 'drift-kept', previousCommand: found.hook.command,
+      });
     }
   }
 
-  list.push({
-    matcher: HOOK_MATCHER,
-    hooks: [{
-      id: HOOK_ID,
-      type: 'command',
-      command: HOOK_COMMAND,
-    }],
-  });
+  if (modified) writeSettings(settingsPath, settings);
 
-  settings.hooks.PreToolUse = list;
-  writeSettings(settingsPath, settings);
-  return { status: existing ? 'updated' : 'created', path: settingsPath };
+  return {
+    malformed: false,
+    path: settingsPath,
+    created: modified && wasNew,
+    updated: modified && !wasNew,
+    results,
+  };
 }
 
+// ---------------------------------------------------------------------------
+// Unregister — remove every BALDART hook from settings.json
+// ---------------------------------------------------------------------------
+
 /**
- * Remove the hook from settings.json. Used by tests and as an undo helper.
+ * Remove every hook defined in the registry from settings.json. Idempotent.
+ *
+ * @param {string} [cwd]
+ * @returns {{ malformed: boolean, path: string,
+ *             results: Array<{ id: string, status: 'removed'|'not-found' }> }}
  */
-function unregister(cwd = process.cwd()) {
+function unregisterAll(cwd = process.cwd()) {
   const { path: settingsPath, settings, malformed } = readSettings(cwd);
-  if (malformed || !settings || !settings.hooks || !Array.isArray(settings.hooks.PreToolUse)) {
-    return { status: 'not-found', path: settingsPath };
+  if (malformed || !settings || !settings.hooks) {
+    return {
+      malformed,
+      path: settingsPath,
+      results: HOOK_REGISTRY.map((d) => ({ id: d.id, status: 'not-found' })),
+    };
   }
 
-  const filtered = settings.hooks.PreToolUse
-    .map((entry) => {
-      if (!entry || !Array.isArray(entry.hooks)) return entry;
-      const innerKept = entry.hooks.filter((h) => {
-        if (!h) return true;
-        if (h.id === HOOK_ID) return false;
-        if (h.type === 'command' && typeof h.command === 'string'
-            && h.command.includes('framework-edit-gate.js')) return false;
-        return true;
-      });
-      if (innerKept.length === 0) return null;
-      return { ...entry, hooks: innerKept };
-    })
-    .filter(Boolean);
+  const next = structuredClone(settings);
+  const results = [];
+  let modified = false;
 
-  if (filtered.length === settings.hooks.PreToolUse.length) {
-    return { status: 'not-found', path: settingsPath };
+  for (const def of HOOK_REGISTRY) {
+    const list = Array.isArray(next.hooks[def.event]) ? next.hooks[def.event] : null;
+    if (!list) {
+      results.push({ id: def.id, status: 'not-found' });
+      continue;
+    }
+    let removed = false;
+    const filtered = list
+      .map((entry) => {
+        if (!entry || !Array.isArray(entry.hooks)) return entry;
+        const innerKept = entry.hooks.filter((h) => {
+          if (!h) return true;
+          if (h.id === def.id) { removed = true; return false; }
+          if (def.legacyMatch && h.type === 'command'
+              && typeof h.command === 'string' && h.command.includes(def.legacyMatch)) {
+            removed = true;
+            return false;
+          }
+          return true;
+        });
+        if (innerKept.length === 0) return null;
+        return { ...entry, hooks: innerKept };
+      })
+      .filter(Boolean);
+
+    if (removed) {
+      if (filtered.length === 0) {
+        delete next.hooks[def.event];
+      } else {
+        next.hooks[def.event] = filtered;
+      }
+      modified = true;
+      results.push({ id: def.id, status: 'removed' });
+    } else {
+      results.push({ id: def.id, status: 'not-found' });
+    }
   }
 
-  const next = { ...settings, hooks: { ...settings.hooks, PreToolUse: filtered } };
-  if (next.hooks.PreToolUse.length === 0) delete next.hooks.PreToolUse;
   if (Object.keys(next.hooks).length === 0) delete next.hooks;
-  writeSettings(settingsPath, next);
-  return { status: 'removed', path: settingsPath };
+  if (modified) writeSettings(settingsPath, next);
+
+  return { malformed: false, path: settingsPath, results };
+}
+
+// ---------------------------------------------------------------------------
+// Drift prompt helper (interactive Keep / Replace / Show diff)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an `onDrift` callback suitable for `registerAll`. Wraps inquirer via
+ * the project's UI helper so the CLI output stays consistent.
+ *
+ * @param {Object} UI                 the `src/utils/ui.js` module (avoids a
+ *                                    circular require by accepting it from
+ *                                    the caller)
+ * @param {Object} [options]
+ * @param {boolean} [options.autoYes] non-interactive mode: skip prompt and
+ *                                    always return 'keep' (safe default)
+ * @returns {(info: {id:string, event:string, expected:string, actual:string})
+ *           => Promise<'keep'|'replace'>}
+ */
+function createDriftPrompt(UI, { autoYes = false } = {}) {
+  if (autoYes) {
+    return async ({ id }) => {
+      UI.warning(`Hook drift detected for \`${id}\` — keeping current command (auto mode). Run \`baldart doctor\` interactively to resolve.`);
+      return 'keep';
+    };
+  }
+
+  const truncate = (s, n = 70) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+  return async function onDrift({ id, event, expected, actual }) {
+    UI.warning(`Hook \`${id}\` (${event}) is registered with a non-default command.`);
+    // Loop while the user keeps choosing 'diff'
+    for (;;) {
+      const choice = await UI.select(
+        `What do you want to do with \`${id}\`?`,
+        [
+          { name: `Keep current        — leave: ${truncate(actual)}`,        value: 'keep' },
+          { name: `Replace with BALDART — set:  ${truncate(expected)}`,      value: 'replace' },
+          { name: `Show full diff and decide`,                               value: 'diff' },
+        ],
+      );
+      if (choice !== 'diff') return choice;
+      console.log(`  expected: ${expected}`);
+      console.log(`  actual:   ${actual}`);
+    }
+  };
 }
 
 module.exports = {
-  isRegistered,
-  register,
-  unregister,
-  HOOK_ID,
-  HOOK_COMMAND,
+  HOOK_REGISTRY,
   SETTINGS_FILE,
+  getStatus,
+  registerAll,
+  unregisterAll,
+  createDriftPrompt,
 };