baldart 4.86.0 → 4.88.0

package/src/commands/doctor.js

@@ -274,6 +274,31 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) {}
 
+    // ---- Codex hook health (S2) ----------------------------------------
+    // Probe .codex/hooks.json when Codex is an enabled tool. Reports missing /
+    // drifted / untrusted separately — hook trust is an interactive Codex step
+    // BALDART cannot complete, so `untrusted` is advisory, never a hard failure.
+    state.codexHooksEnabled = false;
+    state.codexHooksStatus = { malformed: false, hooks: [] };
+    state.codexHooksMissing = [];
+    state.codexHooksDrifted = [];
+    state.codexHooksUntrusted = [];
+    try {
+      const toolsEnabled = (config && !config.__malformed && config.tools && Array.isArray(config.tools.enabled))
+        ? config.tools.enabled : ['claude'];
+      if (toolsEnabled.includes('codex')) {
+        state.codexHooksEnabled = true;
+        const CodexHooks = require('../utils/hooks/codex');
+        const cstatus = CodexHooks.getStatus(cwd);
+        state.codexHooksStatus = cstatus;
+        if (!cstatus.malformed) {
+          state.codexHooksMissing   = cstatus.hooks.filter((h) => !h.registered).map((h) => h.id);
+          state.codexHooksDrifted   = cstatus.hooks.filter((h) => h.registered && h.drift).map((h) => h.id);
+          state.codexHooksUntrusted = cstatus.hooks.filter((h) => h.registered && !h.trusted).map((h) => h.id);
+        }
+      }
+    } catch (_) {}
+
     // ---- Git-hooks health (since v3.34.0) ------------------------------
     // Assert that the repo's versioned git hooks (pre-commit/pre-push/…) are
     // actually being run — i.e. `core.hooksPath` resolves to the directory
@@ -811,6 +836,53 @@ function planActions(state) {
     });
   }
 
+  // Codex hooks (S2). Same three buckets in .codex/hooks.json, gated on Codex
+  // being an enabled tool. Trust is NOT repaired here (BALDART never fakes hook
+  // trust) — it is surfaced in reportStatus as an advisory.
+  if (state.codexHooksEnabled && state.codexHooksMissing && state.codexHooksMissing.length > 0) {
+    actions.push({
+      key: 'register-codex-hooks',
+      label: `Register BALDART hook(s) in .codex/hooks.json (${state.codexHooksMissing.join(', ')})`,
+      why: 'Codex is an enabled tool but one or more BALDART hooks are missing from .codex/hooks.json. Registration is additive (Graphify and user hooks are preserved) and idempotent. After it runs, Codex will ask you to approve the new hook(s) once (hook trust) before they activate.',
+      autoOk: true,
+      run: async () => {
+        const CodexHooks = require('../utils/hooks/codex');
+        const res = await CodexHooks.registerAll(process.cwd(), {
+          onDrift: CodexHooks.createDriftPrompt(UI, { autoYes: state.autoMode }),
+        });
+        if (res.malformed) {
+          UI.warning('.codex/hooks.json is malformed; fix it manually then re-run `npx baldart doctor`.');
+          return;
+        }
+        for (const r of res.results) {
+          if (r.status === 'created') UI.success(`Registered Codex hook \`${r.id}\``);
+        }
+        const cv = CodexHooks.verifyAll(process.cwd());
+        if (cv.untrusted && cv.untrusted.length) {
+          UI.info(`Approve ${cv.untrusted.length} new hook(s) on the next Codex session (hook trust): ${cv.untrusted.join(', ')}.`);
+        }
+      },
+    });
+  }
+  if (state.codexHooksEnabled && state.codexHooksDrifted && state.codexHooksDrifted.length > 0) {
+    actions.push({
+      key: 'reconcile-codex-hooks-drift',
+      label: `Reconcile drifted Codex hook(s) (${state.codexHooksDrifted.join(', ')})`,
+      why: 'These Codex hooks are registered in .codex/hooks.json but their command differs from the BALDART default. Reconciliation prompts you per hook (Keep / Replace / Show diff).',
+      autoOk: false,
+      run: async () => {
+        const CodexHooks = require('../utils/hooks/codex');
+        const res = await CodexHooks.registerAll(process.cwd(), {
+          onDrift: CodexHooks.createDriftPrompt(UI),
+        });
+        for (const r of res.results) {
+          if (r.status === 'drift-replaced') UI.success(`Replaced Codex hook \`${r.id}\` (was: ${r.previousCommand})`);
+          else if (r.status === 'drift-kept') UI.info(`Kept Codex hook \`${r.id}\` as-is.`);
+        }
+      },
+    });
+  }
+
   // Git-hooks health (since v3.34.0). ADVISORY ONLY — the action's run() never
   // mutates `core.hooksPath` (a wrong heuristic + auto-fix is worse than the
   // original silent-inactive bug). It surfaces the WARN + the exact remediation
@@ -1448,6 +1520,38 @@ function renderDiagnostic(state) {
       console.log(`   • pre-v3.18: ${state.hooksLegacy.join(', ')}`);
   }
 
+  // Codex hooks (S2). Only shown when Codex is an enabled tool. Trust is
+  // reported separately from presence: a hook can be correctly configured yet
+  // awaiting the user's one-time Codex trust approval.
+  if (state.codexHooksEnabled) {
+    const total = state.codexHooksStatus && state.codexHooksStatus.hooks ? state.codexHooksStatus.hooks.length : 0;
+    const missing = state.codexHooksMissing ? state.codexHooksMissing.length : 0;
+    const drifted = state.codexHooksDrifted ? state.codexHooksDrifted.length : 0;
+    const untrusted = state.codexHooksUntrusted ? state.codexHooksUntrusted.length : 0;
+    const registered = total - missing;
+    let summary; let status;
+    if (state.codexHooksStatus && state.codexHooksStatus.malformed) {
+      summary = '.codex/hooks.json is malformed';
+      status = 'warn';
+    } else if (missing === 0 && drifted === 0 && untrusted === 0) {
+      summary = `${registered}/${total} registered & trusted`;
+      status = 'ok';
+    } else {
+      const parts = [`${registered}/${total} registered`];
+      if (missing) parts.push(`${missing} missing`);
+      if (drifted) parts.push(`${drifted} drifted`);
+      if (untrusted) parts.push(`${untrusted} untrusted`);
+      summary = parts.join(', ');
+      // Untrusted-only is not a defect (it needs an interactive Codex approval),
+      // so it stays 'ok'-toned unless something is actually missing/drifted.
+      status = (missing || drifted) ? 'warn' : 'ok';
+    }
+    console.log(statusLine('Codex hooks', summary, status));
+    if (missing) console.log(`   • missing:   ${state.codexHooksMissing.join(', ')}`);
+    if (drifted) console.log(`   • drifted:   ${state.codexHooksDrifted.join(', ')}`);
+    if (untrusted) console.log(`   • untrusted: ${state.codexHooksUntrusted.join(', ')} (approve once on the next Codex session)`);
+  }
+
   // Git-hooks health (v3.34.0+). Silent when no versioned-hooks dir exists
   // (`checked:false`) — most consumers have no managed git hooks and must see
   // zero noise here.

package/src/commands/update.js

@@ -1315,6 +1315,37 @@ async function update(options = {}, unknownArgs = []) {
       UI.warning(`Hook registration skipped: ${err.message}`);
     }
 
+    // Codex hooks (S2) — backfill the framework-edit-gate (PreToolUse/apply_patch)
+    // + agent-discovery-info (SessionStart) hooks into .codex/hooks.json when
+    // Codex is an enabled tool. Additive: foreign entries (Graphify, user hooks)
+    // are preserved; hook trust is NEVER faked (Codex asks the user to approve
+    // new/changed hooks on the next session — surfaced below).
+    if (Array.isArray(enabledTools) && enabledTools.includes('codex')) {
+      try {
+        const CodexHooks = require('../utils/hooks/codex');
+        const res = await CodexHooks.registerAll(process.cwd(), {
+          onDrift: CodexHooks.createDriftPrompt(UI, { autoYes }),
+        });
+        if (res.malformed) {
+          UI.warning('.codex/hooks.json is malformed; skipped Codex hook registration. Run `npx baldart doctor` after fixing it.');
+        } else {
+          const created = res.results.filter((r) => r.status === 'created').map((r) => r.id);
+          if (created.length === 1) UI.success(`Registered Codex hook \`${created[0]}\` in .codex/hooks.json.`);
+          else if (created.length > 1) UI.success(`Auto-registered ${created.length} Codex hook(s): ${created.join(', ')}.`);
+          for (const r of res.results) {
+            if (r.status === 'drift-replaced') UI.success(`Replaced drifted Codex hook \`${r.id}\` (was: ${r.previousCommand})`);
+            else if (r.status === 'drift-kept') UI.info(`Kept user-customized Codex hook \`${r.id}\` as-is.`);
+          }
+          const verify = CodexHooks.verifyAll(process.cwd());
+          if (verify.untrusted && verify.untrusted.length) {
+            UI.info(`Codex will ask you to approve ${verify.untrusted.length} new hook(s) on the next session (hook trust): ${verify.untrusted.join(', ')}. Until approved, they stay inactive.`);
+          }
+        }
+      } catch (err) {
+        UI.warning(`Codex hook registration skipped: ${err.message}`);
+      }
+    }
+
     // Project configuration check (since v3.0.0)
     // Never overwrite baldart.config.yml on update. Offer to (re)run configure
     // if the schema has gained required keys, or if no config exists at all.

package/src/utils/hooks/claude.js

@@ -0,0 +1,402 @@
+/**
+ * Claude Code hook renderer for `.claude/settings.json`.
+ *
+ * This module owns the Claude-side settings-file schema + I/O. The hook *set*
+ * is defined once, runtime-neutrally, in `./registry.js`; this renderer
+ * consumes `defsFor('claude')` and knows nothing about other runtimes. The
+ * Codex renderer (`./codex.js`, S2) is its sibling, sharing the same
+ * registry and the same call sites in add/update/doctor.
+ *
+ * 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`.
+ *
+ * **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 { defsFor } = require('./registry');
+
+const SETTINGS_FILE = path.join('.claude', 'settings.json');
+
+/**
+ * The Claude-runtime hook definitions, in the flat shape the loops below
+ * expect (`{ id, order, event, matcher, command, legacyMatch? }`). Sourced
+ * from the neutral registry so the hook set lives in exactly one place.
+ * @type {Array<{id:string,order:number,event:string,matcher:string,command:string,legacyMatch?:string}>}
+ */
+const HOOK_REGISTRY = defsFor('claude');
+
+// ---------------------------------------------------------------------------
+// settings.json I/O
+// ---------------------------------------------------------------------------
+
+function readSettings(cwd = process.cwd()) {
+  const full = path.join(cwd, SETTINGS_FILE);
+  if (!fs.existsSync(full)) return { path: full, settings: null, malformed: false };
+  try {
+    const raw = fs.readFileSync(full, 'utf8');
+    if (!raw.trim()) return { path: full, settings: {}, malformed: false };
+    return { path: full, settings: JSON.parse(raw), malformed: false };
+  } catch (_) {
+    return { path: full, settings: null, malformed: true };
+  }
+}
+
+function writeSettings(settingsPath, settings) {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Internal: locate an entry that owns a given hook definition
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 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 (let j = 0; j < entry.hooks.length; j++) {
+      const h = entry.hooks[j];
+      if (!h) continue;
+      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 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
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 }> }>}
+ */
+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 { malformed: true, path: settingsPath, created: false, updated: false, results: [] };
+  }
+
+  const wasNew = !existing;
+  const settings = existing && typeof existing === 'object' ? structuredClone(existing) : {};
+  settings.hooks = settings.hooks && typeof settings.hooks === 'object'
+    ? settings.hooks
+    : {};
+
+  const results = [];
+  let modified = false;
+
+  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,
+      });
+    }
+  }
+
+  if (modified) writeSettings(settingsPath, settings);
+
+  return {
+    malformed: false,
+    path: settingsPath,
+    created: modified && wasNew,
+    updated: modified && !wasNew,
+    results,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Unregister — remove every BALDART hook from settings.json
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 unregisterAll(cwd = process.cwd()) {
+  const { path: settingsPath, settings, malformed } = readSettings(cwd);
+  if (malformed || !settings || !settings.hooks) {
+    return {
+      malformed,
+      path: settingsPath,
+      results: HOOK_REGISTRY.map((d) => ({ id: d.id, status: 'not-found' })),
+    };
+  }
+
+  const next = structuredClone(settings);
+  const results = [];
+  let modified = false;
+
+  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' });
+    }
+  }
+
+  if (Object.keys(next.hooks).length === 0) delete next.hooks;
+  if (modified) writeSettings(settingsPath, next);
+
+  return { malformed: false, path: settingsPath, results };
+}
+
+// ---------------------------------------------------------------------------
+// Verify — post-flight assertion that every active hook is registered
+// ---------------------------------------------------------------------------
+
+/**
+ * Confirms that every active hook in the registry is present in
+ * `.claude/settings.json`. Pure read (delegates to `getStatus`). Designed as
+ * the post-flight gate for `add` / `update --reset`: the install must never
+ * declare success while a hook is missing (the silent partial-install class,
+ * v3.27.1 / mayo 3.28→3.31).
+ *
+ * A malformed settings.json counts as a failure: registration was skipped, so
+ * the hooks are not verifiably present.
+ *
+ * @param {string} [cwd]
+ * @returns {{ ok: boolean, malformed: boolean, missing: string[], path: string }}
+ */
+function verifyAll(cwd = process.cwd()) {
+  const status = getStatus(cwd);
+  if (status.malformed) {
+    return {
+      ok: false,
+      malformed: true,
+      missing: HOOK_REGISTRY.map((d) => d.id),
+      path: status.path,
+    };
+  }
+  const missing = status.hooks.filter((h) => !h.registered).map((h) => h.id);
+  return { ok: missing.length === 0, malformed: false, missing, path: status.path };
+}
+
+// ---------------------------------------------------------------------------
+// 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 = {
+  HOOK_REGISTRY,
+  SETTINGS_FILE,
+  getStatus,
+  verifyAll,
+  registerAll,
+  unregisterAll,
+  createDriftPrompt,
+};