failproofai 0.0.1 → 0.0.2-beta.2

package/.next/standalone/docs/architecture.md

@@ -1,4 +1,8 @@
-# Architecture
+---
+title: Architecture
+description: "How the hook handler, config loading, and policy evaluation work internally"
+icon: sitemap
+---
 
 This document explains how failproofai works internally: how the hook system processes events, how configuration is loaded and merged, how policies are evaluated, and how the dashboard fits in.
 

package/.next/standalone/docs/built-in-policies.md

@@ -1,4 +1,8 @@
-# Built-in Policies
+---
+title: Built-in Policies
+description: "All 35+ security policies with descriptions and parameters"
+icon: shield
+---
 
 failproofai ships with 35+ built-in security policies. Each policy fires on a specific hook event type and tool name. Eight policies accept parameters that let you tune their behavior without writing code.
 

package/.next/standalone/docs/cli-reference.md

@@ -1,4 +1,8 @@
-# CLI Reference
+---
+title: CLI Reference
+description: "All commands, flags, and environment variables for the failproofai CLI"
+icon: terminal
+---
 
 All commands are invoked via the `failproofai` binary.
 

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

@@ -1,4 +1,8 @@
-# Configuration
+---
+title: Configuration
+description: "Config file format, three-scope system, and merge rules"
+icon: gear
+---
 
 failproofai uses JSON configuration files to control which policies are active, how they behave, and where custom hooks are loaded from.
 

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

@@ -1,4 +1,8 @@
-# Custom Hooks
+---
+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.
 

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

@@ -1,4 +1,8 @@
-# Dashboard
+---
+title: Dashboard
+description: "Session viewer, policy management, and activity log"
+icon: chart-line
+---
 
 The failproofai dashboard is a local web application for browsing Claude Code sessions and managing security policies.
 

package/.next/standalone/docs/docs.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "luma",
+  "name": "FailproofAI",
+  "colors": {
+    "primary": "#002CA7",
+    "light": "#e4587d",
+    "dark": "#002CA7"
+  },
+  "favicon": "/favicon.ico",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Docs",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": [
+              "introduction",
+              "getting-started"
+            ]
+          },
+          {
+            "group": "Core Concepts",
+            "pages": [
+              "configuration",
+              "built-in-policies",
+              "custom-hooks"
+            ]
+          },
+          {
+            "group": "Tools",
+            "pages": [
+              "cli-reference",
+              "dashboard"
+            ]
+          },
+          {
+            "group": "Advanced",
+            "pages": [
+              "architecture",
+              "testing",
+              "package-aliases"
+            ]
+          }
+        ]
+      }
+    ],
+    "global": {
+      "anchors": [
+        {
+          "anchor": "GitHub",
+          "href": "https://github.com/exospherehost/failproofai",
+          "icon": "github"
+        },
+        {
+          "anchor": "npm",
+          "href": "https://www.npmjs.com/package/failproofai",
+          "icon": "npm"
+        },
+        {
+          "anchor": "Discord",
+          "href": "https://discord.com/invite/zT92CAgvkj",
+          "icon": "discord"
+        }
+      ]
+    }
+  },
+  "navbar": {
+    "links": [],
+    "primary": {
+      "type": "button",
+      "label": "Get started",
+      "href": "/getting-started"
+    }
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/exospherehost/failproofai",
+      "x": "https://x.com/exospherehost"
+    }
+  }
+}

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

@@ -1,9 +1,13 @@
-# Getting Started
+---
+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 (used as the runtime and bundler)
+- **Bun** >= 1.3.0 (optional — only needed for development / building from source)
 
 ---
 
@@ -11,6 +15,8 @@
 
 ```bash
 npm install -g failproofai
+# or
+bun add -g failproofai
 ```
 
 ---

package/.next/standalone/docs/introduction.md

@@ -0,0 +1,47 @@
+---
+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.

package/.next/standalone/docs/package-aliases.md

@@ -1,4 +1,8 @@
-# Package Aliases & Typosquatting Protection
+---
+title: Package Aliases
+description: "Registered typosquat-prevention aliases and how they work"
+icon: copy
+---
 
 ## Official package
 
@@ -6,6 +10,8 @@ The canonical npm package is **`failproofai`**:
 
 ```bash
 npm install -g failproofai
+# or
+bun add -g failproofai
 ```
 
 ---

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

@@ -1,4 +1,8 @@
-# Testing
+---
+title: Testing
+description: "Unit tests, E2E tests, and test helpers"
+icon: flask-vial
+---
 
 failproofai has two test suites: **unit tests** (fast, mocked) and **end-to-end tests** (real subprocess invocations).
 

package/.next/standalone/package.json

@@ -1,9 +1,9 @@
 {
   "name": "failproofai",
-  "version": "0.0.1",
+  "version": "0.0.2-beta.2",
   "description": "Open-source hooks, policies, and project visualization for Claude Code & Agents SDK",
   "bin": {
-    "failproofai": "./bin/failproofai.mjs"
+    "failproofai": "./dist/cli.mjs"
   },
   "files": [
     "bin/",
@@ -19,10 +19,11 @@
     "bun": ">=1.3.0"
   },
   "scripts": {
-    "predev": "bun link",
+    "predev": "bun run build:cli && bun link",
     "dev": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/dev.ts --port 8020",
-    "build": "bun build --target=node --format=cjs --outfile=dist/index.js src/index.ts && bun --bun next build && node -e \"const {cpSync}=require('fs');cpSync('.next/static','.next/standalone/.next/static',{recursive:true});\"",
-    "prestart": "bun link",
+    "build:cli": "bun build --target=node --format=esm --outfile=dist/cli.mjs bin/failproofai.mjs --external posthog-node && node -e \"const fs=require('fs');const c=fs.readFileSync('dist/cli.mjs','utf8');fs.writeFileSync('dist/cli.mjs',c.replace('#!/usr/bin/env bun','#!/usr/bin/env node').replace('// @bun\\n',''))\"",
+    "build": "bun build --target=node --format=cjs --outfile=dist/index.js src/index.ts && bun run build:cli && bun --bun next build && node -e \"const {cpSync}=require('fs');cpSync('.next/static','.next/standalone/.next/static',{recursive:true});\"",
+    "prestart": "bun run build:cli && bun link",
     "start": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/start.ts",
     "test": "vitest",
     "test:run": "vitest run",

package/.next/standalone/scripts/launch.ts

@@ -49,7 +49,7 @@ export function launch(mode: "dev" | "start"): void {
     const serverJsPath = resolve(packageRoot, ".next/standalone/server.js");
     if (!existsSync(serverJsPath)) {
       console.error(
-        `\nError: Cannot find server binary at:\n  ${serverJsPath}\n\n` +
+        `\nError: Cannot find server.js at:\n  ${serverJsPath}\n\n` +
         `The package may be missing its build output.\n` +
         `Try reinstalling:\n  npm install -g failproofai@latest\n`
       );

package/.next/standalone/scripts/postinstall.mjs

@@ -18,6 +18,17 @@ import { trackInstallEvent } from "./install-telemetry.mjs";
 // from process.cwd() only when we are being installed as a dependency by someone else.
 if (!process.env.INIT_CWD || process.env.INIT_CWD === process.cwd()) process.exit(0);
 
+// Verify server.js exists — fail the install early if the dashboard build is missing.
+const serverJsPath = resolve(process.cwd(), ".next", "standalone", "server.js");
+if (!existsSync(serverJsPath)) {
+  console.error(
+    `\n[failproofai] Error: server.js not found at:\n  ${serverJsPath}\n\n` +
+    `  The package may not have been built correctly.\n` +
+    `  Try reinstalling: npm install -g failproofai@latest\n`
+  );
+  process.exit(1);
+}
+
 const FAILPROOFAI_HOOK_MARKER = "__failproofai_hook__";
 const NAMESPACE = "failproofai-telemetry-v1";
 

package/.next/standalone/src/cli-error.ts

@@ -0,0 +1,18 @@
+/**
+ * CliError — structured error for the failproofai CLI.
+ *
+ * Throw this for any error that should be reported to the user as a clean
+ * message (no stack trace). The exit code communicates the failure class:
+ *
+ *   1 — user error   (bad args, unknown policy name, invalid flag)
+ *   2 — internal     (file I/O failure, unexpected state)
+ */
+export class CliError extends Error {
+  readonly exitCode: 1 | 2;
+
+  constructor(message: string, exitCode: 1 | 2 = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}

package/.next/standalone/src/hooks/manager.ts

@@ -21,6 +21,7 @@ import { BUILTIN_POLICIES } from "./builtin-policies";
 import { loadCustomHooks } from "./custom-hooks-loader";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId, hashToId } from "../../lib/telemetry-id";
+import { CliError } from "../cli-error";
 
 const VALID_POLICY_NAMES = new Set(BUILTIN_POLICIES.map((p) => p.name));
 
@@ -67,7 +68,7 @@ function resolveFailproofaiBinary(): string {
     // `where` on Windows may return multiple lines; take the first
     return result.split("\n")[0].trim();
   } catch {
-    throw new Error(
+    throw new CliError(
       "failproofai binary not found in PATH.\n" +
       "Install it globally first: npm install -g failproofai"
     );
@@ -85,7 +86,7 @@ function validatePolicyNames(names: string[]): void {
   const invalid = names.filter((n) => !VALID_POLICY_NAMES.has(n));
   if (invalid.length > 0) {
     const validList = [...VALID_POLICY_NAMES].join(", ");
-    throw new Error(
+    throw new CliError(
       `Unknown policy name(s): ${invalid.join(", ")}\n` +
       `Valid policies: ${validList}`
     );
@@ -185,6 +186,20 @@ export async function installHooks(
   customPoliciesPath?: string,
   removeCustomHooks = false,
 ): Promise<void> {
+  // Validate user input first before any system checks
+  if (policyNames !== undefined && policyNames.length > 0) {
+    const nonAllNames = policyNames.filter((n) => n !== "all");
+    // Check unknown names first (most actionable error for the user)
+    if (nonAllNames.length > 0) validatePolicyNames(nonAllNames);
+    // Then check if "all" is mixed with valid specific names
+    if (policyNames.includes("all") && nonAllNames.length > 0) {
+      throw new CliError(
+        `"all" cannot be combined with specific policy names.\n` +
+        `Use either: --install all  or  --install block-sudo sanitize-jwt ...`
+      );
+    }
+  }
+
   const binaryPath = resolveFailproofaiBinary();
 
   // Capture existing config before overwriting (used for telemetry diff)
@@ -201,7 +216,6 @@ export async function installHooks(
         .filter((p) => includeBeta || !p.beta)
         .map((p) => p.name);
     } else {
-      if (policyNames.length > 0) validatePolicyNames(policyNames);
       incoming = policyNames;
     }
     // Additive: union with whatever was already enabled, deduplicated.

package/README.md

@@ -9,6 +9,12 @@
 
 # Failproof AI
 
+[![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://befailproof.ai)
+[![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
+[![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/exospherehost/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/exospherehost/failproofai/actions)
+[![Discord](https://img.shields.io/discord/1234567890?style=flat-square&label=Discord&color=5865F2)](https://discord.com/invite/zT92CAgvkj)
+
 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.
@@ -23,7 +29,7 @@ Everything runs locally — no data leaves your machine.
 ## Requirements
 
 - Node.js >= 20.9.0
-- Bun >= 1.3.0
+- Bun >= 1.3.0 (optional — only needed for development / building from source)
 
 ---
 
@@ -31,6 +37,8 @@ Everything runs locally — no data leaves your machine.
 
 ```bash
 npm install -g failproofai
+# or
+bun add -g failproofai
 ```
 
 ---
@@ -40,7 +48,7 @@ npm install -g failproofai
 ### 1. Enable policies globally
 
 ```bash
-failproofai --install-policies
+failproofai policies --install
 ```
 
 Writes hook entries into `~/.claude/settings.json`. Claude Code will now invoke failproofai before and after each tool call.
@@ -56,7 +64,7 @@ Opens `http://localhost:8020` — browse sessions, inspect logs, manage policies
 ### 3. Check what's active
 
 ```bash
-failproofai --list-policies
+failproofai policies
 ```
 
 ---
@@ -67,22 +75,22 @@ failproofai --list-policies
 
 | 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` |
+| Global (default) | `failproofai policies --install` | `~/.claude/settings.json` |
+| Project | `failproofai policies --install --scope project` | `.claude/settings.json` |
+| Local | `failproofai policies --install --scope local` | `.claude/settings.local.json` |
 
 ### Install specific policies
 
 ```bash
-failproofai --install-policies block-sudo block-rm-rf sanitize-api-keys
+failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
 ```
 
 ### Remove policies
 
 ```bash
-failproofai --remove-policies
+failproofai policies --uninstall
 # or for a specific scope:
-failproofai --remove-policies --scope project
+failproofai policies --uninstall --scope project
 ```
 
 ---
@@ -182,7 +190,7 @@ customPolicies.add({
 Install with:
 
 ```bash
-failproofai --install-policies --custom ./my-policies.js
+failproofai policies --install --custom ./my-policies.js
 ```
 
 ### Decision helpers