failproofai 0.0.1-beta.1

package/src/hooks/policy-evaluator.ts

@@ -0,0 +1,171 @@
+/**
+ * Evaluates enabled policies against a hook event payload.
+ * Returns exit code, stdout, and stderr for the hook handler.
+ */
+import type { HookEventType, SessionMetadata } from "./types";
+import type { PolicyContext, HooksConfig } from "./policy-types";
+import { BUILTIN_POLICIES } from "./builtin-policies";
+import { getPoliciesForEvent } from "./policy-registry";
+import { hookLogInfo, hookLogWarn } from "./hook-logger";
+
+export interface EvaluationResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  policyName: string | null;
+  reason: string | null;
+  decision: "allow" | "deny" | "instruct";
+}
+
+// Build a map from policy name to its params schema (for injecting defaults)
+const POLICY_PARAMS_MAP = new Map(
+  BUILTIN_POLICIES.filter((p) => p.params).map((p) => [p.name, p.params!]),
+);
+
+export async function evaluatePolicies(
+  eventType: HookEventType,
+  payload: Record<string, unknown>,
+  session?: SessionMetadata,
+  config?: HooksConfig,
+): Promise<EvaluationResult> {
+  const toolName = payload.tool_name as string | undefined;
+  const toolInput = payload.tool_input as Record<string, unknown> | undefined;
+
+  const policies = getPoliciesForEvent(eventType, toolName);
+
+  hookLogInfo(`evaluating ${policies.length} policies for ${eventType}`);
+
+  if (policies.length === 0) {
+    return { exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow" };
+  }
+
+  const baseCtx: PolicyContext = {
+    eventType,
+    payload,
+    toolName,
+    toolInput,
+    session,
+  };
+
+  // Track the first instruct result (accumulated, does not short-circuit)
+  let instructPolicyName: string | null = null;
+  let instructReason: string | null = null;
+
+  for (const policy of policies) {
+    // Inject params: merge policyParams[policy.name] over schema defaults
+    const schema = POLICY_PARAMS_MAP.get(policy.name);
+    let ctx: PolicyContext;
+    if (schema) {
+      const userParams = config?.policyParams?.[policy.name] ?? {};
+      const resolvedParams: Record<string, unknown> = {};
+      for (const [key, spec] of Object.entries(schema)) {
+        resolvedParams[key] = key in userParams ? userParams[key] : spec.default;
+      }
+      ctx = { ...baseCtx, params: resolvedParams };
+    } else {
+      // Custom hooks and policies without schema get empty params
+      ctx = { ...baseCtx, params: {} };
+    }
+
+    let result: Awaited<ReturnType<typeof policy.fn>>;
+    try {
+      result = await policy.fn(ctx);
+    } catch (err) {
+      hookLogWarn(`policy "${policy.name}" threw: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+
+    if (result.decision === "deny") {
+      const reason = result.reason ?? `Blocked by policy: ${policy.name}`;
+      hookLogInfo(`deny by "${policy.name}": ${reason}`);
+
+      const displayTool = ctx.toolName ?? "unknown tool";
+
+      if (eventType === "PreToolUse") {
+        const response = {
+          hookSpecificOutput: {
+            hookEventName: eventType,
+            permissionDecision: "deny",
+            permissionDecisionReason: `Blocked ${displayTool} by failproofai because: ${reason}, as per the policy configured by the user`,
+          },
+        };
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify(response),
+          stderr: "",
+          policyName: policy.name,
+          reason,
+          decision: "deny",
+        };
+      }
+
+      if (eventType === "PostToolUse") {
+        const response = {
+          hookSpecificOutput: {
+            hookEventName: eventType,
+            additionalContext: `Blocked ${displayTool} by failproofai because: ${reason}, as per the policy configured by the user`,
+          },
+        };
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify(response),
+          stderr: "",
+          policyName: policy.name,
+          reason,
+          decision: "deny",
+        };
+      }
+
+      // Other event types: exit 2
+      return {
+        exitCode: 2,
+        stdout: "",
+        stderr: "",
+        policyName: policy.name,
+        reason,
+        decision: "deny",
+      };
+    }
+
+    // Accumulate first instruct (does not short-circuit — later policies can still deny)
+    if (result.decision === "instruct" && !instructPolicyName) {
+      instructPolicyName = policy.name;
+      instructReason = result.reason ?? `Instruction from policy: ${policy.name}`;
+      hookLogInfo(`instruct by "${policy.name}": ${instructReason}`);
+    }
+  }
+
+  // No deny — check if we accumulated an instruct
+  if (instructPolicyName && instructReason) {
+    if (eventType === "Stop") {
+      // Stop hook: exitCode 2 blocks Claude from stopping.
+      // Reason goes to stderr so Claude Code receives it as context.
+      return {
+        exitCode: 2,
+        stdout: "",
+        stderr: instructReason,
+        policyName: instructPolicyName,
+        reason: instructReason,
+        decision: "instruct",
+      };
+    }
+
+    const response = {
+      hookSpecificOutput: {
+        hookEventName: eventType,
+        additionalContext: `Instruction from failproofai: ${instructReason}`,
+      },
+    };
+    return {
+      exitCode: 0,
+      stdout: JSON.stringify(response),
+      stderr: "",
+      policyName: instructPolicyName,
+      reason: instructReason,
+      decision: "instruct",
+    };
+  }
+
+  // All policies allowed
+  return { exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow" };
+}

package/src/hooks/policy-helpers.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared decision helper functions for builtin and custom policies.
+ */
+import type { PolicyResult } from "./policy-types";
+
+export function allow(): PolicyResult {
+  return { decision: "allow" };
+}
+
+export function deny(reason: string): PolicyResult {
+  return { decision: "deny", reason };
+}
+
+export function instruct(reason: string): PolicyResult {
+  return { decision: "instruct", reason };
+}

package/src/hooks/policy-registry.ts

@@ -0,0 +1,90 @@
+/**
+ * Module-level singleton policy registry backed by globalThis.
+ *
+ * Policies are keyed by name — registering a duplicate name replaces
+ * the previous entry. Using globalThis ensures the registry survives
+ * chunk splitting and remains a true singleton across dynamic imports.
+ */
+import type { HookEventType } from "./types";
+import type { PolicyFunction, PolicyMatcher, RegisteredPolicy } from "./policy-types";
+
+const REGISTRY_KEY = "__FAILPROOFAI_POLICY_REGISTRY__";
+const INDEX_CACHE_KEY = "__FAILPROOFAI_POLICY_INDEX_CACHE__";
+
+interface GlobalWithRegistry {
+  [REGISTRY_KEY]?: RegisteredPolicy[];
+}
+
+interface GlobalWithCache extends GlobalWithRegistry {
+  [INDEX_CACHE_KEY]?: Map<string, RegisteredPolicy[]> | null;
+}
+
+function getIndexCache(): Map<string, RegisteredPolicy[]> | null | undefined {
+  return (globalThis as GlobalWithCache)[INDEX_CACHE_KEY];
+}
+
+function setIndexCache(cache: Map<string, RegisteredPolicy[]> | null): void {
+  (globalThis as GlobalWithCache)[INDEX_CACHE_KEY] = cache;
+}
+
+function getRegistry(): RegisteredPolicy[] {
+  const g = globalThis as GlobalWithRegistry;
+  if (!g[REGISTRY_KEY]) {
+    g[REGISTRY_KEY] = [];
+  }
+  return g[REGISTRY_KEY];
+}
+
+export function registerPolicy(
+  name: string,
+  description: string,
+  fn: PolicyFunction,
+  match: PolicyMatcher,
+  priority: number = 0,
+): void {
+  const registry = getRegistry();
+  const idx = registry.findIndex((p) => p.name === name);
+  const entry: RegisteredPolicy = { name, description, fn, match, priority };
+  if (idx >= 0) {
+    registry[idx] = entry;
+  } else {
+    registry.push(entry);
+  }
+  setIndexCache(null); // invalidate on any registry change
+}
+
+export function getPoliciesForEvent(
+  eventType: HookEventType,
+  toolName?: string,
+): RegisteredPolicy[] {
+  let cache = getIndexCache();
+  if (!cache) {
+    cache = new Map();
+    setIndexCache(cache);
+  }
+  const key = `${eventType}:${toolName ?? ""}`;
+  const cached = cache.get(key);
+  if (cached) return cached;
+
+  const result = getRegistry()
+    .filter((p) => {
+      // If events specified, must match
+      if (p.match.events && p.match.events.length > 0) {
+        if (!p.match.events.includes(eventType)) return false;
+      }
+      // If toolNames specified, must match
+      if (p.match.toolNames && p.match.toolNames.length > 0) {
+        if (!toolName || !p.match.toolNames.includes(toolName)) return false;
+      }
+      return true;
+    })
+    .sort((a, b) => b.priority - a.priority);
+  cache.set(key, result);
+  return result;
+}
+
+export function clearPolicies(): void {
+  const g = globalThis as GlobalWithRegistry;
+  g[REGISTRY_KEY] = [];
+  setIndexCache(null);
+}

package/src/hooks/policy-types.ts

@@ -0,0 +1,77 @@
+/**
+ * Types for the hook policy system.
+ */
+import type { HookEventType, SessionMetadata } from "./types";
+
+export type PolicyDecision = "allow" | "deny" | "instruct";
+
+export interface PolicyContext {
+  eventType: HookEventType;
+  payload: Record<string, unknown>;
+  toolName?: string;
+  toolInput?: Record<string, unknown>;
+  session?: SessionMetadata;
+  params?: Record<string, unknown>;
+}
+
+export interface PolicyResult {
+  decision: PolicyDecision;
+  reason?: string;
+  message?: string;
+}
+
+export type PolicyFunction = (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+
+export interface PolicyMatcher {
+  events?: HookEventType[];
+  toolNames?: string[];
+}
+
+export interface RegisteredPolicy {
+  name: string;
+  description: string;
+  fn: PolicyFunction;
+  match: PolicyMatcher;
+  priority: number;
+}
+
+export interface PolicyParamsSchema {
+  [paramName: string]: {
+    type: "string" | "number" | "boolean" | "string[]" | "pattern[]";
+    description: string;
+    default: unknown;
+  };
+}
+
+export interface BuiltinPolicyDefinition {
+  name: string;
+  description: string;
+  fn: PolicyFunction;
+  match: PolicyMatcher;
+  defaultEnabled: boolean;
+  category: string;
+  beta?: boolean;
+  params?: PolicyParamsSchema;
+}
+
+export interface CustomHook {
+  name: string;
+  description?: string;
+  match?: {
+    events?: HookEventType[];
+  };
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+}
+
+export interface LlmConfig {
+  baseUrl?: string;
+  apiKey?: string;
+  model?: string;
+}
+
+export interface HooksConfig {
+  enabledPolicies: string[];
+  llm?: LlmConfig;
+  policyParams?: Record<string, Record<string, unknown>>;
+  customHooksPath?: string;
+}

package/src/hooks/types.ts

@@ -0,0 +1,54 @@
+/**
+ * Constants and interfaces for Claude Code hooks integration.
+ */
+
+export const HOOK_SCOPES = ["user", "project", "local"] as const;
+export type HookScope = (typeof HOOK_SCOPES)[number];
+
+export const HOOK_EVENT_TYPES = [
+  "SessionStart",
+  "SessionEnd",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "PostToolUseFailure",
+  "PermissionRequest",
+  "Notification",
+  "SubagentStart",
+  "SubagentStop",
+  "Stop",
+  "TeammateIdle",
+  "TaskCompleted",
+  "ConfigChange",
+  "WorktreeCreate",
+  "WorktreeRemove",
+  "PreCompact",
+] as const;
+
+export type HookEventType = (typeof HOOK_EVENT_TYPES)[number];
+
+export const FAILPROOFAI_HOOK_MARKER = "__failproofai_hook__" as const;
+
+export interface ClaudeHookEntry {
+  type: "command";
+  command: string;
+  timeout: number;
+  [FAILPROOFAI_HOOK_MARKER]: true;
+}
+
+export interface ClaudeHookMatcher {
+  hooks: Array<ClaudeHookEntry | Record<string, unknown>>;
+}
+
+export interface SessionMetadata {
+  sessionId?: string;
+  transcriptPath?: string;
+  cwd?: string;
+  permissionMode?: string;
+  hookEventName?: string;
+}
+
+export interface ClaudeSettings {
+  hooks?: Record<string, ClaudeHookMatcher[]>;
+  [key: string]: unknown;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Public API for failproofai custom hooks.
+ *
+ * Used as the bundle entry point for `dist/index.js` (CJS) and re-exported
+ * by the ESM shim that rewrites `from 'failproofai'` in user hook files.
+ */
+export {
+  customPolicies,
+  getCustomHooks,
+  clearCustomHooks,
+} from "./hooks/custom-hooks-registry";
+export { allow, deny, instruct } from "./hooks/policy-helpers";
+export type {
+  PolicyContext,
+  PolicyResult,
+  CustomHook,
+  PolicyDecision,
+  PolicyFunction,
+} from "./hooks/policy-types";

package/src/posthog-key.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared PostHog API key used by both the Next.js telemetry client
+ * and the compiled hook binary telemetry. Write-only (safe to commit).
+ */
+export const POSTHOG_API_KEY = "phc_Ac1Ww1GqKc0z1SyrRWbmatEeQdlOQIsDEEdP8l8JRgX";