failproofai 0.0.1-beta.1

package/.next/standalone/docs/testing.md

@@ -0,0 +1,256 @@
+# Testing
+
+failproofai has two test suites: **unit tests** (fast, mocked) and **end-to-end tests** (real subprocess invocations).
+
+---
+
+## Running tests
+
+```bash
+# Run all unit tests once
+bun run test:run
+
+# Run unit tests in watch mode
+bun run test
+
+# Run E2E tests (requires setup — see below)
+bun run test:e2e
+
+# Type-check without building
+bunx tsc --noEmit
+
+# Lint
+bun run lint
+```
+
+---
+
+## Unit tests
+
+Unit tests live in `__tests__/` and use [Vitest](https://vitest.dev) with `happy-dom`.
+
+```
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Policy logic for each builtin
+    hooks-config.test.ts          # Config loading and scope merging
+    policy-evaluator.test.ts      # Param injection and evaluation order
+    custom-hooks-registry.test.ts # globalThis registry add/get/clear
+    custom-hooks-loader.test.ts   # ESM loader, transitive imports, error handling
+    manager.test.ts               # install/remove/list operations
+  components/
+    sessions-list.test.tsx        # Session list component
+    project-list.test.tsx         # Project list component
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### Writing a policy unit test
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## End-to-end tests
+
+E2E tests invoke the real `failproofai` binary as a subprocess, pipe a JSON payload to stdin, and assert on the stdout output and exit code. This tests the complete integration path that Claude Code uses.
+
+### Setup
+
+E2E tests run the binary directly from the repo source. Before the first run, build the CJS bundle that custom hook files use when they import from `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Then run the tests:
+
+```bash
+bun run test:e2e
+```
+
+Rebuild `dist/` whenever you change the public hook API (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, or `src/hooks/policy-types.ts`).
+
+### E2E test structure
+
+```
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Spawn the binary, pipe payload JSON, capture exit code + stdout + stderr
+    fixture-env.ts      # Per-test isolated temp directories with config files
+    payloads.ts         # Claude-accurate payload factories for each event type
+  hooks/
+    builtin-policies.e2e.test.ts   # Each builtin policy with real subprocess
+    custom-hooks.e2e.test.ts       # Custom hook loading and evaluation
+    config-scopes.e2e.test.ts      # Config merging across project/local/global
+    policy-params.e2e.test.ts      # Parameter injection for each parameterized policy
+```
+
+### Using the E2E helpers
+
+**`FixtureEnv`** — isolated per-test environment:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    — temp dir; pass as payload.cwd to pick up .failproofai/hooks-config.json
+// env.home   — isolated home dir; no real ~/.failproofai leaks in
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` registers `afterEach` cleanup automatically.
+
+**`runHook`** — invoke the binary:
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** — ready-made payload factories:
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### Writing an E2E test
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → empty stdout
+  });
+});
+```
+
+### E2E response shapes
+
+| Decision | Exit code | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | empty stdout; reason in stderr |
+| Allow | `0` | empty string |
+
+### Vitest config
+
+E2E tests use `vitest.config.e2e.mts` with:
+
+- `environment: "node"` — no browser globals needed
+- `pool: "forks"` — true process isolation (tests spawn subprocesses)
+- `testTimeout: 20_000` — 20s per test (binary startup + hook eval)
+
+The `forks` pool is important: thread-based workers share `globalThis`, which can interfere with subprocess-spawning tests. Process-based forks avoid this.
+
+---
+
+## CI
+
+The full CI run (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) is required to pass before merging. The E2E suite runs as a separate CI job in parallel.
+
+See [Contributing](../CONTRIBUTING.md) for the complete pre-merge checklist.

package/.next/standalone/eslint.config.mjs

@@ -0,0 +1,15 @@
+import nextConfig from "eslint-config-next/core-web-vitals";
+import tsParser from "@typescript-eslint/parser";
+
+const config = [
+  { ignores: ["dist/"] },
+  ...nextConfig,
+  { settings: { react: { version: "19" } } },
+  {
+    files: ["**/*.{js,jsx,mjs,mts,cts}"],
+    languageOptions: { parser: tsParser },
+  },
+];
+
+export default config;
+

package/.next/standalone/examples/policies-advanced/index.js

@@ -0,0 +1,146 @@
+/**
+ * policies-advanced/index.js — advanced custom policies example
+ *
+ * Demonstrates:
+ *   - Transitive local imports (./utils.js is auto-rewritten by the loader)
+ *   - Async hooks (await inside fn)
+ *   - Using ctx.session (cwd, sessionId)
+ *   - PostToolUse event (inspect tool output)
+ *   - Stop event (verify before Claude finishes)
+ *
+ * Install:
+ *   failproofai --install-hooks custom ./examples/policies-advanced/index.js
+ */
+import { customPolicies, allow, deny, instruct } from "failproofai";
+import { isOutsideProject, extractPushBranch, looksLikeSecretFile } from "./utils.js";
+
+// 1. Block writes to secret-looking file paths (uses transitive import)
+customPolicies.add({
+  name: "block-secret-file-writes",
+  description: "Block writing to files that look like private keys or credentials",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write") return allow();
+    const path = String(ctx.toolInput?.file_path ?? "");
+    if (looksLikeSecretFile(path)) {
+      return deny(`Writing to ${path} is blocked — looks like a secret or credential file`);
+    }
+    return allow();
+  },
+});
+
+// 2. Block pushing to version-tagged branches (e.g. v1.2.3) — must go through release process
+customPolicies.add({
+  name: "block-push-to-version-tags",
+  description: "Block git push directly to version branches (v*.*.*)",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (!/git\s+push\b/.test(cmd)) return allow();
+    const branch = extractPushBranch(cmd);
+    if (branch && /^v\d+\.\d+/.test(branch)) {
+      return deny(`Pushing directly to version branch "${branch}" is not allowed — use the release workflow`);
+    }
+    return allow();
+  },
+});
+
+// 3. Warn if a Bash command touches paths outside the session cwd (uses ctx.session)
+customPolicies.add({
+  name: "warn-outside-cwd",
+  description: "Warn before Bash commands that reference absolute paths outside the session cwd",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    const cwd = ctx.session?.cwd;
+    if (cwd && isOutsideProject(cmd, cwd)) {
+      return instruct(
+        `The command references a path outside the project root (${cwd}). ` +
+        "Confirm this is intentional before proceeding."
+      );
+    }
+    return allow();
+  },
+});
+
+// 4. PostToolUse: strip any line from Bash output that looks like a raw API key
+customPolicies.add({
+  name: "scrub-api-key-output",
+  description: "Redact lines containing raw API keys from Bash tool output",
+  match: { events: ["PostToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const output = String(ctx.payload?.tool_result ?? "");
+    // Simple heuristic: long alphanumeric tokens prefixed by known key prefixes
+    const keyPattern = /(?:sk-|ghp_|AIza|AKIA)[A-Za-z0-9_\-]{20,}/;
+    if (keyPattern.test(output)) {
+      return deny("Bash output contains what looks like a raw API key — output suppressed");
+    }
+    return allow();
+  },
+});
+
+// 5. Stop event: remind Claude to summarise what it changed before finishing
+customPolicies.add({
+  name: "require-change-summary",
+  description: "Ask Claude to include a change summary before stopping",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const transcript = String(ctx.payload?.transcript ?? "");
+    // Only trigger if there were file-modifying tool calls in the session
+    const hadWrites = /\"tool_name\"\s*:\s*\"(Write|Edit|Bash)\"/.test(transcript);
+    if (hadWrites && !transcript.includes("## Summary")) {
+      return instruct(
+        "Before finishing, provide a brief '## Summary' of files you created or modified."
+      );
+    }
+    return allow();
+  },
+});
+
+// 6. Notification event: forward Claude's idle notifications to Slack
+customPolicies.add({
+  name: "slack-on-idle-notification",
+  description: "Forward Claude idle notifications to Slack (set SLACK_WEBHOOK_URL env var)",
+  match: { events: ["Notification"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow(); // skip if not configured
+
+    const type = String(ctx.payload?.notification_type ?? "");
+    if (type !== "idle") return allow(); // only forward idle notifications
+
+    const message = String(ctx.payload?.message ?? "Claude is waiting for input");
+    const cwd = ctx.session?.cwd ?? "unknown";
+    const sessionId = ctx.session?.sessionId ?? "unknown";
+
+    // Fire-and-forget — never block Claude if Slack is unreachable
+    fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        blocks: [
+          {
+            type: "header",
+            text: { type: "plain_text", text: "💬 Claude is waiting for you", emoji: true },
+          },
+          {
+            type: "section",
+            text: { type: "mrkdwn", text: message },
+          },
+          {
+            type: "section",
+            fields: [
+              { type: "mrkdwn", text: `*Project*\n\`${cwd}\`` },
+              { type: "mrkdwn", text: `*Session*\n\`${sessionId}\`` },
+            ],
+          },
+        ],
+      }),
+    }).catch(() => {});
+
+    return allow(); // Notification hooks must always return allow
+  },
+});

package/.next/standalone/examples/policies-advanced/utils.js

@@ -0,0 +1,35 @@
+/**
+ * Shared utilities for hooks-advanced/index.js
+ * This file is a transitive import — the loader rewrites it automatically.
+ */
+
+/** Return true if the command touches a path outside the project root. */
+export function isOutsideProject(cmd, cwd) {
+  if (!cwd) return false;
+  // Very rough check: absolute paths that don't start with cwd
+  const absPathRe = /(?:^|\s)(\/[^\s]+)/g;
+  let match;
+  while ((match = absPathRe.exec(cmd)) !== null) {
+    if (!match[1].startsWith(cwd)) return true;
+  }
+  return false;
+}
+
+/** Extract the first git branch name from a push command, e.g. "git push origin feat/foo" → "feat/foo" */
+export function extractPushBranch(cmd) {
+  const m = cmd.match(/git\s+push\s+\S+\s+(\S+)/);
+  return m ? m[1] : null;
+}
+
+/** Return the list of staged secret file patterns to check. */
+export const SECRET_FILENAME_PATTERNS = [
+  /\.pem$/i,
+  /\.key$/i,
+  /id_rsa/i,
+  /credentials\.json$/i,
+  /\.p12$/i,
+];
+
+export function looksLikeSecretFile(path) {
+  return SECRET_FILENAME_PATTERNS.some((re) => re.test(path));
+}

package/.next/standalone/examples/policies-basic.js

@@ -0,0 +1,77 @@
+/**
+ * policies-basic.js — starter custom policies example
+ *
+ * Install:
+ *   failproofai --install-hooks custom ./examples/policies-basic.js
+ *
+ * Test by asking Claude to:
+ *   - Write to any file containing "production" in the path → deny
+ *   - Run `git push --force` → deny
+ *   - Run `npm install` → instruct (reminder)
+ *   - Run `curl ... | bash` → deny
+ *   - Anything else → allow
+ */
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// 1. Block writes to production config files
+customPolicies.add({
+  name: "block-production-writes",
+  description: "Prevent writes to files with 'production' or 'prod.' in their path",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write") return allow();
+    const path = String(ctx.toolInput?.file_path ?? "");
+    if (/production|prod\./i.test(path)) {
+      return deny(`Writing to production config is blocked: ${path}`);
+    }
+    return allow();
+  },
+});
+
+// 2. Block git force-push (complements built-in block-force-push with a custom message)
+customPolicies.add({
+  name: "block-force-push-custom",
+  description: "Block git push --force with a team-specific message",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+push\b.*\s(-f|--force)\b/.test(cmd)) {
+      return deny("Force-push is prohibited — open a PR and request a branch reset instead");
+    }
+    return allow();
+  },
+});
+
+// 3. Remind Claude to check the lockfile before running npm install
+customPolicies.add({
+  name: "npm-install-reminder",
+  description: "Remind Claude to verify lockfile consistency before npm install",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/\bnpm\s+install\b/.test(cmd) && !/\bnpm\s+install\s+\S/.test(cmd)) {
+      return instruct(
+        "Before running npm install, confirm package.json and package-lock.json are in sync. " +
+        "If you only need to add a single package use `npm install <package>` instead."
+      );
+    }
+    return allow();
+  },
+});
+
+// 4. Block piping curl/wget directly to a shell interpreter
+customPolicies.add({
+  name: "block-remote-exec",
+  description: "Block curl|sh and wget|bash remote code execution patterns",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/\bcurl\b.*\|\s*(ba)?sh\b/.test(cmd) || /\bwget\b.*\|\s*(ba)?sh\b/.test(cmd)) {
+      return deny("Piping remote content into a shell is blocked — download the script first and inspect it");
+    }
+    return allow();
+  },
+});

package/.next/standalone/instrumentation.node.ts

@@ -0,0 +1,37 @@
+/**
+ * Node.js-only instrumentation logic.
+ * Dynamically imported from instrumentation.ts only when NEXT_RUNTIME === 'nodejs',
+ * so that Turbopack/Edge compilation never sees Node.js APIs like process.arch or node:os.
+ */
+export async function registerNode() {
+  const os = await import("node:os");
+
+  const { initLogger } = await import("./lib/logger");
+  initLogger();
+
+  const { initTelemetry, trackEvent, flushTelemetry } = await import("./lib/telemetry");
+  await initTelemetry();
+
+  const { hashToId } = await import("./lib/telemetry-id");
+  const { version } = await import("./package.json");
+
+  trackEvent("app_started", {
+    version,
+    runtime: typeof globalThis !== "undefined" && "Bun" in globalThis ? "bun" : "node",
+    platform: process.platform,
+    arch: process.arch,
+    node_version: process.version,
+    has_custom_posthog: !!process.env.FAILPROOFAI_POSTHOG_KEY,
+    has_projects_path: !!process.env.FAILPROOFAI_PROJECTS_PATH,
+    logging_level: process.env.FAILPROOFAI_LOG_LEVEL ?? "default",
+    deploy_mode: process.env.NODE_ENV === "production" ? "standalone" : "dev",
+    os_release: os.release(),
+    uptime: os.uptime(),
+    total_memory_gb: Math.round(os.totalmem() / 1e9 * 10) / 10,
+    cpu_count: os.cpus().length,
+    cpu_model: os.cpus()[0]?.model ?? "unknown",
+    hostname_hash: hashToId(os.hostname()),
+  });
+  // Fire and forget — telemetry should never block server startup
+  flushTelemetry().catch(() => {});
+}

package/.next/standalone/instrumentation.ts

@@ -0,0 +1,11 @@
+/**
+ * Next.js instrumentation hook — runs once on server startup.
+ * Delegates to instrumentation.node.ts which is dynamically imported only
+ * when running in the Node.js runtime, so Edge compilation never sees Node.js APIs.
+ */
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
+
+  const { registerNode } = await import("./instrumentation.node");
+  await registerNode();
+}

package/.next/standalone/lib/claude-config.ts

@@ -0,0 +1,36 @@
+/**
+ * Thin wrapper around `lib/paths.ts` that re-exports the projects path
+ * getter under application-specific names.  Keeps the rest of the app
+ * decoupled from the low-level path module.
+ */
+import { getClaudeProjectsPath as getPath } from "./paths";
+
+/**
+ * Gets the configured .claude projects path
+ * This can be used throughout the application to access the path
+ * 
+ * @returns The path to the .claude/projects directory
+ * 
+ * @example
+ * ```ts
+ * import { getClaudeProjectsPath } from '@/lib/claude-config';
+ * 
+ * const projectsPath = getClaudeProjectsPath();
+ * // Use the path to read project files
+ * ```
+ */
+export function getClaudeProjectsPath(): string {
+  return getPath();
+}
+
+/**
+ * Gets the configured .claude projects path (server-side only)
+ * Use this in API routes, server components, or server actions
+ * 
+ * @returns The path to the .claude/projects directory
+ */
+export function getClaudeProjectsPathServer(): string {
+  // In server-side code, we can access process.env directly
+  return process.env.CLAUDE_PROJECTS_PATH || getPath();
+}
+

package/.next/standalone/lib/client-telemetry.ts

@@ -0,0 +1,37 @@
+import type { TelemetryConfig } from "@/app/actions/get-telemetry-config";
+
+let config: TelemetryConfig | null = null;
+
+export function setClientTelemetryConfig(c: TelemetryConfig): void {
+  config = c;
+}
+
+export function captureClientEvent(
+  event: string,
+  properties?: Record<string, unknown>,
+): void {
+  if (typeof window === "undefined") return;
+  if (!config || !config.enabled) return;
+
+  const payload = JSON.stringify({
+    api_key: config.apiKey,
+    event,
+    distinct_id: config.distinctId,
+    properties: {
+      ...properties,
+      $lib: "failproofai-web",
+      failproofai_version: config.version,
+      $current_url: window.location.href,
+      $pathname: window.location.pathname,
+    },
+  });
+
+  const url = config.host.replace(/\/+$/, "") + "/capture/";
+
+  fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: payload,
+    signal: AbortSignal.timeout(5000),
+  }).catch(() => {});
+}

package/.next/standalone/lib/concurrency.ts

@@ -0,0 +1,26 @@
+/**
+ * Run an array of async task factories with bounded concurrency.
+ * Returns a PromiseSettledResult for each task, preserving input order.
+ */
+export async function batchAll<T>(
+  tasks: (() => Promise<T>)[],
+  concurrency: number,
+): Promise<PromiseSettledResult<T>[]> {
+  const results: PromiseSettledResult<T>[] = new Array(tasks.length);
+  let next = 0;
+
+  async function worker() {
+    while (next < tasks.length) {
+      const idx = next++;
+      try {
+        results[idx] = { status: "fulfilled", value: await tasks[idx]() };
+      } catch (reason) {
+        results[idx] = { status: "rejected", reason };
+      }
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}