failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,82 @@
+---
+title: Aliases de Pacotes
+description: "Aliases registrados para prevenção de typosquatting e como funcionam"
+icon: copy
+---
+
+## Pacote oficial
+
+O pacote npm canônico é **`failproofai`**:
+
+```bash
+npm install -g failproofai
+# ou
+bun add -g failproofai
+```
+
+---
+
+## Por que somos donos dos nomes de alias
+
+Typosquatting é um ataque comum à cadeia de suprimentos de software, no qual um agente malicioso registra um nome de pacote que difere por apenas um caractere de um pacote popular. Usuários desatentos que digitam errado o comando de instalação acabam executando código controlado pelo atacante com acesso total ao sistema — exatamente o tipo de ameaça que o Failproof AI foi criado para combater.
+
+Para eliminar essa superfície de ataque, **registramos preventivamente todos os erros ortográficos comuns e variantes de formatação** de `failproofai` no npm. Nenhum desses nomes pode ser registrado por terceiros. Cada um deles é um proxy simples que instala e delega ao pacote real `failproofai`.
+
+---
+
+## Aliases registrados
+
+**Variantes de formatação** — diferentes formas de escrever "failproof ai":
+
+| Pacote | Status |
+|--------|--------|
+| `failproof` | ✅ Publicado |
+| `failproof-ai` | ⏳ Aguardando suporte do npm |
+| `fail-proof-ai` | ⏳ Aguardando suporte do npm |
+| `failproof_ai` | ⏳ Aguardando suporte do npm |
+| `fail_proof_ai` | ⏳ Aguardando suporte do npm |
+| `fail-proofai` | ⏳ Aguardando suporte do npm |
+
+**Erros de digitação `failprof*`** — falta um `o` em "proof":
+
+| Pacote | Status |
+|--------|--------|
+| `failprof` | ✅ Publicado |
+| `failprof-ai` | ✅ Publicado |
+| `failprofai` | ⏳ Aguardando suporte do npm |
+| `fail-prof-ai` | ⏳ Aguardando suporte do npm |
+| `failprof_ai` | ⏳ Aguardando suporte do npm |
+
+**Erros de digitação `faliproof*`** — `a` e `i` invertidos:
+
+| Pacote | Status |
+|--------|--------|
+| `faliproof` | ✅ Publicado |
+| `faliproof-ai` | ✅ Publicado |
+| `faliproofai` | ⏳ Aguardando suporte do npm |
+
+> **Por que "aguardando"?** A política de prevenção de spam do npm bloqueia nomes que, após remoção de pontuação e verificações de similaridade, resultam na mesma string de um pacote já existente. Entramos em contato com o suporte do npm para reservar esses nomes com fins anti-typosquatting. Eles serão ativados após aprovação.
+
+Você pode verificar que qualquer alias publicado pertence a nós:
+
+```bash
+npm info failproof
+# Procure por: "ExosphereHost Inc." no campo maintainers
+```
+
+---
+
+## Como os aliases funcionam
+
+Cada pacote alias:
+
+1. Lista `failproofai` como dependência — assim, o pacote real (incluindo a configuração do hook `postinstall`) é executado durante a instalação
+2. Expõe um binário com seu próprio nome (por exemplo, `failprof-ai`) que repassa todos os argumentos para o binário `failproofai`
+
+O proxy é um script Node de duas linhas; não há lógica adicional, chamadas de rede nem coleta de dados além do que o próprio `failproofai` realiza.
+
+---
+
+## Se você encontrar um nome que esquecemos
+
+Abra uma issue em [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) e nós o registraremos.

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

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

@@ -0,0 +1,334 @@
+---
+
+---
+title: Архитектура
+description: "Как работают обработчик хука, загрузка конфигурации и оценка политик"
+icon: sitemap
+---
+
+В этом документе объясняется, как failproofai работает внутренне: как система хуков перехватывает вызовы инструментов агента, как загружается и объединяется конфигурация, как оцениваются политики и как панель мониторинга отслеживает активность агента.
+
+---
+
+## Обзор
+
+failproofai состоит из двух независимых подсистем:
+
+1. **Обработчик хука** — быстрый CLI подпроцесс, который Claude Code вызывает при каждом вызове инструмента агента. Оценивает политики и возвращает решение.
+2. **Agent Monitor (Dashboard)** — веб-приложение Next.js для мониторинга сеансов агента и управления политиками.
+
+Обе подсистемы совместно используют файлы конфигурации в `~/.failproofai/` и в директории `.failproofai/` проекта, но работают как отдельные процессы и общаются только через файловую систему.
+
+---
+
+## Обработчик хука
+
+### Интеграция с 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` с выходом инструмента.
+
+Обработчик устанавливает ограничение входного потока в 1 МБ. Полезные нагрузки, превышающие этот лимит, отбрасываются и все политики неявно разрешают операцию.
+
+### Формат ответа
+
+**Отклонить (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Отклонить (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Инструкция (любое событие кроме Stop):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Инструкция события Stop:**
+- Код выхода: `2`
+- Причина записана в stderr (не stdout)
+
+**Разрешить:**
+- Код выхода: `0`
+- Пустой stdout
+
+**Разрешить с сообщением (beta):**
+
+Начиная с версии v0.0.2-beta.3, `allow(message)` позволяет политике отправить контекстную информацию в Claude, даже если операция разрешена. Обработчик хука записывает в **stdout** следующий JSON (не в файл конфигурации — это ответ обработчика на Claude Code, как и ответы deny и instruct выше):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Код выхода: `0` (операция разрешена)
+- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются с переносами строк в единую строку `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()` (только глобальная) для чтения и записи, так как она не вызывается с рабочей директорией проекта.
+
+---
+
+## Оценка политик
+
+`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
+```