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

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

@@ -1,333 +0,0 @@
----
----
-title: Mimari
-description: "Hook yöneticisinin, config yüklemesinin ve politika değerlendirmesinin dahili olarak nasıl çalıştığı"
-icon: sitemap
----
-
-Bu belge failproofai'nin dahili olarak nasıl çalıştığını açıklar: hook sistemi agent araç çağrılarını nasıl yakaladığı, konfigürasyon nasıl yüklenip birleştirildiği, politikalar nasıl değerlendirildiği ve panelin agent aktivitesini nasıl izlediği.
-
----
-
-## Genel Bakış
-
-failproofai iki bağımsız alt sisteme sahiptir:
-
-1. **Hook yöneticisi** - Claude Code'un her agent araç çağrısında çağırdığı hızlı bir CLI alt işlemi. Politikaları değerlendirir ve bir karar döndürür.
-2. **Agent Monitor (Panel)** - Agent oturumlarını izlemek ve politikaları yönetmek için bir Next.js web uygulaması.
-
-Her iki alt sistem `~/.failproofai/` ve projenin `.failproofai/` dizinindeki konfigürasyon dosyalarını paylaşır, ancak ayrı işlemler olarak çalışırlar ve yalnızca dosya sistemi aracılığıyla iletişim kurarlar.
-
----
-
-## Hook yöneticisi
-
-### Claude Code ile Entegrasyon
-
-`failproofai policies --install` komutunu ç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 araç çağrısından önce `failproofai --hook PreToolUse` komutunu bir alt işlem olarak çağırır ve stdin'de JSON yükü iletir.
-
-### Yük biçimi
-
-```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, yük ayrıca aracın çıktısını içeren `tool_result` içerir.
-
-Yönetici 1 MB stdin sınırı uygular. Bu sınırı aşan yükler atılır ve tüm politikalar örtük olarak izin verir.
-
-### Yanıt biçimi
-
-**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ışında herhangi bir olay):**
-```json
-{
-  "hookSpecificOutput": {
-    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
-  }
-}
-```
-
-**Stop olay talimatı:**
-- Çıkış kodu: `2`
-- Sebep stderr'ye yazılır (stdout değil)
-
-**İzin Ver:**
-- Çıkış kodu: `0`
-- Boş stdout
-
-**İletili mesaj ile İzin Ver:**
-
-`allow(message)` bir politikanın işlem izin verildiğinde bile Claude'a bilgilendirici bağlam göndermesini sağlar. Hook yöneticisi aşağıdaki JSON'u **stdout**'a yazar (config dosyası değil — bu, yukarıdaki reddet ve talimat yanıtları gibi hook yöneticisinin Claude Code'a verdiği yanıt):
-
-```json
-// Hook yönetici 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 verildi)
-- Birden fazla politika mesaj içeren `allow` döndürdüğünde, mesajları yeni satırlarla birleştirilerek tek `additionalContext` dizesine katılır
-- Hiçbir politika mesaj sağlamadığında, stdout boştur (daha öncekinin aynısı)
-
-### İşleme ardışık düzeni
-
-`src/hooks/handler.ts` tam ardışık düzeni uygular:
-
-```text
-stdin JSON
-  → yük ayrıştırma (maks 1 MB)
-  → oturum meta verisi çıkarma (session_id, cwd, tool_name, tool_input, vb.)
-  → readMergedHooksConfig(cwd)    ← proje + yerel + genel config birleştirir
-  → etkinleştirilen yerleşik politikaları çözülmüş parametrelerle kaydettir
-  → customPoliciesPath'tan özel politikaları yükle (ayarlanmışsa)
-  → özel politikaları politika kaydına kaydettir
-  → tüm politikaları değerlendir (yerleşikleri önce, sonra özel)
-      → ilk reddet kısa devre yapar
-      → talimat kararları birikir
-      → mesajlara izin verir birikiyor
-  → JSON kararını stdout'a yaz
-  → olayı ~/.failproofai/hook-activity.jsonl'ye kaydet
-  → çık
-```
-
-Tüm işlem, LLM çağrıları olmayan tipik yükler için 100 ms altında çalışır.
-
----
-
-## Konfigürasyon yükleme
-
-`src/hooks/hooks-config.ts` üç kapsamlı config yüklemeyi uygular.
-
-```text
-[1] {cwd}/.failproofai/policies-config.json        ← proje  (en yüksek öncelik)
-[2] {cwd}/.failproofai/policies-config.local.json  ← yerel
-[3] ~/.failproofai/policies-config.json             ← genel   (en düşük öncelik)
-```
-
-Birleştirme mantığı:
-- `enabledPolicies` - üç dosya arasında tekilleştirilmiş birleşim
-- `policyParams` - politika başına anahtar, onu tanımlayan ilk dosya tamamen kazanır
-- `customPoliciesPath` - onu tanımlayan ilk dosya kazanır
-- `llm` - onu tanımlayan ilk dosya kazanır
-
-Web paneli, proje cwd'si olmadığı için okuma ve yazma için `readHooksConfig()` (yalnızca genel) kullanır.
-
----
-
-## Politika değerlendirmesi
-
-`src/hooks/policy-evaluator.ts` politikaları sırayla çalıştırır.
-
-Her politika için:
-
-1. Politikanın `params` şemasını arayın (eğer varsa).
-2. Birleştirilmiş config'den `policyParams[policy.name]` okuyun.
-3. `ctx.params` üretmek için kullanıcı tarafından sağlanan değerleri şema varsayılanlarının üzerine birleştirin.
-4. `policy.fn(ctx)` komutunu çözülmüş bağlamla çağırın.
-5. Sonuç `deny` ise, hemen durdurun ve o kararı döndürün.
-6. Sonuç `instruct` ise, mesajı biriktirebilir ve devam edin.
-7. Sonuç `allow` ise, sonraki politikaya devam edin.
-
-Tüm politikalar çalıştıktan sonra:
-- Herhangi bir `deny` döndürüldüyse, reddet yanıtını gönderin.
-- Herhangi bir `instruct` dönüşü toplanmışsa, tüm mesajları birleştirilmiş olarak tek bir talimat yanıtı gönderin.
-- Aksi takdirde, izin yanıtı gönderin (boş stdout, çıkış 0).
-
----
-
-## Yerleşik politikalar
-
-`src/hooks/builtin-policies.ts` tüm 26 yerleşik politikayı `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 politikalar, her parametre için türler ve varsayılanları içeren bir `PolicyParamsSchema` bildirir. Politika değerlendiricisi `fn` çağrılmadan önce çözülmüş değerleri `ctx.params`'a enjekte eder. Politika işlevleri varsayılanlar her zaman önce uygulandığından `ctx.params`'ı null-koruması olmadan okurlar.
-
-Politikalar içindeki desen eşleştirmesi, ham dize eşleştirmesi değil, ayrıştırılmış komut belirteçlerini (argv) kullanır. Bu, shell operatörü enjeksiyonu yoluyla bypass'ı önler (örneğin `sudo systemctl status *` için bir desen `;`rm -rf /` ekleyerek bypass yapılamaz).
-
----
-
-## Özel politikalar
-
-`src/hooks/custom-hooks-registry.ts` bir `globalThis`-destekli kayıt defteri uygular:
-
-```typescript
-const REGISTRY_KEY = "__failproofai_custom_hooks__";
-
-export const customPolicies = {
-  add(hook: CustomHook): void { ... }
-};
-
-export function getCustomHooks(): CustomHook[] { ... }
-export function clearCustomHooks(): void { ... }  // testlerde kullanılır
-```
-
-`src/hooks/custom-hooks-loader.ts` kullanıcının politika dosyasını yükler:
-
-1. Config'den `customPoliciesPath` okuyun; yoksa atla.
-2. Mutlak yola çözümlendirin; dosya varlığını kontrol edin.
-3. Tüm `from "failproofai"` ithalatlarını gerçek dağıtım yoluna yazarak `customPolicies`'in aynı `globalThis` kaydına çözümlenmesini sağla.
-4. ESM uyumluluğunu sağlamak için geçişli yerel ithalatları özyinelemeli olarak yazın.
-5. Geçici `.mjs` dosyaları yazın ve giriş dosyasını `import()` yapın.
-6. Kayıtlı kancaları almak için `getCustomHooks()` çağırın.
-7. Tüm geçici dosyaları bir `finally` bloğunda temizleyin.
-
-Herhangi bir hata durumunda (dosya bulunamadı, sözdizim hatası, ithalatçı hatası), hata `~/.failproofai/hook.log`'a günlüğe kaydedilir ve yükleyici boş bir dizi döndürür. Yerleşik politikalar etkilenmez.
-
-Özel politikalar tüm yerleşik politikalardan sonra değerlendirilir. Özel bir politika `deny` yine sonraki özel politikaları kısa devre yapar (ancak o noktada tüm yerleşikler zaten çalıştırılmışlardır).
-
----
-
-## Aktivite günlüğü kaydı
-
-Her hook olayından sonra, yönetici `~/.failproofai/hook-activity.jsonl`'ye 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
-}
-```
-
-İzin vermeyen kararı alan her politika için bir satır. İzin verme kararları günlüğe kaydedilmez (dosyayı küçük tutmak için).
-
----
-
-## Panel mimarisi
-
-Panel, React Server Components ve Server Actions kullanan App Router'ı içeren bir **Next.js 16** uygulamasıdır.
-
-```text
-app/
-  layout.tsx                  ← Kök düzeni (tema, telemetri, nav)
-  projects/page.tsx           ← Sunucu bileşeni: tüm Claude projelerini listele
-  project/[name]/page.tsx     ← Sunucu bileşeni: bir projedeki oturumları listele
-  project/[name]/session/
-    [sessionId]/page.tsx      ← Sunucu bileşeni: oturum görüntüleyici oluştur
-  policies/page.tsx           ← İstemci bileşeni: politika yönetimi + aktivite günlüğü
-  actions/
-    get-hooks-config.ts       ← Config + politika listesini oku
-    update-hooks-config.ts    ← Politikayı aç/kapat
-    update-policy-params.ts   ← Politika parametrelerini güncelle
-    get-hook-activity.ts      ← Aktivite günlüğünü sayfalara ayır/ara
-    install-hooks-web.ts      ← Tarayıcıdan kancaları kur/kaldır
-  api/
-    download/[project]/[session]/route.ts   ← Oturumu ZIP/JSONL olarak dışa aktar
-```
-
-**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ı yoktur).
-- Politikalar sayfası tüm mutasyonlar için Server Actions kullanır (aç/kapat, parametreler güncellemesi, kur/kaldır).
-- Oturum görüntüleyeni Claude'un JSONL transkript biçimini ayrıştırır ve mesajlar ile araç çağrılarının bir zaman çizelgesini oluşturur.
-
-**Temel tasarım kararları:**
-
-- Veritabanı yok - tüm kalıcı durum düz dosyalardadır (`~/.failproofai/`, `~/.claude/projects/`).
-- Mutasyonlar için Server Actions - CRUD işlemleri için REST API'ye gerek yok.
-- Okuma sayfaları için React Server Components - daha hızlı ilk yükleme, veri getirme için istemci paketi yok.
-- İstemci bileşenleri yalnızca etkileşimin gerekli olduğu yerlerde (politika aç/kapanır, aktivite araması, günlük görüntüleyici).
-
----
-
-## Dosya düzeni
-
-```text
-failproofai/
-├── bin/
-│   └── failproofai.mjs           # CLI yönlendiricisi (hook / panel / kurulum / vb.)
-├── src/hooks/
-│   ├── handler.ts                # Hook olay ardışık düzeni
-│   ├── builtin-policies.ts       # 26 politika tanımı
-│   ├── policy-evaluator.ts       # Politika yürütme motoru
-│   ├── policy-registry.ts        # Politika kaydı ve arama
-│   ├── policy-types.ts           # TypeScript arayüzleri
-│   ├── hooks-config.ts           # Çok kapsamlı config yükleme
-│   ├── custom-hooks-registry.ts  # globalThis-destekli kanca kaydı
-│   ├── custom-hooks-loader.ts    # Kullanıcı JS kankaları için ESM yükleyici
-│   ├── manager.ts                # kurulum / kaldırma / listeleme işlemleri
-│   ├── install-prompt.ts         # Etkileşimli politika seçim istemi
-│   ├── hook-logger.ts            # hook.log'a günlük kaydı
-│   ├── hook-activity-store.ts    # Aktiviteyi hook-activity.jsonl'ye kaydet
-│   └── llm-client.ts             # LLM API istemcisi (AI güçlendirilmiş politikalar için)
-├── app/                          # Next.js paneli (sayfalar + sunucu eylemleri)
-├── lib/                          # Paylaşılan yardımcılar
-│   ├── projects.ts               # Dosya sisteminden Claude projelerini listelendirme
-│   ├── log-entries.ts            # Claude transkript JSONL biçimini ayrıştırma
-│   ├── paths.ts                  # Sistem yollarını çözümlendirme
-│   └── ...
-├── components/                   # Paylaşılan React UI bileşenleri
-├── contexts/                     # React bağlam sağlayıcıları (tema, otomatik yenileme, telemetri)
-├── examples/                     # Örnek özel kanca dosyaları
-└── __tests__/                    # Birim ve E2E testleri
-```