OmniRoute/docs/i18n/tr/CLAUDE.md

CLAUDE.md (Türkçe)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇳 gu · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇩 in · 🇮🇹 it · 🇯🇵 ja · 🇰🇷 ko · 🇮🇳 mr · 🇲🇾 ms · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

---

Bu dosya, bu depoda kod çalıştırırken Claude Code (claude.ai/code) için rehberlik sağlar.

Hızlı Başlangıç

npm install                    # Bağımlılıkları yükle (otomatik olarak .env.example'dan .env oluşturur)
npm run dev                    # Geliştirme sunucusu http://localhost:20128
npm run build                  # Üretim derlemesi (Next.js 16 bağımsız)
npm run lint                   # ESLint (0 hata bekleniyor; uyarılar önceden mevcut)
npm run typecheck:core         # TypeScript kontrolü (temiz olmalı)
npm run typecheck:noimplicit:core  # Sıkı kontrol (implicit any yok)
npm run test:coverage          # Birim testleri + kapsama kapısı (75/75/75/70 — ifadeler/hatlar/fonksiyonlar/dallar)
npm run check                  # lint + test birleştirilmiş
npm run check:cycles           # Dairesel bağımlılıkları tespit et

Testleri Çalıştırma

# Tek test dosyası (Node.js yerel test koşucusu — çoğu test)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP sunucusu, autoCombo, önbellek)
npm run test:vitest

# Tüm test paketleri
npm run test:all

Tam test matrisini görmek için CONTRIBUTING.md → "Testleri Çalıştırma" kısmına bakın. Derin mimari için AGENTS.md dosyasına bakın.

---

Projeye Genel Bakış

OmniRoute — birleşik AI proxy/yönlendirici. Tek uç nokta, 160'tan fazla LLM sağlayıcısı, otomatik geri dönüş.

Katman	Konum	Amaç
API Yolları	src/app/api/v1/	Next.js Uygulama Yönlendiricisi — giriş noktaları
İşleyiciler	open-sse/handlers/	İstek işleme (sohbet, gömme, vb.)
Yürütücüler	open-sse/executors/	Sağlayıcıya özel HTTP dağıtımı
Çeviriciler	open-sse/translator/	Format dönüşümü (OpenAI↔Claude↔Gemini)
Dönüştürücü	open-sse/transformer/	Yanıtlar API ↔ Sohbet Tamamlamaları
Hizmetler	open-sse/services/	Kombinasyon yönlendirme, hız sınırlamaları, önbellekleme, vb.
Veritabanı	src/lib/db/	SQLite alan modülleri (45'ten fazla dosya, 55 göç)
Alan/Politika	src/domain/	Politika motoru, maliyet kuralları, geri dönüş mantığı
MCP Sunucusu	open-sse/mcp-server/	37 araç (30 temel + 3 bellek + 4 beceri), 3 taşıma, ~13 kapsam
A2A Sunucusu	src/lib/a2a/	JSON-RPC 2.0 ajan protokolü
Beceriler	src/lib/skills/	Genişletilebilir beceri çerçevesi
Bellek	src/lib/memory/	Kalıcı konuşma belleği

Monorepo: src/ (Next.js 16 uygulaması), open-sse/ (akış motoru çalışma alanı), electron/ (masaüstü uygulaması), tests/, bin/ (CLI giriş noktası).

---

İstek Boru Hattı

Client → /v1/chat/completions (Next.js route)
  → CORS → Zod doğrulama → kimlik doğrulama? → politika kontrolü → istemci enjeksiyon koruması
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → önbellek kontrolü → oran sınırlaması → kombinasyon yönlendirmesi?
      → resolveComboTargets() → hedef başına handleSingleModel()
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() yukarı akış → geri çekilme ile yeniden deneme
    → yanıt çevirisi → SSE akışı veya JSON
    → Eğer Yanıtlar API'si: responsesTransformer.ts TransformStream

API yolları tutarlı bir desen izler: Route → CORS ön uç → Zod gövde doğrulama → Opsiyonel kimlik doğrulama (extractApiKey/isValidApiKey) → API anahtarı politika uygulaması → İşleyici delegasyonu (open-sse). Global Next.js ara yazılımı yok — kesme işlemi yol spesifik.

Kombinasyon yönlendirmesi (open-sse/services/combo.ts): 14 strateji (öncelik, ağırlıklı, ilk doldur, dairesel, P2C, rastgele, en az kullanılan, maliyet optimize edilmiş, sıfırlama farkında, katı rastgele, otomatik, lkgp, bağlam optimize edilmiş, bağlam iletim). Her hedef handleSingleModel() çağrısı yapar ve bu, hedef başına hata işleme ve devre kesici kontrolleri ile handleChatCore()'u sarar. 9 faktörlü Auto-Combo puanlaması için docs/routing/AUTO-COMBO.md ve 3 dayanıklılık katmanı için docs/architecture/RESILIENCE_GUIDE.md'ye bakın.

---

Dayanıklılık Çalışma Durumu

OmniRoute, üç ilgili ancak farklı geçici hata mekanizmasına sahiptir. Yönlendirme davranışını hata ayıklarken kapsamlarını ayrı tutun. Bir bakışta harita için 3 katmanlı dayanıklılık diyagramı (kaynak: docs/diagrams/resilience-3layers.mmd)'na bakın.

Sağlayıcı Devre Kesici

Kapsam: tüm sağlayıcı, örneğin glm, openai, anthropic.

Amaç: yukarı akış/hizmet seviyesinde sürekli olarak başarısız olan bir sağlayıcıya trafik göndermeyi durdurmak, böylece bir sağlıksız sağlayıcı her isteği yavaşlatmaz.

Uygulama:

• Temel sınıf: src/shared/utils/circuitBreaker.ts
• Sohbet kapısı/uygulama kablolaması: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
• Çalışma durumu API'si: src/app/api/monitoring/health/route.ts
• Paylaşılan sarmalayıcılar: open-sse/services/accountFallback.ts
• Kalıcı durum tablosu: domain_circuit_breakers

Durumlar:

• CLOSED: normal trafik izin verilir.
• OPEN: sağlayıcı geçici olarak engellenmiştir; arayanlar bir sağlayıcı-devre-açık yanıtı alır veya kombinasyon yönlendirmesi başka bir hedefe atlar.
• HALF_OPEN: sıfırlama zaman aşımı dolmuştur; bir prob isteğine izin verilir. Başarı devre kesiciyi kapatır, başarısızlık tekrar açar.

Varsayılanlar (open-sse/config/constants.ts):

• OAuth sağlayıcıları: eşik 3, sıfırlama zaman aşımı 60s.
• API anahtarı sağlayıcıları: eşik 5, sıfırlama zaman aşımı 30s.
• Yerel sağlayıcılar: eşik 2, sıfırlama zaman aşımı 15s.

Sadece sağlayıcı düzeyindeki hata durumları sağlayıcı devre kesicisini tetiklemelidir:

(408, 500, 502, 503, 504);

Normal hesap/anahtar/model hataları gibi çoğu 401, 403 veya 429 durumları için tüm sağlayıcı devre kesicisini tetiklemeyin. Bunlar genellikle bağlantı soğuma veya model kilitlenmesi ile ilgilidir. Genel bir API anahtarı sağlayıcı 403 kurtarılabilir olmalıdır, aksi takdirde terminal sağlayıcı/hesap hatası olarak sınıflandırılır.

Devre kesici tembel kurtarma kullanır, arka planda bir zamanlayıcı değil. OPEN süresi dolduğunda, getStatus(), canExecute() ve getRetryAfterMs() gibi okumalar durumu HALF_OPEN olarak yeniler, böylece paneller ve kombinasyon aday oluşturucuları süresi dolmuş bir sağlayıcıyı sonsuza kadar hariç tutmaz.

Bağlantı Soğuma

Kapsam: bir sağlayıcı bağlantısı/hesap/anahtar.

Amaç: aynı sağlayıcı için diğer bağlantıların istekleri karşılamaya devam etmesine izin verirken, bir kötü anahtar/hesabı geçici olarak atlamak.

Uygulama:

• Yazma/güncelleme yolu: src/sse/services/auth.ts::markAccountUnavailable()
• Hesap seçimi/filtreleme: src/sse/services/auth.ts::getProviderCredentials...
• Soğuma hesaplaması: open-sse/services/accountFallback.ts::checkFallbackError()
• Ayarlar: src/lib/resilience/settings.ts

Sağlayıcı bağlantılarındaki önemli alanlar:

rateLimitedUntil;
testStatus: "unavailable";
lastError;
lastErrorType;
errorCode;
backoffLevel;

Hesap seçimi sırasında, bir bağlantı atlanırken:

new Date(rateLimitedUntil).getTime() > Date.now();

Soğumalar da tembel: rateLimitedUntil geçmişte olduğunda, bağlantı tekrar uygun hale gelir. Başarılı kullanımda, clearAccountError() testStatus, rateLimitedUntil, hata alanlarını ve backoffLevel'ı temizler.

Varsayılan bağlantı soğuma davranışı:

• OAuth temel soğuma: 5s.
• API anahtarı temel soğuma: 3s.
• API anahtarı 429, mevcut olduğunda yukarı akış yeniden deneme ipuçlarını (Retry-After, sıfırlama başlıkları veya ayrıştırılabilir sıfırlama metni) tercih etmelidir.
• Tekrarlanan kurtarılabilir hatalar üstel geri çekilme kullanır:

baseCooldownMs * 2 ** failureIndex;

Anti-thundering-herd koruması, aynı bağlantıda eşzamanlı hataların soğumayı sürekli uzatmasını veya backoffLevel'ı iki katına çıkarmasını önler.

Terminal durumlar soğumalar değildir. banned, expired ve credits_exhausted kimlik bilgileri/ayarlar değişene kadar veya bir operatör bunları sıfırlayana kadar kullanılamaz durumda kalması amaçlanmıştır. Terminal durumları geçici soğuma durumu ile üzerine yazmayın.

Model Kilitlenmesi

Kapsam: sağlayıcı + bağlantı + model.

Amaç: yalnızca bir modelin kullanılamaz veya kota sınırlı olduğu durumlarda tüm bağlantıyı devre dışı bırakmaktan kaçınmak.

Örnekler:

• Her model için kota sağlayıcıları 429 döndürüyor.
• Bir eksik model için 404 döndüren yerel sağlayıcılar.
• Seçilen Grok modları gibi sağlayıcıya özgü mod/model izin hataları.

Model kilitlenmesi open-sse/services/accountFallback.ts içinde yer alır ve aynı bağlantının diğer modelleri sunmaya devam etmesine izin verir.

Hata Ayıklama Rehberi

• Bir sağlayıcı için tüm anahtarlar atlanıyorsa, hem sağlayıcı devre kesici durumunu hem de her bağlantının rateLimitedUntil/testStatus'ını kontrol edin.
• Bir sağlayıcı sıfırlama penceresinden sonra kalıcı olarak hariç tutuluyorsa, kodun getStatus()/canExecute() yerine ham state okuduğundan emin olun.
• Bir sağlayıcı anahtarı başarısız olursa ancak diğerleri çalışıyorsa, sağlayıcı devre kesicisi yerine bağlantı soğumasını tercih edin.
• Sadece bir model başarısız olursa, bağlantı soğuması yerine model kilitlenmesini tercih edin.
• Bir durum kendiliğinden kurtulmalıysa, gelecekteki bir zaman damgasına/sıfırlama zaman aşımına ve süresi dolmuş durumu yenileyen bir okuma yoluna sahip olmalıdır. Kalıcı durumlar manuel kimlik bilgisi veya yapılandırma değişiklikleri gerektirir.

Anahtar Sözleşmeler

Kod Stili

• 2 boşluk, noktalı virgüller, çift tırnak, 100 karakter genişliği, es5 son virgüller (lint-staged tarafından Prettier ile zorunlu kılınır)
• İthalatlar: harici → dahili (@/, @omniroute/open-sse) → göreceli
• İsimlendirme: dosyalar=camelCase/kebab, bileşenler=PascalCase, sabitler=UPPER_SNAKE
• ESLint: no-eval, no-implied-eval, no-new-func = her yerde hata; no-explicit-any = open-sse/ ve tests/ içinde uyarı
• TypeScript: strict: false, hedef ES2022, modül esnext, çözümleyici paketleyici. Açık türleri tercih edin.

Veritabanı

• Her zaman src/lib/db/ alan modüllerinden geçin — asla rotalarda veya işleyicilerde ham SQL yazmayın
• Asla src/lib/localDb.ts içine mantık eklemeyin (sadece yeniden ihracat katmanı)
• Asla localDb.ts'den silindirik ithalat yapmayın — bunun yerine belirli db/ modüllerini içe aktarın
• DB singleton: getDbInstance() src/lib/db/core.ts'den (WAL günlüğü)
• Göçler: src/lib/db/migrations/ — sürümlü SQL dosyaları, idempotent, işlemler içinde çalıştırılır

Hata Yönetimi

• belirli hata türleri ile try/catch, pino bağlamı ile günlüğe kaydet
• SSE akışlarında hataları yutmayın — temizlik için iptal sinyalleri kullanın
• Uygun HTTP durum kodlarını döndürün (4xx/5xx)

Güvenlik

• Asla eval(), new Function(), veya dolaylı eval kullanmayın
• Tüm girdileri Zod şemaları ile doğrulayın
• Kimlik bilgilerini dinlenirken şifreleyin (AES-256-GCM)
• Yukarı akış başlıkları yasak listesi: src/shared/constants/upstreamHeaders.ts — düzenlerken temizleme, Zod şemaları ve birim testlerinin uyumlu kalmasını sağlayın
• Halka açık yukarı akış kimlik bilgileri (Gemini/Antigravity/Windsurf tarzı OAuth client_id/secret + halka açık CLI'lerden çıkarılan Firebase Web anahtarları): MUTLAKA resolvePublicCred() ile gömülmelidir open-sse/utils/publicCreds.ts'den — asla dize sabitleri olarak. Zorunlu desen için docs/security/PUBLIC_CREDS.md'ye bakın.
• Hata yanıtları (HTTP / SSE / yürütücü / MCP işleyici): MUTLAKA buildErrorBody() veya sanitizeErrorMessage() üzerinden yönlendirilmelidir open-sse/utils/error.ts'den — asla ham err.stack veya err.message'i bir yanıt gövdesine koymayın. docs/security/ERROR_SANITIZATION.md'ye bakın.
• Değişkenlerden oluşturulan kabuk komutları: exec()/spawn() ile çalışma zamanı değerlerine ihtiyaç duyan bir betik çağırırken, bunları env seçeneği aracılığıyla geçirin (otomatik olarak kabukta kaçış yapılır) — asla güvenilmeyen/dış yolları betik gövdesine dize ile birleştirmeyin. Referans: src/mitm/cert/install.ts::updateNssDatabases.
• Varsayılan olarak güvenli kütüphaneler (tldrsec/awesome-secure-defaults): yeni güvenlik hassas yüzeyleri eklerken, özel uygulamalar yerine Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink'i tercih edin.

---

Yaygın Değişiklik Senaryoları

Yeni Bir Sağlayıcı Ekleme

1. src/shared/constants/providers.ts içinde kaydedin (yükleme sırasında Zod ile doğrulanır)
2. Özel mantık gerekiyorsa open-sse/executors/ içinde yürütücü ekleyin ( BaseExecutor'ı genişletin)
3. OpenAI dışı bir format varsa open-sse/translator/ içinde çevirmen ekleyin
4. OAuth tabanlı ise src/lib/oauth/constants/oauth.ts içinde OAuth yapılandırması ekleyin — yukarı akış CLI'si halka açık bir client_id/secret gönderiyorsa, resolvePublicCred() aracılığıyla gömün (bkz. docs/security/PUBLIC_CREDS.md), asla bir literal olarak
5. open-sse/config/providerRegistry.ts içinde modelleri kaydedin
6. tests/unit/ içinde testler yazın (yeni bir gömülü varsayılan eklediyseniz publicCreds şekil doğrulamasını dahil edin)

Yeni Bir API Rotası Ekleme

1. src/app/api/v1/your-route/ altında dizin oluşturun
2. GET/POST işleyicileri ile route.ts oluşturun
3. Deseni takip edin: CORS → Zod gövde doğrulaması → isteğe bağlı kimlik doğrulama → işleyici delegasyonu
4. İşleyici open-sse/handlers/ içinde yer alır (oradan içe aktarın, satır içinde değil)
5. Hata yanıtları buildErrorBody() / errorResponse() kullanır open-sse/utils/error.ts'den (otomatik olarak temizlenir — asla err.stack veya err.message'i ham olarak gövdeye koymayın). docs/security/ERROR_SANITIZATION.md'ye bakın.
6. Testler ekleyin — hata yanıtlarının yığın izlerini sızdırmadığını doğrulayan en az bir doğrulama dahil edin (!body.error.message.includes("at /"))

Yeni Bir DB Modülü Ekleme

1. src/lib/db/yourModule.ts oluşturun — ./core.ts'den getDbInstance'i içe aktarın
2. Alan tablonuz için CRUD işlevlerini dışa aktarın
3. Yeni tablolara ihtiyaç varsa src/lib/db/migrations/ içinde göç ekleyin
4. src/lib/localDb.ts'den yeniden dışa aktarın (sadece yeniden dışa aktarma listesine ekleyin)
5. Testler yazın

Yeni Bir MCP Aracı Ekleme

1. Zod girdi şeması + asenkron işleyici ile open-sse/mcp-server/tools/ içinde araç tanımını ekleyin
2. Araç setinde kaydedin ( createMcpServer() ile bağlanır)
3. Uygun kapsam(lar)a atayın
4. Testler yazın (araç çağrısı mcp_audit tablosuna kaydedilir)

Yeni Bir A2A Yeteneği Ekleme

1. src/lib/a2a/skills/ içinde yetenek oluşturun (zaten 5 tane var: akıllı yönlendirme, kota yönetimi, sağlayıcı keşfi, maliyet analizi, sağlık raporu)
2. Yetenek görev bağlamını alır (mesajlar, meta veriler) → yapılandırılmış sonuç döndürür
3. src/lib/a2a/taskExecution.ts içinde A2A_SKILL_HANDLERS'da kaydedin
4. src/app/.well-known/agent.json/route.ts içinde açığa çıkarın (Agent Kartı)
5. tests/unit/ içinde testler yazın
6. docs/frameworks/A2A-SERVER.md içinde yetenek tablosunu belgeleyin

Yeni Bir Bulut Ajanı Ekleme

1. src/lib/cloudAgent/agents/ içinde CloudAgentBase'i genişleten ajan sınıfı oluşturun (zaten 3 tane var: codex-cloud, devin, jules)
2. createTask, getStatus, approvePlan, sendMessage, listSources'ı uygulayın
3. src/lib/cloudAgent/registry.ts içinde kaydedin
4. Gerekirse OAuth/kimlik bilgileri yönetimini ekleyin (src/lib/oauth/providers/)
5. Testler + docs/frameworks/CLOUD_AGENT.md içinde belgeleyin

Yeni Bir Guardrail / Eval / Yetenek / Webhook olayı Ekleme

• Guardrail: src/lib/guardrails/ → belgeler: docs/security/GUARDRAILS.md
• Eval paketi: src/lib/evals/ → belgeler: docs/frameworks/EVALS.md
• Yetenek (sandbox): src/lib/skills/ → belgeler: docs/frameworks/SKILLS.md
• Webhook olayı: src/lib/webhookDispatcher.ts → belgeler: docs/frameworks/WEBHOOKS.md

Referans Dokümantasyonu

Herhangi bir önemsiz değişiklik için, önce ilgili derinlemesine incelemeyi okuyun:

Alan	Doküman
Repo navigasyonu	docs/architecture/REPOSITORY_MAP.md
Mimari	docs/architecture/ARCHITECTURE.md
Mühendislik referansı	docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (9 faktör puanlama, 14 strateji)	docs/routing/AUTO-COMBO.md
Dayanıklılık (3 mekanizma)	docs/architecture/RESILIENCE_GUIDE.md
Akıl yürütme tekrarları	docs/routing/REASONING_REPLAY.md
Yetenekler çerçevesi	docs/frameworks/SKILLS.md
Bellek sistemi (FTS5 + Qdrant)	docs/frameworks/MEMORY.md
Bulut ajanları	docs/frameworks/CLOUD_AGENT.md
Koruma önlemleri (Kişisel Veriler / enjeksiyon / vizyon)	docs/security/GUARDRAILS.md
Kamu üst akış kimlik bilgileri (Gemini/vb.)	docs/security/PUBLIC_CREDS.md
Hata mesajı temizleme	docs/security/ERROR_SANITIZATION.md
Değerlendirmeler	docs/frameworks/EVALS.md
Uyum / denetim	docs/security/COMPLIANCE.md
Webhook'lar	docs/frameworks/WEBHOOKS.md
Yetkilendirme akışı	docs/architecture/AUTHZ_GUIDE.md
Gizlilik (TLS / parmak izi)	docs/security/STEALTH_GUIDE.md
Ajan protokolleri (A2A / ACP / Bulut)	docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP sunucusu	docs/frameworks/MCP-SERVER.md
A2A sunucusu	docs/frameworks/A2A-SERVER.md
API referansı + OpenAPI	docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Sağlayıcı kataloğu (otomatik oluşturulmuş)	docs/reference/PROVIDER_REFERENCE.md
Sürüm akışı	docs/ops/RELEASE_CHECKLIST.md

Test Etme

Ne	Komut
Birim testleri	npm run test:unit
Tek dosya	node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo)	npm run test:vitest
E2E (Playwright)	npm run test:e2e
Protokol E2E (MCP+A2A)	npm run test:protocols:e2e
Ekosistem	npm run test:ecosystem
Kapsam kapısı	npm run test:coverage (75/75/75/70 — ifadeler/hatlar/fonksiyonlar/kolonlar)
Kapsam raporu	npm run coverage:report

PR kuralı: Eğer src/, open-sse/, electron/ veya bin/ içindeki üretim kodunu değiştirirseniz, aynı PR içinde testleri eklemeli veya güncellemelisiniz.

Test katmanı tercihi: birim önce → entegrasyon (çok modüllü veya DB durumu) → e2e (sadece UI/iş akışı). Hata yeniden üretimlerini düzeltmeden önce veya yanında otomatik testler olarak kodlayın.

Copilot kapsam politikası: Bir PR üretim kodunu değiştiriyorsa ve kapsam %75'in (ifadeler/hatlar/fonksiyonlar) veya %70'in (kolonlar) altındaysa, sadece rapor etmekle kalmayın — test ekleyin veya güncelleyin, kapsam kapısını yeniden çalıştırın, ardından onay isteyin. Çalıştırılan komutları, değiştirilen test dosyalarını ve son kapsam sonucunu PR raporuna dahil edin.

---

Git İş Akışı

# Asla doğrudan main'e commit yapmayın
git checkout -b feat/your-feature
git commit -m "feat: değişikliğinizi tanımlayın"
git push -u origin feat/your-feature

Dal ön ekleri: feat/, fix/, refactor/, docs/, test/, chore/

Commit formatı (Geleneksel Commits): feat(db): devre kesici ekle — kapsamlar: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky kancaları:

• pre-commit: lint-staged + check-docs-sync + check:any-budget:t11
• pre-push: npm run test:unit

---

Ortam

• Çalışma Zamanı: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modülleri
• TypeScript: 5.9+, hedef ES2022, modül esnext, çözümleyici paketleyici
• Yol takma adları: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
• Varsayılan port: 20128 (API + kontrol paneli aynı portta)
• Veri dizini: DATA_DIR env değişkeni, varsayılan olarak ~/.omniroute/
• Ana env değişkenleri: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
• Kurulum: cp .env.example .env ardından JWT_SECRET (openssl rand -base64 48) ve API_KEY_SECRET (openssl rand -hex 32) oluşturun

---

Sert Kurallar

1. Asla gizli bilgileri veya kimlik bilgilerini commit etmeyin
2. Asla localDb.ts içine mantık eklemeyin
3. Asla eval() / new Function() / dolaylı eval kullanmayın
4. Asla doğrudan main'e commit yapmayın
5. Asla rotalarda ham SQL yazmayın — src/lib/db/ modüllerini kullanın
6. Asla SSE akışlarında hataları sessizce yutmayın
7. Her zaman Zod şemaları ile girdileri doğrulayın
8. Üretim kodunu değiştirirken her zaman testleri dahil edin
9. Kapsam ≥%75 (ifadeler, hatlar, fonksiyonlar) / ≥%70 (kolonlar) olmalıdır. Mevcut ölçülen: ~%82.
10. Açık operatör onayı olmadan Husky kancalarını (--no-verify, --no-gpg-sign) asla atlamayın.
11. Asla kamuya açık yukarı akış OAuth client_id/secret veya Firebase Web anahtarlarını string literal olarak gömün — her zaman resolvePublicCred() üzerinden geçin (open-sse/utils/publicCreds.ts). docs/security/PUBLIC_CREDS.md'ye bakın.
12. Asla HTTP / SSE / yürütücü yanıtlarında ham err.stack / err.message döndürmeyin — her zaman buildErrorBody() veya sanitizeErrorMessage() üzerinden yönlendirin (open-sse/utils/error.ts). docs/security/ERROR_SANITIZATION.md'ye bakın.
13. Asla dış yolları veya çalışma zamanı değerlerini exec()/spawn()'a geçirilen shell betiklerine string-interpolate etmeyin — bunun yerine env seçeneği aracılığıyla geçirin. Referans: src/mitm/cert/install.ts::updateNssDatabases.
14. Asla bir CodeQL / Secret-Scanning uyarısını (a) yukarıdaki desen belgelerini kontrol etmeden ve (b) reddetme yorumunda teknik gerekçeyi kaydetmeden geçiştirmeyin. Örnek: js/stack-trace-exposure hatası, zaten sanitizeErrorMessage() üzerinden yönlendirilmiş çağrı noktalarında ortaya çıkmaktadır ve bu bilinen bir CodeQL sınırlamasıdır (özel temizleyiciler tanınmaz) — docs/security/ERROR_SANITIZATION.md'ye atıfta bulunarak false positive olarak reddedin.
15. Asla çocuk süreçleri başlatan rotaları (/api/mcp/, /api/cli-tools/runtime/) src/server/authz/routeGuard.ts içinde isLocalOnlyPath() sınıflandırması olmadan dahil etmeyin. Döngü geri uygulaması, herhangi bir kimlik doğrulama kontrolünden önce koşulsuz olarak gerçekleşir — tünel aracılığıyla sızdırılan JWT, süreç başlatmayı tetikleyemez. docs/security/ROUTE_GUARD_TIERS.md'ye bakın.
16. Asla AI asistanı, LLM veya otomasyon hesabını krediye alan Co-Authored-By ekleri içermeyin (örn. "Claude", "GPT", "Copilot", "Bot" içeren isimler; anthropic.com / openai.com / bot sahipli noreply.github.com adreslerindeki e-postalar). Bu tür ekler GitHub'da commit atfını bot hesabına yönlendirir ve PR geçmişinde gerçek yazarı (diegosouzapw) gizler. İnsan katkıda bulunanlar — upstream PR yazarları ve OmniRoute'a port edilen issue raporlayıcıları dahil — standart Co-authored-by: Name <email> ekleriyle krediye ALINABİLİR ve ALINMALIDIR; upstream-port iş akışları (/port-upstream-features, /port-upstream-issues) buna bağlıdır.