failproofai 0.0.2 → 0.0.4-beta.0

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

@@ -0,0 +1,142 @@
+---
+title: Dashboard
+description: "Supervisa sesiones de agentes, revisa llamadas a herramientas y gestiona políticas"
+icon: chart-line
+---
+
+El dashboard de failproofai es una aplicación web local para supervisar tus sesiones de agentes de IA y gestionar políticas. Descubre lo que hicieron tus agentes mientras no estabas.
+
+---
+
+## Iniciar el dashboard
+
+```bash
+failproofai
+```
+
+Se abre en `http://localhost:8020`.
+
+El dashboard lee directamente del sistema de archivos: tus carpetas de proyectos de Claude Code y los archivos de configuración de failproofai. No se escribe nada en ningún servicio remoto.
+
+---
+
+## Páginas
+
+### Proyectos
+
+Muestra todos los proyectos de Claude Code encontrados en tu máquina. Los proyectos se descubren desde `~/.claude/projects/` (o la ruta definida por `CLAUDE_PROJECTS_PATH`).
+
+Cada proyecto muestra:
+- Nombre del proyecto (derivado de la ruta de la carpeta)
+- Número de sesiones
+- Fecha de la actividad más reciente
+
+Haz clic en un proyecto para ver sus sesiones.
+
+### Sesiones
+
+Lista todas las sesiones dentro de un proyecto. Cada sesión muestra:
+- ID de sesión
+- Marcas de tiempo de inicio y fin
+- Número de llamadas a herramientas
+- Recuento de actividad de hooks (políticas que se activaron)
+
+Usa el filtro de rango de fechas y la búsqueda por ID de sesión para acotar la lista. Las sesiones están paginadas.
+
+Haz clic en una sesión para abrir el visor de sesiones.
+
+### Visor de sesiones
+
+El visor de sesiones responde la pregunta clave sobre los agentes autónomos: ¿qué hizo el agente y se mantuvo en el camino correcto? Muestra una línea de tiempo de todo lo que ocurrió en una sesión:
+
+- **Mensajes** - Las respuestas de texto de Claude y los prompts del usuario
+- **Llamadas a herramientas** - Cada herramienta que Claude invocó, con su entrada y salida
+- **Actividad de políticas** - Para cada llamada a herramienta, qué políticas se activaron y qué decisión devolvieron
+
+La barra de estadísticas en la parte superior muestra la duración de la sesión, el total de llamadas a herramientas y un resumen de las decisiones de los hooks (conteos de allow / deny / instruct).
+
+Puedes exportar la sesión como archivo ZIP o JSONL usando el botón de descarga.
+
+### Políticas
+
+Una página con dos pestañas para gestionar políticas y revisar la actividad.
+
+<Tabs>
+  <Tab title="Pestaña Políticas">
+  - Activa o desactiva políticas individuales con un solo clic (escribe en `~/.failproofai/policies-config.json`)
+  - Expande una política para configurar sus parámetros (para políticas que admiten `policyParams`)
+  - Instala o elimina hooks para un ámbito determinado
+  - Establece una ruta de archivo de políticas personalizada
+  </Tab>
+  <Tab title="Pestaña Actividad">
+  - Historial completo y paginado de cada evento de hook que se ha activado en todas las sesiones
+  - Búsqueda por nombre de política, ID de sesión, nombre de herramienta o decisión
+  - Cada fila muestra: marca de tiempo, nombre de política, decisión, nombre de herramienta, ID de sesión y el motivo de las decisiones deny/instruct
+  </Tab>
+</Tabs>
+
+---
+
+## Actualización automática
+
+El dashboard tiene un interruptor de actualización automática en la navegación superior. Cuando está activado, la página actual se actualiza periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Es esencial para supervisar sesiones de agentes autónomos de larga duración.
+
+---
+
+## Deshabilitar páginas
+
+Si solo necesitas algunas partes del dashboard, establece `FAILPROOFAI_DISABLE_PAGES` con una lista separada por comas de nombres de páginas:
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+Valores válidos: `policies`, `projects`.
+
+---
+
+## Tema
+
+El dashboard admite modo claro y oscuro. Cámbialo mediante el botón en la barra de navegación. La preferencia se guarda en el almacenamiento local de tu navegador.
+
+---
+
+## Configurar la ruta de proyectos
+
+De forma predeterminada, el dashboard lee desde el directorio estándar de proyectos de Claude Code. Puedes sobreescribirlo para configuraciones personalizadas:
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```
+
+---
+
+## Acceder desde un host que no sea localhost
+
+Cuando ejecutas el dashboard en **modo desarrollo** (`npm run dev`) y accedes a él desde un hostname diferente a `localhost` —por ejemplo, un dominio personalizado, una IP remota o una URL tunelizada— es posible que veas una advertencia como:
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+Esto es Next.js bloqueando el acceso de origen cruzado a su websocket HMR (hot module reload), que es una función exclusiva del modo desarrollo. Para permitir tu host, usa el flag `--allowed-origins`:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+Para múltiples hosts o IPs, pasa una lista separada por comas:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+También puedes establecer la variable de entorno `FAILPROOFAI_ALLOWED_DEV_ORIGINS` en su lugar:
+
+```bash
+FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
+```
+
+<Note>
+Esto solo aplica al modo desarrollo. Al ejecutar `failproofai` (modo producción), no hay websocket HMR ni problemas de recursos de desarrollo de origen cruzado.
+</Note>

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

@@ -0,0 +1,253 @@
+---
+title: Ejemplos
+description: "Cómo configurar hooks para Claude Code y el Agents SDK"
+icon: book-open
+---
+
+Ejemplos listos para usar en escenarios comunes. Cada uno muestra cómo instalar y qué esperar.
+
+---
+
+## Configurar hooks para Claude Code
+
+Failproof AI se integra con Claude Code a través de su [sistema de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Al ejecutar `failproofai policies --install`, registra comandos de hook en el `settings.json` de Claude Code que se activan en cada llamada a herramientas.
+
+<Steps>
+  <Step title="Instalar failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Habilitar todas las políticas integradas">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Verificar que los hooks están registrados">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    Deberías ver entradas de hook para los eventos `PreToolUse`, `PostToolUse`, `Notification` y `Stop`.
+  </Step>
+  <Step title="Ejecutar Claude Code">
+    ```bash
+    claude
+    ```
+
+    Las políticas ahora se ejecutan automáticamente en cada llamada a herramientas. Intenta pedirle a Claude que ejecute `sudo rm -rf /` — será bloqueado.
+  </Step>
+</Steps>
+
+---
+
+## Configurar hooks para el Agents SDK
+
+Si estás desarrollando con el [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), puedes usar el mismo sistema de hooks de forma programática.
+
+<Steps>
+  <Step title="Instalar failproofai en tu proyecto">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Configurar hooks en tu agente">
+    Pasa comandos de hook al crear el proceso de tu agente. Los hooks se activan de la misma manera que en Claude Code — mediante JSON por stdin/stdout:
+
+    ```bash
+    failproofai --hook PreToolUse   # se llama antes de cada herramienta
+    failproofai --hook PostToolUse  # se llama después de cada herramienta
+    ```
+  </Step>
+  <Step title="Escribir una política personalizada para tu agente">
+    ```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="Instalar la política personalizada">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Bloquear comandos destructivos
+
+La configuración más común: evitar que los agentes causen daños irreversibles.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+Qué hace esto:
+- `block-sudo` — bloquea todos los comandos `sudo`
+- `block-rm-rf` — bloquea la eliminación recursiva de archivos
+- `block-force-push` — bloquea `git push --force`
+- `block-curl-pipe-sh` — bloquea la ejecución de scripts remotos canalizados a la shell
+
+---
+
+## Prevenir la filtración de secretos
+
+Impide que los agentes vean o filtren credenciales en la salida de herramientas.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+Estas políticas se activan en `PostToolUse` — después de que se ejecuta una herramienta, limpian la salida antes de que el agente la vea.
+
+---
+
+## Recibir alertas en Slack cuando los agentes necesitan atención
+
+Usa el hook de notificación para reenviar alertas de inactividad a 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 {
+      // nunca bloquear el agente si Slack no está disponible
+    }
+
+    return allow();
+  },
+});
+```
+
+Instálalo:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Mantener los agentes en una rama
+
+Evita que los agentes cambien de rama o hagan push a ramas protegidas.
+
+```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();
+  },
+});
+```
+
+---
+
+## Requerir pruebas antes de hacer commit
+
+Recuerda a los agentes que ejecuten las pruebas antes de hacer commit.
+
+```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();
+  },
+});
+```
+
+---
+
+## Bloquear un repositorio de producción
+
+Incluye una configuración a nivel de proyecto para que todos los desarrolladores de tu equipo compartan las mismas políticas.
+
+Crea `.failproofai/policies-config.json` en tu repositorio:
+
+```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"]
+    }
+  }
+}
+```
+
+Luego confírmalo:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Cada miembro del equipo que tenga failproofai instalado adoptará estas reglas automáticamente.
+
+---
+
+## Más ejemplos
+
+El directorio [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) del repositorio contiene:
+
+| Archivo | Qué muestra |
+|---------|-------------|
+| `policies-basic.js` | Políticas básicas: bloquear escrituras en producción, force-push y scripts canalizados |
+| `policies-notification.js` | Alertas de Slack para notificaciones de inactividad y fin de sesión |
+| `policies-advanced/index.js` | Importaciones transitivas, hooks asíncronos, limpieza de salida en PostToolUse y manejo del evento Stop |

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

@@ -0,0 +1,38 @@
+---
+title: "Para agentes"
+description: "Añade el conocimiento de Failproof AI a tu agente de codificación con un solo comando. Compatible con Claude Code, Cursor, Windsurf y más."
+---
+
+Añade la referencia completa de Failproof AI a tu agente de codificación con un solo comando. Compatible con Claude Code, Cursor, Windsurf y cualquier otro agente que soporte skills.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+`npx skills` detecta qué agentes tienes instalados y añade la skill en el formato correcto para cada uno de forma automática.
+
+## Qué cubre la skill
+
+| Área | Qué incluye |
+|------|-------------|
+| Políticas | Nombres de políticas integradas, tipos de eventos, parámetros, activar/desactivar |
+| Políticas personalizadas | `customPolicies.add()`, filtros de coincidencia, API `allow`/`deny`/`instruct` |
+| Objeto de contexto | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| Configuración | Estructura de `policies-config.json`, fusión de scopes, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes |
+| Dashboard | Visor de sesiones, actividad de políticas, variables de entorno |
+| Arquitectura | Flujo del hook handler, códigos de salida, contrato stdin/stdout |
+
+## ¿La skill está completa?
+
+Mintlify genera `llms.txt` a partir de todas las páginas de la navegación. La documentación de Failproof AI cubre la API completa: cada política, opción y ejemplo está incluido. Si encuentras algo que falta, el origen está en `https://docs.befailproof.ai/llms-full.txt`.
+
+Para contexto más específico, enlaza directamente a una página concreta:
+
+```bash
+# Solo la API de políticas personalizadas
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# Solo las políticas integradas
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

package/.next/standalone/docs/es/getting-started.mdx

@@ -0,0 +1,134 @@
+---
+title: Primeros pasos
+description: "Instala failproofai, activa las políticas y deja que tus agentes funcionen de forma fiable"
+icon: rocket
+---
+
+## Requisitos
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (opcional — solo necesario para compilar desde el código fuente)
+
+---
+
+## Instalación
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Inicio rápido
+
+<Steps>
+  <Step title="Activar las políticas">
+    Las políticas son reglas que se ejecutan antes y después de cada llamada a una herramienta del agente. Detectan comandos destructivos, fugas de secretos y otros modos de fallo antes de que causen daño.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Esto escribe entradas de hook en el archivo `settings.json` de Claude Code. También puedes instalar para un único proyecto o seleccionar políticas específicas:
+
+    ```bash
+    failproofai policies --install --scope project
+    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
+    ```
+  </Step>
+  <Step title="Verificar">
+    ```bash
+    failproofai policies
+    ```
+
+    Muestra todas las políticas, si están activadas y los parámetros configurados.
+  </Step>
+  <Step title="Abrir el panel de control">
+    ```bash
+    failproofai
+    ```
+
+    Abre un panel de control local en `http://localhost:8020` donde puedes explorar sesiones, inspeccionar llamadas a herramientas y gestionar políticas.
+  </Step>
+  <Step title="Ejecutar tu agente">
+    Inicia Claude Code como de costumbre. Si el agente intenta hacer algo arriesgado, failproofai lo intercepta automáticamente. Déjalo correr sin supervisión y revisa lo ocurrido en el panel de control.
+  </Step>
+</Steps>
+
+---
+
+## Cómo funcionan las políticas
+
+Cada vez que un agente ejecuta una herramienta, Claude Code llama a failproofai como subproceso:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
+                                                 evaluates policies
+                                                 writes decision to stdout
+```
+
+Cada política devuelve una de tres decisiones:
+
+- **allow** — el agente continúa con normalidad
+- **deny** — la acción es bloqueada y el agente recibe una explicación
+- **instruct** — se añade contexto adicional al prompt del agente
+
+<Note>
+Las políticas se ejecutan en tu proceso local. No se envía nada a ningún servicio remoto.
+</Note>
+
+---
+
+## Almacenamiento de datos
+
+Toda la configuración y los registros permanecen en tu máquina:
+
+| Ruta | Contenido |
+|------|-----------|
+| `~/.failproofai/policies-config.json` | Configuración global de políticas |
+| `~/.failproofai/hook-activity.jsonl` | Historial de ejecución de hooks |
+| `~/.failproofai/hook.log` | Registro de depuración para errores de hooks personalizados |
+| `.failproofai/policies-config.json` | Configuración por proyecto (incluida en el repositorio) |
+| `.failproofai/policies-config.local.json` | Ajustes personales (excluidos con gitignore) |
+
+---
+
+## Desinstalación
+
+```bash
+failproofai policies --uninstall
+```
+
+Elimina las entradas de hook de `~/.claude/settings.json`. Los archivos de configuración en `~/.failproofai/` se conservan.
+
+---
+
+## Próximos pasos
+
+<CardGroup cols={2}>
+
+<Card title="Configuración" icon="gear" href="/es/configuration">
+  Ámbitos y formato de los archivos de configuración
+</Card>
+
+<Card title="Políticas integradas" icon="shield" href="/es/built-in-policies">
+  Las 26 políticas disponibles con sus parámetros
+</Card>
+
+<Card title="Políticas personalizadas" icon="code" href="/es/custom-policies">
+  Escribe tus propias políticas en JavaScript
+</Card>
+
+<Card title="Monitor de agentes" icon="chart-line" href="/es/dashboard">
+  Supervisa sesiones y revisa la actividad de las políticas
+</Card>
+
+</CardGroup>

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

@@ -0,0 +1,57 @@
+---
+title: Failproof AI
+description: "Gestiona hooks y políticas que mantienen tus agentes de IA confiables y funcionando de forma autónoma"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+Hooks y políticas que mantienen tus agentes de IA confiables y funcionando de forma autónoma — para **Claude Code** y el **Agents SDK**.
+
+Los agentes de IA fallan de maneras predecibles. Ejecutan comandos destructivos, filtran secretos, se desvían de su tarea, se quedan atascados en bucles o hacen push directamente a main. Sin supervisión, los pequeños fallos se acumulan y escalan.
+
+Failproof AI resuelve esto con **políticas** — reglas que se enganchan en cada llamada de herramienta del agente y pueden **detectar fallos**, **mitigarlos** (bloquear, instruir, sanitizar) y **alertarte** cuando algo requiere atención. Un panel de control local te permite revisar todo posteriormente.
+
+Todo se ejecuta localmente. Ningún dato sale de tu máquina.
+
+## Comenzar
+
+<CardGroup cols={2}>
+
+<Card title="26 políticas integradas" icon="shield" href="/es/built-in-policies">
+  Bloquea comandos destructivos, evita la filtración de secretos, mantén a los agentes dentro de los límites del proyecto y más — desde el primer momento.
+</Card>
+
+<Card title="Políticas personalizadas" icon="code" href="/es/custom-policies">
+  Escribe tus propias reglas en JavaScript con una API sencilla de allow / deny / instruct.
+</Card>
+
+<Card title="Monitor de agentes" icon="chart-line" href="/es/dashboard">
+  Ve lo que hicieron tus agentes mientras no estabas. Explora sesiones, inspecciona llamadas a herramientas y revisa dónde se activaron las políticas.
+</Card>
+
+<Card title="Configuración sencilla" icon="gear" href="/es/configuration">
+  Ajusta cualquier política sin código. Define listas de permisos, ramas protegidas o umbrales por proyecto o de forma global.
+</Card>
+
+</CardGroup>
+
+## Inicio rápido
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # habilitar políticas
+failproofai                      # abrir el panel de control
+```
+
+Consulta la guía de [Primeros pasos](/es/getting-started) para el recorrido completo.