failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/pt-br/dashboard.mdx

@@ -0,0 +1,142 @@
+---
+title: Dashboard
+description: "Monitore sessões de agentes, revise chamadas de ferramentas e gerencie políticas"
+icon: chart-line
+---
+
+O dashboard do failproofai é uma aplicação web local para monitorar suas sessões de agentes de IA e gerenciar políticas. Veja o que seus agentes fizeram enquanto você estava ausente.
+
+---
+
+## Iniciando o dashboard
+
+```bash
+failproofai
+```
+
+Abre em `http://localhost:8020`.
+
+O dashboard lê diretamente do sistema de arquivos — suas pastas de projeto do Claude Code e os arquivos de configuração do failproofai. Nada é gravado em um serviço remoto.
+
+---
+
+## Páginas
+
+### Projetos
+
+Lista todos os projetos do Claude Code encontrados na sua máquina. Os projetos são descobertos a partir de `~/.claude/projects/` (ou do caminho definido por `CLAUDE_PROJECTS_PATH`).
+
+Cada projeto exibe:
+- Nome do projeto (derivado do caminho da pasta)
+- Número de sessões
+- Data da atividade mais recente da sessão
+
+Clique em um projeto para ver suas sessões.
+
+### Sessões
+
+Lista todas as sessões dentro de um projeto. Cada sessão exibe:
+- ID da sessão
+- Timestamps de início e fim
+- Número de chamadas de ferramentas
+- Contagem de atividade de hooks (políticas que foram acionadas)
+
+Use o filtro de intervalo de datas e a busca por ID de sessão para refinar a lista. As sessões são paginadas.
+
+Clique em uma sessão para abrir o visualizador de sessão.
+
+### Visualizador de sessão
+
+O visualizador de sessão responde à pergunta central para agentes autônomos: o que o agente fez e ele se manteve no caminho certo? Ele exibe uma linha do tempo de tudo o que aconteceu em uma sessão:
+
+- **Mensagens** — Respostas de texto do Claude e prompts do usuário
+- **Chamadas de ferramentas** — Cada ferramenta que o Claude invocou, com sua entrada e saída
+- **Atividade de políticas** — Para cada chamada de ferramenta, quais políticas foram acionadas e qual decisão elas retornaram
+
+A barra de estatísticas no topo exibe a duração da sessão, o total de chamadas de ferramentas e um resumo das decisões de hooks (contagens de allow / deny / instruct).
+
+Você pode exportar a sessão como um arquivo ZIP ou JSONL usando o botão de download.
+
+### Políticas
+
+Uma página com duas abas para gerenciar políticas e revisar atividades.
+
+<Tabs>
+  <Tab title="Aba Políticas">
+  - Ative ou desative políticas individuais com um único clique (grava em `~/.failproofai/policies-config.json`)
+  - Expanda uma política para configurar seus parâmetros (para políticas que suportam `policyParams`)
+  - Instale ou remova hooks para um determinado escopo
+  - Defina um caminho de arquivo de políticas personalizado
+  </Tab>
+  <Tab title="Aba Atividade">
+  - Histórico completo e paginado de todos os eventos de hook que foram acionados em todas as sessões
+  - Busque por nome de política, ID de sessão, nome de ferramenta ou decisão
+  - Cada linha exibe: timestamp, nome da política, decisão, nome da ferramenta, ID da sessão e o motivo das decisões deny/instruct
+  </Tab>
+</Tabs>
+
+---
+
+## Atualização automática
+
+O dashboard possui um botão de alternância de atualização automática na navegação superior. Quando ativado, a página atual é atualizada periodicamente para exibir novas sessões e atividades de políticas à medida que aparecem. Essencial para monitorar sessões de agentes autônomos de longa duração.
+
+---
+
+## Desativando páginas
+
+Se você precisar apenas de algumas partes do dashboard, defina `FAILPROOFAI_DISABLE_PAGES` com uma lista de nomes de páginas separados por vírgula:
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+Valores válidos: `policies`, `projects`.
+
+---
+
+## Tema
+
+O dashboard suporta modo claro e escuro. Alterne pelo botão na barra de navegação. A preferência é armazenada no armazenamento local do seu navegador.
+
+---
+
+## Configurando o caminho dos projetos
+
+Por padrão, o dashboard lê a partir do diretório de projetos padrão do Claude Code. Substitua-o para configurações personalizadas:
+
+```bash
+CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
+```
+
+---
+
+## Acessando a partir de um host não-localhost
+
+Ao executar o dashboard em **modo dev** (`npm run dev`) e acessá-lo a partir de um hostname diferente de `localhost` — por exemplo, um domínio personalizado, um IP remoto ou uma URL tunelada — você pode ver um aviso como:
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+Este é o Next.js bloqueando o acesso cross-origin ao seu websocket de HMR (hot module reload), que é um recurso exclusivo do modo dev. Para permitir seu host, use a flag `--allowed-origins`:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+Para múltiplos hosts ou IPs, passe uma lista separada por vírgulas:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+Você também pode definir a variável de ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS`:
+
+```bash
+FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
+```
+
+<Note>
+Isso se aplica apenas ao modo dev. Ao executar `failproofai` (modo de produção), não há websocket de HMR nem problema de recurso dev cross-origin.
+</Note>

package/.next/standalone/docs/pt-br/examples.mdx

@@ -0,0 +1,253 @@
+---
+title: Exemplos
+description: "Como configurar hooks para Claude Code e o Agents SDK"
+icon: book-open
+---
+
+Exemplos prontos para uso em cenários comuns. Cada um mostra como instalar e o que esperar.
+
+---
+
+## Configurando hooks para o Claude Code
+
+O Failproof AI se integra ao Claude Code por meio do seu [sistema de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando você executa `failproofai policies --install`, ele registra comandos de hook no `settings.json` do Claude Code que são acionados em cada chamada de ferramenta.
+
+<Steps>
+  <Step title="Instale o failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Ative todas as políticas integradas">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Verifique se os hooks foram registrados">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    Você deverá ver entradas de hook para os eventos `PreToolUse`, `PostToolUse`, `Notification` e `Stop`.
+  </Step>
+  <Step title="Execute o Claude Code">
+    ```bash
+    claude
+    ```
+
+    As políticas agora são executadas automaticamente em cada chamada de ferramenta. Tente pedir ao Claude para executar `sudo rm -rf /` — o comando será bloqueado.
+  </Step>
+</Steps>
+
+---
+
+## Configurando hooks para o Agents SDK
+
+Se você está desenvolvendo com o [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), pode usar o mesmo sistema de hooks de forma programática.
+
+<Steps>
+  <Step title="Instale o failproofai no seu projeto">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Configure os hooks no seu agente">
+    Passe os comandos de hook ao criar o processo do seu agente. Os hooks são acionados da mesma forma que no Claude Code — via stdin/stdout JSON:
+
+    ```bash
+    failproofai --hook PreToolUse   # chamado antes de cada ferramenta
+    failproofai --hook PostToolUse  # chamado após cada ferramenta
+    ```
+  </Step>
+  <Step title="Escreva uma política personalizada para seu 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="Instale a política personalizada">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Bloquear comandos destrutivos
+
+A configuração mais comum — impede que agentes causem danos irreversíveis.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+O que isso faz:
+- `block-sudo` — bloqueia todos os comandos `sudo`
+- `block-rm-rf` — bloqueia a exclusão recursiva de arquivos
+- `block-force-push` — bloqueia `git push --force`
+- `block-curl-pipe-sh` — bloqueia o redirecionamento de scripts remotos para o shell
+
+---
+
+## Prevenir vazamento de segredos
+
+Impede que agentes visualizem ou vazem credenciais na saída de ferramentas.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+Essas políticas são acionadas no `PostToolUse` — após a execução de uma ferramenta, elas limpam a saída antes que o agente a veja.
+
+---
+
+## Receber alertas no Slack quando agentes precisam de atenção
+
+Use o hook de notificação para encaminhar alertas de inatividade ao 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 bloqueie o agente se o Slack estiver inacessível
+    }
+
+    return allow();
+  },
+});
+```
+
+Instale assim:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Manter agentes em uma branch
+
+Impede que agentes troquem de branch ou façam push em branches 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();
+  },
+});
+```
+
+---
+
+## Exigir testes antes de commits
+
+Lembra os agentes de executar os testes antes de fazer 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();
+  },
+});
+```
+
+---
+
+## Proteger um repositório de produção
+
+Faça commit de uma configuração no nível do projeto para que todos os desenvolvedores do seu time usem as mesmas políticas.
+
+Crie o arquivo `.failproofai/policies-config.json` no seu repositório:
+
+```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"]
+    }
+  }
+}
+```
+
+Em seguida, faça o commit:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Todos os membros do time que tiverem o failproofai instalado irão automaticamente receber essas regras.
+
+---
+
+## Mais exemplos
+
+O diretório [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) no repositório contém:
+
+| Arquivo | O que demonstra |
+|---------|-----------------|
+| `policies-basic.js` | Políticas iniciais — bloqueia escritas em produção, force-push e scripts redirecionados |
+| `policies-notification.js` | Alertas no Slack para notificações de inatividade e encerramento de sessão |
+| `policies-advanced/index.js` | Importações transitivas, hooks assíncronos, limpeza de saída no PostToolUse e tratamento do evento Stop |

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

@@ -0,0 +1,38 @@
+---
+title: "Para agentes"
+description: "Adicione o conhecimento do Failproof AI ao seu agente de codificação com um único comando. Funciona com Claude Code, Cursor, Windsurf e mais."
+---
+
+Adicione a referência completa do Failproof AI ao seu agente de codificação com um único comando. Funciona com Claude Code, Cursor, Windsurf e qualquer outro agente que suporte skills.
+
+```bash
+npx skills add https://docs.befailproof.ai
+```
+
+O `npx skills` detecta quais agentes você tem instalados e adiciona a skill no formato correto para cada um automaticamente.
+
+## O que a skill cobre
+
+| Área | O que está incluído |
+|------|----------------|
+| Policies | Nomes de policies integradas, tipos de eventos, parâmetros, ativar/desativar |
+| Custom policies | `customPolicies.add()`, filtros de correspondência, API `allow`/`deny`/`instruct` |
+| Objeto de contexto | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` |
+| Configuração | Estrutura do `policies-config.json`, mesclagem de escopos, `policyParams` |
+| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, escopos |
+| Dashboard | Visualizador de sessões, atividade de policies, variáveis de ambiente |
+| Arquitetura | Fluxo do hook handler, códigos de saída, contrato stdin/stdout |
+
+## A skill é completa?
+
+O Mintlify gera o `llms.txt` a partir de todas as páginas da navegação. A documentação do Failproof AI cobre a API completa — cada policy, opção e exemplo está incluído. Se você encontrar algo faltando, a fonte está em `https://docs.befailproof.ai/llms-full.txt`.
+
+Para contexto direcionado, vincule diretamente a uma página específica:
+
+```bash
+# Apenas a API de custom policies
+npx skills add https://docs.befailproof.ai/custom-policies
+
+# Apenas as policies integradas
+npx skills add https://docs.befailproof.ai/built-in-policies
+```

package/.next/standalone/docs/pt-br/getting-started.mdx

@@ -0,0 +1,134 @@
+---
+title: Primeiros passos
+description: "Instale o failproofai, ative as políticas e deixe seus agentes rodando com confiabilidade"
+icon: rocket
+---
+
+## Requisitos
+
+- **Node.js** >= 20.9.0
+- **Bun** >= 1.3.0 (opcional — necessário apenas para compilar a partir do código-fonte)
+
+---
+
+## Instalação
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+---
+
+## Início rápido
+
+<Steps>
+  <Step title="Ativar políticas">
+    Políticas são regras executadas antes e depois de cada chamada de ferramenta do agente. Elas interceptam comandos destrutivos, vazamento de segredos e outros modos de falha antes que causem danos.
+
+    ```bash
+    failproofai policies --install
+    ```
+
+    Isso grava entradas de hook no `settings.json` do Claude Code. Você também pode instalar para um único projeto ou escolher 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
+    ```
+
+    Exibe todas as políticas, se estão ativas e quaisquer parâmetros configurados.
+  </Step>
+  <Step title="Abrir o painel">
+    ```bash
+    failproofai
+    ```
+
+    Abre um painel local em `http://localhost:8020` onde você pode navegar por sessões, inspecionar chamadas de ferramentas e gerenciar políticas.
+  </Step>
+  <Step title="Executar seu agente">
+    Inicie o Claude Code normalmente. Se o agente tentar algo arriscado, o failproofai o intercepta automaticamente. Deixe-o rodando sem supervisão e revise o que aconteceu no painel.
+  </Step>
+</Steps>
+
+---
+
+## Como as políticas funcionam
+
+Toda vez que um agente executa uma ferramenta, o Claude Code chama o failproofai como um subprocesso:
+
+```text
+Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
+                                                 evaluates policies
+                                                 writes decision to stdout
+```
+
+Cada política retorna uma das três decisões:
+
+- **allow** — o agente continua normalmente
+- **deny** — a ação é bloqueada e o agente recebe uma explicação do motivo
+- **instruct** — contexto adicional é inserido no prompt do agente
+
+<Note>
+As políticas são executadas no seu processo local. Nenhuma informação é enviada para um serviço remoto.
+</Note>
+
+---
+
+## Armazenamento de dados
+
+Todas as configurações e logs ficam na sua máquina:
+
+| Caminho | O que armazena |
+|---------|----------------|
+| `~/.failproofai/policies-config.json` | Configuração global de políticas |
+| `~/.failproofai/hook-activity.jsonl` | Histórico de execução de hooks |
+| `~/.failproofai/hook.log` | Log de depuração para erros em hooks personalizados |
+| `.failproofai/policies-config.json` | Configuração por projeto (versionada) |
+| `.failproofai/policies-config.local.json` | Substituições pessoais (ignoradas pelo git) |
+
+---
+
+## Desinstalação
+
+```bash
+failproofai policies --uninstall
+```
+
+Remove as entradas de hook do `~/.claude/settings.json`. Os arquivos de configuração em `~/.failproofai/` são mantidos.
+
+---
+
+## Próximos passos
+
+<CardGroup cols={2}>
+
+<Card title="Configuração" icon="gear" href="/pt-br/configuration">
+  Escopos e formato dos arquivos de configuração
+</Card>
+
+<Card title="Políticas integradas" icon="shield" href="/pt-br/built-in-policies">
+  Todas as 26 políticas com seus parâmetros
+</Card>
+
+<Card title="Políticas personalizadas" icon="code" href="/pt-br/custom-policies">
+  Escreva suas próprias políticas em JavaScript
+</Card>
+
+<Card title="Monitor de agentes" icon="chart-line" href="/pt-br/dashboard">
+  Monitore sessões e revise a atividade das políticas
+</Card>
+
+</CardGroup>

package/.next/standalone/docs/pt-br/introduction.mdx

@@ -0,0 +1,57 @@
+---
+title: Failproof AI
+description: "Gerencie hooks e políticas que mantêm seus agentes de IA confiáveis e 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 e políticas que mantêm seus agentes de IA confiáveis e funcionando de forma autônoma - para o **Claude Code** e o **Agents SDK**.
+
+Agentes de IA falham de maneiras previsíveis. Eles executam comandos destrutivos, vazam segredos, desviam do objetivo, ficam presos em loops ou fazem push direto para a main. Sem supervisão, falhas pequenas se tornam grandes problemas.
+
+Failproof AI resolve isso com **políticas** — regras que se integram a cada chamada de ferramenta do agente e podem **detectar falhas**, **mitigá-las** (bloquear, instruir, sanitizar) e **alertar você** quando algo precisa de atenção. Um painel local permite revisar tudo posteriormente.
+
+Tudo roda localmente. Nenhum dado sai da sua máquina.
+
+## Primeiros passos
+
+<CardGroup cols={2}>
+
+<Card title="26 políticas integradas" icon="shield" href="/pt-br/built-in-policies">
+  Bloqueie comandos destrutivos, evite vazamento de segredos, mantenha os agentes dentro dos limites do projeto e muito mais — pronto para uso.
+</Card>
+
+<Card title="Políticas personalizadas" icon="code" href="/pt-br/custom-policies">
+  Escreva suas próprias regras em JavaScript com uma API simples de allow / deny / instruct.
+</Card>
+
+<Card title="Monitor de agentes" icon="chart-line" href="/pt-br/dashboard">
+  Veja o que seus agentes fizeram enquanto você estava ausente. Navegue pelas sessões, inspecione chamadas de ferramentas e revise onde as políticas foram acionadas.
+</Card>
+
+<Card title="Configuração fácil" icon="gear" href="/pt-br/configuration">
+  Ajuste qualquer política sem escrever código. Defina listas de permissão, branches protegidas ou limites por projeto ou globalmente.
+</Card>
+
+</CardGroup>
+
+## Início rápido
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # ativar políticas
+failproofai                      # iniciar o painel
+```
+
+Consulte o guia de [Primeiros passos](/pt-br/getting-started) para o passo a passo completo.