failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/es/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: Alias de Paquetes
+description: "Alias registrados para prevención de typosquatting y cómo funcionan"
+icon: copy
+---
+
+## Paquete oficial
+
+El paquete npm canónico es **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## Por qué tenemos los alias registrados
+
+El typosquatting es un ataque común a la cadena de suministro en el que un actor malicioso registra un nombre de paquete que difiere por una sola tecla del paquete popular. Los usuarios que escriben mal el comando de instalación terminan ejecutando código controlado por el atacante con acceso completo al sistema — exactamente el tipo de amenaza que Failproof AI está diseñado para defender.
+
+Para eliminar esta superficie de ataque, **registramos de forma preventiva todas las variantes ortográficas y de formato más comunes** de `failproofai` en npm. Ninguno de estos nombres puede ser registrado por terceros. Cada uno es un proxy ligero que instala y delega al paquete real `failproofai`.
+
+---
+
+## Alias registrados
+
+**Variantes de formato** - diferentes formas de escribir "failproof ai":
+
+| Paquete | Estado |
+|---------|--------|
+| `failproof` | ✅ Publicado |
+| `failproof-ai` | ⏳ Pendiente de aprobación de npm |
+| `fail-proof-ai` | ⏳ Pendiente de aprobación de npm |
+| `failproof_ai` | ⏳ Pendiente de aprobación de npm |
+| `fail_proof_ai` | ⏳ Pendiente de aprobación de npm |
+| `fail-proofai` | ⏳ Pendiente de aprobación de npm |
+
+**Errores tipográficos `failprof*`** - falta una `o` en "proof":
+
+| Paquete | Estado |
+|---------|--------|
+| `failprof` | ✅ Publicado |
+| `failprof-ai` | ✅ Publicado |
+| `failprofai` | ⏳ Pendiente de aprobación de npm |
+| `fail-prof-ai` | ⏳ Pendiente de aprobación de npm |
+| `failprof_ai` | ⏳ Pendiente de aprobación de npm |
+
+**Errores tipográficos `faliproof*`** - `a` e `i` transpuestas:
+
+| Paquete | Estado |
+|---------|--------|
+| `faliproof` | ✅ Publicado |
+| `faliproof-ai` | ✅ Publicado |
+| `faliproofai` | ⏳ Pendiente de aprobación de npm |
+
+> **¿Por qué están pendientes?** La política de prevención de spam de npm bloquea nombres que, tras eliminar la puntuación y aplicar comprobaciones de similitud, se normalizan a la misma cadena que un paquete existente. Hemos contactado con el soporte de npm para reservar estos nombres con fines de protección contra squatting. Se activarán una vez aprobados.
+
+Puedes verificar que cualquier alias publicado nos pertenece:
+
+```bash
+npm info failproof
+# Look for: "ExosphereHost Inc." in the maintainers field
+```
+
+---
+
+## Cómo funcionan los alias
+
+Cada paquete alias:
+
+1. Incluye `failproofai` como dependencia, por lo que el paquete real (incluida la configuración de su hook `postinstall`) se ejecuta durante la instalación
+2. Expone un binario con su propio nombre (p. ej. `failprof-ai`) que redirige todos los argumentos al binario `failproofai`
+
+El proxy es un script de Node de dos líneas; no contiene ninguna lógica adicional, no realiza llamadas de red ni recopila datos más allá de lo que hace el propio `failproofai`.
+
+---
+
+## Si encuentras un nombre que nos hemos perdido
+
+Abre un issue en [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) y lo registraremos.

package/.next/standalone/docs/es/testing.mdx

@@ -0,0 +1,260 @@
+---
+title: Pruebas
+description: "Pruebas unitarias, pruebas E2E y utilidades de prueba"
+icon: flask-vial
+---
+
+failproofai cuenta con dos suites de pruebas: **pruebas unitarias** (rápidas, con mocks) y **pruebas end-to-end** (invocaciones reales de subprocesos).
+
+---
+
+## Ejecutar las pruebas
+
+```bash
+# Ejecutar todas las pruebas unitarias una vez
+bun run test:run
+
+# Ejecutar pruebas unitarias en modo watch
+bun run test
+
+# Ejecutar pruebas E2E (requiere configuración previa; ver más abajo)
+bun run test:e2e
+
+# Verificar tipos sin compilar
+bunx tsc --noEmit
+
+# Linting
+bun run lint
+```
+
+---
+
+## Pruebas unitarias
+
+Las pruebas unitarias se encuentran en `__tests__/` y utilizan [Vitest](https://vitest.dev) con `happy-dom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Lógica de políticas para cada builtin
+    hooks-config.test.ts          # Carga de configuración y fusión de scopes
+    policy-evaluator.test.ts      # Inyección de parámetros y orden de evaluación
+    custom-hooks-registry.test.ts # Registro globalThis: add/get/clear
+    custom-hooks-loader.test.ts   # Loader ESM, imports transitivos, manejo de errores
+    manager.test.ts               # Operaciones install/remove/list
+  components/
+    sessions-list.test.tsx        # Componente de lista de sesiones
+    project-list.test.tsx         # Componente de lista de proyectos
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### Escribir una prueba unitaria para una política
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## Pruebas end-to-end
+
+Las pruebas E2E invocan el binario real de `failproofai` como un subproceso, envían un payload JSON a stdin y verifican la salida por stdout y el código de salida. Esto prueba el flujo de integración completo que utiliza Claude Code.
+
+### Configuración
+
+Las pruebas E2E ejecutan el binario directamente desde el código fuente del repositorio. Antes de la primera ejecución, compila el bundle CJS que utilizan los archivos de hooks personalizados cuando importan desde `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Luego ejecuta las pruebas:
+
+```bash
+bun run test:e2e
+```
+
+Recompila `dist/` cada vez que modifiques la API pública de hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` o `src/hooks/policy-types.ts`).
+
+### Estructura de las pruebas E2E
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Lanza el binario, envía el payload JSON, captura código de salida + stdout + stderr
+    fixture-env.ts      # Directorios temporales aislados por prueba con archivos de configuración
+    payloads.ts         # Factorías de payloads precisas para cada tipo de evento de Claude
+  hooks/
+    builtin-policies.e2e.test.ts   # Cada política builtin con subproceso real
+    custom-hooks.e2e.test.ts       # Carga y evaluación de hooks personalizados
+    config-scopes.e2e.test.ts      # Fusión de configuración entre scopes: project/local/global
+    policy-params.e2e.test.ts      # Inyección de parámetros para cada política parametrizada
+```
+
+### Uso de los helpers E2E
+
+**`FixtureEnv`** — entorno aislado por prueba:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - directorio temporal; pásalo como payload.cwd para que detecte .failproofai/policies-config.json
+// env.home   - directorio home aislado; evita que ~/.failproofai real interfiera
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` registra la limpieza con `afterEach` automáticamente.
+
+**`runHook`** — invocar el binario:
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** — factorías de payloads predefinidas:
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### Escribir una prueba E2E
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → stdout vacío
+  });
+});
+```
+
+### Formas de respuesta E2E
+
+| Decisión | Código de salida | stdout |
+|----------|-----------------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (no Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | stdout vacío; motivo en stderr |
+| Allow | `0` | cadena vacía |
+
+### Configuración de Vitest
+
+Las pruebas E2E utilizan `vitest.config.e2e.mts` con:
+
+- `environment: "node"` — no se necesitan globales del navegador
+- `pool: "forks"` — aislamiento real de procesos (las pruebas lanzan subprocesos)
+- `testTimeout: 20_000` — 20 segundos por prueba (arranque del binario + evaluación del hook)
+
+El pool `forks` es importante: los workers basados en hilos comparten `globalThis`, lo que puede interferir con pruebas que lanzan subprocesos. Los forks basados en procesos evitan este problema.
+
+---
+
+## CI
+
+La ejecución completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) debe pasar antes de hacer merge. La suite E2E se ejecuta como un job de CI separado en paralelo.
+
+Consulta [Contributing](../CONTRIBUTING.md) para ver el checklist completo previo al merge.

package/.next/standalone/docs/examples.mdx

@@ -0,0 +1,253 @@
+---
+title: Examples
+description: "How to set up hooks for Claude Code and the Agents SDK"
+icon: book-open
+---
+
+Ready-to-use examples for common scenarios. Each one shows how to install and what to expect.
+
+---
+
+## Setting up hooks for Claude Code
+
+Failproof AI integrates with Claude Code via its [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks). When you run `failproofai policies --install`, it registers hook commands in Claude Code's `settings.json` that fire on every tool call.
+
+<Steps>
+  <Step title="Install failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Enable all built-in policies">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Verify hooks are registered">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    You should see hook entries for `PreToolUse`, `PostToolUse`, `Notification`, and `Stop` events.
+  </Step>
+  <Step title="Run Claude Code">
+    ```bash
+    claude
+    ```
+
+    Policies now run automatically on every tool call. Try asking Claude to run `sudo rm -rf /` - it will be blocked.
+  </Step>
+</Steps>
+
+---
+
+## Setting up hooks for the Agents SDK
+
+If you're building with the [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), you can use the same hook system programmatically.
+
+<Steps>
+  <Step title="Install failproofai in your project">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Configure hooks in your agent">
+    Pass hook commands when creating your agent process. The hooks fire the same way as in Claude Code - via stdin/stdout JSON:
+
+    ```bash
+    failproofai --hook PreToolUse   # called before each tool
+    failproofai --hook PostToolUse  # called after each tool
+    ```
+  </Step>
+  <Step title="Write a custom policy for your agent">
+    ```javascript
+    import { customPolicies, allow, deny } from "failproofai";
+
+    customPolicies.add({
+      name: "limit-to-project-dir",
+      description: "Keep the agent inside the project directory",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        const path = String(ctx.toolInput?.file_path ?? "");
+        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
+          return deny("Agent is restricted to the project directory");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Install the custom policy">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Block destructive commands
+
+The most common setup - prevent agents from doing irreversible damage.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+What this does:
+- `block-sudo` - blocks all `sudo` commands
+- `block-rm-rf` - blocks recursive file deletion
+- `block-force-push` - blocks `git push --force`
+- `block-curl-pipe-sh` - blocks piping remote scripts to shell
+
+---
+
+## Prevent secret leakage
+
+Stop agents from seeing or leaking credentials in tool output.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+These fire on `PostToolUse` - after a tool runs, they scrub the output before the agent sees it.
+
+---
+
+## Get Slack alerts when agents need attention
+
+Use the notification hook to forward idle alerts to Slack.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "slack-on-idle",
+  description: "Alert Slack when the agent is waiting for input",
+  match: { events: ["Notification"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow();
+
+    const message = String(ctx.payload?.message ?? "Agent is waiting");
+    const project = ctx.session?.cwd ?? "unknown";
+
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: `*${message}*\nProject: \`${project}\``,
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // never block the agent if Slack is unreachable
+    }
+
+    return allow();
+  },
+});
+```
+
+Install it:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Keep agents on a branch
+
+Prevent agents from switching branches or pushing to protected ones.
+
+```javascript
+import { customPolicies, allow, deny } from "failproofai";
+
+customPolicies.add({
+  name: "stay-on-branch",
+  description: "Prevent the agent from checking out other branches",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
+      return deny("Stay on the current branch. Create a new branch with -b if needed.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Require tests before commits
+
+Remind agents to run tests before committing.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Remind the agent to run tests before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Lock down a production repo
+
+Commit a project-level config so every developer on your team gets the same policies.
+
+Create `.failproofai/policies-config.json` in your repo:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-force-push",
+    "block-push-master",
+    "block-env-files",
+    "sanitize-api-keys",
+    "sanitize-jwt"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "production"]
+    }
+  }
+}
+```
+
+Then commit it:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Every team member who has failproofai installed will automatically pick up these rules.
+
+---
+
+## More examples
+
+The [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) directory in the repo contains:
+
+| File | What it shows |
+|------|---------------|
+| `policies-basic.js` | Starter policies - block production writes, force-push, piped scripts |
+| `policies-notification.js` | Slack alerts for idle notifications and session end |
+| `policies-advanced/index.js` | Transitive imports, async hooks, PostToolUse output scrubbing, Stop event handling |

package/.next/standalone/docs/for-agents.mdx

@@ -0,0 +1,38 @@
+---
+title: "For agents"
+description: "Add Failproof AI knowledge to your coding agent in one command. Works with Claude Code, Cursor, Windsurf, and more."
+---
+
+Add the full Failproof AI reference to your coding agent in one command. Works with Claude Code, Cursor, Windsurf, and any other agent that supports skills.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills` detects which agents you have installed and adds the skill in the right format for each one automatically.
+
+## What the skill covers
+
+| Area | What's included |
+|------|----------------|
+| Policies | Built-in policy names, event types, parameters, enable/disable |
+| Custom policies | `customPolicies.add()`, match filters, `allow`/`deny`/`instruct` API |
+| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| Configuration | `policies-config.json` structure, scope merging, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes |
+| Dashboard | Session viewer, policy activity, environment variables |
+| Architecture | Hook handler flow, exit codes, stdin/stdout contract |
+
+## Is the skill complete?
+
+Mintlify generates `llms.txt` from all pages in the navigation. The Failproof AI docs cover the full API - every policy, option, and example is included. If you find something missing, the source is at `https://docs.befailproof.ai/llms-full.txt`.
+
+For targeted context, link directly to a specific page:
+
+```bash
+# Just the custom policies API
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# Just the built-in policies
+npx skills add https://docs.befailproof.ai/built-in-policies
+```