failproofai 0.0.1-beta.1

package/src/hooks/custom-hooks-loader.ts

@@ -0,0 +1,61 @@
+/**
+ * Loads a user-authored hooks.js file with ESM import rewriting.
+ * Supports transitive local imports and `import { ... } from 'failproofai'`.
+ *
+ * Fail-open: any error (file not found, syntax error, import failure) is logged
+ * and results in an empty hook list. Builtins continue running normally.
+ */
+import { resolve, isAbsolute } from "node:path";
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { hookLogWarn, hookLogError } from "./hook-logger";
+import { getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
+import { findDistIndex, rewriteFileTree, TMP_SUFFIX, cleanupTmpFiles } from "./loader-utils";
+import type { CustomHook } from "./policy-types";
+
+const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
+
+export async function loadCustomHooks(
+  customHooksPath: string | undefined,
+  opts?: { strict?: boolean },
+): Promise<CustomHook[]> {
+  if (!customHooksPath) return [];
+
+  const absPath = isAbsolute(customHooksPath)
+    ? customHooksPath
+    : resolve(process.cwd(), customHooksPath);
+
+  if (!existsSync(absPath)) {
+    if (opts?.strict) throw new Error(`Custom hooks file not found: ${absPath}`);
+    hookLogWarn(`customHooksPath not found: ${absPath}`);
+    return [];
+  }
+
+  // Clear registry before loading so each invocation starts fresh
+  clearCustomHooks();
+
+  const g = globalThis as Record<string, unknown>;
+  g[LOADING_KEY] = true;
+
+  let tmpFiles: string[] = [];
+  try {
+    const distIndex = await findDistIndex();
+    const distUrl = distIndex ? pathToFileURL(distIndex).href : null;
+
+    tmpFiles = await rewriteFileTree(absPath, distUrl, distIndex);
+
+    const entryTmp = absPath + TMP_SUFFIX;
+    const fileUrl = pathToFileURL(entryTmp).href;
+    await import(/* webpackIgnore: true */ fileUrl);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (opts?.strict) throw new Error(`Failed to load custom hooks from ${absPath}: ${msg}`);
+    hookLogError(`failed to load custom hooks from ${absPath}: ${msg}`);
+    return [];
+  } finally {
+    g[LOADING_KEY] = false;
+    await cleanupTmpFiles(tmpFiles);
+  }
+
+  return getCustomHooks();
+}

package/src/hooks/custom-hooks-registry.ts

@@ -0,0 +1,30 @@
+/**
+ * GlobalThis-backed registry for custom hooks.
+ * Shared via globalThis so that the user's hook file (which imports customPolicies
+ * from 'failproofai') and the hook handler (which reads from this file) share the
+ * same in-process state when running within the same Node.js process.
+ */
+import type { CustomHook } from "./policy-types";
+
+const REGISTRY_KEY = "__failproofai_custom_hooks__";
+
+function getRegistry(): CustomHook[] {
+  const g = globalThis as Record<string, unknown>;
+  if (!Array.isArray(g[REGISTRY_KEY])) g[REGISTRY_KEY] = [];
+  return g[REGISTRY_KEY] as CustomHook[];
+}
+
+export const customPolicies = {
+  add(hook: CustomHook): void {
+    getRegistry().push(hook);
+  },
+};
+
+export function getCustomHooks(): CustomHook[] {
+  return getRegistry();
+}
+
+export function clearCustomHooks(): void {
+  const g = globalThis as Record<string, unknown>;
+  g[REGISTRY_KEY] = [];
+}

package/src/hooks/handler.ts

@@ -0,0 +1,175 @@
+/**
+ * Hook event handler — invoked when Claude Code triggers a hook.
+ *
+ * Reads the JSON payload from stdin, loads enabled policies from
+ * ~/.failproofai/hooks-config.json, evaluates matching policies, persists
+ * activity to disk, and returns the appropriate exit code + stdout response.
+ */
+import type { HookEventType, SessionMetadata } from "./types";
+import type { PolicyFunction, PolicyResult } from "./policy-types";
+import { readMergedHooksConfig } from "./hooks-config";
+import { registerBuiltinPolicies } from "./builtin-policies";
+import { evaluatePolicies } from "./policy-evaluator";
+import { clearPolicies, registerPolicy } from "./policy-registry";
+import { loadCustomHooks } from "./custom-hooks-loader";
+import { persistHookActivity } from "./hook-activity-store";
+import { trackHookEvent } from "./hook-telemetry";
+import { getInstanceId } from "../../lib/telemetry-id";
+import { hookLogInfo, hookLogWarn } from "./hook-logger";
+
+export async function handleHookEvent(eventType: string): Promise<number> {
+  const startTime = performance.now();
+
+  // Read stdin payload (Claude passes JSON)
+  const MAX_STDIN_BYTES = 1_048_576; // 1 MB
+  let payload = "";
+  try {
+    payload = await new Promise<string>((resolve, reject) => {
+      const chunks: string[] = [];
+      let totalBytes = 0;
+      process.stdin.setEncoding("utf8");
+      process.stdin.on("data", (chunk: string) => {
+        totalBytes += Buffer.byteLength(chunk);
+        if (totalBytes > MAX_STDIN_BYTES) {
+          hookLogWarn(`stdin payload exceeds 1 MB for ${eventType}, discarding`);
+          process.stdin.destroy();
+          resolve("");
+          return;
+        }
+        chunks.push(chunk);
+      });
+      process.stdin.on("end", () => resolve(chunks.join("")));
+      process.stdin.on("error", reject);
+      // If stdin is already closed or not piped, resolve immediately
+      if (process.stdin.readableEnded) resolve("");
+    });
+  } catch {
+    hookLogWarn(`stdin read failed for ${eventType}`);
+  }
+
+  let parsed: Record<string, unknown> = {};
+  if (payload) {
+    try {
+      parsed = JSON.parse(payload) as Record<string, unknown>;
+    } catch {
+      hookLogWarn(`payload parse failed for ${eventType} (${payload.length} bytes)`);
+    }
+  }
+
+  // Extract session metadata from payload
+  const session: SessionMetadata = {
+    sessionId: parsed.session_id as string | undefined,
+    transcriptPath: parsed.transcript_path as string | undefined,
+    cwd: parsed.cwd as string | undefined,
+    permissionMode: parsed.permission_mode as string | undefined,
+    hookEventName: parsed.hook_event_name as string | undefined,
+  };
+
+  // Load enabled policies (merge across project/local/global scopes)
+  const config = readMergedHooksConfig(session.cwd);
+  clearPolicies();
+  registerBuiltinPolicies(config.enabledPolicies);
+
+  // Load and register custom hooks (layer 2, after builtins)
+  const customHooksList = await loadCustomHooks(config.customHooksPath);
+  for (const hook of customHooksList) {
+    const hookName = hook.name;
+    const fn: PolicyFunction = async (ctx): Promise<PolicyResult> => {
+      try {
+        const result = await Promise.race([
+          hook.fn(ctx),
+          new Promise<PolicyResult>((_, reject) =>
+            setTimeout(() => reject(new Error("timeout")), 10_000),
+          ),
+        ]);
+        return result;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const isTimeout = msg === "timeout";
+        hookLogWarn(`custom hook "${hookName}" failed: ${msg}`);
+        void trackHookEvent(getInstanceId(), "custom_hook_error", {
+          hook_name: hookName,
+          error_type: isTimeout ? "timeout" : "exception",
+          event_type: eventType,
+        });
+        return { decision: "allow" };
+      }
+    };
+    registerPolicy(
+      `custom/${hookName}`,
+      hook.description ?? "",
+      fn,
+      hook.match ?? {},
+      -1, // Custom hooks run after builtins (priority 0)
+    );
+  }
+
+  // Fire telemetry once per invocation for custom hook loads
+  if (customHooksList.length > 0) {
+    void trackHookEvent(getInstanceId(), "custom_hooks_loaded", {
+      custom_hooks_count: customHooksList.length,
+      custom_hook_names: customHooksList.map((h) => h.name),
+      event_types_covered: [...new Set(customHooksList.flatMap((h) => h.match?.events ?? []))],
+    });
+  }
+
+  hookLogInfo(`event=${eventType} policies=${config.enabledPolicies.length} custom=${customHooksList.length}`);
+
+  // Evaluate policies
+  const result = await evaluatePolicies(eventType as HookEventType, parsed, session, config);
+  const durationMs = Math.round(performance.now() - startTime);
+  hookLogInfo(`result=${result.decision} policy=${result.policyName ?? "none"} duration=${durationMs}ms`);
+
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  // Persist activity to disk (visible in /policies activity tab)
+  try {
+    persistHookActivity({
+      timestamp: Date.now(),
+      eventType,
+      toolName: (parsed.tool_name as string) ?? null,
+      policyName: result.policyName,
+      decision: result.decision,
+      reason: result.reason,
+      durationMs,
+      sessionId: session.sessionId,
+      transcriptPath: session.transcriptPath,
+      cwd: session.cwd,
+      permissionMode: session.permissionMode,
+      hookEventName: session.hookEventName,
+    });
+  } catch {
+    hookLogWarn("activity persistence failed");
+  }
+
+  // Fire PostHog telemetry for decisions that affect Claude's behavior
+  if (result.decision === "deny" || result.decision === "instruct") {
+    try {
+      const isCustomHook = result.policyName?.startsWith("custom/") ?? false;
+      const hasCustomParams =
+        !isCustomHook && !!(result.policyName && config.policyParams?.[result.policyName]);
+      const paramKeysOverridden = hasCustomParams
+        ? Object.keys(config.policyParams![result.policyName!])
+        : [];
+      const distinctId = getInstanceId();
+      await trackHookEvent(distinctId, "hook_policy_triggered", {
+        event_type: eventType,
+        tool_name: (parsed.tool_name as string) ?? null,
+        policy_name: result.policyName,
+        decision: result.decision,
+        is_custom_hook: isCustomHook,
+        has_custom_params: hasCustomParams,
+        param_keys_overridden: paramKeysOverridden,
+      });
+    } catch {
+      // Telemetry is best-effort — never block the hook
+    }
+  }
+
+  return result.exitCode;
+}

package/src/hooks/hook-activity-store.ts

@@ -0,0 +1,344 @@
+/**
+ * Disk persistence for hook activity entries using page-sized JSONL files.
+ *
+ * Storage location: ~/.failproofai/cache/hook-activity/
+ *
+ * File structure:
+ * - current.jsonl — actively written to, 0–PAGE_SIZE entries
+ * - page-{timestamp}-{seq}.jsonl — rotated archive files, exactly PAGE_SIZE entries each
+ *
+ * The hook handler is a short-lived process so writes are synchronous (no buffer).
+ * Dashboard reads are async and lazy (per-page).
+ */
+import {
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+  renameSync,
+  readdirSync,
+  mkdirSync,
+  existsSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export const PAGE_SIZE = 25;
+
+const DEFAULT_STORE_DIR = join(homedir(), ".failproofai", "cache", "hook-activity");
+const CURRENT_FILE = "current.jsonl";
+const COUNT_FILE = "current.count"; // tracks line count; O(1) read/write vs rereading current.jsonl
+const STATS_FILE = "stats.json";
+const LOCK_FILE = "current.lock";  // advisory lock for concurrent hook processes
+const LOCK_STALE_MS = 2000;        // steal lock if older than 2 s (covers crashed processes)
+
+let storeDir = DEFAULT_STORE_DIR;
+let rotateSeq = 0;
+
+// ── Types ──
+
+export interface HookActivityEntry {
+  timestamp: number;
+  eventType: string;
+  toolName: string | null;
+  policyName: string | null;
+  decision: "allow" | "deny" | "instruct";
+  reason: string | null;
+  durationMs: number;
+  sessionId?: string;
+  transcriptPath?: string;
+  cwd?: string;
+  permissionMode?: string;
+  hookEventName?: string;
+}
+
+export interface HookActivityFilters {
+  decision?: "allow" | "deny" | "instruct";
+  eventType?: string;
+  policyName?: string;
+  sessionId?: string;
+}
+
+export interface HookActivityStats {
+  totalEvents: number;
+  denyCount: number;
+  topPolicy: string | null;
+  topPolicyCount: number;
+}
+
+// ── Directory setup ──
+
+function ensureDir(): void {
+  if (!existsSync(storeDir)) {
+    mkdirSync(storeDir, { recursive: true });
+  }
+}
+
+// ── Advisory lock (protects count + stats read-modify-write cycles) ──
+
+function acquireLock(): void {
+  ensureDir();
+  const lockPath = join(storeDir, LOCK_FILE);
+  const deadline = Date.now() + LOCK_STALE_MS;
+  while (Date.now() < deadline) {
+    try {
+      // Exclusive create — fails with EEXIST if another process holds the lock
+      writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+      return; // acquired
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "EEXIST") return; // unexpected — proceed unlocked
+      // Check if the lock is stale (process may have crashed)
+      try {
+        const s = statSync(lockPath);
+        if (Date.now() - s.mtimeMs > LOCK_STALE_MS) {
+          writeFileSync(lockPath, String(process.pid), "utf-8"); // steal stale lock
+          return;
+        }
+      } catch { /* lock file disappeared — retry */ }
+    }
+  }
+  // Timed out — proceed without lock (best-effort, extremely rare)
+}
+
+function releaseLock(): void {
+  try { unlinkSync(join(storeDir, LOCK_FILE)); } catch { /* ignore */ }
+}
+
+// ── Writing (synchronous — hook handler is short-lived) ──
+
+export function persistHookActivity(entry: HookActivityEntry): void {
+  ensureDir();
+  acquireLock();
+  try {
+    const currentPath = join(storeDir, CURRENT_FILE);
+    const countPath = join(storeDir, COUNT_FILE);
+
+    const lineCount = readCount(countPath);
+    if (lineCount >= PAGE_SIZE) {
+      try {
+        rotate(currentPath, countPath);
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+        // Another process rotated concurrently — proceed to append to fresh file.
+      }
+    }
+
+    appendFileSync(currentPath, JSON.stringify(entry) + "\n", "utf-8");
+    writeCount(countPath, lineCount >= PAGE_SIZE ? 1 : lineCount + 1);
+    updateStats(entry);
+  } finally {
+    releaseLock();
+  }
+}
+
+function rotate(currentPath: string, countPath: string): void {
+  const archiveName = `page-${Date.now()}-${rotateSeq++}.jsonl`;
+  const archivePath = join(storeDir, archiveName);
+  renameSync(currentPath, archivePath);
+  // Reset count for the fresh file (write 0 — next append will set it to 1)
+  writeCount(countPath, 0);
+}
+
+// O(1) line count via a tiny sidecar file; avoids rereading current.jsonl.
+function readCount(countPath: string): number {
+  try {
+    const n = parseInt(readFileSync(countPath, "utf-8"), 10);
+    return isNaN(n) ? 0 : n;
+  } catch {
+    return 0;
+  }
+}
+
+function writeCount(countPath: string, n: number): void {
+  try {
+    writeFileSync(countPath, String(n), "utf-8");
+  } catch {
+    // Non-fatal: worst case we recount from 0 next time
+  }
+}
+
+function readFileSafe(filePath: string): string {
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+// ── Incremental stats (O(1) reads/writes) ──
+
+interface StoredStats {
+  totalEvents: number;
+  denyCount: number;
+  policyMap: Record<string, number>;
+}
+
+function readStoredStats(): StoredStats {
+  try {
+    return JSON.parse(readFileSync(join(storeDir, STATS_FILE), "utf-8")) as StoredStats;
+  } catch {
+    return { totalEvents: 0, denyCount: 0, policyMap: {} };
+  }
+}
+
+function updateStats(entry: HookActivityEntry): void {
+  const s = readStoredStats();
+  s.totalEvents += 1;
+  if (entry.decision === "deny") s.denyCount += 1;
+  if (entry.policyName) {
+    s.policyMap[entry.policyName] = (s.policyMap[entry.policyName] ?? 0) + 1;
+  }
+  // Write atomically: write to a PID-unique temp file then rename — prevents partial reads.
+  const tmpPath = join(storeDir, `stats.json.${process.pid}.tmp`);
+  try {
+    writeFileSync(tmpPath, JSON.stringify(s), "utf-8");
+    renameSync(tmpPath, join(storeDir, STATS_FILE));
+  } catch {
+    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+    // Non-fatal: stats file write failure doesn't block the hook
+  }
+}
+
+function readStats(): HookActivityStats {
+  const s = readStoredStats();
+  let topPolicy: string | null = null;
+  let topPolicyCount = 0;
+  for (const [name, count] of Object.entries(s.policyMap)) {
+    if (count > topPolicyCount) {
+      topPolicy = name;
+      topPolicyCount = count;
+    }
+  }
+  return { totalEvents: s.totalEvents, denyCount: s.denyCount, topPolicy, topPolicyCount };
+}
+
+// ── Reading (lazy, per-page) ──
+
+export function getHookActivityPage(page: number): HookActivityEntry[] {
+  ensureDir();
+  if (page < 1) return [];
+
+  if (page === 1) {
+    const currentPath = join(storeDir, CURRENT_FILE);
+    return readJsonlFile(currentPath).reverse();
+  }
+
+  const archives = getArchiveFiles();
+  const archiveIndex = page - 2;
+  if (archiveIndex >= archives.length) return [];
+
+  return readJsonlFile(join(storeDir, archives[archiveIndex])).reverse();
+}
+
+export function getHookActivityPageCount(): number {
+  ensureDir();
+  return 1 + getArchiveFiles().length;
+}
+
+export function getAllHookActivityEntries(): HookActivityEntry[] {
+  ensureDir();
+
+  const currentPath = join(storeDir, CURRENT_FILE);
+  const currentEntries = readJsonlFile(currentPath).reverse();
+
+  const archives = getArchiveFiles();
+  const archiveEntries: HookActivityEntry[] = [];
+  for (const file of archives) {
+    const entries = readJsonlFile(join(storeDir, file));
+    archiveEntries.push(...entries.reverse());
+  }
+
+  return [...currentEntries, ...archiveEntries];
+}
+
+
+export function searchHookActivity(
+  filters: HookActivityFilters,
+  page: number,
+): { entries: HookActivityEntry[]; totalPages: number; page: number; stats: HookActivityStats } {
+  const all = getAllHookActivityEntries();
+
+  const filtered = all.filter((entry) => {
+    if (filters.decision && entry.decision !== filters.decision) return false;
+    if (filters.eventType && entry.eventType !== filters.eventType) return false;
+    if (
+      filters.policyName &&
+      (!entry.policyName || !entry.policyName.toLowerCase().includes(filters.policyName.toLowerCase()))
+    ) {
+      return false;
+    }
+    if (
+      filters.sessionId &&
+      (!entry.sessionId || !entry.sessionId.toLowerCase().includes(filters.sessionId.toLowerCase()))
+    ) {
+      return false;
+    }
+    return true;
+  });
+
+  const totalPages = Math.max(1, Math.ceil(filtered.length / PAGE_SIZE));
+  const start = (page - 1) * PAGE_SIZE;
+  const entries = filtered.slice(start, start + PAGE_SIZE);
+  // Stats come from the O(1) incremental stats file rather than a full rescan.
+  const stats = readStats();
+
+  return { entries, totalPages, page, stats };
+}
+
+export function getHookActivityHistory(page: number): {
+  entries: HookActivityEntry[];
+  totalPages: number;
+  page: number;
+  stats: HookActivityStats;
+} {
+  const entries = getHookActivityPage(page);
+  const totalPages = getHookActivityPageCount();
+  // Stats come from the O(1) incremental stats file rather than a full rescan.
+  const stats = readStats();
+  return { entries, totalPages, page, stats };
+}
+
+// ── Internal helpers ──
+
+function readJsonlFile(filePath: string): HookActivityEntry[] {
+  const content = readFileSafe(filePath);
+  if (!content.trim()) return [];
+
+  const entries: HookActivityEntry[] = [];
+  for (const line of content.trim().split("\n")) {
+    try {
+      entries.push(JSON.parse(line) as HookActivityEntry);
+    } catch {
+      // Skip malformed lines
+    }
+  }
+  return entries;
+}
+
+function getArchiveFiles(): string[] {
+  try {
+    const files = readdirSync(storeDir);
+    return files
+      .filter((f) => f.startsWith("page-") && f.endsWith(".jsonl"))
+      .sort((a, b) => {
+        const partsA = a.slice(5, -6).split("-");
+        const partsB = b.slice(5, -6).split("-");
+        const tsA = parseInt(partsA[0], 10);
+        const tsB = parseInt(partsB[0], 10);
+        if (tsA !== tsB) return tsB - tsA;
+        const seqA = partsA.length > 1 ? parseInt(partsA[1], 10) : 0;
+        const seqB = partsB.length > 1 ? parseInt(partsB[1], 10) : 0;
+        return seqB - seqA;
+      });
+  } catch {
+    return [];
+  }
+}
+
+// ── Test helpers ──
+
+export function _resetForTest(testDir?: string): void {
+  rotateSeq = 0;
+  storeDir = testDir ?? DEFAULT_STORE_DIR;
+}