failproofai 0.0.6-beta.3 → 0.0.6-beta.4

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

@@ -1,260 +0,0 @@
----
-title: Testes
-description: "Testes unitários, testes E2E e utilitários de teste"
-icon: flask-vial
----
-
-failproofai possui duas suítes de testes: **testes unitários** (rápidos, com mocks) e **testes end-to-end** (invocações reais de subprocessos).
-
----
-
-## Executando os testes
-
-```bash
-# Executar todos os testes unitários uma vez
-bun run test:run
-
-# Executar testes unitários em modo watch
-bun run test
-
-# Executar testes E2E (requer configuração - veja abaixo)
-bun run test:e2e
-
-# Verificar tipos sem compilar
-bunx tsc --noEmit
-
-# Lint
-bun run lint
-```
-
----
-
-## Testes unitários
-
-Os testes unitários ficam em `__tests__/` e utilizam o [Vitest](https://vitest.dev) com `happy-dom`.
-
-```text
-__tests__/
-  hooks/
-    builtin-policies.test.ts      # Lógica de políticas para cada builtin
-    hooks-config.test.ts          # Carregamento de configuração e mesclagem de escopos
-    policy-evaluator.test.ts      # Injeção de parâmetros e ordem de avaliação
-    custom-hooks-registry.test.ts # Registro globalThis: add/get/clear
-    custom-hooks-loader.test.ts   # Loader ESM, imports transitivos, tratamento de erros
-    manager.test.ts               # Operações install/remove/list
-  components/
-    sessions-list.test.tsx        # Componente de lista de sessões
-    project-list.test.tsx         # Componente de lista de projetos
-    ...
-  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
-```
-
-### Escrevendo um teste unitário de 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());
-  });
-});
-```
-
----
-
-## Testes end-to-end
-
-Os testes E2E invocam o binário real do `failproofai` como subprocesso, enviam um payload JSON via stdin e verificam a saída no stdout e o código de saída. Isso testa o caminho completo de integração que o Claude Code utiliza.
-
-### Configuração
-
-Os testes E2E executam o binário diretamente do código-fonte do repositório. Antes da primeira execução, compile o bundle CJS que os arquivos de hook customizados usam ao importar de `'failproofai'`:
-
-```bash
-bun build src/index.ts --outdir dist --target node --format cjs
-```
-
-Em seguida, execute os testes:
-
-```bash
-bun run test:e2e
-```
-
-Recompile o `dist/` sempre que alterar a API pública de hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` ou `src/hooks/policy-types.ts`).
-
-### Estrutura dos testes E2E
-
-```text
-__tests__/e2e/
-  helpers/
-    hook-runner.ts      # Inicia o binário, envia payload JSON, captura código de saída + stdout + stderr
-    fixture-env.ts      # Diretórios temporários isolados por teste com arquivos de configuração
-    payloads.ts         # Fábricas de payload compatíveis com Claude para cada tipo de evento
-  hooks/
-    builtin-policies.e2e.test.ts   # Cada política builtin com subprocesso real
-    custom-hooks.e2e.test.ts       # Carregamento e avaliação de hooks customizados
-    config-scopes.e2e.test.ts      # Mesclagem de configuração entre escopos project/local/global
-    policy-params.e2e.test.ts      # Injeção de parâmetros para cada política parametrizada
-```
-
-### Usando os utilitários E2E
-
-**`FixtureEnv`** - ambiente isolado por teste:
-
-```typescript
-import { createFixtureEnv } from "../helpers/fixture-env";
-
-const env = createFixtureEnv();
-// env.cwd    - diretório temporário; passe como payload.cwd para carregar .failproofai/policies-config.json
-// env.home   - home isolado; evita vazamento do ~/.failproofai real
-
-env.writeConfig({
-  enabledPolicies: ["block-sudo"],
-  policyParams: {
-    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
-  },
-});
-```
-
-`createFixtureEnv()` registra a limpeza via `afterEach` automaticamente.
-
-**`runHook`** - invoca o binário:
-
-```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`** - fábricas de payload prontas para uso:
-
-```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)
-```
-
-### Escrevendo um teste 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 vazio
-  });
-});
-```
-
-### Formatos de resposta E2E
-
-| Decisão | Código de saída | stdout |
-|----------|-----------|--------|
-| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
-| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
-| Instruct (não-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
-| Stop instruct | `2` | stdout vazio; motivo no stderr |
-| Allow | `0` | string vazia |
-
-### Configuração do Vitest
-
-Os testes E2E utilizam `vitest.config.e2e.mts` com:
-
-- `environment: "node"` - sem necessidade de globals do navegador
-- `pool: "forks"` - isolamento real de processos (os testes iniciam subprocessos)
-- `testTimeout: 20_000` - 20s por teste (inicialização do binário + avaliação do hook)
-
-O pool `forks` é importante: workers baseados em threads compartilham `globalThis`, o que pode interferir com testes que iniciam subprocessos. Forks baseados em processos evitam esse problema.
-
----
-
-## CI
-
-A execução completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) deve passar antes do merge. A suíte E2E é executada como um job de CI separado, em paralelo.
-
-Consulte [Contributing](../CONTRIBUTING.md) para o checklist completo de pré-merge.

package/.next/standalone/docs/ru/architecture.mdx

@@ -1,333 +0,0 @@
----
----
-title: Архитектура
-description: "Как работают обработчик хуков, загрузка конфига и оценка политик"
-icon: sitemap
----
-
-Этот документ объясняет, как работает failproofai изнутри: как система хуков перехватывает вызовы инструментов агента, как загружается и объединяется конфигурация, как оцениваются политики и как панель мониторинга отслеживает активность агента.
-
----
-
-## Обзор
-
-failproofai состоит из двух независимых подсистем:
-
-1. **Hook handler** — быстрый CLI подпроцесс, который Claude Code вызывает при каждом вызове инструмента агента. Оценивает политики и возвращает решение.
-2. **Agent Monitor (Dashboard)** — веб-приложение Next.js для мониторинга сессий агента и управления политиками.
-
-Обе подсистемы совместно используют файлы конфигурации в `~/.failproofai/` и в директории проекта `.failproofai/`, но работают как отдельные процессы и взаимодействуют только через файловую систему.
-
----
-
-## Hook handler
-
-### Интеграция с Claude Code
-
-Когда вы запускаете `failproofai policies --install`, он записывает записи подобно этой в `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "failproofai --hook PreToolUse"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [ ... ]
-  }
-}
-```
-
-Claude Code затем вызывает `failproofai --hook PreToolUse` как подпроцесс перед каждым вызовом инструмента, передавая JSON-полезную нагрузку на stdin.
-
-### Формат полезной нагрузки
-
-```json
-{
-  "session_id": "abc123",
-  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
-  "cwd": "/home/user/myproject",
-  "permission_mode": "default",
-  "hook_event_name": "PreToolUse",
-  "tool_name": "Bash",
-  "tool_input": { "command": "sudo apt install nodejs" }
-}
-```
-
-Для событий `PostToolUse` полезная нагрузка также содержит `tool_result` с результатом работы инструмента.
-
-Обработчик устанавливает лимит stdin в 1 МБ. Полезные нагрузки, превышающие этот лимит, отбрасываются и все политики неявно разрешают операцию.
-
-### Формат ответа
-
-**Deny (PreToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "permissionDecision": "deny",
-    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
-  }
-}
-```
-
-**Deny (PostToolUse):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Blocked by failproofai because: API key detected in output"
-  }
-}
-```
-
-**Instruct (любое событие, кроме Stop):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-
-**Instruct для события Stop:**
-- Код выхода: `2`
-- Причина выводится в stderr (не в stdout)
-
-**Allow:**
-- Код выхода: `0`
-- Пустой stdout
-
-**Allow с сообщением:**
-
-`allow(message)` позволяет политике отправлять информационный контекст обратно в Claude даже когда операция разрешена. Обработчик хуков записывает следующий JSON в **stdout** (не в файл конфига — это ответ обработчика для Claude Code, как и ответы deny и instruct выше):
-
-```json
-// Написано в stdout процессом обработчика хуков
-{
-  "hookSpecificOutput": {
-    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
-  }
-}
-```
-- Код выхода: `0` (операция разрешена)
-- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются с переводами строк в один string `additionalContext`
-- Если ни одна политика не предоставляет сообщение, stdout пуст (как и раньше)
-
-### Конвейер обработки
-
-`src/hooks/handler.ts` реализует полный конвейер:
-
-```text
-stdin JSON
-  → parse payload (max 1 MB)
-  → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
-  → readMergedHooksConfig(cwd)    ← merges project + local + global config
-  → register enabled builtin policies with resolved params
-  → load custom policies from customPoliciesPath (if set)
-  → register custom policies into policy registry
-  → evaluate all policies (builtins first, then custom)
-      → first deny short-circuits
-      → instruct decisions accumulate
-      → allow messages accumulate
-  → write JSON decision to stdout
-  → persist event to ~/.failproofai/hook-activity.jsonl
-  → exit
-```
-
-Весь процесс выполняется менее чем за 100 мс для типичных полезных нагрузок без вызовов LLM.
-
----
-
-## Загрузка конфигурации
-
-`src/hooks/hooks-config.ts` реализует загрузку конфигурации в трёх областях.
-
-```text
-[1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
-[2] {cwd}/.failproofai/policies-config.local.json  ← local
-[3] ~/.failproofai/policies-config.json             ← global   (lowest priority)
-```
-
-Логика объединения:
-- `enabledPolicies` — дедублицированное объединение всех трёх файлов
-- `policyParams` — по ключу политики, первый файл, который его определяет, получает полный приоритет
-- `customPoliciesPath` — первый файл, который его определяет, получает приоритет
-- `llm` — первый файл, который его определяет, получает приоритет
-
-Веб-панель использует `readHooksConfig()` (только глобальный) для чтения и записи, поскольку она вызывается без cwd проекта.
-
----
-
-## Оценка политик
-
-`src/hooks/policy-evaluator.ts` запускает политики по порядку.
-
-Для каждой политики:
-
-1. Поиск схемы `params` политики (если она есть).
-2. Чтение `policyParams[policy.name]` из объединённой конфигурации.
-3. Объединение предоставленных пользователем значений со значениями по умолчанию из схемы для создания `ctx.params`.
-4. Вызов `policy.fn(ctx)` с разрешённым контекстом.
-5. Если результат `deny`, остановиться немедленно и вернуть это решение.
-6. Если результат `instruct`, накопить сообщение и продолжить.
-7. Если результат `allow`, перейти к следующей политике.
-
-После выполнения всех политик:
-- Если была возвращена какая-либо `deny`, вывести ответ deny.
-- Если были собраны какие-либо `instruct`, вывести один ответ instruct со всеми объединёнными сообщениями.
-- В противном случае вывести ответ allow (пустой stdout, выход 0).
-
----
-
-## Встроенные политики
-
-`src/hooks/builtin-policies.ts` определяет все 26 встроенных политик как объекты `BuiltinPolicyDefinition`:
-
-```typescript
-interface BuiltinPolicyDefinition {
-  name: string;
-  description: string;
-  fn: (ctx: PolicyContext) => PolicyResult;
-  match: {
-    events: HookEventType[];
-    tools?: string[];
-  };
-  defaultEnabled: boolean;
-  category: string;
-  beta?: boolean;
-  params?: PolicyParamsSchema;
-}
-```
-
-Политики, которые принимают `params`, объявляют `PolicyParamsSchema` с типами и значениями по умолчанию для каждого параметра. Оценщик политик внедряет разрешённые значения в `ctx.params` перед вызовом `fn`. Функции политик читают `ctx.params` без проверки на null, поскольку значения по умолчанию всегда применяются в первую очередь.
-
-Сопоставление шаблонов внутри политик использует разобранные токены команды (argv), а не простое совпадение строк. Это предотвращает обход с помощью инъекции оператора оболочки (например, шаблон для `sudo systemctl status *` не может быть обойден путём добавления `; rm -rf /` к команде).
-
----
-
-## Пользовательские политики
-
-`src/hooks/custom-hooks-registry.ts` реализует реестр, поддерживаемый `globalThis`:
-
-```typescript
-const REGISTRY_KEY = "__failproofai_custom_hooks__";
-
-export const customPolicies = {
-  add(hook: CustomHook): void { ... }
-};
-
-export function getCustomHooks(): CustomHook[] { ... }
-export function clearCustomHooks(): void { ... }  // used in tests
-```
-
-`src/hooks/custom-hooks-loader.ts` загружает файл политики пользователя:
-
-1. Чтение `customPoliciesPath` из конфигурации; пропуск, если отсутствует.
-2. Разрешение в абсолютный путь; проверка существования файла.
-3. Переписывание всех импортов `from "failproofai"` на фактический путь dist, чтобы `customPolicies` разрешался в одинаковый реестр `globalThis`.
-4. Рекурсивное переписывание переходных локальных импортов для обеспечения совместимости ESM.
-5. Запись временных файлов `.mjs` и `import()` файла входа.
-6. Вызов `getCustomHooks()` для получения зарегистрированных хуков.
-7. Очистка всех временных файлов в блоке `finally`.
-
-При любой ошибке (файл не найден, синтаксическая ошибка, ошибка импорта) ошибка регистрируется в `~/.failproofai/hook.log` и загрузчик возвращает пустой массив. Встроенные политики не затрагиваются.
-
-Пользовательские политики оцениваются после всех встроенных политик. Пользовательская политика `deny` по-прежнему прерывает дальнейшие пользовательские политики (но к тому моменту все встроенные уже выполнены).
-
----
-
-## Логирование активности
-
-После каждого события хука обработчик добавляет строку JSONL в `~/.failproofai/hook-activity.jsonl`:
-
-```json
-{
-  "timestamp": "2026-04-06T12:34:56.789Z",
-  "sessionId": "abc123",
-  "eventType": "PreToolUse",
-  "toolName": "Bash",
-  "policyName": "block-sudo",
-  "decision": "deny",
-  "reason": "sudo command blocked by failproofai",
-  "durationMs": 12
-}
-```
-
-По одной строке на каждую политику, которая приняла решение, отличное от allow. Решения allow не регистрируются (чтобы держать файл в разумном размере).
-
----
-
-## Архитектура панели
-
-Панель — это приложение **Next.js 16** с использованием App Router, React Server Components и Server Actions.
-
-```text
-app/
-  layout.tsx                  ← Root layout (theme, telemetry, nav)
-  projects/page.tsx           ← Server component: list all Claude projects
-  project/[name]/page.tsx     ← Server component: list sessions in a project
-  project/[name]/session/
-    [sessionId]/page.tsx      ← Server component: render session viewer
-  policies/page.tsx           ← Client component: policy management + activity log
-  actions/
-    get-hooks-config.ts       ← Read config + policy list
-    update-hooks-config.ts    ← Toggle policy on/off
-    update-policy-params.ts   ← Update policy parameters
-    get-hook-activity.ts      ← Paginate/search activity log
-    install-hooks-web.ts      ← Install/remove hooks from the browser
-  api/
-    download/[project]/[session]/route.ts   ← Export session as ZIP/JSONL
-```
-
-**Поток данных:**
-
-- Компоненты страниц вызывают `lib/projects.ts` и `lib/log-entries.ts` для чтения данных проекта/сессии непосредственно из файловой системы (без слоя API для чтения).
-- Страница Policies использует Server Actions для всех изменений (переключение, обновление параметров, установка/удаление).
-- Просмотрщик сессии анализирует формат JSONL транскрипта Claude и отображает временную шкалу сообщений и вызовов инструментов.
-
-**Ключевые решения проектирования:**
-
-- Нет базы данных — всё постоянное состояние хранится в простых файлах (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions для изменений — REST API не требуется для CRUD операций.
-- React Server Components для страниц чтения — более быстрая начальная загрузка, без клиентского пакета для получения данных.
-- Клиентские компоненты только где требуется интерактивность (переключение политик, поиск по активности, просмотр логов).
-
----
-
-## Структура файлов
-
-```text
-failproofai/
-├── bin/
-│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
-├── src/hooks/
-│   ├── handler.ts                # Hook event pipeline
-│   ├── builtin-policies.ts       # 26 policy definitions
-│   ├── policy-evaluator.ts       # Policy execution engine
-│   ├── policy-registry.ts        # Policy registration and lookup
-│   ├── policy-types.ts           # TypeScript interfaces
-│   ├── hooks-config.ts           # Multi-scope config loading
-│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
-│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
-│   ├── manager.ts                # install / remove / list operations
-│   ├── install-prompt.ts         # Interactive policy selection prompt
-│   ├── hook-logger.ts            # Logging to hook.log
-│   ├── hook-activity-store.ts    # Persist activity to hook-activity.jsonl
-│   └── llm-client.ts             # LLM API client (for AI-powered policies)
-├── app/                          # Next.js dashboard (pages + server actions)
-├── lib/                          # Shared utilities
-│   ├── projects.ts               # Enumerate Claude projects from filesystem
-│   ├── log-entries.ts            # Parse Claude transcript JSONL format
-│   ├── paths.ts                  # Resolve system paths
-│   └── ...
-├── components/                   # Shared React UI components
-├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
-├── examples/                     # Example custom hook files
-└── __tests__/                    # Unit and E2E tests
-```