failproofai 0.0.7 → 0.0.9-beta.0

package/src/hooks/integrations.ts

@@ -0,0 +1,373 @@
+/**
+ * Per-CLI hook integration registry.
+ *
+ * An `Integration` describes how failproofai hooks are installed, detected, and
+ * read for a specific agent CLI (Claude Code, OpenAI Codex). The runtime hot
+ * path (`handler.ts`, `policy-evaluator.ts`, `BUILTIN_POLICIES`, `policy-helpers`)
+ * is agent-agnostic — only install/uninstall plumbing varies.
+ */
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import {
+  HOOK_EVENT_TYPES,
+  HOOK_SCOPES,
+  CODEX_HOOK_EVENT_TYPES,
+  CODEX_HOOK_SCOPES,
+  CODEX_EVENT_MAP,
+  FAILPROOFAI_HOOK_MARKER,
+  INTEGRATION_TYPES,
+  type IntegrationType,
+  type HookScope,
+  type ClaudeSettings,
+  type ClaudeHookMatcher,
+  type ClaudeHookEntry,
+  type CodexHookEventType,
+} from "./types";
+
+// ── Generic helpers ─────────────────────────────────────────────────────────
+
+function readJsonFile(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, "utf8");
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+function writeJsonFile(path: string, data: Record<string, unknown>): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function isMarkedHook(hook: Record<string, unknown>): boolean {
+  if (hook[FAILPROOFAI_HOOK_MARKER] === true) return true;
+  // Fallback for legacy installs predating the marker
+  const cmd = typeof hook.command === "string" ? hook.command : "";
+  return cmd.includes("failproofai") && cmd.includes("--hook");
+}
+
+function binaryExists(name: string): boolean {
+  try {
+    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
+    execSync(cmd, { encoding: "utf8", stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Integration interface ───────────────────────────────────────────────────
+
+export interface Integration {
+  id: IntegrationType;
+  displayName: string;
+  /** Settings scopes this integration supports (e.g. claude: user/project/local; codex: user/project). */
+  scopes: readonly HookScope[];
+  /** Hook events this integration fires (Claude: PascalCase, Codex: snake_case stored as Pascal in settings). */
+  eventTypes: readonly string[];
+
+  /** Resolve the per-scope settings/hooks file path. */
+  getSettingsPath(scope: HookScope, cwd?: string): string;
+
+  /** Read the raw settings/hooks file (returns {} when missing). */
+  readSettings(settingsPath: string): Record<string, unknown>;
+
+  /** Write the settings/hooks file. */
+  writeSettings(settingsPath: string, settings: Record<string, unknown>): void;
+
+  /** Build a single hook entry for a given event. */
+  buildHookEntry(binaryPath: string, eventType: string, scope?: HookScope): Record<string, unknown>;
+
+  /** Whether a hook entry is owned by failproofai. */
+  isFailproofaiHook(hook: Record<string, unknown>): boolean;
+
+  /** Mutate `settings` in place, registering failproofai across all event types. Idempotent. */
+  writeHookEntries(settings: Record<string, unknown>, binaryPath: string, scope?: HookScope): void;
+
+  /** Remove all failproofai hook entries from a settings file. Returns the number removed. */
+  removeHooksFromFile(settingsPath: string): number;
+
+  /** Whether failproofai hooks are present in a given scope. */
+  hooksInstalledInSettings(scope: HookScope, cwd?: string): boolean;
+
+  /** Whether the agent CLI binary is installed (probes PATH). */
+  detectInstalled(): boolean;
+}
+
+// ── Claude Code integration ─────────────────────────────────────────────────
+
+export const claudeCode: Integration = {
+  id: "claude",
+  displayName: "Claude Code",
+  scopes: HOOK_SCOPES,
+  eventTypes: HOOK_EVENT_TYPES,
+
+  getSettingsPath(scope, cwd) {
+    const base = cwd ? resolve(cwd) : process.cwd();
+    switch (scope) {
+      case "user":
+        return resolve(homedir(), ".claude", "settings.json");
+      case "project":
+        return resolve(base, ".claude", "settings.json");
+      case "local":
+        return resolve(base, ".claude", "settings.local.json");
+    }
+  },
+
+  readSettings(settingsPath) {
+    return readJsonFile(settingsPath);
+  },
+
+  writeSettings(settingsPath, settings) {
+    writeJsonFile(settingsPath, settings);
+  },
+
+  buildHookEntry(binaryPath, eventType, scope) {
+    // No --cli flag on the Claude command line: the handler defaults to
+    // claude when --cli is omitted, preserving back-compat with hooks
+    // installed before multi-CLI support was added.
+    const command =
+      scope === "project"
+        ? `npx -y failproofai --hook ${eventType}`
+        : `"${binaryPath}" --hook ${eventType}`;
+    return {
+      type: "command",
+      command,
+      timeout: 60_000,
+      [FAILPROOFAI_HOOK_MARKER]: true,
+    };
+  },
+
+  isFailproofaiHook: isMarkedHook,
+
+  writeHookEntries(settings, binaryPath, scope) {
+    const s = settings as ClaudeSettings;
+    if (!s.hooks) s.hooks = {};
+
+    for (const eventType of HOOK_EVENT_TYPES) {
+      const hookEntry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as ClaudeHookEntry;
+      if (!s.hooks[eventType]) s.hooks[eventType] = [];
+      const matchers: ClaudeHookMatcher[] = s.hooks[eventType];
+
+      let found = false;
+      for (const matcher of matchers) {
+        if (!matcher.hooks) continue;
+        const idx = matcher.hooks.findIndex((h) => isMarkedHook(h as Record<string, unknown>));
+        if (idx >= 0) {
+          matcher.hooks[idx] = hookEntry;
+          found = true;
+          break;
+        }
+      }
+      if (!found) matchers.push({ hooks: [hookEntry] });
+    }
+  },
+
+  removeHooksFromFile(settingsPath) {
+    const settings = this.readSettings(settingsPath) as ClaudeSettings;
+    if (!settings.hooks) return 0;
+
+    let removed = 0;
+    for (const eventType of Object.keys(settings.hooks)) {
+      const matchers = settings.hooks[eventType];
+      if (!Array.isArray(matchers)) continue;
+      for (let i = matchers.length - 1; i >= 0; i--) {
+        const matcher = matchers[i];
+        if (!matcher.hooks) continue;
+        const before = matcher.hooks.length;
+        matcher.hooks = matcher.hooks.filter((h) => !isMarkedHook(h as Record<string, unknown>));
+        removed += before - matcher.hooks.length;
+        if (matcher.hooks.length === 0) matchers.splice(i, 1);
+      }
+      if (matchers.length === 0) delete settings.hooks[eventType];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+    this.writeSettings(settingsPath, settings as Record<string, unknown>);
+    return removed;
+  },
+
+  hooksInstalledInSettings(scope, cwd) {
+    const settingsPath = this.getSettingsPath(scope, cwd);
+    if (!existsSync(settingsPath)) return false;
+    try {
+      const settings = this.readSettings(settingsPath) as ClaudeSettings;
+      if (!settings.hooks) return false;
+      for (const matchers of Object.values(settings.hooks)) {
+        if (!Array.isArray(matchers)) continue;
+        for (const matcher of matchers) {
+          if (!matcher.hooks) continue;
+          if (matcher.hooks.some((h) => isMarkedHook(h as Record<string, unknown>))) return true;
+        }
+      }
+    } catch {
+      // Corrupt settings — treat as not installed
+    }
+    return false;
+  },
+
+  detectInstalled() {
+    return binaryExists("claude") || binaryExists("claude-code");
+  },
+};
+
+// ── OpenAI Codex integration ────────────────────────────────────────────────
+//
+// Codex's hook protocol is Claude-compatible by design (see the parity matrix
+// in plans/great-in-failproofai-i-vectorized-treasure.md). The only material
+// differences are:
+//   • Settings paths: ~/.codex/hooks.json (user) and <cwd>/.codex/hooks.json (project)
+//   • Stdin event names arrive snake_case (pre_tool_use); we canonicalize to PascalCase before policy lookup
+//   • No "local" scope
+//   • Settings file carries a top-level "version": 1 marker
+
+interface CodexSettingsFile {
+  version?: number;
+  hooks?: Record<string, ClaudeHookMatcher[]>;
+  [key: string]: unknown;
+}
+
+export const codex: Integration = {
+  id: "codex",
+  displayName: "OpenAI Codex",
+  scopes: CODEX_HOOK_SCOPES,
+  eventTypes: CODEX_HOOK_EVENT_TYPES,
+
+  getSettingsPath(scope, cwd) {
+    const base = cwd ? resolve(cwd) : process.cwd();
+    switch (scope) {
+      case "user":
+        return resolve(homedir(), ".codex", "hooks.json");
+      case "project":
+        return resolve(base, ".codex", "hooks.json");
+      case "local":
+        // Codex has no "local" scope; fall back to project so callers don't crash.
+        // The CLI rejects --cli codex --scope local before reaching here.
+        return resolve(base, ".codex", "hooks.json");
+    }
+  },
+
+  readSettings(settingsPath) {
+    const raw = readJsonFile(settingsPath);
+    if (raw.version === undefined) raw.version = 1;
+    return raw;
+  },
+
+  writeSettings(settingsPath, settings) {
+    writeJsonFile(settingsPath, settings);
+  },
+
+  buildHookEntry(binaryPath, eventType, scope) {
+    // `eventType` here is the snake_case Codex event name; Codex stores under
+    // PascalCase keys but invokes the command with the snake_case form, which
+    // we canonicalize on the way into policy-evaluator.
+    const command =
+      scope === "project"
+        ? `npx -y failproofai --hook ${eventType} --cli codex`
+        : `"${binaryPath}" --hook ${eventType} --cli codex`;
+    return {
+      type: "command",
+      command,
+      timeout: 60_000,
+      [FAILPROOFAI_HOOK_MARKER]: true,
+    };
+  },
+
+  isFailproofaiHook: isMarkedHook,
+
+  writeHookEntries(settings, binaryPath, scope) {
+    const s = settings as CodexSettingsFile;
+    if (s.version === undefined) s.version = 1;
+    if (!s.hooks) s.hooks = {};
+
+    for (const eventType of CODEX_HOOK_EVENT_TYPES) {
+      const pascalKey = CODEX_EVENT_MAP[eventType as CodexHookEventType];
+      const hookEntry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as ClaudeHookEntry;
+      if (!s.hooks[pascalKey]) s.hooks[pascalKey] = [];
+      const matchers: ClaudeHookMatcher[] = s.hooks[pascalKey];
+
+      let found = false;
+      for (const matcher of matchers) {
+        if (!matcher.hooks) continue;
+        const idx = matcher.hooks.findIndex((h) => isMarkedHook(h as Record<string, unknown>));
+        if (idx >= 0) {
+          matcher.hooks[idx] = hookEntry;
+          found = true;
+          break;
+        }
+      }
+      if (!found) matchers.push({ hooks: [hookEntry] });
+    }
+  },
+
+  removeHooksFromFile(settingsPath) {
+    const settings = this.readSettings(settingsPath) as CodexSettingsFile;
+    if (!settings.hooks) return 0;
+
+    let removed = 0;
+    for (const eventType of Object.keys(settings.hooks)) {
+      const matchers = settings.hooks[eventType];
+      if (!Array.isArray(matchers)) continue;
+      for (let i = matchers.length - 1; i >= 0; i--) {
+        const matcher = matchers[i];
+        if (!matcher.hooks) continue;
+        const before = matcher.hooks.length;
+        matcher.hooks = matcher.hooks.filter((h) => !isMarkedHook(h as Record<string, unknown>));
+        removed += before - matcher.hooks.length;
+        if (matcher.hooks.length === 0) matchers.splice(i, 1);
+      }
+      if (matchers.length === 0) delete settings.hooks[eventType];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+    this.writeSettings(settingsPath, settings as Record<string, unknown>);
+    return removed;
+  },
+
+  hooksInstalledInSettings(scope, cwd) {
+    const settingsPath = this.getSettingsPath(scope, cwd);
+    if (!existsSync(settingsPath)) return false;
+    try {
+      const settings = this.readSettings(settingsPath) as CodexSettingsFile;
+      if (!settings.hooks) return false;
+      for (const matchers of Object.values(settings.hooks)) {
+        if (!Array.isArray(matchers)) continue;
+        for (const matcher of matchers) {
+          if (!matcher.hooks) continue;
+          if (matcher.hooks.some((h) => isMarkedHook(h as Record<string, unknown>))) return true;
+        }
+      }
+    } catch {
+      // Corrupt settings — treat as not installed
+    }
+    return false;
+  },
+
+  detectInstalled() {
+    return binaryExists("codex");
+  },
+};
+
+// ── Registry ────────────────────────────────────────────────────────────────
+
+const INTEGRATIONS: Record<IntegrationType, Integration> = {
+  claude: claudeCode,
+  codex,
+};
+
+export function getIntegration(id: IntegrationType): Integration {
+  const integration = INTEGRATIONS[id];
+  if (!integration) {
+    throw new Error(`Unknown integration: ${id}. Valid: ${INTEGRATION_TYPES.join(", ")}`);
+  }
+  return integration;
+}
+
+export function listIntegrations(): Integration[] {
+  return INTEGRATION_TYPES.map((id) => INTEGRATIONS[id]);
+}
+
+/** Detect which agent CLIs are installed on PATH. */
+export function detectInstalledClis(): IntegrationType[] {
+  return INTEGRATION_TYPES.filter((id) => INTEGRATIONS[id].detectInstalled());
+}