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

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

@@ -1,260 +0,0 @@
----
-title: Test Etme
-description: "Birim testleri, uçtan uca testleri ve test yardımcıları"
-icon: flask-vial
----
-
-failproofai iki test paketi içerir: **birim testleri** (hızlı, simüle edilmiş) ve **uçtan uca testleri** (gerçek alt işlem çağırmaları).
-
----
-
-## Testleri çalıştırma
-
-```bash
-# Tüm birim testlerini bir kez çalıştır
-bun run test:run
-
-# Birim testlerini izleme modunda çalıştır
-bun run test
-
-# E2E testlerini çalıştır (setup gerektirir - aşağıya bakın)
-bun run test:e2e
-
-# Derlemeden tip kontrolü yap
-bunx tsc --noEmit
-
-# Lint
-bun run lint
-```
-
----
-
-## Birim testleri
-
-Birim testleri `__tests__/` içinde bulunur ve [Vitest](https://vitest.dev) ile `happy-dom` kullanır.
-
-```text
-__tests__/
-  hooks/
-    builtin-policies.test.ts      # Her yerleşik ilke için ilke mantığı
-    hooks-config.test.ts          # Yapılandırma yükleme ve kapsam birleştirme
-    policy-evaluator.test.ts      # Parametre enjeksiyonu ve değerlendirme sırası
-    custom-hooks-registry.test.ts # globalThis kayıt defteri ekleme/alma/temizleme
-    custom-hooks-loader.test.ts   # ESM yükleyici, geçişli içeri aktarmalar, hata işleme
-    manager.test.ts               # kurulum/kaldırma/listeleme işlemleri
-  components/
-    sessions-list.test.tsx        # Oturum listesi bileşeni
-    project-list.test.tsx         # Proje listesi bileşeni
-    ...
-  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
-```
-
-### İlke birim testi yazma
-
-```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("sudo komutlarını reddeder", () => {
-    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("sudo olmayan komutlara izin verir", () => {
-    const ctx = {
-      eventType: "PreToolUse" as const,
-      payload: {},
-      toolName: "Bash",
-      toolInput: { command: "ls -la" },
-      params: { allowPatterns: [] },
-    };
-    expect(policy.fn(ctx)).toEqual(allow());
-  });
-
-  it("allowPatterns içindeki desenlere izin verir", () => {
-    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());
-  });
-});
-```
-
----
-
-## Uçtan uca testleri
-
-E2E testleri gerçek `failproofai` ikilisini alt işlem olarak çağırır, JSON yükünü stdin'e aktarır ve stdout çıkışı ile çıkış kodu üzerinde doğrulamalar yapar. Bu, Claude Code'un kullandığı tam entegrasyon yolunu test eder.
-
-### Setup
-
-E2E testleri doğrudan depo kaynağından ikiliyi çalıştırır. İlk çalıştırmadan önce, özel kanca dosyalarının `'failproofai'`'den içeri aktarırken kullanacağı CJS paketini oluşturun:
-
-```bash
-bun build src/index.ts --outdir dist --target node --format cjs
-```
-
-Ardından testleri çalıştırın:
-
-```bash
-bun run test:e2e
-```
-
-Genel kanca API'sini değiştirdiğinizde `dist/` öğesini yeniden oluşturun (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` veya `src/hooks/policy-types.ts`).
-
-### E2E test yapısı
-
-```text
-__tests__/e2e/
-  helpers/
-    hook-runner.ts      # İkiliyi oluştur, yük JSON'unu aktar, çıkış kodu + stdout + stderr'ı yakala
-    fixture-env.ts      # Test başına izole edilen geçici dizinler yapılandırma dosyalarıyla
-    payloads.ts         # Her olay türü için Claude'a uygun yük fabrikaları
-  hooks/
-    builtin-policies.e2e.test.ts   # Her yerleşik ilke gerçek alt işlemle
-    custom-hooks.e2e.test.ts       # Özel kanca yükleme ve değerlendirmesi
-    config-scopes.e2e.test.ts      # Proje/yerel/genel arasında yapılandırma birleştirme
-    policy-params.e2e.test.ts      # Her parametreli ilke için parametre enjeksiyonu
-```
-
-### E2E yardımcılarını kullanma
-
-**`FixtureEnv`** - test başına izole ortam:
-
-```typescript
-import { createFixtureEnv } from "../helpers/fixture-env";
-
-const env = createFixtureEnv();
-// env.cwd    - geçici dizin; .failproofai/policies-config.json'ı almak için payload.cwd olarak geçir
-// env.home   - izole ev dizini; gerçek ~/.failproofai sızıntıya uğramaz
-
-env.writeConfig({
-  enabledPolicies: ["block-sudo"],
-  policyParams: {
-    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
-  },
-});
-```
-
-`createFixtureEnv()` `afterEach` temizlemesini otomatik olarak kaydeder.
-
-**`runHook`** - ikiliyi çağır:
-
-```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`** - hazır yük fabrikaları:
-
-```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 testi yazma
-
-```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("rm -rf'yi reddeder", 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("özyinelemeli olmayan rm'ye izin verir", 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("");  // izin ver → boş stdout
-  });
-});
-```
-
-### E2E yanıt şekilleri
-
-| Karar | Çıkış kodu | stdout |
-|----------|-----------|--------|
-| `PreToolUse` reddet | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
-| `PostToolUse` reddet | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
-| Talimati (Stop olmayan) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
-| Stop talimatı | `2` | boş stdout; neden stderr'de |
-| İzin ver | `0` | boş dize |
-
-### Vitest yapılandırması
-
-E2E testleri `vitest.config.e2e.mts` kullanır:
-
-- `environment: "node"` - tarayıcı globalleri gerekli değil
-- `pool: "forks"` - gerçek işlem izolasyonu (testler alt işlemler oluşturur)
-- `testTimeout: 20_000` - test başına 20 saniye (ikili başlatma + kanca değerlendirmesi)
-
-`forks` havuzu önemlidir: iş parçacığı tabanlı işçiler `globalThis` paylaşırlar ve bu, alt işlem oluşturan testleri etkileyebilir. İşlem tabanlı çatallama bunu önler.
-
----
-
-## CI
-
-Birleştirmeden önce tam CI çalıştırması (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) geçmesi gerekir. E2E paketi paralel olarak ayrı bir CI işinde çalışır.
-
-Tam ön birleştirme kontrol listesi için [Contributing](../CONTRIBUTING.md) bölümüne bakın.

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

@@ -1,334 +0,0 @@
----
-
----
-title: Kiến trúc
-description: "Cách hook handler, config loading, và policy evaluation hoạt động nội bộ"
-icon: sitemap
----
-
-Tài liệu này giải thích cách failproofai hoạt động nội bộ: cách hook system chặn các tool call của agent, cách configuration được load và merge, cách policies được đánh giá, và cách dashboard giám sát hoạt động của agent.
-
----
-
-## Tổng quan
-
-failproofai có hai subsystem độc lập:
-
-1. **Hook handler** - Một subprocess CLI nhanh mà Claude Code gọi trên mỗi agent tool call. Đánh giá policies và trả về quyết định.
-2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để giám sát các agent session và quản lý policies.
-
-Cả hai subsystem chia sẻ các file cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của project, nhưng chúng chạy như các process riêng biệt và chỉ giao tiếp thông qua filesystem.
-
----
-
-## Hook handler
-
-### Tích hợp với Claude Code
-
-Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các entry như sau vào `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "failproofai --hook PreToolUse"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [ ... ]
-  }
-}
-```
-
-Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess trước mỗi tool call, truyền một JSON payload trên stdin.
-
-### Định dạng payload
-
-```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" }
-}
-```
-
-Đối với `PostToolUse` events, payload cũng chứa `tool_result` với output của tool.
-
-Handler enforces giới hạn stdin 1 MB. Các payload vượt quá giới hạn này được loại bỏ và tất cả policies implicit cho phép.
-
-### Định dạng response
-
-**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 (any event except Stop):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-
-**Stop event instruct:**
-- Exit code: `2`
-- Lý do được ghi vào stderr (không phải stdout)
-
-**Allow:**
-- Exit code: `0`
-- Stdout trống
-
-**Allow với message:**
-
-`allow(message)` cho phép một policy gửi informational context trở lại Claude ngay cả khi operation được phép. Hook handler ghi JSON sau vào **stdout** (không phải config file — đây là handler's response tới Claude Code, giống như deny và instruct responses ở trên):
-
-```json
-// Written to stdout by the hook handler process
-{
-  "hookSpecificOutput": {
-    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
-  }
-}
-```
-- Exit code: `0` (operation được phép)
-- Khi nhiều policies trả về `allow` với một message, các messages của chúng được join với newlines thành một single `additionalContext` string
-- Nếu không có policy nào cung cấp message, stdout trống (giống như trước)
-
-### Processing pipeline
-
-`src/hooks/handler.ts` implements toàn bộ pipeline:
-
-```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
-```
-
-Toàn bộ process chạy dưới 100ms cho các typical payloads mà không có LLM calls.
-
----
-
-## Configuration loading
-
-`src/hooks/hooks-config.ts` implements three-scope config loading.
-
-```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)
-```
-
-Merge logic:
-- `enabledPolicies` - deduplicated union across all three files
-- `policyParams` - per-policy key, first file that defines it wins entirely
-- `customPoliciesPath` - first file that defines it wins
-- `llm` - first file that defines it wins
-
-Web dashboard sử dụng `readHooksConfig()` (global only) để đọc và ghi, vì nó không được gọi với project cwd.
-
----
-
-## Policy evaluation
-
-`src/hooks/policy-evaluator.ts` chạy policies theo thứ tự.
-
-Với mỗi policy:
-
-1. Look up policy's `params` schema (nếu nó có).
-2. Đọc `policyParams[policy.name]` từ merged config.
-3. Merge user-provided values over schema defaults để tạo `ctx.params`.
-4. Gọi `policy.fn(ctx)` với resolved context.
-5. Nếu result là `deny`, dừng ngay lập tức và trả về quyết định đó.
-6. Nếu result là `instruct`, accumulate message và tiếp tục.
-7. Nếu result là `allow`, tiếp tục tới policy tiếp theo.
-
-Sau khi tất cả policies chạy:
-- Nếu bất kỳ `deny` nào được trả về, emit deny response.
-- Nếu bất kỳ `instruct` returns nào được collected, emit một single instruct response với tất cả messages được join.
-- Ngoài ra, emit một allow response (empty stdout, exit 0).
-
----
-
-## Builtin policies
-
-`src/hooks/builtin-policies.ts` định nghĩa tất cả 26 built-in policies như `BuiltinPolicyDefinition` objects:
-
-```typescript
-interface BuiltinPolicyDefinition {
-  name: string;
-  description: string;
-  fn: (ctx: PolicyContext) => PolicyResult;
-  match: {
-    events: HookEventType[];
-    tools?: string[];
-  };
-  defaultEnabled: boolean;
-  category: string;
-  beta?: boolean;
-  params?: PolicyParamsSchema;
-}
-```
-
-Các policies chấp nhận `params` khai báo một `PolicyParamsSchema` với types và defaults cho mỗi parameter. Policy evaluator injects resolved values vào `ctx.params` trước khi gọi `fn`. Policy functions đọc `ctx.params` mà không cần null-guarding vì defaults luôn được applied trước.
-
-Pattern matching bên trong policies sử dụng parsed command tokens (argv), không phải raw string matching. Điều này ngăn chặn bypass thông qua shell operator injection (ví dụ: một pattern cho `sudo systemctl status *` không thể bypass bằng cách append `; rm -rf /` vào command).
-
----
-
-## Custom policies
-
-`src/hooks/custom-hooks-registry.ts` implements một `globalThis`-backed registry:
-
-```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` load user's policy file:
-
-1. Đọc `customPoliciesPath` từ config; skip nếu absent.
-2. Resolve tới absolute path; check file exists.
-3. Rewrite tất cả `from "failproofai"` imports tới actual dist path để `customPolicies` resolve tới cùng `globalThis` registry.
-4. Recursively rewrite transitive local imports để ensure ESM compatibility.
-5. Write temporary `.mjs` files và `import()` entry file.
-6. Gọi `getCustomHooks()` để retrieve registered hooks.
-7. Clean up tất cả temp files trong một `finally` block.
-
-Trên bất kỳ error nào (file not found, syntax error, import failure), error được logged tới `~/.failproofai/hook.log` và loader trả về một empty array. Built-in policies không bị ảnh hưởng.
-
-Custom policies được đánh giá sau tất cả built-in policies. Một custom policy `deny` vẫn short-circuits further custom policies (nhưng tất cả built-ins đã chạy rồi ở điểm đó).
-
----
-
-## Activity logging
-
-Sau mỗi hook event, handler appends một JSONL line tới `~/.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
-}
-```
-
-Một line cho mỗi policy mà có một non-allow decision. Allow decisions không được logged (để giữ file nhỏ).
-
----
-
-## Dashboard architecture
-
-Dashboard là một **Next.js 16** application sử dụng App Router với React Server Components và 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
-```
-
-**Data flow:**
-
-- Page components gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc project/session data trực tiếp từ filesystem (không API layer cho reads).
-- Policies page sử dụng Server Actions cho tất cả mutations (toggle, params update, install/remove).
-- Session viewer parse Claude's JSONL transcript format và render một timeline của messages và tool calls.
-
-**Key design decisions:**
-
-- Không database - tất cả persistent state nằm trong plain files (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions cho mutations - không cần REST API cho CRUD operations.
-- React Server Components cho read pages - faster initial load, không client bundle cho data fetching.
-- Client components chỉ ở nơi cần interactivity (policy toggles, activity search, log viewer).
-
----
-
-## File layout
-
-```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
-```