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

package/.next/standalone/docs/es/custom-policies.mdx

@@ -1,353 +0,0 @@
----
-title: Políticas Personalizadas
-description: "Escribe tus propias políticas en JavaScript: aplica convenciones de proyecto, previene la deriva, detecta fallos e integra con sistemas externos"
-icon: code
----
-
-Las políticas personalizadas te permiten escribir reglas para cualquier comportamiento del agente: aplicar convenciones de proyecto, prevenir la deriva, bloquear operaciones destructivas, detectar agentes atascados o integrarse con Slack, flujos de aprobación y mucho más. Utilizan el mismo sistema de eventos de hook y las decisiones `allow`, `deny`, `instruct` que las políticas integradas.
-
----
-
-## Ejemplo rápido
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-customPolicies.add({
-  name: "no-production-writes",
-  description: "Block writes to paths containing 'production'",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("production")) {
-      return deny("Writes to production paths are blocked");
-    }
-    return allow();
-  },
-});
-```
-
-Instálala:
-
-```bash
-failproofai policies --install --custom ./my-policies.js
-```
-
----
-
-## Dos formas de cargar políticas personalizadas
-
-### Opción 1: Basada en convención (recomendada)
-
-Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargarán automáticamente — sin necesidad de flags ni cambios de configuración. Funciona como los git hooks: dejas el archivo y listo.
-
-```
-# A nivel de proyecto — incluido en git, compartido con el equipo
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# A nivel de usuario — personal, aplica a todos los proyectos
-~/.failproofai/policies/my-policies.mjs
-```
-
-**Cómo funciona:**
-- Se analizan tanto el directorio del proyecto como el del usuario (unión — no gana el primer ámbito)
-- Los archivos se cargan en orden alfabético dentro de cada directorio. Usa prefijos `01-`, `02-` para controlar el orden
-- Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}`; el resto se ignora
-- Cada archivo se carga de forma independiente (fallo abierto por archivo)
-- Funciona junto con `--custom` explícito y las políticas integradas
-
-<Tip>
-Las políticas por convención son la forma más fácil de establecer un estándar de calidad para tu organización. Incluye `.failproofai/policies/` en git y todos los miembros del equipo obtendrán las mismas reglas automáticamente — sin configuración individual. A medida que el equipo descubre nuevos modos de fallo, agrega una política y haz push. Con el tiempo, estas se convierten en un estándar de calidad vivo que mejora con cada contribución.
-</Tip>
-
-### Opción 2: Ruta de archivo explícita
-
-```bash
-# Instalar con un archivo de políticas personalizado
-failproofai policies --install --custom ./my-policies.js
-
-# Reemplazar la ruta del archivo de políticas
-failproofai policies --install --custom ./new-policies.js
-
-# Eliminar la ruta de políticas personalizadas de la configuración
-failproofai policies --uninstall --custom
-```
-
-La ruta absoluta resuelta se almacena en `policies-config.json` como `customPoliciesPath`. El archivo se carga de nuevo en cada evento de hook — no hay caché entre eventos.
-
-### Usar ambas opciones a la vez
-
-Las políticas por convención y el archivo `--custom` explícito pueden coexistir. Orden de carga:
-
-1. Archivo `customPoliciesPath` explícito (si está configurado)
-2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, en orden alfabético)
-3. Archivos de convención del usuario (`~/.failproofai/policies/`, en orden alfabético)
-
----
-
-## API
-
-### Importación
-
-```js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-```
-
-### `customPolicies.add(hook)`
-
-Registra una política. Puedes llamarla tantas veces como necesites para definir múltiples políticas en el mismo archivo.
-
-```ts
-customPolicies.add({
-  name: string;                         // requerido - identificador único
-  description?: string;                 // se muestra en la salida de `failproofai policies`
-  match?: { events?: HookEventType[] }; // filtra por tipo de evento; omitir para coincidir con todos
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-});
-```
-
-### Funciones de decisión
-
-| Función | Efecto | Cuándo usarla |
-|----------|--------|----------|
-| `allow()` | Permite la operación silenciosamente | La acción es segura, no se necesita mensaje |
-| `deny(message)` | Bloquea la operación | El agente no debería realizar esta acción |
-| `instruct(message)` | Añade contexto sin bloquear | Proporciona contexto adicional al agente para mantenerlo en curso |
-
-`deny(message)` — el mensaje se muestra a Claude con el prefijo `"Blocked by failproofai:"`. Un único `deny` cortocircuita toda evaluación posterior.
-
-`instruct(message)` — el mensaje se añade al contexto de Claude para la llamada de herramienta actual. Todos los mensajes de `instruct` se acumulan y se entregan juntos.
-
-<Tip>
-Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` agregando un campo `hint` en `policyParams` — sin necesidad de cambiar el código. Esto funciona también para políticas personalizadas (`custom/`), de convención de proyecto (`.failproofai-project/`) y de convención de usuario (`.failproofai-user/`). Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles.
-</Tip>
-
-### Mensajes informativos en allow
-
-`allow(message)` permite la operación **y** envía un mensaje informativo a Claude. El mensaje se entrega como `additionalContext` en la respuesta stdout del manejador de hooks — el mismo mecanismo que usa `instruct`, pero semánticamente distinto: es una actualización de estado, no una advertencia.
-
-| Función | Efecto | Cuándo usarla |
-|----------|--------|----------|
-| `allow(message)` | Permite y envía contexto a Claude | Confirmar que una verificación pasó, o explicar por qué se omitió |
-
-Casos de uso:
-- **Confirmaciones de estado:** `allow("All CI checks passed.")` — le dice a Claude que todo está bien
-- **Explicaciones de fallo abierto:** `allow("GitHub CLI not installed, skipping CI check.")` — le dice a Claude por qué se omitió una verificación para que tenga contexto completo
-- **Acumulación de múltiples mensajes:** si varias políticas retornan `allow(message)`, todos los mensajes se unen con saltos de línea y se entregan juntos
-
-```js
-customPolicies.add({
-  name: "confirm-branch-status",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    const cwd = ctx.session?.cwd;
-    if (!cwd) return allow("No working directory, skipping branch check.");
-
-    // ... check branch status ...
-    if (allPushed) {
-      return allow("Branch is up to date with remote.");
-    }
-    return deny("Unpushed changes detected.");
-  },
-});
-```
-
-### Campos de `PolicyContext`
-
-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | La herramienta que se está llamando (p. ej. `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | Los parámetros de entrada de la herramienta |
-| `payload` | `Record<string, unknown>` | Carga útil completa del evento en bruto desde Claude Code |
-| `session` | `SessionMetadata \| undefined` | Contexto de sesión (ver más abajo) |
-
-### Campos de `SessionMetadata`
-
-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| `sessionId` | `string` | Identificador de sesión de Claude Code |
-| `cwd` | `string` | Directorio de trabajo de la sesión de Claude Code |
-| `transcriptPath` | `string` | Ruta al archivo de transcripción JSONL de la sesión |
-
-### Tipos de eventos
-
-| Evento | Cuándo se dispara | Contenido de `toolInput` |
-|-------|--------------|----------------------|
-| `PreToolUse` | Antes de que Claude ejecute una herramienta | La entrada de la herramienta (p. ej. `{ command: "..." }` para Bash) |
-| `PostToolUse` | Después de que una herramienta finaliza | La entrada de la herramienta + `tool_result` (la salida) |
-| `Notification` | Cuando Claude envía una notificación | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — los hooks siempre deben retornar `allow()`, no pueden bloquear notificaciones |
-| `Stop` | Cuando finaliza la sesión de Claude | Vacío |
-
----
-
-## Orden de evaluación
-
-Las políticas se evalúan en este orden:
-
-1. Políticas integradas (en orden de definición)
-2. Políticas personalizadas explícitas de `customPoliciesPath` (en orden de `.add()`)
-3. Políticas por convención del proyecto en `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno)
-4. Políticas por convención del usuario en `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno)
-
-<Note>
-El primer `deny` cortocircuita todas las políticas siguientes. Todos los mensajes de `instruct` se acumulan y se entregan juntos.
-</Note>
-
----
-
-## Importaciones transitivas
-
-Los archivos de política personalizados pueden importar módulos locales mediante rutas relativas:
-
-```js
-// my-policies.js
-import { isBlockedPath } from "./utils.js";
-import { checkApproval } from "./approval-client.js";
-
-customPolicies.add({
-  name: "approval-gate",
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
-    return approved ? allow() : deny("Approval required for this command");
-  },
-});
-```
-
-Se resuelven todas las importaciones relativas alcanzables desde el archivo de entrada. Esto se implementa reescribiendo las importaciones `from "failproofai"` a la ruta real de dist y creando archivos `.mjs` temporales para garantizar la compatibilidad con ESM.
-
----
-
-## Filtrado por tipo de evento
-
-Usa `match.events` para limitar cuándo se dispara una política:
-
-```js
-customPolicies.add({
-  name: "require-summary-on-stop",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    // Solo se dispara cuando finaliza la sesión
-    // ctx.session.transcriptPath contiene el registro completo de la sesión
-    return allow();
-  },
-});
-```
-
-Omite `match` por completo para disparar en cada tipo de evento.
-
----
-
-## Manejo de errores y modos de fallo
-
-Las políticas personalizadas son **fail-open**: los errores nunca bloquean las políticas integradas ni provocan un crash del manejador de hooks.
-
-| Fallo | Comportamiento |
-|---------|----------|
-| `customPoliciesPath` no configurado | No se ejecutan políticas personalizadas explícitas; las políticas por convención y las integradas continúan normalmente |
-| Archivo no encontrado | Se registra una advertencia en `~/.failproofai/hook.log`; las políticas integradas continúan |
-| Error de sintaxis/importación (explícito) | Error registrado en `~/.failproofai/hook.log`; se omiten las políticas personalizadas explícitas |
-| Error de sintaxis/importación (convención) | Error registrado; ese archivo se omite, los demás archivos de convención se cargan igual |
-| `fn` lanza un error en tiempo de ejecución | Error registrado; ese hook se trata como `allow`; los demás hooks continúan |
-| `fn` tarda más de 10 segundos | Timeout registrado; se trata como `allow` |
-| Directorio de convención inexistente | No se ejecutan políticas por convención; sin error |
-
-<Tip>
-Para depurar errores de políticas personalizadas, observa el archivo de log:
-
-```bash
-tail -f ~/.failproofai/hook.log
-```
-</Tip>
-
----
-
-## Ejemplo completo: múltiples políticas
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-// Prevent agent from writing to secrets/ directory
-customPolicies.add({
-  name: "block-secrets-dir",
-  description: "Prevent agent from writing to secrets/ directory",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
-    const path = ctx.toolInput?.file_path ?? "";
-    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
-    return allow();
-  },
-});
-
-// Keep the agent on track: verify tests before committing
-customPolicies.add({
-  name: "remind-test-before-commit",
-  description: "Keep the agent on track: verify tests pass before committing",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    if (/git\s+commit/.test(cmd)) {
-      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
-    }
-    return allow();
-  },
-});
-
-// Prevent unplanned dependency changes during freeze
-customPolicies.add({
-  name: "dependency-freeze",
-  description: "Prevent unplanned dependency changes during freeze period",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = ctx.toolInput?.command ?? "";
-    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
-    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
-      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
-    }
-    return allow();
-  },
-});
-
-export { customPolicies };
-```
-
----
-
-## Ejemplos
-
-El directorio `examples/` contiene archivos de política listos para ejecutar:
-
-| Archivo | Contenido |
-|------|----------|
-| `examples/policies-basic.js` | Cinco políticas de inicio que cubren los modos de fallo más comunes de los agentes |
-| `examples/policies-advanced/index.js` | Patrones avanzados: importaciones transitivas, llamadas asíncronas, limpieza de salida y hooks de fin de sesión |
-| `examples/convention-policies/security-policies.mjs` | Políticas de seguridad basadas en convención (bloquear escrituras en .env, prevenir reescritura del historial de git) |
-| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo basadas en convención (recordatorios de pruebas, registro de escrituras de archivos) |
-
-### Usar los ejemplos con archivo explícito
-
-```bash
-failproofai policies --install --custom ./examples/policies-basic.js
-```
-
-### Usar los ejemplos basados en convención
-
-```bash
-# Copiar al nivel de proyecto
-mkdir -p .failproofai/policies
-cp examples/convention-policies/*.mjs .failproofai/policies/
-
-# O copiar al nivel de usuario
-mkdir -p ~/.failproofai/policies
-cp examples/convention-policies/*.mjs ~/.failproofai/policies/
-```
-
-No se necesita ningún comando de instalación — los archivos se detectan automáticamente en el próximo evento de hook.

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

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