failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,260 @@
+---
+title: Тестирование
+description: "Модульные тесты, E2E тесты и вспомогательные инструменты для тестирования"
+icon: flask-vial
+---
+
+failproofai имеет два набора тестов: **модульные тесты** (быстрые, с моками) и **сквозные тесты** (реальные вызовы подпроцессов).
+
+---
+
+## Запуск тестов
+
+```bash
+# Запустить все модульные тесты один раз
+bun run test:run
+
+# Запустить модульные тесты в режиме наблюдения
+bun run test
+
+# Запустить E2E тесты (требуется подготовка - см. ниже)
+bun run test:e2e
+
+# Проверка типов без сборки
+bunx tsc --noEmit
+
+# Проверка кода
+bun run lint
+```
+
+---
+
+## Модульные тесты
+
+Модульные тесты находятся в `__tests__/` и используют [Vitest](https://vitest.dev) с `happy-dom`.
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # Логика политик для каждой встроенной
+    hooks-config.test.ts          # Загрузка конфига и объединение областей
+    policy-evaluator.test.ts      # Внедрение параметров и порядок оценки
+    custom-hooks-registry.test.ts # Реестр globalThis добавления/получения/очистки
+    custom-hooks-loader.test.ts   # ESM загрузчик, транзитивные импорты, обработка ошибок
+    manager.test.ts               # Операции установки/удаления/списания
+  components/
+    sessions-list.test.tsx        # Компонент списка сессий
+    project-list.test.tsx         # Компонент списка проектов
+    ...
+  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
+```
+
+### Написание модульного теста политики
+
+```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());
+  });
+});
+```
+
+---
+
+## Сквозные тесты
+
+E2E тесты вызывают реальный бинарный файл `failproofai` как подпроцесс, передают JSON-полезную нагрузку в stdin и проверяют выходные данные stdout и код выхода. Это тестирует полный путь интеграции, который использует Claude Code.
+
+### Подготовка
+
+E2E тесты запускают бинарный файл непосредственно из исходного кода репозитория. Перед первым запуском соберите CJS-пакет, который используют файлы пользовательских хуков при импорте из `'failproofai'`:
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+Затем запустите тесты:
+
+```bash
+bun run test:e2e
+```
+
+Пересобирайте `dist/` всякий раз, когда вы изменяете публичный API хуков (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` или `src/hooks/policy-types.ts`).
+
+### Структура E2E теста
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # Запуск бинарного файла, передача полезной нагрузки JSON, захват кода выхода + stdout + stderr
+    fixture-env.ts      # Изолированные на тест временные каталоги с файлами конфига
+    payloads.ts         # Фабрики полезных нагрузок с точностью Claude для каждого типа события
+  hooks/
+    builtin-policies.e2e.test.ts   # Каждая встроенная политика с реальным подпроцессом
+    custom-hooks.e2e.test.ts       # Загрузка и оценка пользовательских хуков
+    config-scopes.e2e.test.ts      # Объединение конфига между проектом/локальным/глобальным
+    policy-params.e2e.test.ts      # Внедрение параметров для каждой параметризованной политики
+```
+
+### Использование E2E вспомогательных инструментов
+
+**`FixtureEnv`** - изолированная среда для каждого теста:
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - временный каталог; передайте как payload.cwd для использования .failproofai/policies-config.json
+// env.home   - изолированный домашний каталог; нет утечек реального ~/.failproofai
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` автоматически регистрирует очистку `afterEach`.
+
+**`runHook`** - запуск бинарного файла:
+
+```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`** - готовые фабрики полезных нагрузок:
+
+```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)
+```
+
+### Написание 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
+  });
+});
+```
+
+### Формы ответов E2E
+
+| Решение | Код выхода | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct (не-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | пустой stdout; причина в stderr |
+| Allow | `0` | пустая строка |
+
+### Конфигурация Vitest
+
+E2E тесты используют `vitest.config.e2e.mts` с:
+
+- `environment: "node"` - глобальные переменные браузера не требуются
+- `pool: "forks"` - истинная изоляция процессов (тесты запускают подпроцессы)
+- `testTimeout: 20_000` - 20 сек на тест (запуск бинарного файла + оценка хука)
+
+Пул `forks` важен: рабочие потоки используют совместно `globalThis`, что может помешать тестам, запускающим подпроцессы. Процессные fork избегают этой проблемы.
+
+---
+
+## CI
+
+Полный запуск CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) должен пройти перед слиянием. Набор E2E запускается как отдельная задача CI параллельно.
+
+См. [Contributing](../CONTRIBUTING.md) для полного контрольного списка перед слиянием.

package/.next/standalone/docs/{testing.md → testing.mdx}

@@ -17,7 +17,7 @@ bun run test:run
 # Run unit tests in watch mode
 bun run test
 
-# Run E2E tests (requires setup — see below)
+# Run E2E tests (requires setup - see below)
 bun run test:e2e
 
 # Type-check without building
@@ -33,7 +33,7 @@ bun run lint
 
 Unit tests live in `__tests__/` and use [Vitest](https://vitest.dev) with `happy-dom`.
 
-```
+```text
 __tests__/
   hooks/
     builtin-policies.test.ts      # Policy logic for each builtin
@@ -130,7 +130,7 @@ Rebuild `dist/` whenever you change the public hook API (`src/hooks/custom-hooks
 
 ### E2E test structure
 
-```
+```text
 __tests__/e2e/
   helpers/
     hook-runner.ts      # Spawn the binary, pipe payload JSON, capture exit code + stdout + stderr
@@ -145,14 +145,14 @@ __tests__/e2e/
 
 ### Using the E2E helpers
 
-**`FixtureEnv`** — isolated per-test environment:
+**`FixtureEnv`** - isolated per-test environment:
 
 ```typescript
 import { createFixtureEnv } from "../helpers/fixture-env";
 
 const env = createFixtureEnv();
-// env.cwd    — temp dir; pass as payload.cwd to pick up .failproofai/policies-config.json
-// env.home   — isolated home dir; no real ~/.failproofai leaks in
+// env.cwd    - temp dir; pass as payload.cwd to pick up .failproofai/policies-config.json
+// env.home   - isolated home dir; no real ~/.failproofai leaks in
 
 env.writeConfig({
   enabledPolicies: ["block-sudo"],
@@ -164,7 +164,7 @@ env.writeConfig({
 
 `createFixtureEnv()` registers `afterEach` cleanup automatically.
 
-**`runHook`** — invoke the binary:
+**`runHook`** - invoke the binary:
 
 ```typescript
 import { runHook } from "../helpers/hook-runner";
@@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0);
 expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
 ```
 
-**`Payloads`** — ready-made payload factories:
+**`Payloads`** - ready-made payload factories:
 
 ```typescript
 Payloads.preToolUse.bash(command, cwd)
@@ -245,9 +245,9 @@ describe("block-rm-rf (E2E)", () => {
 
 E2E tests use `vitest.config.e2e.mts` with:
 
-- `environment: "node"` — no browser globals needed
-- `pool: "forks"` — true process isolation (tests spawn subprocesses)
-- `testTimeout: 20_000` — 20s per test (binary startup + hook eval)
+- `environment: "node"` - no browser globals needed
+- `pool: "forks"` - true process isolation (tests spawn subprocesses)
+- `testTimeout: 20_000` - 20s per test (binary startup + hook eval)
 
 The `forks` pool is important: thread-based workers share `globalThis`, which can interfere with subprocess-spawning tests. Process-based forks avoid this.
 

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

@@ -0,0 +1,333 @@
+---
+---
+title: Mimari
+description: "Hook handler, config yükleme ve policy değerlendirmesinin dahili olarak nasıl çalıştığı"
+icon: sitemap
+---
+
+Bu belge failproofai'nin dahili işleyişini açıklar: hook sistemi agent tool çağrılarını nasıl keser, yapılandırma nasıl yüklenir ve birleştirilir, policiler nasıl değerlendirilir ve dashboard agent aktivitesini nasıl izler.
+
+---
+
+## Genel Bakış
+
+failproofai iki bağımsız alt sistemden oluşur:
+
+1. **Hook handler** - Claude Code'un her agent tool çağrısında invoke ettiği hızlı bir CLI alt işlemi. Policileri değerlendirir ve bir karar döner.
+2. **Agent Monitor (Dashboard)** - Agent oturumlarını izlemek ve policileri yönetmek için bir Next.js web uygulaması.
+
+Her iki alt sistem `~/.failproofai/` ve projenin `.failproofai/` dizininde yapılandırma dosyalarını paylaşır, ancak ayrı işlemler olarak çalışırlar ve yalnızca dosya sistemi üzerinden iletişim kurarlar.
+
+---
+
+## Hook handler
+
+### Claude Code ile Entegrasyon
+
+`failproofai policies --install` çalıştırdığınızda, `~/.claude/settings.json` dosyasına şu gibi girişler yazar:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "failproofai --hook PreToolUse"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [ ... ]
+  }
+}
+```
+
+Claude Code daha sonra her tool çağrısından önce `failproofai --hook PreToolUse` komutunu bir alt işlem olarak invoke eder, stdin üzerinde bir JSON payload iletir.
+
+### Payload formatı
+
+```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` olayları için, payload ayrıca tool'un çıktısını içeren `tool_result` öğesini içerir.
+
+Handler 1 MB'lık stdin sınırını zorunlu kılar. Bu limiti aşan payload'lar atılır ve tüm policiler zımnen izin verir.
+
+### Yanıt formatı
+
+**Reddet (PreToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
+  }
+}
+```
+
+**Reddet (PostToolUse):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Blocked by failproofai because: API key detected in output"
+  }
+}
+```
+
+**Talimat (Stop dışındaki herhangi bir olay):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Stop olayı talimatı:**
+- Çıkış kodu: `2`
+- Neden stderr'e yazılır (stdout'a değil)
+
+**İzin Ver:**
+- Çıkış kodu: `0`
+- Boş stdout
+
+**İzinle mesaj (beta):**
+
+v0.0.2-beta.3'ten itibaren `allow(message)`, bir policy işleme izin verildiğinde bile Claude'a bilgilendirici bağlam gönderebilir. Hook handler aşağıdaki JSON'u **stdout'a** yazar (bir config dosyasına değil — bu handler'ın Claude Code'a yanıtıdır, reddet ve talimat yanıtları gibi):
+
+```json
+// Hook handler işlemi tarafından stdout'a yazılır
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Çıkış kodu: `0` (işleme izin verilir)
+- Birden çok policy `allow` ile mesaj döndüğünde, mesajları satır sonlarıyla birleştirilmiş bir `additionalContext` dizesine katılır
+- Hiçbir policy mesaj sağlamıyorsa, stdout boştur (öncekiyle aynı)
+
+### İşleme hattı
+
+`src/hooks/handler.ts` tam hattı uygular:
+
+```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
+```
+
+Tipik payload'lar için tüm işlem LLM çağrıları olmadan 100ms altında çalışır.
+
+---
+
+## Yapılandırma yükleme
+
+`src/hooks/hooks-config.ts` üç kapsamlı config yüklemeyi uygular.
+
+```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)
+```
+
+Birleştirme mantığı:
+- `enabledPolicies` - üç dosya arasında birleştirilmiş tekil union
+- `policyParams` - policy başına anahtar, bunu tanımlayan ilk dosya tamamen kazanır
+- `customPoliciesPath` - bunu tanımlayan ilk dosya kazanır
+- `llm` - bunu tanımlayan ilk dosya kazanır
+
+Web dashboard, project cwd ile invoke edilmediği için okuma ve yazma için `readHooksConfig()` (yalnızca global) kullanır.
+
+---
+
+## Policy değerlendirmesi
+
+`src/hooks/policy-evaluator.ts` policileri sırayla çalıştırır.
+
+Her policy için:
+
+1. Policy'nin `params` şemasını ara (varsa).
+2. Birleştirilmiş config'ten `policyParams[policy.name]` oku.
+3. Kullanıcı tarafından sağlanan değerleri schema varsayılanları üzerine birleştirerek `ctx.params` oluştur.
+4. Çözümlenen context ile `policy.fn(ctx)` çağır.
+5. Sonuç `deny` ise, hemen dur ve bu kararı döndür.
+6. Sonuç `instruct` ise, mesajı birikdir ve devam et.
+7. Sonuç `allow` ise, sonraki policiye geç.
+
+Tüm policiler çalıştıktan sonra:
+- Herhangi bir `deny` döndürülüyse, deny yanıtını yayınla.
+- Herhangi bir `instruct` dönüşü toplanmışsa, tüm mesajlar birleştirilmiş tek bir instruct yanıtı yayınla.
+- Aksi halde, allow yanıtını yayınla (boş stdout, exit 0).
+
+---
+
+## Yerleşik policiler
+
+`src/hooks/builtin-policies.ts` 26 yerleşik policy'yi `BuiltinPolicyDefinition` nesneleri olarak tanımlar:
+
+```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` kabul eden policiler, her parametre için türler ve varsayılanlar ile bir `PolicyParamsSchema` bildirirler. Policy değerlendiricisi çözümlenen değerleri `fn` çağrılmadan önce `ctx.params` içerisine enjekte eder. Policy fonksiyonları `ctx.params` okur, null kontrol etmez çünkü varsayılanlar her zaman önce uygulanır.
+
+Policilerin içindeki desen eşleştirmesi, ham string eşleştirmesinde değil, ayrıştırılmış command token'larını (argv) kullanır. Bu, shell operatörü enjeksiyonu yoluyla bypass'ı engeller (örn. `sudo systemctl status *` için bir desen `;` ekleyerek bypass edilemez rm -rf /`).
+
+---
+
+## Özel policiler
+
+`src/hooks/custom-hooks-registry.ts` `globalThis` destekli bir registry uygular:
+
+```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` kullanıcı policy dosyasını yükler:
+
+1. Config'ten `customPoliciesPath` oku; yoksa atla.
+2. Mutlak yola çöz; dosyayı kontrol et var mı.
+3. Tüm `from "failproofai"` importlarını gerçek dist path'e yeniden yaz böylece `customPolicies` aynı `globalThis` registry'ye çözülür.
+4. ESM uyumluluğunu sağlamak için geçişli yerel importları yinelemeli olarak yeniden yaz.
+5. Geçici `.mjs` dosyaları yaz ve giriş dosyasını `import()` et.
+6. Kayıtlı hook'ları almak için `getCustomHooks()` çağır.
+7. Tüm temp dosyaları bir `finally` bloğunda temizle.
+
+Herhangi bir hata (dosya bulunamadı, söz dizimi hatası, import başarısızlığı) durumunda, hata `~/.failproofai/hook.log` dosyasına kaydedilir ve loader boş bir dizi döner. Yerleşik policiler etkilenmez.
+
+Özel policiler tüm yerleşik policilerden sonra değerlendirilir. Bir özel policy `deny` yine de diğer özel policileri kısa devreye soksa da (yerleşik policilerin tümü o noktada zaten çalıştırılmıştır).
+
+---
+
+## Aktivite Logging
+
+Her hook olayından sonra, handler `~/.failproofai/hook-activity.jsonl` dosyasına bir JSONL satırı ekler:
+
+```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
+}
+```
+
+Non-allow kararı alan her policy için bir satır. Allow kararları kaydedilmez (dosya küçük tutmak için).
+
+---
+
+## Dashboard mimarisi
+
+Dashboard, App Router ile React Server Components ve Server Actions kullanan bir **Next.js 16** uygulamasıdır.
+
+```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
+```
+
+**Veri akışı:**
+
+- Sayfa bileşenleri proje/oturum verilerini doğrudan dosya sisteminden okumak için `lib/projects.ts` ve `lib/log-entries.ts` çağırır (okumalar için API katmanı yok).
+- Policies sayfası tüm mutasyonlar (toggle, params güncelleme, install/remove) için Server Actions kullanır.
+- Oturum viewer'ı Claude'un JSONL transkript formatını ayrıştırır ve mesajlar ile tool çağrılarının bir zaman çizelgesini renderler.
+
+**Temel tasarım kararları:**
+
+- Veritabanı yok - tüm kalıcı state düz dosyalardadır (`~/.failproofai/`, `~/.claude/projects/`).
+- Mutasyonlar için Server Actions - CRUD işlemleri için REST API gerekli değil.
+- Okuma sayfaları için React Server Components - daha hızlı ilk yükleme, veri getirme için client bundle yok.
+- Client bileşenleri sadece etkileşimlilik gerekli yerlerde (policy toggle'ları, aktivite arama, log viewer).
+
+---
+
+## Dosya düzeni
+
+```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
+```