failproofai 0.0.1-beta.9 → 0.0.2-beta.1

package/.next/standalone/dist/index.js

@@ -0,0 +1,80 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  instruct: () => instruct,
+  getCustomHooks: () => getCustomHooks,
+  deny: () => deny,
+  customPolicies: () => customPolicies,
+  clearCustomHooks: () => clearCustomHooks,
+  allow: () => allow
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/hooks/custom-hooks-registry.ts
+var REGISTRY_KEY = "__failproofai_custom_hooks__";
+function getRegistry() {
+  const g = globalThis;
+  if (!Array.isArray(g[REGISTRY_KEY]))
+    g[REGISTRY_KEY] = [];
+  return g[REGISTRY_KEY];
+}
+var customPolicies = {
+  add(hook) {
+    getRegistry().push(hook);
+  }
+};
+function getCustomHooks() {
+  return getRegistry();
+}
+function clearCustomHooks() {
+  const g = globalThis;
+  g[REGISTRY_KEY] = [];
+}
+// src/hooks/policy-helpers.ts
+function allow() {
+  return { decision: "allow" };
+}
+function deny(reason) {
+  return { decision: "deny", reason };
+}
+function instruct(reason) {
+  return { decision: "instruct", reason };
+}

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
 ```
 
 ---
@@ -22,39 +28,39 @@ To eliminate this surface, **we pre-emptively own all common misspellings and fo
 
 **Formatting variants** — different ways to write "failproof ai":
 
-| Package | Install command | Status |
-|---------|----------------|--------|
-| `failproof` | `npm install -g failproof` | ✅ published |
-| `failproof-ai` | `npm install -g failproof-ai` | ⏳ pending npm support approval |
-| `fail-proof-ai` | `npm install -g fail-proof-ai` | ⏳ pending npm support approval |
-| `failproof_ai` | `npm install -g failproof_ai` | ⏳ pending npm support approval |
-| `fail_proof_ai` | `npm install -g fail_proof_ai` | ⏳ pending npm support approval |
-| `fail-proofai` | `npm install -g fail-proofai` | ⏳ pending npm support approval |
-
-> **Why pending?** npm's spam-prevention policy blocks registration of names that normalize to the same string as an existing package after stripping punctuation (e.g. `failproof-ai` → `failproofai`). We have contacted npm support to reserve these names for anti-squatting purposes. They will be activated once approved.
+| Package | Status |
+|---------|--------|
+| `failproof` | ✅ Published |
+| `failproof-ai` | ⏳ Pending npm support |
+| `fail-proof-ai` | ⏳ Pending npm support |
+| `failproof_ai` | ⏳ Pending npm support |
+| `fail_proof_ai` | ⏳ Pending npm support |
+| `fail-proofai` | ⏳ Pending npm support |
 
 **`failprof*` typos** — missing one `o` from "proof":
 
-| Package | Install command |
-|---------|----------------|
-| `failprof` | `npm install -g failprof` |
-| `failprof-ai` | `npm install -g failprof-ai` |
-| `failprofai` | `npm install -g failprofai` |
-| `fail-prof-ai` | `npm install -g fail-prof-ai` |
-| `failprof_ai` | `npm install -g failprof_ai` |
+| Package | Status |
+|---------|--------|
+| `failprof` | ✅ Published |
+| `failprof-ai` | ✅ Published |
+| `failprofai` | ⏳ Pending npm support |
+| `fail-prof-ai` | ⏳ Pending npm support |
+| `failprof_ai` | ⏳ Pending npm support |
 
 **`faliproof*` typos** — transposed `a` and `i`:
 
-| Package | Install command |
-|---------|----------------|
-| `faliproof` | `npm install -g faliproof` |
-| `faliproof-ai` | `npm install -g faliproof-ai` |
-| `faliproofai` | `npm install -g faliproofai` |
+| Package | Status |
+|---------|--------|
+| `faliproof` | ✅ Published |
+| `faliproof-ai` | ✅ Published |
+| `faliproofai` | ⏳ Pending npm support |
+
+> **Why pending?** npm's spam-prevention policy blocks names that normalize to the same string as an existing package after stripping punctuation and running similarity checks. We have contacted npm support to reserve these names for anti-squatting purposes. They will be activated once approved.
 
-All 14 aliases are published by **ExosphereHost Inc.** (the same npm account as `failproofai`). You can verify any of them:
+You can verify any published alias is owned by us:
 
 ```bash
-npm info failproof-ai
+npm info failproof
 # Look for: "ExosphereHost Inc." in the maintainers field
 ```
 
@@ -65,7 +71,7 @@ npm info failproof-ai
 Each alias package:
 
 1. Lists `failproofai` as a dependency — so the real package (including its `postinstall` hook setup) runs on install
-2. Exposes a binary matching its own name (e.g. `failproof-ai`) that proxies all arguments to the `failproofai` binary
+2. Exposes a binary matching its own name (e.g. `failprof-ai`) that proxies all arguments to the `failproofai` binary
 
 The proxy is a two-line Node script; there is no logic, no network calls, and no data collection beyond what `failproofai` itself does.
 

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/examples/policies-notification.js

@@ -1,7 +1,7 @@
 /**
- * policies-notification.js — Notification event example
+ * policies-notification.js — Notification and SessionEnd event examples
  *
- * Forwards Claude's idle notifications to Slack.
+ * Forwards Claude's idle notifications and session-end events to Slack.
  *
  * Prerequisites:
  *   Set the SLACK_WEBHOOK_URL environment variable to your Slack incoming webhook URL.
@@ -10,8 +10,9 @@
  *   failproofai --install-hooks custom ./examples/policies-notification.js
  *
  * Test by letting Claude finish a task and go idle — you should receive a Slack message.
+ * Test session end by exiting Claude — you should receive a session summary message.
  */
-import { customPolicies, allow } from "failproofai";
+import { customPolicies, allow, instruct } from "failproofai";
 
 // Forward Claude idle notifications to Slack
 customPolicies.add({
@@ -22,38 +23,82 @@ customPolicies.add({
     const webhookUrl = process.env.SLACK_WEBHOOK_URL;
     if (!webhookUrl) return allow(); // skip if not configured
 
-    const type = String(ctx.payload?.notification_type ?? "");
-    if (type !== "idle") return allow(); // only forward idle notifications
-
     const message = String(ctx.payload?.message ?? "Claude is waiting for input");
     const cwd = ctx.session?.cwd ?? "unknown";
     const sessionId = ctx.session?.sessionId ?? "unknown";
 
-    // Fire-and-forget — never block Claude if Slack is unreachable
-    fetch(webhookUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        blocks: [
-          {
-            type: "header",
-            text: { type: "plain_text", text: "💬 Claude is waiting for you", emoji: true },
-          },
-          {
-            type: "section",
-            text: { type: "mrkdwn", text: message },
-          },
-          {
-            type: "section",
-            fields: [
-              { type: "mrkdwn", text: `*Project*\n\`${cwd}\`` },
-              { type: "mrkdwn", text: `*Session*\n\`${sessionId}\`` },
-            ],
-          },
-        ],
-      }),
-    }).catch(() => {});
-
-    return allow(); // Notification hooks must always return allow
+    // Await so the request completes before process.exit() is called by the CLI
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          blocks: [
+            {
+              type: "header",
+              text: { type: "plain_text", text: "💬 Claude is waiting for you", emoji: true },
+            },
+            {
+              type: "section",
+              text: { type: "mrkdwn", text: message },
+            },
+            {
+              type: "section",
+              fields: [
+                { type: "mrkdwn", text: `*Project*\n\`${cwd}\`` },
+                { type: "mrkdwn", text: `*Session*\n\`${sessionId}\`` },
+              ],
+            },
+          ],
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // Never block Claude if Slack is unreachable
+    }
+
+    return instruct(`We have sent the notification to the user on Slack about: ${message}`);
+  },
+});
+
+// Notify Slack when a Claude session ends
+customPolicies.add({
+  name: "slack-on-session-end",
+  description: "Notify Slack when a Claude session ends (set SLACK_WEBHOOK_URL env var)",
+  match: { events: ["SessionEnd"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow(); // skip if not configured
+
+    const cwd = ctx.session?.cwd ?? "unknown";
+    const sessionId = ctx.session?.sessionId ?? "unknown";
+
+    // Await so the request completes before process.exit() is called by the CLI
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          blocks: [
+            {
+              type: "header",
+              text: { type: "plain_text", text: "✅ Claude session ended", emoji: true },
+            },
+            {
+              type: "section",
+              fields: [
+                { type: "mrkdwn", text: `*Project*\n\`${cwd}\`` },
+                { type: "mrkdwn", text: `*Session*\n\`${sessionId}\`` },
+              ],
+            },
+          ],
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // Never block Claude if Slack is unreachable
+    }
+
+    return instruct(`We have sent the notification to the user on Slack about: Claude session ended (project: ${cwd}, session: ${sessionId})`);
   },
 });

package/.next/standalone/package.json

@@ -1,9 +1,9 @@
 {
   "name": "failproofai",
-  "version": "0.0.1-beta.9",
+  "version": "0.0.2-beta.1",
   "description": "Open-source hooks, policies, and project visualization for Claude Code & Agents SDK",
   "bin": {
-    "failproofai": "./bin/failproofai.mjs"
+    "failproofai": "./dist/cli.mjs"
   },
   "files": [
     "bin/",
@@ -11,6 +11,7 @@
     "scripts/",
     "lib/",
     ".next/standalone/",
+    "dist/",
     "README.md"
   ],
   "engines": {
@@ -18,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 --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/scripts/sync-hook-events-prompt.md

@@ -0,0 +1,60 @@
+You are an automated agent running in GitHub Actions to keep failproofai's hook
+event types in sync with the official Claude Code documentation.
+
+## Your task
+
+1. Fetch the Claude Code hooks reference pages using WebFetch:
+   - https://code.claude.com/docs/en/hooks (full reference — has the complete event table)
+   - https://code.claude.com/docs/en/hooks-guide (guide — also has a summary event table)
+   Extract the complete list of all hook event type names (e.g. SessionStart,
+   PreToolUse, PostToolUse, etc.) from the event lifecycle/trigger table.
+   Use both pages; union the results if they differ. Prefer the reference page.
+
+2. Read `src/hooks/types.ts` and extract the current `HOOK_EVENT_TYPES` array
+   (the TypeScript `as const` array of strings).
+
+3. Diff the two lists:
+   - **added**: event types in the docs but NOT in our array
+   - **removed**: event types in our array but NOT in the docs
+
+4. If there are NO differences:
+   Write the following JSON to `.sync-hook-events-output.json` in the repo root:
+   ```json
+   { "changed": false }
+   ```
+   Then stop.
+
+5. If there are differences:
+
+   a. Update `HOOK_EVENT_TYPES` in `src/hooks/types.ts`:
+      - Add new event types (append after the last existing entry, before `] as const`)
+      - Remove stale event types if any
+
+   b. Update `__tests__/hooks/manager.test.ts` — find the hardcoded event-type
+      counts and update them to the new total:
+      - The test description string matching `all N event types`
+      - The `toHaveLength(N)` assertion(s) that check `Object.keys(written.hooks)`
+      Search by the current count number to locate them.
+
+   c. Write the following JSON to `.sync-hook-events-output.json` in the repo root:
+      ```json
+      {
+        "changed": true,
+        "added": ["EventA", "EventB"],
+        "removed": ["EventC"],
+        "prTitle": "[auto] sync hook event types with Claude Code docs",
+        "prBody": "..."
+      }
+      ```
+      The `prBody` must be a Markdown string containing:
+      - List of **added** event types (or "none")
+      - List of **removed** event types (or "none")
+      - Source URLs used
+      - A note: "CI must pass and this PR must be reviewed before merging."
+
+## Constraints
+
+- **Only edit `src/hooks/types.ts`, `__tests__/hooks/manager.test.ts`, and
+  `.sync-hook-events-output.json`**. No other files.
+- Do NOT run any shell commands (no git, no gh, no bun).
+- Do NOT modify `policy-evaluator.ts`, `manager.ts`, or any other source file.