@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/scripts/lib/hooks.mjs

@@ -1,585 +0,0 @@
-/**
- * hooks.mjs — plugin hook reconciliation and stale standalone drift-hook cleanup.
- */
-
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-
-// Stable marker used to detect an existing entry (idempotency key).
-const CLAUDE_HOOK_MARKER = "enact-extensions:session-start-drift-check";
-const TOML_HOOK_MARKER = "enact-extensions:session-start-drift-check";
-
-// ---------------------------------------------------------------------------
-// Default home paths per surface
-// ---------------------------------------------------------------------------
-function defaultHome(surface) {
-  const home = homedir();
-  switch (surface) {
-    case "claude": return join(home, ".claude");
-    case "codex":  return join(home, ".codex");
-    case "enact":  return join(home, ".enact", "agent");
-    case "cursor": return join(home, ".cursor");
-    default:       throw new Error(`Unknown surface: ${surface}`);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Claude settings.json helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Read and parse settings.json. Returns empty object on missing/error.
- */
-function readSettings(settingsPath) {
-  if (!existsSync(settingsPath)) return {};
-  try {
-    return JSON.parse(readFileSync(settingsPath, "utf8"));
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Write settings.json (pretty-printed JSON, creates parent dir).
- */
-function writeSettings(settingsPath, settings) {
-  mkdirSync(dirname(settingsPath), { recursive: true });
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-}
-
-/**
- * Remove the drift-check hook from Claude's (or Cursor's) settings.json.
- * Idempotent: safe if entry not present.
- *
- * @param {string} settingsPath
- * @returns {"removed"|"not_found"} result
- */
-function removeClaudeHook(settingsPath) {
-  if (!existsSync(settingsPath)) return "not_found";
-  const settings = readSettings(settingsPath);
-  if (!settings.hooks?.SessionStart) return "not_found";
-
-  const before = settings.hooks.SessionStart.length;
-  settings.hooks.SessionStart = settings.hooks.SessionStart.filter(
-    (e) => !(
-      e &&
-      (
-        // New schema: { matcher, hooks: [{ type, command }] }
-        (Array.isArray(e.hooks) && e.hooks.some((h) => (h.command ?? "").includes("session-start-drift-check"))) ||
-        // Old schema (pre-fix): { _enact_marker, command }
-        e._enact_marker === CLAUDE_HOOK_MARKER ||
-        (e.command ?? "").includes("session-start-drift-check")
-      )
-    ),
-  );
-  if (settings.hooks.SessionStart.length === before) return "not_found";
-
-  writeSettings(settingsPath, settings);
-  return "removed";
-}
-
-// ---------------------------------------------------------------------------
-// Codex / Enact config.toml helpers
-//
-// Assumption: the codex-fork and enact-agent config.toml supports a
-// `[[hooks.session_start]]` array of tables, each with a `command` field.
-// This mirrors common codex-rs config patterns. If the exact schema differs,
-// the entry is still safely parseable as TOML and clearly marked for removal.
-// ---------------------------------------------------------------------------
-
-const TOML_BEGIN_MARKER = `# [${TOML_HOOK_MARKER}] BEGIN`;
-const TOML_END_MARKER = `# [${TOML_HOOK_MARKER}] END`;
-const TOML_DRIFT_COMMAND_MARKER = "session-start-drift-check";
-
-function pluginMarker(pluginName) {
-  return `enact-extensions:plugin-hooks:${pluginName}`;
-}
-
-function eventTomlName(eventName) {
-  return String(eventName)
-    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
-    .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
-    .toLowerCase();
-}
-
-/**
- * Map a PascalCase Claude/Enact event name to the camelCase key Cursor uses
- * in its plugin-shipped hooks.json.
- *
- * Cursor hook events (from spec/cursor.md and plugin format):
- *   SessionStart       → sessionStart
- *   UserPromptSubmit   → beforeSubmitPrompt
- *   PreToolUse         → preToolUse
- *   PostToolUse        → postToolUse
- *   Stop               → stop
- *   PreCompact         → preCompact
- *   SessionEnd         → sessionEnd
- *   SubagentStart      → subagentStart
- *   SubagentStop       → subagentStop
- *
- * Any unmapped event falls back to lowercase-first (simple camelCase).
- *
- * NOTE: Cursor reads hooks from the plugin-bundled hooks/hooks.json
- * (installed into ~/.cursor/plugins/local/<name>/hooks/hooks.json via
- * installCursorPluginBundle). There is NO global ~/.cursor/hooks.json.
- * This function exists so the bundled hooks.json can be serialised with
- * the Cursor-native camelCase event keys when needed.
- *
- * @param {string} event — PascalCase event name
- * @returns {string} camelCase Cursor event name
- */
-export function eventCursorName(event) {
-  const MAP = {
-    SessionStart:     "sessionStart",
-    UserPromptSubmit: "beforeSubmitPrompt",
-    PreToolUse:       "preToolUse",
-    PostToolUse:      "postToolUse",
-    Stop:             "stop",
-    PreCompact:       "preCompact",
-    SessionEnd:       "sessionEnd",
-    SubagentStart:    "subagentStart",
-    SubagentStop:     "subagentStop",
-  };
-  const mapped = MAP[String(event)];
-  if (mapped) return mapped;
-  // Fallback: lowercase the first character.
-  const s = String(event);
-  return s.charAt(0).toLowerCase() + s.slice(1);
-}
-
-function tomlString(value) {
-  return JSON.stringify(String(value));
-}
-
-function flattenHookCommands(hookConfig) {
-  const out = [];
-  const hooks = hookConfig?.hooks && typeof hookConfig.hooks === "object" ? hookConfig.hooks : {};
-  for (const [eventName, groups] of Object.entries(hooks)) {
-    if (!Array.isArray(groups)) continue;
-    for (const group of groups) {
-      if (!group || typeof group !== "object") continue;
-      const commands = Array.isArray(group.hooks) ? group.hooks : [];
-      for (const hook of commands) {
-        if (!hook || typeof hook !== "object" || hook.type !== "command" || typeof hook.command !== "string") {
-          continue;
-        }
-        out.push({
-          eventName,
-          matcher: typeof group.matcher === "string" ? group.matcher : undefined,
-          command: hook.command,
-          statusMessage: typeof hook.statusMessage === "string" ? hook.statusMessage : undefined,
-          timeout: typeof hook.timeout === "number" ? hook.timeout : undefined,
-        });
-      }
-    }
-  }
-  return out;
-}
-
-function commandLooksPluginOwned(command) {
-  return /^enact-context\s+hook\s+/.test(String(command));
-}
-
-/**
- * True when `command` is owned by the named plugin's runtime CLI, i.e. it
- * starts with `<pluginName> hook `.
- *
- * Scoping removal to the SPECIFIC plugin avoids reconciling one plugin from
- * stripping a sibling plugin's marker-less entries. Falls back to the known
- * context hook command shape when no plugin name is given.
- */
-function commandOwnedByPlugin(command, pluginName) {
-  if (!pluginName) return commandLooksPluginOwned(command);
-  const esc = String(pluginName).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return new RegExp(`^${esc}\\s+hook\\s+`).test(String(command));
-}
-
-function registerJsonPluginHooks(settingsPath, pluginName, hookConfig) {
-  const settings = readSettings(settingsPath);
-  if (!settings.hooks) settings.hooks = {};
-  const marker = pluginMarker(pluginName);
-  let registered = 0;
-  let already = 0;
-
-  for (const entry of flattenHookCommands(hookConfig)) {
-    if (!commandLooksPluginOwned(entry.command)) continue;
-    if (!Array.isArray(settings.hooks[entry.eventName])) settings.hooks[entry.eventName] = [];
-    const exists = settings.hooks[entry.eventName].some((group) =>
-      group?._enact_marker === marker &&
-      Array.isArray(group.hooks) &&
-      group.hooks.some((hook) => hook?.command === entry.command),
-    );
-    if (exists) {
-      already += 1;
-      continue;
-    }
-    settings.hooks[entry.eventName].push({
-      _enact_marker: marker,
-      ...(entry.matcher ? { matcher: entry.matcher } : {}),
-      hooks: [
-        {
-          type: "command",
-          command: entry.command,
-          ...(entry.statusMessage ? { statusMessage: entry.statusMessage } : {}),
-          ...(entry.timeout ? { timeout: entry.timeout } : {}),
-        },
-      ],
-    });
-    registered += 1;
-  }
-
-  if (registered > 0) writeSettings(settingsPath, settings);
-  return registered > 0 ? "registered" : already > 0 ? "already_registered" : "skipped";
-}
-
-function removeJsonPluginHooks(settingsPath, pluginName) {
-  if (!existsSync(settingsPath)) return "not_found";
-  const settings = readSettings(settingsPath);
-  if (!settings.hooks || typeof settings.hooks !== "object") return "not_found";
-  const marker = pluginMarker(pluginName);
-  let removed = 0;
-
-  for (const [eventName, groups] of Object.entries(settings.hooks)) {
-    if (!Array.isArray(groups)) continue;
-    const next = groups.filter((group) => {
-      const markerMatch = group?._enact_marker === marker;
-      const commandMatch =
-        Array.isArray(group?.hooks) &&
-        group.hooks.some((hook) => commandOwnedByPlugin(hook?.command, pluginName));
-      const shouldRemove = markerMatch || commandMatch;
-      if (shouldRemove) removed += 1;
-      return !shouldRemove;
-    });
-    // Drop event keys we have fully emptied so a removed/unsupported event
-    // (e.g. SessionIdle) does not linger as `[]` and trip host "unknown hook
-    // event" warnings. Personal/other-plugin entries keep the key alive.
-    if (next.length === 0) delete settings.hooks[eventName];
-    else settings.hooks[eventName] = next;
-  }
-
-  if (removed === 0) return "not_found";
-  writeSettings(settingsPath, settings);
-  return "removed";
-}
-
-function pluginTomlBlock(pluginName, entry) {
-  const marker = pluginMarker(pluginName);
-  const eventName = eventTomlName(entry.eventName);
-  const suffix = `${entry.eventName}:${entry.command}`;
-  const fields = [
-    `# [${marker}] BEGIN ${suffix}`,
-    `[[hooks.${eventName}]]`,
-    ...(entry.matcher ? [`matcher = ${tomlString(entry.matcher)}`] : []),
-    `command = ${tomlString(entry.command)}`,
-    ...(entry.statusMessage ? [`status_message = ${tomlString(entry.statusMessage)}`] : []),
-    ...(entry.timeout ? [`timeout = ${entry.timeout}`] : []),
-    `# [${marker}] END ${suffix}`,
-  ];
-  return `${fields.join("\n")}\n`;
-}
-
-function registerTomlPluginHooks(configPath, pluginName, hookConfig) {
-  const existing = readToml(configPath);
-  const marker = pluginMarker(pluginName);
-  const blocks = [];
-  let already = 0;
-  for (const entry of flattenHookCommands(hookConfig)) {
-    if (!commandLooksPluginOwned(entry.command)) continue;
-    const suffix = `${entry.eventName}:${entry.command}`;
-    if (existing.includes(`# [${marker}] BEGIN ${suffix}`)) {
-      already += 1;
-      continue;
-    }
-    blocks.push(pluginTomlBlock(pluginName, entry));
-  }
-  if (blocks.length === 0) return already > 0 ? "already_registered" : "skipped";
-  const next = `${existing.replace(/\s+$/, "")}${existing.trim() ? "\n\n" : ""}${blocks.join("\n")}`;
-  writeToml(configPath, next.endsWith("\n") ? next : `${next}\n`);
-  return "registered";
-}
-
-function removeTomlPluginHooks(configPath, pluginName) {
-  const existing = readToml(configPath);
-  const marker = pluginMarker(pluginName);
-  const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const pattern = new RegExp(`\\n?# \\[${escaped}\\] BEGIN[^\\n]*\\n[\\s\\S]*?# \\[${escaped}\\] END[^\\n]*\\n?`, "g");
-  let next = existing.replace(pattern, "\n");
-  let removed = next !== existing;
-
-  // Legacy cleanup: older codex installs could preserve the hook tables while
-  // dropping the marker comments when config.toml was reserialized. Remove any
-  // remaining plain [[hooks.*]] blocks that still point at this plugin's hook
-  // command set.
-  const lines = next.split(/\r?\n/);
-  const out = [];
-  for (let i = 0; i < lines.length;) {
-    const line = lines[i];
-    if (line.startsWith("[[hooks.")) {
-      const block = [line];
-      i += 1;
-      while (
-        i < lines.length &&
-        !lines[i].startsWith("[[hooks.") &&
-        !/^\[[^\[]/.test(lines[i]) &&
-        !lines[i].startsWith(`# [${marker}] BEGIN`)
-      ) {
-        block.push(lines[i]);
-        i += 1;
-      }
-      const commandLine = block.find((entry) => entry.trim().startsWith("command = "));
-      const commandMatch = commandLine
-        ? commandOwnedByPlugin(commandLine.replace(/^command\s*=\s*/, "").replace(/^"|"$/g, ""), pluginName)
-        : false;
-      const markerMatch = block.some((entry) => entry.includes(marker));
-      if (markerMatch || commandMatch) {
-        removed = true;
-        continue;
-      }
-      out.push(...block);
-      continue;
-    }
-    out.push(line);
-    i += 1;
-  }
-
-  if (!removed) return "not_found";
-  next = out.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
-  writeToml(configPath, next.endsWith("\n") ? next : `${next}\n`);
-  return "removed";
-}
-
-/**
- * Read config.toml content. Returns empty string on missing.
- */
-function readToml(configPath) {
-  if (!existsSync(configPath)) return "";
-  try {
-    return readFileSync(configPath, "utf8");
-  } catch {
-    return "";
-  }
-}
-
-/**
- * Write config.toml (creates parent dir).
- */
-function writeToml(configPath, content) {
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(configPath, content, "utf8");
-}
-
-function stripTomlDriftHookBlocks(content) {
-  let next = content;
-  let removed = false;
-
-  const markedPattern = new RegExp(
-    `\\n?${TOML_BEGIN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${TOML_END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[^\\n]*\\n?`,
-    "g",
-  );
-  next = next.replace(markedPattern, () => {
-    removed = true;
-    return "\n";
-  });
-
-  const lines = next.split(/\r?\n/);
-  const out = [];
-  for (let i = 0; i < lines.length;) {
-    const line = lines[i];
-    if (line.trim() === "[[hooks.session_start]]") {
-      const block = [line];
-      i += 1;
-      while (i < lines.length && !/^\s*\[/.test(lines[i])) {
-        block.push(lines[i]);
-        i += 1;
-      }
-      if (block.some((entry) => entry.includes(TOML_DRIFT_COMMAND_MARKER))) {
-        removed = true;
-        continue;
-      }
-      out.push(...block);
-      continue;
-    }
-    out.push(line);
-    i += 1;
-  }
-
-  next = out.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
-  return {
-    content: next.endsWith("\n") || next.length === 0 ? next : `${next}\n`,
-    removed,
-  };
-}
-
-/**
- * Remove the drift-check hook block from config.toml.
- * Removes the content between BEGIN and END markers (inclusive).
- *
- * @param {string} configPath
- * @returns {"removed"|"not_found"} result
- */
-function removeTomlHook(configPath) {
-  const existing = readToml(configPath);
-  const stripped = stripTomlDriftHookBlocks(existing);
-  if (!stripped.removed) return "not_found";
-
-  writeToml(configPath, stripped.content);
-  return "removed";
-}
-
-// ---------------------------------------------------------------------------
-// Public API: removeHook / registerPluginHooks / removePluginHooks
-// ---------------------------------------------------------------------------
-
-/**
- * Remove the session-start drift-check hook for a given surface.
- *
- * @param {string} surface
- * @param {object} [opts] — same as registerHook
- * @returns {{ surface: string, result: "removed"|"not_found"|"skipped", note?: string }}
- */
-export function removeHook(surface, opts = {}) {
-  try {
-    switch (surface) {
-      case "claude": {
-        const home = opts.claudeHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".claude") : defaultHome("claude"));
-        const settingsPath = join(home, "settings.json");
-        const result = removeClaudeHook(settingsPath);
-        return { surface, result, location: settingsPath };
-      }
-
-      case "cursor": {
-        const home = opts.cursorHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".cursor") : defaultHome("cursor"));
-        const settingsPath = join(home, "settings.json");
-        const result = removeClaudeHook(settingsPath);
-        return { surface, result, location: settingsPath };
-      }
-
-      case "codex": {
-        const home = opts.codexHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".codex") : defaultHome("codex"));
-        const configPath = join(home, "config.toml");
-        const result = removeTomlHook(configPath);
-        return { surface, result, location: configPath };
-      }
-
-      case "enact": {
-        const home = opts.enactHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".enact", "agent") : defaultHome("enact"));
-        const configPath = join(home, "config.toml");
-        const result = removeTomlHook(configPath);
-        return { surface, result, location: configPath };
-      }
-
-      default:
-        return { surface, result: "skipped", note: `Unknown surface: ${surface}` };
-    }
-  } catch (err) {
-    return {
-      surface,
-      result: "skipped",
-      note: `Error: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-}
-
-export function registerPluginHooks(surface, pluginName, hookConfig, opts = {}) {
-  try {
-    switch (surface) {
-      case "claude": {
-        return {
-          surface,
-          result: "skipped",
-          note: "Claude reads plugin runtime hooks from the enabled plugin bundle. No settings.json plugin hook registration is performed.",
-        };
-      }
-
-      case "cursor": {
-        // Cursor reads hooks from the plugin-bundled hooks/hooks.json
-        // (installed to ~/.cursor/plugins/local/<name>/hooks/hooks.json by
-        // installCursorPluginBundle). There is NO global ~/.cursor/hooks.json
-        // to write to. Registering into ~/.cursor/settings.json is incorrect.
-        // Hook lifecycle is handled by the plugin bundle itself — skip here.
-        return {
-          surface,
-          result: "skipped",
-          note: "Cursor reads hooks from the plugin bundle (hooks/hooks.json installed via installCursorPluginBundle). No global hook file to register into.",
-        };
-      }
-
-      case "codex": {
-        const home = opts.codexHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".codex") : defaultHome("codex"));
-        const configPath = join(home, "config.toml");
-        const result = registerTomlPluginHooks(configPath, pluginName, hookConfig);
-        return { surface, result, location: configPath };
-      }
-
-      case "enact": {
-        return {
-          surface,
-          result: "skipped",
-          note: "Enact follows the Codex-compatible bundle-owned plugin hook model. No config.toml plugin hook registration is performed.",
-        };
-      }
-
-      default:
-        return { surface, result: "skipped", note: `Unknown surface: ${surface}` };
-    }
-  } catch (err) {
-    return {
-      surface,
-      result: "skipped",
-      note: `Error: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-}
-
-export function removePluginHooks(surface, pluginName, opts = {}) {
-  try {
-    switch (surface) {
-      case "claude": {
-        const home = opts.claudeHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".claude") : defaultHome("claude"));
-        const settingsPath = join(home, "settings.json");
-        const result = removeJsonPluginHooks(settingsPath, pluginName);
-        return { surface, result, location: settingsPath };
-      }
-
-      case "cursor": {
-        // Cursor reads hooks from the plugin bundle — nothing to remove globally.
-        return {
-          surface,
-          result: "skipped",
-          note: "Cursor reads hooks from the plugin bundle (hooks/hooks.json installed via installCursorPluginBundle). No global hook file to remove from.",
-        };
-      }
-
-      case "codex": {
-        const home = opts.codexHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".codex") : defaultHome("codex"));
-        const configPath = join(home, "config.toml");
-        const result = removeTomlPluginHooks(configPath, pluginName);
-        return { surface, result, location: configPath };
-      }
-
-      case "enact": {
-        const home = opts.enactHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".enact", "agent") : defaultHome("enact"));
-        const configPath = join(home, "config.toml");
-        const result = removeTomlPluginHooks(configPath, pluginName);
-        return { surface, result, location: configPath };
-      }
-
-      default:
-        return { surface, result: "skipped", note: `Unknown surface: ${surface}` };
-    }
-  } catch (err) {
-    return {
-      surface,
-      result: "skipped",
-      note: `Error: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-}
-
-// The 4 supported surfaces.