failproofai 0.0.1-beta.1

package/.next/standalone/docs/configuration.md

@@ -0,0 +1,172 @@
+# Configuration
+
+failproofai uses JSON configuration files to control which policies are active, how they behave, and where custom hooks are loaded from.
+
+---
+
+## Configuration scopes
+
+There are three configuration scopes, evaluated in priority order:
+
+| Scope | File path | Purpose |
+|-------|-----------|---------|
+| **project** | `.failproofai/hooks-config.json` | Per-repo settings, committed to version control |
+| **local** | `.failproofai/hooks-config.local.json` | Personal per-repo overrides, gitignored |
+| **global** | `~/.failproofai/hooks-config.json` | User-level defaults across all projects |
+
+When failproofai receives a hook event, it loads and merges all three files that exist for the current working directory.
+
+### Merge rules
+
+**`enabledPolicies`** — the union of all three scopes. A policy enabled at any level is active.
+
+```
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplicated union
+```
+
+**`policyParams`** — first scope that defines params for a given policy wins entirely. There is no deep merging of values within a policy's params.
+
+```
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project wins, global ignored
+```
+
+```
+project:  (no block-sudo entry)
+local:    (no block-sudo entry)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← falls through to global
+```
+
+**`customHooksPath`** — first scope that defines it wins.
+
+**`llm`** — first scope that defines it wins.
+
+---
+
+## Config file format
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customHooksPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## Field reference
+
+### `enabledPolicies`
+
+Type: `string[]`
+
+List of policy names to enable. Names must match exactly the policy identifiers shown in `failproofai --list-policies`. See [Built-in Policies](./built-in-policies.md) for the full list.
+
+Policies not in `enabledPolicies` are inactive, even if they have entries in `policyParams`.
+
+### `policyParams`
+
+Type: `Record<string, Record<string, unknown>>`
+
+Per-policy parameter overrides. The outer key is the policy name; the inner keys are policy-specific. Each policy documents its available parameters in [Built-in Policies](./built-in-policies.md).
+
+If a policy has parameters but you don't specify them, the policy's built-in defaults are used. Users who do not configure `policyParams` at all get identical behavior to previous versions.
+
+Unknown keys inside a policy's params block are silently ignored at hook-fire time but flagged as warnings when you run `failproofai --list-policies`.
+
+### `customHooksPath`
+
+Type: `string` (absolute path)
+
+Path to a JavaScript file containing custom hook policies. This is set automatically by `failproofai --install-policies --custom-hooks <path>` (the path is resolved to absolute before being stored).
+
+The file is loaded fresh on every hook event — there is no caching. See [Custom Hooks](./custom-hooks.md) for authoring details.
+
+### `llm`
+
+Type: `object` (optional)
+
+LLM client configuration for policies that make AI calls. Not required for most setups.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## Managing configuration from the CLI
+
+The `--install-policies` and `--remove-policies` commands write to Claude Code's `settings.json` (the hook entry points), while `hooks-config.json` is the file you manage directly. The two are separate:
+
+- **`settings.json`** — tells Claude Code to call `failproofai --hook <event>` on each tool use
+- **`hooks-config.json`** — tells failproofai which policies to evaluate and with what params
+
+You can edit `hooks-config.json` directly at any time; changes take effect immediately on the next hook event with no restart needed.
+
+---
+
+## Example: project-level config with team defaults
+
+Commit `.failproofai/hooks-config.json` to your repo:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+Each developer can then create `.failproofai/hooks-config.local.json` (gitignored) for personal overrides without affecting teammates.

package/.next/standalone/docs/custom-hooks.md

@@ -0,0 +1,257 @@
+# Custom Hooks
+
+Custom hooks let you write your own policies in JavaScript. They integrate with the same hook event system as built-in policies and support the same `allow`, `deny`, and `instruct` decisions.
+
+---
+
+## Quick example
+
+```js
+// my-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 (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Install it:
+
+```bash
+failproofai --install-policies --custom-hooks ./my-policies.js
+```
+
+---
+
+## Installing and updating
+
+```bash
+# Install with a custom hooks file
+failproofai --install-policies --custom-hooks ./my-policies.js
+
+# Replace the hooks file path
+failproofai --install-policies --custom-hooks ./new-policies.js
+
+# Remove the custom hooks path from config
+failproofai --remove-policies --remove-custom-hooks
+```
+
+The resolved absolute path is stored in `hooks-config.json` as `customHooksPath`. The file is loaded fresh on every hook event — there is no caching between events.
+
+---
+
+## API
+
+### Import
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+Registers a hook. Call this as many times as needed for multiple hooks in the same file.
+
+```ts
+customPolicies.add({
+  name: string;                         // required — unique identifier
+  description?: string;                 // shown in --list-policies output
+  match?: { events?: HookEventType[] }; // filter by event type; omit to match all
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Decision helpers
+
+| Function | Effect | Use when |
+|----------|--------|----------|
+| `allow()` | Permit the tool call | Nothing to block or warn about |
+| `deny(message)` | Block the tool call | The action should not proceed |
+| `instruct(message)` | Add context to Claude's prompt | You want Claude to be careful but not stopped |
+
+`deny(message)` — the message appears to Claude prefixed with `"Blocked by failproofai:"`.
+
+`instruct(message)` — the message is appended to Claude's context for the current tool call. Multiple `instruct` returns from different hooks accumulate; a single `deny` short-circuits all further evaluation.
+
+### `PolicyContext` fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | The tool being called (e.g. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | The tool's input parameters |
+| `payload` | `Record<string, unknown>` | Full raw event payload from Claude Code |
+| `session` | `SessionMetadata \| undefined` | Session context (see below) |
+
+### `SessionMetadata` fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code session identifier |
+| `cwd` | `string` | Working directory of the Claude Code session |
+| `transcriptPath` | `string` | Path to the session's JSONL transcript file |
+
+### Event types
+
+| Event | When it fires | `toolInput` contents |
+|-------|--------------|----------------------|
+| `PreToolUse` | Before Claude runs a tool | The tool's input (e.g. `{ command: "..." }` for Bash) |
+| `PostToolUse` | After a tool completes | The tool's input + `tool_result` (the output) |
+| `Notification` | When Claude sends a notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — hooks must always return `allow()`, they cannot block notifications |
+| `Stop` | When the Claude session ends | Empty |
+
+---
+
+## Evaluation order
+
+Hooks are evaluated in this order:
+
+1. Built-in policies (in definition order)
+2. Custom hooks (in `.add()` order)
+
+The first `deny` short-circuits all subsequent hooks. All `instruct` returns accumulate into a single message regardless of which hook produced them.
+
+---
+
+## Transitive imports
+
+Custom hook files can import local modules using relative paths:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+All relative imports reachable from the entry file are resolved. This is implemented by rewriting `from "failproofai"` imports to the actual dist path and creating temporary `.mjs` files to ensure ESM compatibility.
+
+---
+
+## Hook event type filtering
+
+Use `match.events` to limit when a hook fires:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Only fires when the session ends
+    // ctx.session.transcriptPath contains the full session log
+    return allow();
+  },
+});
+```
+
+Omit `match` entirely to fire on every event type.
+
+---
+
+## Error handling and failure modes
+
+Custom hooks are **fail-open**: errors never block built-in policies or crash the hook handler.
+
+| Failure | Behavior |
+|---------|----------|
+| `customHooksPath` not set | No custom hooks run; built-ins continue normally |
+| File not found | Warning logged to `~/.failproofai/hook.log`; built-ins continue |
+| Syntax/import error | Error logged to `~/.failproofai/hook.log`; all custom hooks skipped |
+| `fn` throws at runtime | Error logged; that hook treated as `allow`; other hooks continue |
+| `fn` takes longer than 10s | Timeout logged; treated as `allow` |
+
+To debug custom hook errors:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+
+---
+
+## Full example: multiple hooks
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Block any write to a path containing "secrets/"
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Block writes to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Remind Claude to check test results before committing
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Remind Claude to verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Block npm install during a freeze period
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Block new package installs during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Examples in the repository
+
+The `examples/` directory contains ready-to-run hook files:
+
+| File | Contents |
+|------|----------|
+| `examples/policies-basic.js` | Five starter policies covering common use cases |
+| `examples/policies-advanced/index.js` | Advanced patterns including transitive imports, async calls, and `Stop` event hooks |
+
+Install the basic examples:
+
+```bash
+failproofai --install-policies --custom-hooks ./examples/policies-basic.js
+```

package/.next/standalone/docs/dashboard.md

@@ -0,0 +1,111 @@
+# Dashboard
+
+The failproofai dashboard is a local web application for browsing Claude Code sessions and managing security policies.
+
+---
+
+## Starting the dashboard
+
+```bash
+failproofai
+```
+
+Opens at `http://localhost:8020`.
+
+For production mode (faster startup, no file watching):
+
+```bash
+failproofai --start
+```
+
+The dashboard reads directly from the filesystem — your Claude Code project folders and the failproofai config files. Nothing is written to a remote service.
+
+---
+
+## Pages
+
+### Projects
+
+Lists all Claude Code projects found on your machine. Projects are discovered from `~/.claude/projects/` (or the path set by `CLAUDE_PROJECTS_PATH`).
+
+Each project shows:
+- Project name (derived from the folder path)
+- Number of sessions
+- Date of most recent session activity
+
+Click a project to see its sessions.
+
+### Sessions
+
+Lists all sessions within a project. Each session shows:
+- Session ID
+- Start and end timestamps
+- Number of tool calls
+- Hook activity count (policies that fired)
+
+Use the date range filter and session ID search to narrow the list. Sessions are paginated.
+
+Click a session to open the session viewer.
+
+### Session viewer
+
+A timeline of everything that happened in a session:
+
+- **Messages** — Claude's text responses and user prompts
+- **Tool calls** — Every tool Claude invoked, with its input and output
+- **Hook activity** — For each tool call, which policies fired and what decision they returned
+
+The stats bar at the top shows session duration, total tool calls, and a summary of hook decisions (allow / deny / instruct counts).
+
+You can export the session as a ZIP or JSONL file using the download button.
+
+### Policies
+
+A two-tab page for managing policies and reviewing activity.
+
+**Policies tab:**
+
+- Toggle individual policies on or off with a single click (writes to `~/.failproofai/hooks-config.json`)
+- Expand a policy to configure its parameters (for policies that support `policyParams`)
+- Install or remove hooks for a given scope
+- Set a custom hooks file path
+
+**Activity tab:**
+
+- Full paginated history of every hook event that has fired across all sessions
+- Search by policy name, session ID, tool name, or decision
+- Each row shows: timestamp, policy name, decision, tool name, session ID, and the reason for deny/instruct decisions
+
+---
+
+## Auto-refresh
+
+The dashboard has an auto-refresh toggle in the top navigation. When enabled, the current page refreshes periodically to show new sessions and hook activity as they appear. Useful when you have an active Claude Code session running in parallel.
+
+---
+
+## Disabling pages
+
+If you only need some parts of the dashboard, set `FAILPROOFAI_DISABLE_PAGES` to a comma-separated list of page names:
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+Valid values: `policies`, `projects`.
+
+---
+
+## Theme
+
+The dashboard supports light and dark mode. Toggle via the button in the navigation bar. The preference is stored in your browser's local storage.
+
+---
+
+## Configuring the projects path
+
+By default, the dashboard reads from the standard Claude Code projects directory. Override it for custom setups:
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```

package/.next/standalone/docs/getting-started.md

@@ -0,0 +1,122 @@
+# Getting Started
+
+## Requirements
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (used as the runtime and bundler)
+
+---
+
+## Installation
+
+```bash
+npm install -g failproofai
+```
+
+---
+
+## Quick Start
+
+### 1. Launch the dashboard
+
+```bash
+failproofai
+```
+
+Opens a local web dashboard at `http://localhost:8020`. The dashboard lets you browse your Claude Code projects and sessions, inspect session logs and tool calls, and manage policies.
+
+### 2. Install policies
+
+Policies are the security rules that Claude Code enforces when it runs tools. Installing them writes hook entries into Claude Code's `settings.json`.
+
+**Install globally** (applies to all Claude Code sessions):
+
+```bash
+failproofai --install-policies
+```
+
+**Install for the current project only:**
+
+```bash
+failproofai --install-policies --scope project
+```
+
+**Install specific policies by name:**
+
+```bash
+failproofai --install-policies block-sudo block-rm-rf sanitize-api-keys
+```
+
+See [Built-in Policies](./built-in-policies.md) for the full list.
+
+### 3. Verify installation
+
+```bash
+failproofai --list-policies
+```
+
+This shows every policy, whether it is enabled, and any configured parameters.
+
+### 4. Try it out
+
+Once policies are installed, run Claude Code as normal. When Claude attempts a blocked action (e.g. `sudo`, `rm -rf`, or outputting an API key), failproofai intercepts and blocks it automatically.
+
+---
+
+## How policies work
+
+When Claude Code is about to run a tool (a `PreToolUse` event), or has just run one (a `PostToolUse` event), it invokes failproofai as a subprocess:
+
+```
+Claude Code  →  failproofai --hook PreToolUse  →  stdin: JSON payload
+                                                  stdout: decision JSON
+                                                  exit code: 0 (allow/instruct) or 2 (deny on Stop)
+```
+
+failproofai reads the tool name and input, evaluates all enabled policies, and returns a decision:
+
+- **allow** — Claude proceeds normally (empty stdout)
+- **deny** — Claude is told the action is blocked and why
+- **instruct** — Claude gets extra context/instructions added to its prompt
+
+Policies run entirely in your local process. Nothing is sent to a remote service.
+
+---
+
+## Data storage
+
+failproofai stores all configuration and logs locally:
+
+| Path | Contents |
+|------|----------|
+| `~/.failproofai/hooks-config.json` | Global policy configuration |
+| `~/.failproofai/hook-activity.jsonl` | Hook execution history (one JSON line per event) |
+| `~/.failproofai/hook.log` | Debug log for custom hook errors |
+| `.failproofai/hooks-config.json` | Per-project policy configuration (committed) |
+| `.failproofai/hooks-config.local.json` | Per-project personal overrides (gitignored) |
+
+---
+
+## Uninstalling
+
+```bash
+failproofai --remove-policies
+```
+
+Removes the hook entries from `~/.claude/settings.json`. The failproofai configuration files in `~/.failproofai/` are left in place.
+
+To remove for a specific scope:
+
+```bash
+failproofai --remove-policies --scope project
+```
+
+---
+
+## Next steps
+
+- [Configuration](./configuration.md) — understand scopes and the config file format
+- [Built-in Policies](./built-in-policies.md) — full list of policies and their parameters
+- [Custom Hooks](./custom-hooks.md) — write your own policies in JavaScript
+- [Dashboard](./dashboard.md) — using the session viewer and policy manager
+- [CLI Reference](./cli-reference.md) — all flags and commands

package/.next/standalone/docs/index.md

@@ -0,0 +1,47 @@
+# Failproof AI — Documentation
+
+Open-source hooks, policies, and session visualization for **Claude Code** and the **Agents SDK**. Runs entirely locally — no data leaves your machine.
+
+---
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./getting-started.md) | Install failproofai, enable policies, and take it for a spin |
+| [CLI Reference](./cli-reference.md) | All commands, flags, and environment variables |
+| [Configuration](./configuration.md) | Config file format, three-scope system, and merge rules |
+| [Built-in Policies](./built-in-policies.md) | All 35+ policies with descriptions and parameters |
+| [Custom Hooks](./custom-hooks.md) | Write your own policies in JavaScript |
+| [Dashboard](./dashboard.md) | Session viewer, policy management, and activity log |
+| [Architecture](./architecture.md) | How the hook handler, config loading, and policy evaluation work |
+| [Testing](./testing.md) | Unit tests, E2E tests, and test helpers |
+
+---
+
+## Quick reference
+
+**Install:**
+```bash
+npm install -g failproofai
+```
+
+**Enable policies globally:**
+```bash
+failproofai --install-policies
+```
+
+**Launch dashboard:**
+```bash
+failproofai
+```
+
+**List active policies:**
+```bash
+failproofai --list-policies
+```
+
+**Add a custom policy file:**
+```bash
+failproofai --install-policies --custom-hooks ./my-policies.js
+```