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

package/.next/standalone/docs/pt-br/custom-policies.mdx

@@ -1,353 +0,0 @@
----
-title: Políticas Personalizadas
-description: "Escreva suas próprias políticas em JavaScript — aplique convenções, evite desvios, detecte falhas e integre com sistemas externos"
-icon: code
----
-
-As políticas personalizadas permitem criar regras para qualquer comportamento do agente: aplicar convenções do projeto, evitar desvios, bloquear operações destrutivas, detectar agentes travados ou integrar com Slack, fluxos de aprovação e muito mais. Elas utilizam o mesmo sistema de eventos de hook e as mesmas decisões `allow`, `deny` e `instruct` das políticas integradas.
-
----
-
-## Exemplo 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();
-  },
-});
-```
-
-Instale com:
-
-```bash
-failproofai policies --install --custom ./my-policies.js
-```
-
----
-
-## Duas formas de carregar políticas personalizadas
-
-### Opção 1: Baseada em convenção (recomendada)
-
-Coloque arquivos `*policies.{js,mjs,ts}` na pasta `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como git hooks: adicione o arquivo e pronto.
-
-```
-# Nível do projeto — commitado no git, compartilhado com o time
-.failproofai/policies/security-policies.mjs
-.failproofai/policies/workflow-policies.mjs
-
-# Nível do usuário — pessoal, aplicado a todos os projetos
-~/.failproofai/policies/my-policies.mjs
-```
-
-**Como funciona:**
-- Tanto o diretório do projeto quanto o do usuário são verificados (união — sem prioridade por escopo)
-- Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use prefixos como `01-`, `02-` para controlar a ordem
-- Apenas arquivos que correspondem ao padrão `*policies.{js,mjs,ts}` são carregados; os demais são ignorados
-- Cada arquivo é carregado de forma independente (fail-open por arquivo)
-- Funciona junto com `--custom` explícito e políticas integradas
-
-<Tip>
-As políticas por convenção são a forma mais fácil de estabelecer um padrão de qualidade para sua organização. Faça commit de `.failproofai/policies/` no git e todos os membros do time receberão as mesmas regras automaticamente — sem configuração individual. À medida que o time identifica novos modos de falha, adicione uma política e faça push. Com o tempo, elas se tornam um padrão de qualidade vivo que melhora a cada contribuição.
-</Tip>
-
-### Opção 2: Caminho de arquivo explícito
-
-```bash
-# Instalar com um arquivo de políticas personalizado
-failproofai policies --install --custom ./my-policies.js
-
-# Substituir o caminho do arquivo de políticas
-failproofai policies --install --custom ./new-policies.js
-
-# Remover o caminho de políticas personalizado da configuração
-failproofai policies --uninstall --custom
-```
-
-O caminho absoluto resolvido é armazenado em `policies-config.json` como `customPoliciesPath`. O arquivo é carregado novamente a cada evento de hook — não há cache entre eventos.
-
-### Usando os dois juntos
-
-As políticas por convenção e o arquivo `--custom` explícito podem coexistir. Ordem de carregamento:
-
-1. Arquivo `customPoliciesPath` explícito (se configurado)
-2. Arquivos de convenção do projeto (`{cwd}/.failproofai/policies/`, em ordem alfabética)
-3. Arquivos de convenção do usuário (`~/.failproofai/policies/`, em ordem alfabética)
-
----
-
-## API
-
-### Importação
-
-```js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-```
-
-### `customPolicies.add(hook)`
-
-Registra uma política. Chame quantas vezes forem necessárias para múltiplas políticas no mesmo arquivo.
-
-```ts
-customPolicies.add({
-  name: string;                         // obrigatório - identificador único
-  description?: string;                 // exibido na saída de `failproofai policies`
-  match?: { events?: HookEventType[] }; // filtra por tipo de evento; omita para corresponder a todos
-  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
-});
-```
-
-### Funções auxiliares de decisão
-
-| Função | Efeito | Quando usar |
-|----------|--------|----------|
-| `allow()` | Permite a operação silenciosamente | A ação é segura e não precisa de mensagem |
-| `deny(message)` | Bloqueia a operação | O agente não deve executar esta ação |
-| `instruct(message)` | Adiciona contexto sem bloquear | Fornece contexto adicional ao agente para mantê-lo no caminho certo |
-
-`deny(message)` — a mensagem é exibida para o Claude com o prefixo `"Blocked by failproofai:"`. Um único `deny` interrompe toda avaliação subsequente.
-
-`instruct(message)` — a mensagem é adicionada ao contexto do Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas.
-
-<Tip>
-Você pode adicionar orientações extras a qualquer mensagem `deny` ou `instruct` incluindo um campo `hint` em `policyParams` — sem necessidade de alterar o código. Isso funciona também para políticas personalizadas (`custom/`), por convenção do projeto (`.failproofai-project/`) e por convenção do usuário (`.failproofai-user/`). Consulte [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para mais detalhes.
-</Tip>
-
-### Mensagens informativas de allow
-
-`allow(message)` permite a operação **e** envia uma mensagem informativa de volta ao Claude. A mensagem é entregue como `additionalContext` na resposta stdout do handler de hook — o mesmo mecanismo usado por `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso.
-
-| Função | Efeito | Quando usar |
-|----------|--------|----------|
-| `allow(message)` | Permite e envia contexto ao Claude | Confirmar que uma verificação passou, ou explicar por que foi ignorada |
-
-Casos de uso:
-- **Confirmações de status:** `allow("All CI checks passed.")` — informa ao Claude que tudo está em ordem
-- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa ao Claude por que uma verificação foi ignorada, garantindo contexto completo
-- **Múltiplas mensagens são acumuladas:** se várias políticas retornarem `allow(message)`, todas as mensagens são unidas com quebras de linha e entregues juntas
-
-```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 | Descrição |
-|-------|------|-------------|
-| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
-| `toolName` | `string \| undefined` | A ferramenta sendo chamada (ex.: `"Bash"`, `"Write"`, `"Read"`) |
-| `toolInput` | `Record<string, unknown> \| undefined` | Os parâmetros de entrada da ferramenta |
-| `payload` | `Record<string, unknown>` | Payload bruto completo do evento do Claude Code |
-| `session` | `SessionMetadata \| undefined` | Contexto da sessão (veja abaixo) |
-
-### Campos de `SessionMetadata`
-
-| Campo | Tipo | Descrição |
-|-------|------|-------------|
-| `sessionId` | `string` | Identificador da sessão do Claude Code |
-| `cwd` | `string` | Diretório de trabalho da sessão do Claude Code |
-| `transcriptPath` | `string` | Caminho para o arquivo de transcrição JSONL da sessão |
-
-### Tipos de evento
-
-| Evento | Quando é disparado | Conteúdo de `toolInput` |
-|-------|--------------|----------------------|
-| `PreToolUse` | Antes do Claude executar uma ferramenta | A entrada da ferramenta (ex.: `{ command: "..." }` para Bash) |
-| `PostToolUse` | Após a conclusão de uma ferramenta | A entrada da ferramenta + `tool_result` (a saída) |
-| `Notification` | Quando o Claude envia uma notificação | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — hooks sempre devem retornar `allow()`, não podem bloquear notificações |
-| `Stop` | Quando a sessão do Claude é encerrada | Vazio |
-
----
-
-## Ordem de avaliação
-
-As políticas são avaliadas nesta ordem:
-
-1. Políticas integradas (na ordem de definição)
-2. Políticas personalizadas explícitas de `customPoliciesPath` (na ordem de `.add()`)
-3. Políticas por convenção do projeto em `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo)
-4. Políticas por convenção do usuário em `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo)
-
-<Note>
-O primeiro `deny` interrompe todas as políticas subsequentes. Todas as mensagens `instruct` são acumuladas e entregues juntas.
-</Note>
-
----
-
-## Importações transitivas
-
-Arquivos de política personalizados podem importar módulos locais usando caminhos relativos:
-
-```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");
-  },
-});
-```
-
-Todas as importações relativas acessíveis a partir do arquivo de entrada são resolvidas. Isso é implementado reescrevendo as importações `from "failproofai"` para o caminho real de dist e criando arquivos `.mjs` temporários para garantir compatibilidade com ESM.
-
----
-
-## Filtragem por tipo de evento
-
-Use `match.events` para limitar quando uma política é acionada:
-
-```js
-customPolicies.add({
-  name: "require-summary-on-stop",
-  match: { events: ["Stop"] },
-  fn: async (ctx) => {
-    // Só é acionado quando a sessão é encerrada
-    // ctx.session.transcriptPath contém o log completo da sessão
-    return allow();
-  },
-});
-```
-
-Omita `match` completamente para acionar em todos os tipos de evento.
-
----
-
-## Tratamento de erros e modos de falha
-
-As políticas personalizadas são **fail-open**: erros nunca bloqueiam as políticas integradas nem causam falha no handler de hook.
-
-| Falha | Comportamento |
-|---------|----------|
-| `customPoliciesPath` não configurado | Nenhuma política personalizada explícita é executada; políticas por convenção e integradas continuam normalmente |
-| Arquivo não encontrado | Aviso registrado em `~/.failproofai/hook.log`; políticas integradas continuam |
-| Erro de sintaxe/importação (explícito) | Erro registrado em `~/.failproofai/hook.log`; políticas personalizadas explícitas são ignoradas |
-| Erro de sintaxe/importação (convenção) | Erro registrado; aquele arquivo é ignorado, os demais arquivos de convenção continuam carregando |
-| `fn` lança erro em tempo de execução | Erro registrado; aquele hook é tratado como `allow`; os demais hooks continuam |
-| `fn` demora mais de 10s | Timeout registrado; tratado como `allow` |
-| Diretório de convenção ausente | Nenhuma política por convenção é executada; sem erro |
-
-<Tip>
-Para depurar erros em políticas personalizadas, monitore o arquivo de log:
-
-```bash
-tail -f ~/.failproofai/hook.log
-```
-</Tip>
-
----
-
-## Exemplo completo: múltiplas políticas
-
-```js
-// my-policies.js
-import { customPolicies, allow, deny, instruct } from "failproofai";
-
-// Impede o agente de escrever no diretório secrets/
-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();
-  },
-});
-
-// Mantém o agente no caminho certo: verifica testes antes de commitar
-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();
-  },
-});
-
-// Impede mudanças de dependências não planejadas durante o período de 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 };
-```
-
----
-
-## Exemplos
-
-O diretório `examples/` contém arquivos de política prontos para uso:
-
-| Arquivo | Conteúdo |
-|------|----------|
-| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos de falha comuns de agentes |
-| `examples/policies-advanced/index.js` | Padrões avançados: importações transitivas, chamadas assíncronas, limpeza de saída e hooks de encerramento de sessão |
-| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloquear escritas em .env, impedir reescrita do histórico git) |
-| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho baseadas em convenção (lembretes de teste, auditoria de escritas em arquivo) |
-
-### Usando exemplos com arquivo explícito
-
-```bash
-failproofai policies --install --custom ./examples/policies-basic.js
-```
-
-### Usando exemplos baseados em convenção
-
-```bash
-# Copiar para o nível do projeto
-mkdir -p .failproofai/policies
-cp examples/convention-policies/*.mjs .failproofai/policies/
-
-# Ou copiar para o nível do usuário
-mkdir -p ~/.failproofai/policies
-cp examples/convention-policies/*.mjs ~/.failproofai/policies/
-```
-
-Nenhum comando de instalação é necessário — os arquivos são detectados automaticamente no próximo evento de hook.

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

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