failproofai 0.0.1-beta.1

package/.next/standalone/README.md

@@ -0,0 +1,247 @@
+```
+    ______      _ __                       ____   ___    ____
+   / ____/___ _(_) /___  _________  ____  / __/  /   |  /  _/
+  / /_  / __ `/ / / __ \/ ___/ __ \/ __ \/ /_   / /| |  / /
+ / __/ / /_/ / / / /_/ / /  / /_/ / /_/ / __/  / ___ |_/ /
+/_/    \__,_/_/_/ .___/_/   \____/\____/_/    /_/  |_/___/
+               /_/
+```
+
+# Failproof AI
+
+Open-source hooks, policies, and project visualization for **Claude Code** & the **Agents SDK**.
+
+- **Hooks & Policies** — 35+ built-in security policies that run as Claude Code hooks. Block dangerous commands, sanitize secrets, restrict file access, and more.
+- **Custom Policies** — Write your own policies in JavaScript. Same `allow`/`deny`/`instruct` API as built-in policies, with full async support.
+- **Policy Parameters** — Tune built-in policies without writing code: configure allowlists, protected branches, thresholds, and custom patterns.
+- **Session Viewer** — Browse Claude Code projects and sessions locally. Inspect tool calls, messages, and per-session hook activity side-by-side.
+
+Everything runs locally — no data leaves your machine.
+
+---
+
+## Requirements
+
+- Node.js >= 20.9.0
+- Bun >= 1.3.0
+
+---
+
+## Install
+
+```bash
+npm install -g failproofai
+```
+
+---
+
+## Quick start
+
+### 1. Enable policies globally
+
+```bash
+failproofai --install-policies
+```
+
+Writes hook entries into `~/.claude/settings.json`. Claude Code will now invoke failproofai before and after each tool call.
+
+### 2. Launch the dashboard
+
+```bash
+failproofai
+```
+
+Opens `http://localhost:8020` — browse sessions, inspect logs, manage policies.
+
+### 3. Check what's active
+
+```bash
+failproofai --list-policies
+```
+
+---
+
+## Policy installation
+
+### Scopes
+
+| Scope | Command | Where it writes |
+|-------|---------|-----------------|
+| Global (default) | `failproofai --install-policies` | `~/.claude/settings.json` |
+| Project | `failproofai --install-policies --scope project` | `.claude/settings.json` |
+| Local | `failproofai --install-policies --scope local` | `.claude/settings.local.json` |
+
+### Install specific policies
+
+```bash
+failproofai --install-policies block-sudo block-rm-rf sanitize-api-keys
+```
+
+### Remove policies
+
+```bash
+failproofai --remove-policies
+# or for a specific scope:
+failproofai --remove-policies --scope project
+```
+
+---
+
+## Configuration
+
+Policy configuration lives in `~/.failproofai/hooks-config.json` (global) or `.failproofai/hooks-config.json` in your project (per-project).
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "sanitize-api-keys",
+    "block-push-master",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  }
+}
+```
+
+**Three config scopes** are merged automatically (project → local → global). See [docs/configuration.md](docs/configuration.md) for full merge rules.
+
+---
+
+## Built-in policies
+
+| Policy | Description | Configurable |
+|--------|-------------|:---:|
+| `block-sudo` | Block sudo commands | `allowPatterns` |
+| `block-rm-rf` | Block recursive deletions | `allowPaths` |
+| `block-curl-pipe-sh` | Block curl\|bash and wget\|bash | |
+| `block-failproofai-commands` | Prevent self-uninstallation | |
+| `sanitize-jwt` | Redact JWT tokens from tool output | |
+| `sanitize-api-keys` | Redact API keys from tool output | `additionalPatterns` |
+| `sanitize-connection-strings` | Redact database credentials from tool output | |
+| `sanitize-private-key-content` | Redact PEM private key blocks | |
+| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens | |
+| `block-env-files` | Block access to .env files | |
+| `protect-env-vars` | Block commands that print environment variables | |
+| `block-read-outside-cwd` | Block reading files outside the project | `allowPaths` |
+| `block-secrets-write` | Block writes to private key and certificate files | `additionalPatterns` |
+| `block-push-master` | Block pushing to main/master | `protectedBranches` |
+| `block-work-on-main` | Block checking out main/master | `protectedBranches` |
+| `block-force-push` | Block `git push --force` | |
+| `warn-git-amend` | Warn on `git commit --amend` | |
+| `warn-git-stash-drop` | Warn on `git stash drop` | |
+| `warn-all-files-staged` | Warn on `git add -A` | |
+| `warn-destructive-sql` | Warn on DROP/DELETE SQL statements | |
+| `warn-schema-alteration` | Warn on ALTER TABLE statements | |
+| `warn-large-file-write` | Warn on large file writes | `thresholdKb` |
+| `warn-package-publish` | Warn on `npm publish` | |
+| `warn-background-process` | Warn on background process launches | |
+| `warn-global-package-install` | Warn on global package installs | |
+| …and more | | |
+
+Full policy details and parameter reference: [docs/built-in-policies.md](docs/built-in-policies.md)
+
+---
+
+## Custom policies
+
+Create a `.js` file with your own policies:
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) return deny("Writes to production paths are blocked");
+    return allow();
+  },
+});
+```
+
+Install with:
+
+```bash
+failproofai --install-policies --custom-hooks ./my-policies.js
+```
+
+### Decision helpers
+
+| Function | Effect |
+|----------|--------|
+| `allow()` | Permit the tool call |
+| `deny(message)` | Block the tool call; message shown to Claude |
+| `instruct(message)` | Add context to Claude's prompt; does not block |
+
+### Context object (`ctx`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string` | Tool being called (`"Bash"`, `"Write"`, `"Read"`, …) |
+| `toolInput` | `object` | Tool's input parameters |
+| `payload` | `object` | Full raw event payload |
+| `session.cwd` | `string` | Working directory of the Claude Code session |
+| `session.sessionId` | `string` | Session identifier |
+| `session.transcriptPath` | `string` | Path to the session transcript file |
+
+Custom hooks support transitive local imports, async/await, and access to `process.env`. Errors in custom hooks are fail-open (logged to `~/.failproofai/hook.log`, built-in policies continue). See [docs/custom-hooks.md](docs/custom-hooks.md) for the full guide.
+
+---
+
+## Telemetry
+
+Failproof AI collects anonymous usage telemetry via PostHog to understand feature usage. No session content, file names, tool inputs, or personal information is ever sent.
+
+Disable it:
+
+```bash
+FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai
+```
+
+---
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](docs/getting-started.md) | Installation and first steps |
+| [CLI Reference](docs/cli-reference.md) | All commands and flags |
+| [Configuration](docs/configuration.md) | Config file format and scope merging |
+| [Built-in Policies](docs/built-in-policies.md) | All 35+ policies with parameters |
+| [Custom Hooks](docs/custom-hooks.md) | Write your own policies |
+| [Dashboard](docs/dashboard.md) | Session viewer and policy management |
+| [Architecture](docs/architecture.md) | How the hook system works |
+| [Testing](docs/testing.md) | Running tests and writing new ones |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+See [LICENSE](LICENSE).

package/.next/standalone/app/actions/get-hook-activity.ts

@@ -0,0 +1,27 @@
+"use server";
+
+import {
+  getHookActivityHistory,
+  searchHookActivity,
+  type HookActivityEntry,
+  type HookActivityFilters,
+  type HookActivityStats,
+} from "@/src/hooks/hook-activity-store";
+
+export interface HookActivityPayload {
+  entries: HookActivityEntry[];
+  totalPages: number;
+  page: number;
+  stats: HookActivityStats;
+}
+
+export async function getHookActivityAction(page: number): Promise<HookActivityPayload> {
+  return getHookActivityHistory(page);
+}
+
+export async function searchHookActivityAction(
+  filters: HookActivityFilters,
+  page: number,
+): Promise<HookActivityPayload> {
+  return searchHookActivity(filters, page);
+}

package/.next/standalone/app/actions/get-hooks-config.ts

@@ -0,0 +1,105 @@
+"use server";
+
+import { readHooksConfig } from "@/src/hooks/hooks-config";
+import { hooksInstalledInSettings, getSettingsPath } from "@/src/hooks/manager";
+import { BUILTIN_POLICIES } from "@/src/hooks/builtin-policies";
+import { HOOK_SCOPES } from "@/src/hooks/types";
+import type { HookScope } from "@/src/hooks/types";
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+
+export interface PolicyParamSpec {
+  type: string;
+  description: string;
+  default: unknown;
+}
+
+export interface PolicyInfo {
+  name: string;
+  description: string;
+  category: string;
+  defaultEnabled: boolean;
+  beta: boolean;
+  enabled: boolean;
+  eventScope: string;
+  params?: Record<string, PolicyParamSpec>;
+  currentParams?: Record<string, unknown>;
+}
+
+export interface CustomPolicyInfo {
+  name: string;
+  description?: string;
+  eventScope?: string;
+}
+
+export interface HooksConfigPayload {
+  enabledPolicies: string[];
+  installedScopes: HookScope[];
+  settingsPath: string;
+  policies: PolicyInfo[];
+  customHooksPath?: string;
+  customPolicies?: CustomPolicyInfo[];
+}
+
+async function parseCustomPoliciesFromFile(filePath: string): Promise<CustomPolicyInfo[]> {
+  if (!existsSync(filePath)) return [];
+  const source = await readFile(filePath, "utf-8");
+  const policies: CustomPolicyInfo[] = [];
+  const segments = source.split(/customPolicies\.add\s*\(/);
+  for (let i = 1; i < segments.length; i++) {
+    const seg = segments[i];
+    const nameMatch = seg.match(/name:\s*["'`]([^"'`]+)["'`]/);
+    if (!nameMatch) continue;
+    const descMatch = seg.match(/description:\s*["'`]([^"'`]+)["'`]/);
+    const eventsMatch = seg.match(/events:\s*\[([^\]]+)\]/);
+    const eventScope = eventsMatch
+      ? eventsMatch[1].replace(/["'`\s]/g, "").split(",").filter(Boolean).join(", ")
+      : undefined;
+    policies.push({ name: nameMatch[1], description: descMatch?.[1], eventScope });
+  }
+  return policies;
+}
+
+function buildEventScope(match: { events?: string[]; toolNames?: string[] }): string {
+  const events = match.events?.join(", ") ?? "";
+  const tools = match.toolNames ? ` · ${match.toolNames.join(", ")}` : "";
+  return `${events}${tools}`;
+}
+
+export async function getHooksConfigAction(): Promise<HooksConfigPayload> {
+  const config = readHooksConfig();
+  const enabledSet = new Set(config.enabledPolicies);
+
+  const installedScopes = HOOK_SCOPES.filter((s) => hooksInstalledInSettings(s));
+  const primaryScope: HookScope = installedScopes[0] ?? "user";
+  const settingsPath = getSettingsPath(primaryScope);
+
+  const policies: PolicyInfo[] = BUILTIN_POLICIES.map((p) => ({
+    name: p.name,
+    description: p.description,
+    category: p.category,
+    defaultEnabled: p.defaultEnabled,
+    beta: !!p.beta,
+    enabled: enabledSet.has(p.name),
+    eventScope: buildEventScope(p.match),
+    params: p.params
+      ? Object.fromEntries(
+          Object.entries(p.params).map(([k, v]) => [k, { type: v.type, description: v.description, default: v.default }])
+        )
+      : undefined,
+    currentParams: p.params ? (config.policyParams?.[p.name] ?? {}) : undefined,
+  }));
+
+  const customPolicies = config.customHooksPath
+    ? await parseCustomPoliciesFromFile(config.customHooksPath)
+    : undefined;
+
+  return {
+    enabledPolicies: config.enabledPolicies,
+    installedScopes,
+    settingsPath,
+    policies,
+    customHooksPath: config.customHooksPath,
+    customPolicies: customPolicies?.length ? customPolicies : undefined,
+  };
+}

package/.next/standalone/app/actions/get-telemetry-config.ts

@@ -0,0 +1,27 @@
+"use server";
+
+import { getInstanceId } from "@/lib/telemetry-id";
+import { isTelemetryEnabled } from "@/lib/telemetry";
+import { version } from "../../package.json";
+
+const DEFAULT_API_KEY = "phc_Ac1Ww1GqKc0z1SyrRWbmatEeQdlOQIsDEEdP8l8JRgX";
+const DEFAULT_HOST = "https://us.i.posthog.com";
+
+export interface TelemetryConfig {
+  enabled: boolean;
+  distinctId: string;
+  apiKey: string;
+  host: string;
+  version: string;
+}
+
+export async function getTelemetryConfig(): Promise<TelemetryConfig> {
+  const enabled = isTelemetryEnabled();
+  return {
+    enabled,
+    distinctId: enabled ? getInstanceId() : "",
+    apiKey: process.env.FAILPROOFAI_POSTHOG_KEY ?? DEFAULT_API_KEY,
+    host: process.env.FAILPROOFAI_POSTHOG_HOST ?? DEFAULT_HOST,
+    version,
+  };
+}

package/.next/standalone/app/actions/install-hooks-web.ts

@@ -0,0 +1,21 @@
+"use server";
+
+import { installHooks, removeHooks } from "@/src/hooks/manager";
+import { readHooksConfig } from "@/src/hooks/hooks-config";
+import { BUILTIN_POLICIES } from "@/src/hooks/builtin-policies";
+import type { HookScope } from "@/src/hooks/types";
+
+export async function installHooksWebAction(scope: HookScope = "user"): Promise<void> {
+  const config = readHooksConfig();
+  // On first install (no config yet), default to all defaultEnabled non-beta policies.
+  // Always pass an explicit array so installHooks never triggers the interactive TUI.
+  const policies =
+    config.enabledPolicies.length > 0
+      ? config.enabledPolicies
+      : BUILTIN_POLICIES.filter((p) => p.defaultEnabled && !p.beta).map((p) => p.name);
+  await installHooks(policies, scope, undefined, false, "web");
+}
+
+export async function removeHooksWebAction(scope: HookScope | "all" = "user"): Promise<void> {
+  await removeHooks(undefined, scope, undefined, { source: "web" });
+}

package/.next/standalone/app/actions/update-hooks-config.ts

@@ -0,0 +1,29 @@
+"use server";
+
+import { readHooksConfig, writeHooksConfig } from "@/src/hooks/hooks-config";
+import { trackHookEvent } from "@/src/hooks/hook-telemetry";
+import { getInstanceId } from "@/lib/telemetry-id";
+
+export async function togglePolicyAction(name: string, enabled: boolean): Promise<void> {
+  const config = readHooksConfig();
+  const set = new Set(config.enabledPolicies);
+  if (enabled) {
+    set.add(name);
+  } else {
+    set.delete(name);
+  }
+  writeHooksConfig({ ...config, enabledPolicies: [...set] });
+
+  // Telemetry: track policy toggle from the web UI (best-effort)
+  try {
+    const distinctId = getInstanceId();
+    await trackHookEvent(distinctId, "policy_toggled", {
+      policy_name: name,
+      enabled,                                // new state: true = on, false = off
+      action: enabled ? "enable" : "disable", // human-readable direction
+      source: "web",
+    });
+  } catch {
+    // Never block the operation
+  }
+}

package/.next/standalone/app/actions/update-policy-params.ts

@@ -0,0 +1,26 @@
+"use server";
+
+import { readHooksConfig, writeHooksConfig } from "@/src/hooks/hooks-config";
+import { trackHookEvent } from "@/src/hooks/hook-telemetry";
+import { getInstanceId } from "@/lib/telemetry-id";
+
+export async function updatePolicyParamsAction(
+  policyName: string,
+  params: Record<string, unknown>,
+): Promise<void> {
+  const config = readHooksConfig();
+  const policyParams = { ...(config.policyParams ?? {}), [policyName]: params };
+  writeHooksConfig({ ...config, policyParams });
+
+  // Telemetry: track policy parameter configuration from the web UI (best-effort)
+  try {
+    const distinctId = getInstanceId();
+    await trackHookEvent(distinctId, "policy_params_updated", {
+      policy_name: policyName,
+      param_keys: Object.keys(params),
+      source: "web",
+    });
+  } catch {
+    // Never block the operation
+  }
+}

package/.next/standalone/app/api/download/[project]/[session]/route.ts

@@ -0,0 +1,47 @@
+import { NextRequest, NextResponse } from "next/server";
+import { createReadStream } from "fs";
+import { stat } from "fs/promises";
+import { Readable } from "stream";
+import { logActivity } from "@/lib/logger";
+import { resolveSessionFilePath } from "@/lib/projects";
+
+function jsonError(message: string, status: number): NextResponse {
+  return NextResponse.json({ error: message }, { status });
+}
+
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ project: string; session: string }> }
+): Promise<NextResponse> {
+  const { project, session } = await params;
+
+  let filePath: string;
+  try {
+    // resolveSessionFilePath validates UUID format, rejects absolute/escaping paths
+    filePath = resolveSessionFilePath(project, session);
+  } catch {
+    return jsonError("Invalid project or session", 400);
+  }
+
+  logActivity("anonymous", "download-log", `project=${project} session=${session}`);
+
+  try {
+    // Eagerly check file existence — createReadStream errors are async and would
+    // escape the try/catch after response headers are already sent.
+    await stat(filePath);
+    const nodeStream = createReadStream(filePath);
+    const webStream = Readable.toWeb(nodeStream) as ReadableStream;
+    return new NextResponse(webStream, {
+      headers: {
+        "Content-Type": "application/x-ndjson",
+        "Content-Disposition": `attachment; filename="${session}.jsonl"`,
+      },
+    });
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || e instanceof RangeError) {
+      return jsonError("Session log not found", 404);
+    }
+    return jsonError("Failed to read session log", 500);
+  }
+}

package/.next/standalone/app/components/copy-button.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import { useState, useCallback } from "react";
+import { Copy, Check } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+function fallbackCopyText(text: string): boolean {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.style.position = "fixed";
+  textarea.style.opacity = "0";
+  document.body.appendChild(textarea);
+  try {
+    textarea.select();
+    return document.execCommand("copy");
+  } finally {
+    document.body.removeChild(textarea);
+  }
+}
+
+interface CopyButtonProps {
+  text: string;
+  className?: string;
+}
+
+export function CopyButton({ text, className }: CopyButtonProps) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = useCallback(async () => {
+    try {
+      if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(text);
+      } else if (!fallbackCopyText(text)) {
+        throw new Error("Both clipboard methods failed");
+      }
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch (err) {
+      console.error("Failed to copy to clipboard:", err);
+      // Try fallback if the modern API threw
+      try {
+        if (fallbackCopyText(text)) {
+          setCopied(true);
+          setTimeout(() => setCopied(false), 2000);
+        }
+      } catch {
+        // Both methods failed — do nothing
+      }
+    }
+  }, [text]);
+
+  return (
+    <button
+      onClick={handleCopy}
+      title="Copy to clipboard"
+      className={cn(
+        "inline-flex items-center justify-center rounded p-1 text-muted-foreground hover:text-foreground hover:bg-muted/80 transition-colors",
+        className
+      )}
+    >
+      {copied ? (
+        <Check className="w-3.5 h-3.5 text-green-500" />
+      ) : (
+        <Copy className="w-3.5 h-3.5" />
+      )}
+    </button>
+  );
+}

package/.next/standalone/app/components/date-picker-input.tsx

@@ -0,0 +1,57 @@
+/**
+ * Shared date picker input with a Calendar icon overlay.
+ *
+ * Used in both the project list and session list custom date range
+ * filters.  The Calendar icon acts as a clickable trigger that opens
+ * the browser's native date picker via `showPicker()`.
+ */
+"use client";
+
+import { Calendar } from "lucide-react";
+
+interface DatePickerInputProps {
+  id: string;
+  /** Date object — converted to YYYY-MM-DD via toISOString (UTC). */
+  value: Date | null;
+  /** Optional string value (YYYY-MM-DD) — avoids UTC conversion issues. Takes precedence over `value`. */
+  stringValue?: string | null;
+  onChange: (value: string) => void;
+  "aria-label"?: string;
+}
+
+export default function DatePickerInput({
+  id,
+  value,
+  stringValue,
+  onChange,
+  "aria-label": ariaLabel,
+}: DatePickerInputProps) {
+  const inputValue = stringValue != null ? stringValue : (value ? value.toISOString().split("T")[0] : "");
+  return (
+    <div className="relative group">
+      <input
+        type="date"
+        id={id}
+        value={inputValue}
+        onChange={(e) => onChange(e.target.value)}
+        aria-label={ariaLabel}
+        className="date-input px-3 py-2 pr-8 text-sm bg-input border border-border rounded-md text-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent transition-all hover:border-primary/50 w-[200px]"
+      />
+      <label
+        htmlFor={id}
+        className="absolute right-2.5 top-1/2 -translate-y-1/2 cursor-pointer pointer-events-auto z-10 p-1 rounded hover:bg-muted/50 transition-colors"
+        onClick={(e) => {
+          e.preventDefault();
+          const input = document.getElementById(id) as HTMLInputElement;
+          if (input && typeof input.showPicker === "function") {
+            input.showPicker();
+          } else {
+            input?.click();
+          }
+        }}
+      >
+        <Calendar className="w-4 h-4 text-primary group-hover:text-primary/80 transition-colors" />
+      </label>
+    </div>
+  );
+}