npm - failproofai - Versions diffs - 0.0.6-beta.2 → 0.0.6-beta.4 - Mend

failproofai 0.0.6-beta.2 → 0.0.6-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (511) hide show

package/.next/standalone/docs/built-in-policies.mdx DELETED Viewed

@@ -1,574 +0,0 @@
----
-title: Built-in Policies
-description: "All 30 built-in policies that catch common agent failure modes"
-icon: shield
----
-failproofai ships with 30 built-in policies that catch common agent failure modes. Each policy fires on a specific hook event type and tool name. Nine policies accept parameters that let you tune their behavior without writing code. Four workflow policies enforce a commit → push → PR → CI pipeline before Claude stops.
----
-## Overview
-Policies are grouped into categories:
-| Category | Policies | Hook type |
-|----------|----------|-----------|
-| [Dangerous commands](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse |
-| [Secrets (sanitizers)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
-| [Environment](#environment) | block-env-files, protect-env-vars | PreToolUse |
-| [File access](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse |
-| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
-| [Database](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
-| [Warnings](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
-| [Package managers](#package-managers) | prefer-package-manager | PreToolUse |
-| [Workflow](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stop | Stop |
-- **`block-`** — stop the agent from proceeding.
-- **`warn-`** — give the agent additional context so it can self-correct.
-- **`sanitize-`** — scrub sensitive data from tool output before the agent sees it.
-- **`require-`** — block the Stop event until conditions are met.
----
-<Tip>
-Every policy supports an optional `hint` field in `policyParams`. The hint is appended to the deny or instruct message Claude sees, giving actionable guidance without modifying policy code. Works with built-in, custom, and convention policies. See [Configuration → hint](/configuration#hint-cross-cutting) for details.
-</Tip>
----
-## Dangerous commands
-Prevent agents from running operations that are hard to undo or that could damage the host system.
-### `block-sudo`
-**Event:** PreToolUse (Bash)
-**Default:** Denies any `sudo` command.
-Blocks invocations that include the `sudo` keyword. Pattern matching is done on parsed command tokens, not the raw string, to prevent bypass via shell operator injection.
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `allowPatterns` | `string[]` | `[]` | Exact command prefixes that are permitted. Each entry is matched against the parsed argv tokens. |
-**Example:**
-```json
-{
-  "policyParams": {
-    "block-sudo": {
-      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
-    }
-  }
-}
-```
-With this config, `sudo systemctl status nginx` is allowed, but `sudo rm /etc/hosts` is denied.
-<Note>
-Patterns are matched against parsed tokens, not the raw command string. This prevents bypass via appended shell operators (e.g. `sudo systemctl status x; rm -rf /` does not match `sudo systemctl status *`).
-</Note>
----
-### `block-rm-rf`
-**Event:** PreToolUse (Bash)
-**Default:** Denies `rm -rf`, `rm -fr`, and similar recursive deletion forms.
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `allowPaths` | `string[]` | `[]` | Paths that are safe to recursively delete (e.g. `/tmp`). |
-**Example:**
-```json
-{
-  "policyParams": {
-    "block-rm-rf": {
-      "allowPaths": ["/tmp", "/var/cache"]
-    }
-  }
-}
-```
----
-### `block-curl-pipe-sh`
-**Event:** PreToolUse (Bash)
-**Default:** Denies `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash`, and similar patterns.
-No parameters.
----
-### `block-failproofai-commands`
-**Event:** PreToolUse (Bash)
-**Default:** Denies commands that would uninstall or disable failproofai itself (e.g. `npm uninstall failproofai`, `failproofai policies --uninstall`).
-No parameters.
----
-## Secrets (sanitizers)
-Stop agents from leaking credentials into their context or output. Sanitizer policies fire on **PostToolUse** events. When Claude runs a Bash command, reads a file, or calls any tool, these policies inspect the output before it is returned to Claude. If a secret pattern is detected, the policy returns a deny decision that prevents the output from being passed back.
-### `sanitize-jwt`
-**Event:** PostToolUse (all tools)
-**Default:** Redacts JWT tokens (three base64url segments separated by `.`).
-No parameters.
----
-### `sanitize-api-keys`
-**Event:** PostToolUse (all tools)
-**Default:** Redacts common API key formats: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`), and Google API keys (`AIza`).
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Additional regex patterns to treat as secrets. |
-**Example:**
-```json
-{
-  "policyParams": {
-    "sanitize-api-keys": {
-      "additionalPatterns": [
-        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
-        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
-      ]
-    }
-  }
-}
-```
----
-### `sanitize-connection-strings`
-**Event:** PostToolUse (all tools)
-**Default:** Redacts database connection strings that contain embedded credentials (e.g. `postgresql://user:password@host/db`).
-No parameters.
----
-### `sanitize-private-key-content`
-**Event:** PostToolUse (all tools)
-**Default:** Redacts PEM blocks (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.).
-No parameters.
----
-### `sanitize-bearer-tokens`
-**Event:** PostToolUse (all tools)
-**Default:** Redacts `Authorization: Bearer <token>` headers where the token is 20 or more characters.
-No parameters.
----
-## Environment
-Protect sensitive environment configuration from being read or exposed by agents.
-### `block-env-files`
-**Event:** PreToolUse (Bash, Read)
-**Default:** Denies reading `.env` files via `cat .env`, `Read` tool calls with `.env` as the file path, etc.
-Does not block `.envrc` or other environment-adjacent files - only files named exactly `.env`.
-No parameters.
----
-### `protect-env-vars`
-**Event:** PreToolUse (Bash)
-**Default:** Denies commands that print environment variables: `printenv`, `env`, `echo $VAR`.
-No parameters.
----
-## File access
-Keep agents working inside project boundaries and away from sensitive files.
-### `block-read-outside-cwd`
-**Event:** PreToolUse (Read, Bash)
-**Default:** Denies reading files outside the current working directory (the project root).
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `allowPaths` | `string[]` | `[]` | Absolute path prefixes that are permitted even if outside cwd. |
-**Example:**
-```json
-{
-  "policyParams": {
-    "block-read-outside-cwd": {
-      "allowPaths": ["/shared/data", "/opt/company/config"]
-    }
-  }
-}
-```
----
-### `block-secrets-write`
-**Event:** PreToolUse (Write, Edit)
-**Default:** Denies writes to files commonly used for private keys and certificates: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `additionalPatterns` | `string[]` | `[]` | Additional filename patterns (glob-style) to block. |
-**Example:**
-```json
-{
-  "policyParams": {
-    "block-secrets-write": {
-      "additionalPatterns": [".token", ".secret"]
-    }
-  }
-}
-```
----
-## Git
-Prevent accidental pushes, force-pushes, and branch mistakes that are hard to undo.
-### `block-push-master`
-**Event:** PreToolUse (Bash)
-**Default:** Denies `git push origin main` and `git push origin master`.
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `protectedBranches` | `string[]` | `["main", "master"]` | Branch names that cannot be pushed to directly. |
-**Example:**
-```json
-{
-  "policyParams": {
-    "block-push-master": {
-      "protectedBranches": ["main", "master", "release", "prod"]
-    }
-  }
-}
-```
-<Tip>
-To allow pushing to all branches (effectively disabling this policy without removing it from `enabledPolicies`), set `protectedBranches: []`.
-</Tip>
----
-### `block-work-on-main`
-**Event:** PreToolUse (Bash)
-**Default:** Denies checking out `main` or `master` branches directly.
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `protectedBranches` | `string[]` | `["main", "master"]` | Branch names that cannot be checked out directly. |
----
-### `block-force-push`
-**Event:** PreToolUse (Bash)
-**Default:** Denies `git push --force` and `git push -f`.
-No policy-specific parameters. Use the cross-cutting [`hint`](/configuration#hint-cross-cutting) to suggest alternatives:
-```json
-{
-  "policyParams": {
-    "block-force-push": {
-      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
-    }
-  }
-}
-```
----
-### `warn-git-amend`
-**Event:** PreToolUse (Bash)
-**Default:** Instructs Claude to proceed carefully when running `git commit --amend`. Does not block the command.
-No parameters.
----
-### `warn-git-stash-drop`
-**Event:** PreToolUse (Bash)
-**Default:** Instructs Claude to confirm before running `git stash drop`. Does not block the command.
-No parameters.
----
-### `warn-all-files-staged`
-**Event:** PreToolUse (Bash)
-**Default:** Instructs Claude to review what it is staging when it runs `git add -A` or `git add .`. Does not block the command.
-No parameters.
----
-## Database
-Catch destructive SQL operations before they execute against your database.
-### `warn-destructive-sql`
-**Event:** PreToolUse (Bash)
-**Default:** Instructs Claude to confirm before running SQL containing `DROP TABLE`, `DROP DATABASE`, or `DELETE` without a `WHERE` clause.
-No parameters.
----
-### `warn-schema-alteration`
-**Event:** PreToolUse (Bash)
-**Default:** Instructs Claude to confirm before running `ALTER TABLE` statements.
-No parameters.
----
-## Warnings
-Give agents extra context before potentially risky but non-destructive operations.
-### `warn-large-file-write`
-**Event:** PreToolUse (Write)
-**Default:** Instructs Claude to confirm before writing files larger than 1024 KB.
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `thresholdKb` | `number` | `1024` | File size threshold in kilobytes above which a warning is issued. |
-**Example:**
-```json
-{
-  "policyParams": {
-    "warn-large-file-write": {
-      "thresholdKb": 256
-    }
-  }
-}
-```
-<Note>
-The hook handler enforces a 1 MB stdin limit on payloads. To test this policy with small content, set `thresholdKb` to a value well below 1024.
-</Note>
----
-### `warn-package-publish`
-**Event:** PreToolUse (Bash)
-**Default:** Instructs Claude to confirm before running `npm publish`.
-No parameters.
----
-### `warn-background-process`
-**Event:** PreToolUse (Bash)
-**Default:** Instructs Claude to be careful when launching background processes via `nohup`, `&`, `disown`, or `screen`.
-No parameters.
----
-### `warn-global-package-install`
-**Event:** PreToolUse (Bash)
-**Default:** Instructs Claude to confirm before running `npm install -g`, `yarn global add`, or `pip install` without a virtual environment.
-No parameters.
----
-## Package managers
-Enforce which package managers the agent is allowed to use.
-### `prefer-package-manager`
-**Event:** PreToolUse (Bash)
-**Default:** Disabled. When enabled, blocks any package manager command not in the `allowed` list and tells Claude to rewrite the command using an allowed manager.
-Detects: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `allowed` | string[] | `[]` | Allowed package manager names. Any detected manager not in this list is blocked. When empty, the policy is a no-op. |
-| `blocked` | string[] | `[]` | Additional manager names to block beyond the built-in list (e.g. `['pdm', 'pipx']`). |
-The built-in block list covers: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Use `blocked` to append managers not in this list.
-**Example configuration:**
-```json
-{
-  "enabledPolicies": ["prefer-package-manager"],
-  "policyParams": {
-    "prefer-package-manager": {
-      "allowed": ["uv", "bun"],
-      "blocked": ["pdm", "pipx"]
-    }
-  }
-}
-```
-With this config, `pip install flask` and `pdm install flask` are both denied with a message telling Claude to use `uv` or `bun` instead. Commands like `uv pip install flask` are allowed because `uv` is in the allowlist and is checked first.
----
-## AI behavior
-Detect when agents get stuck or behave unexpectedly.
-### `warn-repeated-tool-calls`
-**Event:** PreToolUse (all tools)
-**Default:** Instructs Claude to reconsider when the same tool is called 3+ times with identical parameters - a common sign the agent is stuck in a loop.
-No parameters.
----
-## Workflow
-Enforce a disciplined end-of-session workflow. These policies fire on the **Stop** event and deny Claude from stopping until each condition is met. They follow a natural dependency chain: commit → push → PR → CI. If a policy denies, later policies in the chain are skipped (deny short-circuits).
-All workflow policies are **fail-open**: if the required tool is not available (e.g. `gh` not installed, no git remote), the policy allows with an informational message explaining why the check was skipped.
-### `require-commit-before-stop`
-**Event:** Stop
-**Default:** Denies stopping when there are uncommitted changes (modified, staged, or untracked files). Returns an informational message when the working directory is clean.
-No parameters.
----
-### `require-push-before-stop`
-**Event:** Stop
-**Default:** Denies stopping when there are unpushed commits or when the current branch has no remote tracking branch. Suggests `git push -u` to create a tracking branch if needed. Fails open if no remote is configured.
-**Parameters:**
-| Param | Type | Default | Description |
-|-------|------|---------|-------------|
-| `remote` | `string` | `"origin"` | Remote name to push to. |
-**Example:**
-```json
-{
-  "policyParams": {
-    "require-push-before-stop": {
-      "remote": "upstream"
-    }
-  }
-}
-```
----
-### `require-pr-before-stop`
-**Event:** Stop
-**Default:** Denies stopping when no pull request exists for the current branch, or when the existing PR is closed/merged. Instructs Claude to create a PR with `gh pr create`.
-No parameters.
-<Note>
-This policy requires [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.
-Run `gh auth login` with a personal access token that has `repo` scope for read access to
-pull requests. If `gh` is not installed or not authenticated, the policy fails open and reports the reason to Claude.
-</Note>
----
-### `require-ci-green-before-stop`
-**Event:** Stop
-**Default:** Denies stopping when CI checks are failing or still running on the current branch. Checks both GitHub Actions workflow runs and third-party bot checks (e.g. CodeRabbit, SonarCloud, Codecov). Treats `skipped` and `cancelled` conclusions as success. Returns an informational message when all checks pass.
-No parameters.
-<Note>
-This policy requires [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.
-Run `gh auth login` with a personal access token that has `repo` scope for read access to
-Actions workflow runs and the Checks API. If `gh` is not installed or not authenticated, the policy fails open and reports the reason to Claude.
-</Note>
----
----
-## Disabling individual policies
-Remove a specific policy from `enabledPolicies` in your config, or toggle it off in the dashboard's Policies tab.
-```json
-{
-  "enabledPolicies": [
-    "block-rm-rf",
-    "sanitize-api-keys"
-  ]
-}
-```
-Policies not listed in `enabledPolicies` do not run, even if `policyParams` entries exist for them.

package/.next/standalone/docs/cli/dashboard.mdx DELETED Viewed

@@ -1,28 +0,0 @@
----
-title: View sessions
-description: "Launch the dashboard to browse agent sessions and manage policies"
----
-```bash
-failproofai
-```
-Starts the web dashboard at `http://localhost:8020`.
-## Options
-| Flag | Description |
-|------|-------------|
-| `--port <number>` | Port to listen on (default: `8020`) |
-| `--projects-path <path>` | Override where Claude Code project folders are found |
-| `--allowed-origins <origins>` | Comma-separated hosts/IPs allowed to access dev resources |
-## Examples
-```bash
-# Launch on a different port
-failproofai --port 9000
-# Use a custom projects path
-failproofai --projects-path ~/my-claude-projects
-```

package/.next/standalone/docs/cli/environment-variables.mdx DELETED Viewed

@@ -1,34 +0,0 @@
----
-title: Environment variables
-description: "Configure failproofai behavior with environment variables"
----
-## Dashboard
-| Variable | Description |
-|----------|-------------|
-| `PORT` | Dashboard port (default: `8020`) |
-| `CLAUDE_PROJECTS_PATH` | Override where Claude Code project folders are found |
-| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Comma-separated dashboard pages to hide |
-| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs allowed to access dev resources. Same as `--allowed-origins`. |
-## Logging
-| Variable | Description |
-|----------|-------------|
-| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Server log level (default: `warn`) |
-| `FAILPROOFAI_HOOK_LOG_FILE` | Custom hook log file path, or `true` for default (`~/.failproofai/logs/hooks.log`) |
-## Telemetry
-| Variable | Description |
-|----------|-------------|
-| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Disable anonymous usage telemetry |
-## LLM (for policy evaluation)
-| Variable | Description |
-|----------|-------------|
-| `FAILPROOFAI_LLM_BASE_URL` | LLM API endpoint (default: `https://api.openai.com/v1`) |
-| `FAILPROOFAI_LLM_API_KEY` | API key for LLM-powered policies |
-| `FAILPROOFAI_LLM_MODEL` | Model name (default: `gpt-4o-mini`) |

package/.next/standalone/docs/cli/hook.mdx DELETED Viewed

@@ -1,30 +0,0 @@
----
-title: Hook handler (internal)
-description: "The subprocess Claude Code calls on each tool event"
----
-```bash
-failproofai --hook <EventType>
-```
-This is the command registered in Claude Code's `settings.json` by `failproofai policies --install`. You don't normally call this directly.
-Reads a JSON payload from stdin, evaluates all enabled policies, and exits with a code indicating the decision:
-| Exit code | Decision | Effect |
-|-----------|----------|--------|
-| `0` | `allow` | Permit the action |
-| `1` | `deny` | Block the action - Claude sees the denial reason |
-| `2` | `instruct` | Inject guidance into Claude's context |
-### Supported event types
-| Category | Events |
-|----------|--------|
-| **Tool execution** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` |
-| **Session lifecycle** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` |
-| **User interaction** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` |
-| **Subagents & tasks** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` |
-| **Configuration** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` |
-| **File system** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` |
-| **Context** | `PreCompact`, `PostCompact` |