failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/tr/agenteye/telemetry.mdx

@@ -0,0 +1,52 @@
+---
+title: "Performans Metrikleri"
+description: "Modellerinizin, araçlarınızın veya hook'larınızın yavaşladığı veya maliyeti artırdığı anı görün ve kullanıcılarınız bunu hissetmeden tail-latency artışını yakalayın."
+---
+
+
+Modellerinizin, araçlarınızın veya hook'larınızın yavaşladığı veya maliyeti artırdığı anı görün ve kullanıcılarınız bunu hissetmeden tail-latency artışını yakalayın. Üç ayrı sayfa ham zamanlama verilerini p50, p95 ve p99'a dönüştürerek bir bakışta okuyabileceğiniz hale getirir.
+
+![Models sayfası, latency ısı haritasını, yüzdelik bantı ve model başına token, maliyet ve bağlam penceresi rakamlarını gösteriyor](/agenteye/images/models.png)
+*Models sayfası: latency ısı haritası, yüzdelik bandı ve model başına tokenler, tahmini maliyet ve bağlam penceresi doldurma.*
+
+## Ortalamaların kötü çalışmaları saklamasına izin vermeyin
+
+Ortalama latency numarası rahatlatıcı ve işe yaramaz: elli çağrıdan birinin takılıp kalıp sabah 2'de on-call personelini çağırmasının üzerini örter. Models, Tools ve Hooks sayfaları bunu yapmayı reddeder. Her biri aynı yapıya sahiptir, böylece bunu bir kez öğrenirsiniz:
+
+- Trendi bir bakışta görmek için **24-kutulu sparkline**: bu durum kötüye gidiyor mu?
+- p50, p95 ve p99 latency ile **vitals şeridi**, böylece tipik çalışma ve tail yan yana oturur.
+- **Latency ısı haritası**, 24 zaman kutusu x latency segmentleri, *ne zaman* yavaş çağrıların kümelendiğini gösterir.
+- **Yüzdelik bant**: p50 çizgisi ile p25 ila p75 ve p10 ila p90 gölgeli şeritleri ve p99 noktaları, böylece yayılma ortalama yerine görünür kalır.
+
+Paylaşılan bir hover crosshair ısı haritasını ve bandı zaman olarak bağlar, böylece tail spike her ikisinde de zaman içinde sıralanır ve tek bir ortalama çizgisinin arkasında gizlenmez. Üç sayfayı da panonuzun **observe** bölümünde bulun, her biri kuruluşunuza kapsamlı ve tarih aralığı, ortam, agent ve oturum ile filtrelenebilir.
+
+## Models: her modelin size ne kadara mal olduğunu tam olarak görün
+
+Models sayfası (üstte gösterilmiştir) bir faturanın her zaman ortaya çıkardığı iki soruya yanıt verir: hangi model ve ne kadar. Paylaşılan latency görünümünün üzerine, **model başına token tüketimi**, **tahmini maliyet** ve **bağlam penceresi doldurma** ekler, böylece kontrolsüz prompt büyümesi ve yaklaşan sıkıştırma sizi şaşırtmadan önce görünür.
+
+Failproof AI Observability ortak model kimliklerini otomatik olarak tanır. Bir pencere yanlış görünüyorsa veya kendi özel modelinizi çalıştırıyorsanız, **Settings** altında, **model context windows** içinde düzeltin veya ekleyin ve doldurma okumaları bunu takip eder.
+
+## Tools: yavaş olanı kırık olandan ayırt edin
+
+Bir tool çağrısı yavaş olabilir veya sessizce başarısız olabilir ve bunu günlükleri inceledikten sonra değil de saniyeler içinde bilmek istersiniz.
+
+![Tools sayfası, paylaşılan latency ısı haritasını ve yüzdelik bandı yanında başarı ve hata dökümü ile tool dağılım çubuğunu gösteriyor](/agenteye/images/tools.png)
+*Tools sayfası: aynı ısı haritası ve yüzdelik bant, artı başarı ve hata dökümü ile tool dağılım çubuğu.*
+
+Paylaşılan latency görünümünün yanında, Tools sayfası bir **başarı ve hata dökümü** ve **tool dağılım çubuğu** ekler, böylece bir bakışta hangi toolları en çok kullandığınızı ve hangilerinin hata bütçenizi tükettiğini görürsünüz.
+
+## Hooks: tam hook ve trigger'ı belirleyin
+
+Bir lifecycle hook bir çalışmayı yavaşlatırken, "hook'lar yavaş" üzerinde harekete geçebileceğiniz bir şey değildir. Hooks sayfası sizi önemli olana götürür.
+
+![Hooks sayfası, latency'nin paylaşılan ısı haritası ve yüzdelik bandı üzerinde hook adı ve trigger olayına göre dökülmüş olarak gösteriyor](/agenteye/images/hooks.png)
+*Hooks sayfası: latency'nin hook adı ve trigger olayına göre dökülmüş.*
+
+Aynı latency ısı haritası ve yüzdelik bandı üzerinde, Hooks sayfası etkinliği **hook adı** ve **trigger olayı** tarafından kırıyor, böylece ilgilenilmesi gereken tek hook'a ve tek olaya inersiniz.
+
+## İlgili
+
+- [Event stream](/tr/agenteye/event-stream): her olayın canlı, renkle kodlanmış izi.
+- [Sessions](/tr/agenteye/sessions): olayları çalışma başına bir satırda toplayın ve yürütme grafiğini açın.
+- [Error tracking](/tr/agenteye/error-tracking): panoda kırmızı olan her şey için tek triage yüzeyi.
+- [Dashboards](/tr/agenteye/dashboards): filoğunuz genelinde toparlama görünümleri.

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

@@ -0,0 +1,332 @@
+---
+title: Mimari
+description: "Hook işleyicisinin, 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 aracı araç çağrılarını nasıl engeller, yapılandırma nasıl yüklenir ve birleştirilir, politikalar nasıl değerlendirilir ve dashboard aracı aktivitesini nasıl izler.
+
+---
+
+## Genel Bakış
+
+failproofai iki bağımsız alt sisteme sahiptir:
+
+1. **Hook işleyicisi** - Claude Code'un her aracı 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. **Aracı İzleme (Dashboard)** - Aracı oturumlarını izlemek ve politikaları yönetmek için bir Next.js web uygulaması.
+
+Her iki alt sistem de `~/.failproofai/` ve projenin `.failproofai/` dizininde bulunan yapılandırma dosyalarını paylaşır, ancak ayrı işlemler olarak çalışır ve yalnızca dosya sistemi üzerinden iletişim kurar.
+
+---
+
+## Hook işleyicisi
+
+### Claude Code ile entegrasyon
+
+`failproofai policies --install` komutunu çalıştırdığınızda, `~/.claude/settings.json` dosyasına şu gibi girdiler yazılır:
+
+```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 üzerinden bir 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ı ile birlikte `tool_result` içerir.
+
+İşleyici 1 MB stdin sınırını zorunlu kılar. 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"
+  }
+}
+```
+
+**Yönerge (Stop hariç herhangi bir olay):**
+```json
+{
+  "hookSpecificOutput": {
+    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
+  }
+}
+```
+
+**Durdur olayı yönergesi:**
+- Çıkış kodu: `2`
+- Sebep stderr'ye yazılır (stdout değil)
+
+**İzin ver:**
+- Çıkış kodu: `0`
+- Boş stdout
+
+**İleti ile izin ver:**
+
+`allow(message)` bir politikanın işlem izin verildiğinde bile bilgilendirici bağlamı Claude'a geri göndermesini sağlar. Hook işleyicisi aşağıdaki JSON'ı **stdout**'a yazar (bir config dosyasına değil — bu, yukarıdaki reddet ve yönerge yanıtları gibi, hook işleyicisinin Claude Code'a verdiği yanıttır):
+
+```json
+// Hook işleyicisi işlemi tarafından stdout'a yazılmış
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Çıkış kodu: `0` (işlem izin verilir)
+- Birden fazla politika bir ileti ile `allow` döndüğünde, bunların mesajları yeni satırlarla birleştirilerek tek bir `additionalContext` dizesine dönüştürülür
+- Hiçbir politika ileti sağlamazsa, stdout boş olur (daha önce olduğu gibi)
+
+### İşleme ardışık düzeni
+
+`src/hooks/handler.ts` tam ardışık düzeni uygular:
+
+```text
+stdin JSON
+  → yükü ayrıştır (max 1 MB)
+  → oturum meta verilerini çıkar (session_id, cwd, tool_name, tool_input, vb.)
+  → readMergedHooksConfig(cwd)    ← proje + yerel + genel config'i birleştirir
+  → etkinleştirilmiş yerleşik politikaları çözülen parametrelerle kaydet
+  → customPoliciesPath'den özel politikaları yükle (ayarlanmışsa)
+  → özel politikaları politika kayıt defterine kaydet
+  → tüm politikaları değerlendir (yerleşikleri önce, ardından özel olanları)
+      → ilk reddet kısa devre
+      → yönerge kararları birikir
+      → izin iletileri birikir
+  → JSON kararı stdout'a yaz
+  → olayı ~/.failproofai/hook-activity/current.jsonl dosyasına kaydet
+  → çık
+```
+
+Tüm işlem LLM çağrıları olmayan tipik yükler için 100ms'den kısa sürer.
+
+---
+
+## Yapılandırma yükleme
+
+`src/hooks/hooks-config.ts` üç kaplam yapılandırması yükleme 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 çoğaltılmamış 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 dashboard, bir proje cwd ile çağrılmadığından, 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 (varsa).
+2. Birleştirilmiş config'den `policyParams[policy.name]` okuyun.
+3. Kullanıcı tarafından sağlanan değerleri şema varsayılanları üzerine birleştirerek `ctx.params` üretin.
+4. Çözülen bağlamla `policy.fn(ctx)` çağırın.
+5. Sonuç `deny` ise, hemen durdurun ve bu kararı döndürün.
+6. Sonuç `instruct` ise, mesajı biriktirir ve devam edin.
+7. Sonuç `allow` ise, sonraki politikaya geçin.
+
+Tüm politikalar çalıştıktan sonra:
+- Herhangi bir `deny` döndürüldüyse, reddet yanıtını yayınlayın.
+- Herhangi bir `instruct` dönüşü toplandıysa, tüm mesajlar birleştirilmiş tek bir yönerge yanıtı yayınlayın.
+- Aksi takdirde, izin yanıtı yayınlayın (boş stdout, çıkış 0).
+
+---
+
+## Yerleşik politikalar
+
+`src/hooks/builtin-policies.ts` tüm 39 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ür ve varsayılan değerler içeren `PolicyParamsSchema` bildirir. Politika değerlendiricisi `fn` çağrısından önce çözülen değerleri `ctx.params` öğesine enjekte eder. Politika işlevleri `ctx.params` öğesini null-koruması olmadan okur çünkü varsayılanlar her zaman önce uygulanır.
+
+Politikalar içindeki desen eşleşmesi ham dizge eşleşmesi değil, ayrıştırılmış komut jetonlarını (argv) kullanır. Bu, shell işleci enjeksiyonu yoluyla atlatmayı engeller (örn. `sudo systemctl status *` için bir desen `; rm -rf /` eklemek suretiyle atlatılamaz).
+
+---
+
+## Özel politikalar
+
+`src/hooks/custom-hooks-registry.ts` bir `globalThis` tabanlı 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ün; dosya varlığını kontrol edin.
+3. Tüm `from "failproofai"` importlarını gerçek dist yoluna yeniden yazın, böylece `customPolicies` aynı `globalThis` kayıt defterine çözülür.
+4. ESM uyumluluğunu sağlamak için transitif yerel importları özyinelemeli olarak yeniden yazın.
+5. Geçici `.mjs` dosyaları yazın ve giriş dosyasını `import()` edin.
+6. Kayıtlı kancaları almak için `getCustomHooks()` çağırın.
+7. `finally` bloğunda tüm geçici dosyaları temizleyin.
+
+Herhangi bir hata durumunda (dosya bulunamadı, sözdizimi hatası, import hatası), hata `~/.failproofai/hook.log` dosyasına kaydedilir ve yükleyici boş bir dizi döndürür. Yerleşik politikalar etkilenmez.
+
+Özel politikalar tüm yerleşik politikaların ardından değerlendirilir. Özel bir politika `deny` yine de başka özel politikaları kısa devreye sokar (ancak bu noktada tüm yerleşikler zaten çalışmıştır).
+
+---
+
+## Aktivite günlüğü
+
+Her hook olayından sonra, işleyici `~/.failproofai/hook-activity/current.jsonl` dosyasına bir JSONL satırı ekler; bu, bir sayfaya ulaştığında `page-<timestamp>-<seq>.jsonl` dosyasına döner:
+
+```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 bir karar alan her politika için bir satır. İzin kararları günlüğe kaydedilmez (dosyayı küçük tutmak için).
+
+---
+
+## Dashboard mimarisi
+
+Dashboard, React Server Components ve Server Actions ile App Router kullanan 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: projedeki oturumları listele
+  project/[name]/session/
+    [sessionId]/page.tsx      ← Sunucu bileşeni: oturum görüntüleyicisini işle
+  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ü sayfalandır/ara
+    install-hooks-web.ts      ← Tarayıcıdan kancaları kur/kaldır
+  api/
+    download/[project]/[session]/route.ts   ← CLI başına oturum dışa aktarması (JSONL veya JSON)
+```
+
+**Veri akışı:**
+
+- Sayfa bileşenleri dosya sisteminden proje/oturum verilerini doğrudan okumak için `lib/projects.ts` ve `lib/log-entries.ts` çağırır (okumalar için API katmanı yok).
+- Politikalar sayfası tüm mutasyonlar için Server Actions kullanır (aç/kapat, parametreler güncellemesi, kur/kaldır).
+- Oturum görüntüleyicisi Claude'un JSONL transkript biçimini ayrıştırır ve mesajların ve araç çağrılarının bir zaman çizelgesini işler.
+
+**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 gerekmez.
+- Okuma sayfaları için React Server Components - daha hızlı ilk yüklemeler, veri getirme için istemci paketi yok.
+- İstemci bileşenleri yalnızca etkileşim gerekli olduğunda (politika açma/kapatma, aktivite arama, günlük görüntüleyicisi).
+
+---
+
+## Dosya düzeni
+
+```text
+failproofai/
+├── bin/
+│   └── failproofai.mjs           # CLI yönlendirici (hook / dashboard / install / vb.)
+├── src/hooks/
+│   ├── handler.ts                # Hook olayı ardışık düzeni
+│   ├── builtin-policies.ts       # 39 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 kaplam yapılandırması yükleme
+│   ├── custom-hooks-registry.ts  # globalThis tabanlı kanca kayıt defteri
+│   ├── custom-hooks-loader.ts    # Kullanıcı JS kancaları için ESM yükleyici
+│   ├── manager.ts                # kur / kaldır / listele işlemleri
+│   ├── install-prompt.ts         # Etkileşimli politika seçim istemi
+│   ├── hook-logger.ts            # hook.log dosyasına günlüğe kaydet
+│   ├── hook-activity-store.ts    # Aktiviteyi hook-activity/ dosyasına kaydet
+│   └── llm-client.ts             # LLM API istemcisi (yapay zeka destekli politikalar için)
+├── app/                          # Next.js dashboard (sayfalar + sunucu eylemleri)
+├── lib/                          # Paylaşılan yardımcı programlar
+│   ├── projects.ts               # Dosya sisteminden Claude projelerini numaralandır
+│   ├── log-entries.ts            # Claude transkript JSONL biçimini ayrıştır
+│   ├── paths.ts                  # Sistem yollarını çöz
+│   └── ...
+├── 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
+```