failproofai 0.0.2 → 0.0.4-beta.0

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

@@ -1,261 +0,0 @@
----
-title: Custom Hooks
-description: "Write your own policies in JavaScript with allow, deny, and instruct decisions"
-icon: code
----
-
-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 ./my-policies.js
-```
-
----
-
-## Installing and updating
-
-```bash
-# Install with a custom hooks file
-failproofai --install-policies --custom ./my-policies.js
-
-# Replace the hooks file path
-failproofai --install-policies --custom ./new-policies.js
-
-# Remove the custom hooks path from config
-failproofai --remove-policies --custom
-```
-
-The resolved absolute path is stored in `policies-config.json` as `customPoliciesPath`. 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 |
-|---------|----------|
-| `customPoliciesPath` 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 ./examples/policies-basic.js
-```

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

@@ -1,128 +0,0 @@
----
-title: Getting Started
-description: "Install failproofai, enable policies, and take it for a spin"
-icon: rocket
----
-
-## Requirements
-
-- **Node.js** >= 20.9.0
-- **Bun** >= 1.3.0 (optional — only needed for development / building from source)
-
----
-
-## Installation
-
-```bash
-npm install -g failproofai
-# or
-bun add -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/policies-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/policies-config.json` | Per-project policy configuration (committed) |
-| `.failproofai/policies-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/introduction.md

@@ -1,47 +0,0 @@
----
-title: Introduction
-description: "Open-source hooks, policies, and session visualization for Claude Code and the Agents SDK"
----
-
-# Failproof AI
-
-Open-source hooks, policies, and session visualization for **Claude Code** and the **Agents SDK**. Runs entirely locally — no data leaves your machine.
-
-## What is Failproof AI?
-
-Failproof AI is a security and observability toolkit that intercepts Claude Code tool calls in real time. It evaluates configurable policies — blocking dangerous commands, redacting secrets, and adding safety instructions — before Claude can act.
-
-It also includes a local web dashboard for browsing Claude Code sessions, inspecting tool calls, and managing policies visually.
-
-## Key features
-
-| Feature | Description |
-|---------|-------------|
-| [35+ Built-in Policies](./built-in-policies.md) | Block sudo, rm -rf, force-push, secret leaks, and more — out of the box. |
-| [Custom Hooks](./custom-hooks.md) | Write your own policies in JavaScript with a simple allow/deny/instruct API. |
-| [Session Dashboard](./dashboard.md) | Browse projects, inspect sessions, and review every tool call and policy decision. |
-| [Three-Scope Config](./configuration.md) | Global, project, and local configuration with automatic merging. |
-
-## Quick start
-
-Install globally:
-
-```bash
-npm install -g failproofai
-# or
-bun add -g failproofai
-```
-
-Enable policies:
-
-```bash
-failproofai --install-policies
-```
-
-Launch the dashboard:
-
-```bash
-failproofai
-```
-
-See the [Getting Started](./getting-started.md) guide for a full walkthrough.