OmniRoute/docs/i18n/az/CLAUDE.md

CLAUDE.md (Azərbaycan dili)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇧🇬 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 · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

---

Bu fayl, bu depo ilə işləyərkən Claude Code (claude.ai/code) üçün rəhbərlik təqdim edir.

Tez Başlama

npm install                    # Asılılıqları quraşdırın (auto-generates .env from .env.example)
npm run dev                    # Dev server http://localhost:20128
npm run build                  # İstehsal üçün qurma (Next.js 16 müstəqil)
npm run lint                   # ESLint (0 səhv gözlənilir; xəbərdarlıqlar mövcuddur)
npm run typecheck:core         # TypeScript yoxlaması (təmiz olmalıdır)
npm run typecheck:noimplicit:core  # Sıx yoxlama (implicit any olmamalıdır)
npm run test:coverage          # Birlik testləri + əhatə qapısı (75/75/75/70 — ifadələr/sətirlər/funksiyalar/şöbələr)
npm run check                  # lint + test birləşdirilmiş
npm run check:cycles           # Dairəvi asılılıqları aşkar et

Testləri İcra Etmək

# Tək test faylı (Node.js yerli test icraçısı — əksər testlər)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP server, autoCombo, cache)
npm run test:vitest

# Bütün dəstlər
npm run test:all

Tam test matrisası üçün CONTRIBUTING.md → "Testləri İcra Etmək" bölməsinə baxın. Dərin arxitektura üçün AGENTS.md-ə baxın.

---

Layihəyə Qısa Baxış

OmniRoute — birləşdirilmiş AI proxy/router. Bir uç nöqtə, 160+ LLM təminatçısı, avtomatik geri dönmə.

Təbəqə	Yer	Məqsəd
API Yolları	src/app/api/v1/	Next.js App Router — giriş nöqtələri
İdarəedicilər	open-sse/handlers/	Sorğu emalı (söhbət, embedding və s.)
İcraçılar	open-sse/executors/	Təminatçıya spesifik HTTP göndərişi
Tercüməçilər	open-sse/translator/	Format çevrilməsi (OpenAI↔Claude↔Gemini)
Transformator	open-sse/transformer/	Cavablar API ↔ Söhbət Tamamlamaları
Xidmətlər	open-sse/services/	Kombinasiya yönləndirmə, sürət limitləri, keşləmə və s.
Veritabanı	src/lib/db/	SQLite domen modulları (45+ fayl, 55 köçürmə)
Domen/Siyasət	src/domain/	Siyasət mühərriki, xərc qaydaları, geri dönmə məntiqi
MCP Server	open-sse/mcp-server/	37 alət (30 əsas + 3 yaddaş + 4 bacarıq), 3 nəqliyyat, ~13 sahə
A2A Server	src/lib/a2a/	JSON-RPC 2.0 agent protokolu
Bacarıqlar	src/lib/skills/	Genişləndirilə bilən bacarıq çərçivəsi
Yaddaş	src/lib/memory/	Davamlı söhbət yaddaşı

Monorepo: src/ (Next.js 16 tətbiqi), open-sse/ (axın mühərriki iş sahəsi), electron/ (masaüstü tətbiqi), tests/, bin/ (CLI giriş nöqtəsi).

---

İstək Boru Kəməri

Müştəri → /v1/chat/completions (Next.js marşrutu)
  → CORS → Zod təsdiqi → auth? → siyasət yoxlaması → prompt injection guard
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → keş yoxlaması → sürət limiti → kombinasiyalı marşrutlama?
      → resolveComboTargets() → handleSingleModel() hədəf üzrə
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → cavab tərcüməsi → SSE axını və ya JSON
    → Əgər Responses API: responsesTransformer.ts TransformStream

API marşrutları ardıcıl bir nümunəni izləyir: Marşrut → CORS əvvəlcədən yoxlama → Zod bədən təsdiqi → İstəyə bağlı auth (extractApiKey/isValidApiKey) → API açar siyasətinin icrası → Handler delegasiyası (open-sse). Qlobal Next.js middleware yoxdur — müdaxilə marşrut spesifikdir.

Kombinasiyalı marşrutlama (open-sse/services/combo.ts): 14 strategiya (prioritet, çəkili, ilk doldur, dövrü, P2C, təsadüfi, ən az istifadə olunan, xərclərə optimallaşdırılmış, sıfırlama ilə tanış, sərt-təsadüfi, avtomatik, lkgp, kontekstə optimallaşdırılmış, kontekst-relay). Hər bir hədəf handleSingleModel() çağırır ki, bu da handleChatCore()-u hədəf üzrə səhv idarəetmə və dövrə qırıcı yoxlamaları ilə sarır. 9-faktorlu Auto-Combo ballandırma üçün docs/routing/AUTO-COMBO.md-a və 3 davamlılıq qatları üçün docs/architecture/RESILIENCE_GUIDE.md-a baxın.

---

Davamlılıq İcraat Vəziyyəti

OmniRoute-un üç əlaqəli, lakin fərqli müvəqqəti uğursuzluq mexanizmi var. Marşrut davranışını düzəldərkən onların sahəsini ayrı saxlayın. Bir baxışda xəritə üçün 3-laylı davamlılıq diaqramı (mənbə: docs/diagrams/resilience-3layers.mmd)-na baxın.

Təchizatçı Dövrə Qırıcı

Sahə: tam təchizatçı, məsələn, glm, openai, anthropic.

Məqsəd: üst səviyyədə/xidmət səviyyəsində dəfələrlə uğursuz olan bir təchizatçıya trafik göndərməni dayandırmaq, beləliklə, bir sağlam olmayan təchizatçı hər bir istəyi yavaşlatmır.

İcra:

• Əsas sinif: src/shared/utils/circuitBreaker.ts
• Chat qapısı/icra kabelləri: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
• İcraat statusu API: src/app/api/monitoring/health/route.ts
• Paylaşılan sarğılar: open-sse/services/accountFallback.ts
• Davamlı vəziyyət cədvəli: domain_circuit_breakers

Vəziyyətlər:

• CLOSED: normal trafikə icazə verilir.
• OPEN: təchizatçı müvəqqəti bloklanmışdır; çağıranlar təchizatçı-dövrə-açıq cavabı alır və ya kombinasiyalı marşrutlama başqa bir hədəfə keçir.
• HALF_OPEN: sıfırlama vaxtı keçmişdir; bir sınaq istəyi icazə verilir. Uğur dövrəni bağlayır, uğursuzluq onu yenidən açır.

Standartlar (open-sse/config/constants.ts):

• OAuth təchizatçıları: hədd 3, sıfırlama vaxtı 60s.
• API-açar təchizatçıları: hədd 5, sıfırlama vaxtı 30s.
• Yerli təchizatçılar: hədd 2, sıfırlama vaxtı 15s.

Yalnız təchizatçı səviyyəsində uğursuzluq statusları təchizatçı dövrəsini işə salmalıdır:

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

Normal hesab/açar/model xətaları üçün tam təchizatçı dövrəsini işə salmayın, məsələn, əksər 401, 403, və ya 429 halları. Bunlar adətən bağlantı cooldown və ya model bloklanması ilə bağlıdır. Ümumi bir API-açar təchizatçısı 403 bərpa oluna bilər, əgər o, terminal təchizatçı/hesab xətası kimi təsnif olunmayıbsa.

Dövrə tənbəl bərpa istifadə edir, arxa planda zamanlayıcı deyil. OPEN müddəti bitdikdə, getStatus(), canExecute(), və getRetryAfterMs() kimi oxumalar vəziyyəti HALF_OPEN-a yeniləyir, beləliklə, panellər və kombinasiyalı namizəd qurucuları bir müddət bitmiş təchizatçını sonsuza qədər istisna etmirlər.

Bağlantı Cooldown

Sahə: bir təchizatçı bağlantısı/hesabı/açar.

Məqsəd: eyni təchizatçı üçün digər bağlantıların istəkləri xidmət etməyə davam etməsinə icazə verərkən bir pis açarı/hesabı müvəqqəti olaraq atlamaq.

İcra:

• Yazma/yeni yol: src/sse/services/auth.ts::markAccountUnavailable()
• Hesab seçimi/süzgəc: src/sse/services/auth.ts::getProviderCredentials...
• Cooldown hesablaması: open-sse/services/accountFallback.ts::checkFallbackError()
• Parametrlər: src/lib/resilience/settings.ts

Təchizatçı bağlantılarında vacib sahələr:

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

Hesab seçimi zamanı, bir bağlantı atlanır, əgər:

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

Cooldown-lar da tənbəldir: rateLimitedUntil keçmişdə olduqda, bağlantı yenidən uyğun olur. Uğurlu istifadə zamanı, clearAccountError() testStatus, rateLimitedUntil, xəta sahələrini və backoffLevel-i təmizləyir.

Standart bağlantı cooldown davranışı:

• OAuth əsas cooldown: 5s.
• API-açar əsas cooldown: 3s.
• API-açar 429 mövcud olduqda upstream retry işarələrini (Retry-After, sıfırlama başlıqları, və ya parseable sıfırlama mətni) üstün tutmalıdır.
• Təkrarlanan bərpa olunan uğursuzluqlar eksponensial geriyə çəkilmə istifadə edir:

baseCooldownMs * 2 ** failureIndex;

Anti-thundering-herd qoruyucusu eyni bağlantıda eyni anda baş verən uğursuzluqların cooldown-u təkrarlanan şəkildə uzatmasını və ya backoffLevel-i ikiqat artırmasını qarşısını alır.

Terminal vəziyyətlər cooldown deyil. banned, expired, və credits_exhausted kredensiallar/parametrlər dəyişənə qədər və ya bir operator onları sıfırlayana qədər mövcud olmamalıdır. Terminal vəziyyətləri müvəqqəti cooldown vəziyyəti ilə üst-üstə düşməməlidir.

Model Bloklanması

Sahə: təchizatçı + bağlantı + model.

Məqsəd: yalnız bir model mövcud olmadıqda və ya bu bağlantı üçün kvota məhdudlaşdırıldıqda bütün bağlantını deaktiv etməmək.

Məsələn:

• Hər model kvota təchizatçıları 429 qaytarır.
• Bir itkin model üçün 404 qaytaran yerli təchizatçılar.
• Seçilmiş Grok modları kimi təchizatçıya spesifik mod/model icazə uğursuzluqları.

Model bloklanması open-sse/services/accountFallback.ts-da yaşayır və eyni bağlantının digər modelləri xidmət etməyə davam etməsinə icazə verir.

Düzəltmə Təlimatları

• Əgər bir təchizatçı üçün bütün açarlar atlanırsa, həm təchizatçı dövrə vəziyyətini, həm də hər bir bağlantının rateLimitedUntil/testStatus-ını yoxlayın.
• Əgər bir təchizatçı sıfırlama pəncərəsindən sonra daimi olaraq istisna olunursa, kodun state-i xam oxuyub-oxumadığını yoxlayın, getStatus()/canExecute() istifadə etməyi unutmayın.
• Əgər bir təchizatçı açarı uğursuz olursa, lakin digərləri işləməlidirsə, təchizatçı dövrəsindən daha çox bağlantı cooldown-u üstün tutun.
• Əgər yalnız bir model uğursuz olursa, model bloklanmasını bağlantı cooldown-dan daha üstün tutun.
• Əgər bir vəziyyət öz-özünə bərpa olunmalıdırsa, o, gələcək zaman damğası/sıfırlama vaxtı və müddəti bitmiş vəziyyəti yeniləyən bir oxuma yolu olmalıdır. Daimi statuslar manual kredensial və ya konfiqurasiya dəyişiklikləri tələb edir.

Əsas Konvensiyalar

Kod Üslubu

• 2 boşluq, nöqtəli vergüllər, ikiqat dırnaqlar, 100 simvol genişlik, es5 son vergüllər (lint-staged vasitəsilə Prettier tərəfindən tətbiq olunur)
• İdxallar: xarici → daxili (@/, @omniroute/open-sse) → nisbət
• Adlandırma: fayllar=camelCase/kebab, komponentlər=PascalCase, sabitlər=UPPER_SNAKE
• ESLint: no-eval, no-implied-eval, no-new-func = hər yerdə səhv; no-explicit-any = open-sse/ və tests/ içində xəbərdarlıq
• TypeScript: strict: false, hədəf ES2022, modul esnext, həll edici bundler. Aydın tipləri üstün tutun.

Veritabanı

• Həmişə src/lib/db/ domen modulları vasitəsilə keçin — heç vaxt marşrutlarda və ya handler-lərdə xam SQL yazmayın
• Heç vaxt src/lib/localDb.ts-ə məntiq əlavə etməyin (yalnız re-export təbəqəsi)
• Heç vaxt localDb.ts-dən barrel-import etməyin — əvəzinə spesifik db/ modullarını idxal edin
• DB singleton: getDbInstance() src/lib/db/core.ts-dən (WAL jurnalizasiya)
• Miqrasiya: src/lib/db/migrations/ — versiyalı SQL faylları, idempotent, tranzaksiyalarda icra olunur

Xəta İdarəetməsi

• spesifik xəta tipləri ilə try/catch, pino konteksti ilə log edin
• SSE axınlarında xətaları udmayın — təmizləmə üçün abort siqnallarından istifadə edin
• Düzgün HTTP status kodları qaytarın (4xx/5xx)

Təhlükəsizlik

• Heç vaxt eval(), new Function(), və ya imzalanmış eval istifadə etməyin
• Bütün girişləri Zod sxemləri ilə təsdiqləyin
• Şifrələri istirahətdə şifrələyin (AES-256-GCM)
• Yuxarı axın başlıq qadağan siyahısı: src/shared/constants/upstreamHeaders.ts — redaktə edərkən sanitizasiya, Zod sxemləri və vahid testlərin uyğunluğunu qoruyun
• İctimai yuxarı axın şifrələri (Gemini/Antigravity/Windsurf üslubunda OAuth client_id/sirri + ictimai CLI-lərdən çıxarılmış Firebase Web açarları): MÜTLƏQ resolvePublicCred() vasitəsilə open-sse/utils/publicCreds.ts-də yerləşdirilməlidir — heç vaxt string literal olaraq. Məcburi nümunə üçün docs/security/PUBLIC_CREDS.md-ə baxın.
• Xəta cavabları (HTTP / SSE / executor / MCP handler): MÜTLƏQ buildErrorBody() və ya sanitizeErrorMessage() vasitəsilə open-sse/utils/error.ts-dən yönləndirilməlidir — heç vaxt xam err.stack və ya err.message cavab bədənində qoymayın. docs/security/ERROR_SANITIZATION.md-ə baxın.
• Dəyişənlərdən yaradılan shell əmrləri: exec()/spawn() çağırarkən runtime dəyərlərinə ehtiyac olan bir skript ilə, onları env seçimi vasitəsilə ötürün (avtomatik olaraq shell-qaçırılmış) — heç vaxt etibarsız/xarici yolları skript bədəninə string-interpolate etməyin. İstinad: src/mitm/cert/install.ts::updateNssDatabases.
• Təhlükəsiz-default kitabxanaları (tldrsec/awesome-secure-defaults): yeni təhlükəsizlik həssas səthlər əlavə edərkən Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink-i öz tətbiqlərinizdən üstün tutun.

---

Ümumi Dəyişiklik Senariləri

Yeni Provayder Əlavə Etmək

1. src/shared/constants/providers.ts-də qeydiyyatdan keçin (yüklənərkən Zod ilə təsdiqlənir)
2. open-sse/executors/-də executor əlavə edin, əgər xüsusi məntiq lazımdırsa ( BaseExecutor-i genişləndirin)
3. open-sse/translator/-də tərcüməçi əlavə edin, əgər OpenAI formatı deyilsə
4. src/lib/oauth/constants/oauth.ts-də OAuth konfiqurasiyası əlavə edin, əgər OAuth əsaslıdırsa — əgər yuxarı axın CLI ictimai client_id/sirri göndərirsə, resolvePublicCred() vasitəsilə yerləşdirin (baxın docs/security/PUBLIC_CREDS.md), heç vaxt literal olaraq
5. open-sse/config/providerRegistry.ts-də modelləri qeyd edin
6. tests/unit/-də testlər yazın (əgər yeni bir yerləşdirilmiş default əlavə etmisinizsə, publicCreds forması təsdiqini daxil edin)

Yeni API Marşrutu Əlavə Etmək

1. src/app/api/v1/your-route/ altında qovluq yaradın
2. GET/POST handler-ləri ilə route.ts yaradın
3. Nümunəni izləyin: CORS → Zod bədən təsdiqi → optional auth → handler delegasiyası
4. Handler open-sse/handlers/-də yerləşir (oradan idxal edin, inline deyil)
5. Xəta cavabları buildErrorBody() / errorResponse() vasitəsilə open-sse/utils/error.ts-dən istifadə edir (avtomatik sanitizasiya — heç vaxt err.stack və ya err.message xam bədəndə qoymayın). docs/security/ERROR_SANITIZATION.md-ə baxın.
6. Testlər əlavə edin — ən azı bir təsdiq daxil olmaqla ki, xəta cavabları stack izlərini sızdırmır (!body.error.message.includes("at /"))

Yeni DB Modulu Əlavə Etmək

1. src/lib/db/yourModule.ts yaradın — ./core.ts-dən getDbInstance-i idxal edin
2. domen cədvəliniz üçün CRUD funksiyalarını ixrac edin
3. Yeni cədvəllər lazım olduqda src/lib/db/migrations/-də miqrasiya əlavə edin
4. src/lib/localDb.ts-dən re-export edin (yalnız re-export siyahısına əlavə edin)
5. Testlər yazın

Yeni MCP Aləti Əlavə Etmək

1. open-sse/mcp-server/tools/-də Zod giriş sxemi + asinxron handler ilə alət tərifini əlavə edin
2. Alət dəstində qeydiyyatdan keçin ( createMcpServer() vasitəsilə bağlanır)
3. Müvafiq sahələrə təyin edin
4. Testlər yazın (alət çağırışı mcp_audit cədvəlinə qeyd olunur)

Yeni A2A Bacarığı Əlavə Etmək

1. src/lib/a2a/skills/-də bacarıq yaradın (artıq 5 mövcuddur: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Bacarıq tapşırıq kontekstini alır (mesajlar, metadata) → strukturlaşdırılmış nəticə qaytarır
3. src/lib/a2a/taskExecution.ts-də A2A_SKILL_HANDLERS-də qeyd edin
4. src/app/.well-known/agent.json/route.ts-də açın (Agent Kartı)
5. tests/unit/-də testlər yazın
6. docs/frameworks/A2A-SERVER.md bacarıq cədvəlində sənədləşdirin

Yeni Bulud Agentini Əlavə Etmək

1. src/lib/cloudAgent/agents/-də CloudAgentBase-dən uzanan agent sinfini yaradın (artıq 3 mövcuddur: codex-cloud, devin, jules)
2. createTask, getStatus, approvePlan, sendMessage, listSources-i həyata keçirin
3. src/lib/cloudAgent/registry.ts-də qeyd edin
4. Lazım olduqda OAuth/şifrələr idarəetməsini əlavə edin (src/lib/oauth/providers/)
5. Testlər + docs/frameworks/CLOUD_AGENT.md-də sənədləşdirin

Yeni Guardrail / Eval / Bacarıq / Webhook hadisəsi Əlavə Etmək

• Guardrail: src/lib/guardrails/ → sənədlər: docs/security/GUARDRAILS.md
• Eval dəsti: src/lib/evals/ → sənədlər: docs/frameworks/EVALS.md
• Bacarıq (sandbox): src/lib/skills/ → sənədlər: docs/frameworks/SKILLS.md
• Webhook hadisəsi: src/lib/webhookDispatcher.ts → sənədlər: docs/frameworks/WEBHOOKS.md

İstinad Sənədi

Hər hansı qeyri-adi dəyişiklik üçün, uyğun dərin araşdırmanı əvvəlcə oxuyun:

Sahə	Sənəd
Repo naviqasiyası	docs/architecture/REPOSITORY_MAP.md
Arxitektura	docs/architecture/ARCHITECTURE.md
Mühəndislik istinadı	docs/architecture/CODEBASE_DOCUMENTATION.md
Avtomatik Kombinasiya (9-faktor qiymətləndirmə, 14 strategiya)	docs/routing/AUTO-COMBO.md
Dayanıqlılıq (3 mexanizm)	docs/architecture/RESILIENCE_GUIDE.md
Düşüncə yenidən oynatma	docs/routing/REASONING_REPLAY.md
Bacarıqlar çərçivəsi	docs/frameworks/SKILLS.md
Yaddaş sistemi (FTS5 + Qdrant)	docs/frameworks/MEMORY.md
Bulud agentləri	docs/frameworks/CLOUD_AGENT.md
Qoruyucu çərçivələr (ŞPİ / inyeksiya / vizyon)	docs/security/GUARDRAILS.md
İctimai yuxarı axın etibarnamələri (Gemini/və s.)	docs/security/PUBLIC_CREDS.md
Xəta mesajlarının sanitizasiyası	docs/security/ERROR_SANITIZATION.md
Qiymətləndirmələr	docs/frameworks/EVALS.md
Uyğunluq / audit	docs/security/COMPLIANCE.md
Webhooklar	docs/frameworks/WEBHOOKS.md
İcazə boru xətti	docs/architecture/AUTHZ_GUIDE.md
Gizlilik (TLS / barmaq izi)	docs/security/STEALTH_GUIDE.md
Agent protokolları (A2A / ACP / Bulud)	docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP server	docs/frameworks/MCP-SERVER.md
A2A server	docs/frameworks/A2A-SERVER.md
API istinadı + OpenAPI	docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Təchizatçı kataloqu (avtomatik yaradılmış)	docs/reference/PROVIDER_REFERENCE.md
Buraxılış axını	docs/ops/RELEASE_CHECKLIST.md

---

Test

Nə	Əmr
Birlik testləri	npm run test:unit
Tək fayl	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
Coverage gate	npm run test:coverage (75/75/75/70 — ifadələr/sətirlər/funksiyalar/şaxələr)
Coverage report	npm run coverage:report

PR qaydası: Əgər src/, open-sse/, electron/, və ya bin/ içərisində istehsal kodunu dəyişsəniz, eyni PR-da testləri daxil etməli və ya yeniləməlisiniz.

Test qatının üstünlüyü: birinci birlik → inteqrasiya (çox-modul və ya DB vəziyyəti) → e2e (UI/iş axını yalnız). Xətaların təkrarlanmasını düzəlişdən əvvəl və ya onunla birlikdə avtomatlaşdırılmış testlər kimi kodlayın.

Copilot coverage siyasəti: Bir PR istehsal kodunu dəyişdikdə və coverage 75%-dən (ifadələr/sətirlər/funksiyalar) və ya 70%-dən (şaxələr) aşağıdırsa, yalnız hesabat verməyin — testləri əlavə edin və ya yeniləyin, coverage gate-i yenidən işə salın, sonra təsdiq istəyin. PR hesabatında icra olunan əmr, dəyişdirilmiş test faylları və son coverage nəticəsini daxil edin.

---

Git İş Prosesi

# Heç vaxt birbaşa main-ə commit etməyin
git checkout -b feat/your-feature
git commit -m "feat: dəyişikliklərinizi təsvir edin"
git push -u origin feat/your-feature

Şaxə prefiksləri: feat/, fix/, refactor/, docs/, test/, chore/

Commit formatı (Konvensional Commits): feat(db): circuit breaker əlavə et — sahələr: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky hook-ları:

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

---

Mühit

• İcra mühiti: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modulları
• TypeScript: 5.9+, hədəf ES2022, modul esnext, resolution bundler
• Yol aliasları: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
• Default port: 20128 (API + dashboard eyni portda)
• Məlumat qovluğu: DATA_DIR env var, varsayılan ~/.omniroute/
• Əsas env var-lar: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
• Quraşdırma: cp .env.example .env sonra JWT_SECRET (openssl rand -base64 48) və API_KEY_SECRET (openssl rand -hex 32) yaradın

---

Sərt Qaydalar

1. Heç vaxt gizli məlumatları və ya kimlikləri commit etməyin
2. Heç vaxt localDb.ts-ə məntiq əlavə etməyin
3. Heç vaxt eval() / new Function() / imalı eval istifadə etməyin
4. Heç vaxt birbaşa main-ə commit etməyin
5. Heç vaxt marşrutlarda xam SQL yazmayın — src/lib/db/ modullarından istifadə edin
6. Heç vaxt SSE axınlarında xətaları səssizcə udmayın
7. Həmişə Zod sxemləri ilə girişləri təsdiqləyin
8. İstehsal kodunu dəyişərkən həmişə testləri daxil edin
9. Coverage ≥75% (ifadələr, sətirlər, funksiyalar) / ≥70% (şaxələr) səviyyəsində qalmalıdır. Cari ölçülən: ~82%.
10. Heç vaxt Husky hook-larını (--no-verify, --no-gpg-sign) açıq operator təsdiqi olmadan keçməyin.
11. Heç vaxt ictimai upstream OAuth client_id/secret və ya Firebase Web açarlarını string literal kimi daxil etməyin — həmişə resolvePublicCred() (open-sse/utils/publicCreds.ts) vasitəsilə keçin. docs/security/PUBLIC_CREDS.md-ə baxın.
12. Heç vaxt HTTP / SSE / executor cavablarında xam err.stack / err.message qaytarmayın — həmişə buildErrorBody() və ya sanitizeErrorMessage() (open-sse/utils/error.ts) vasitəsilə yönləndirin. docs/security/ERROR_SANITIZATION.md-ə baxın.
13. Heç vaxt xarici yolları və ya icra dəyərlərini exec()/spawn()-a ötürülən shell skriptlərinə string-interpolate etməyin — bunun əvəzinə env seçimi vasitəsilə ötürün. İstinad: src/mitm/cert/install.ts::updateNssDatabases.
14. Heç vaxt CodeQL / Gizli-Skanlama xəbərdarlığını (a) əvvəlcə yuxarıdakı naxış sənədlərini yoxlamadan, köməkçinin tətbiq olunub-olunmadığını görmək üçün, və (b) rədd etmə şərhində texniki əsaslandırmanı qeyd etmədən rədd etməyin. Precedent: js/stack-trace-exposure sanitizeErrorMessage() vasitəsilə yönləndirilən çağırış yerlərində qaldırılmışdır, bu, tanınmayan xüsusi sanitizatorların olduğu məlum CodeQL məhdudiyyətidir — docs/security/ERROR_SANITIZATION.md-ə istinad edərək false positive olaraq rədd edin.
15. Heç vaxt uşaq prosesləri yaradan marşrutları (/api/mcp/, /api/cli-tools/runtime/) src/server/authz/routeGuard.ts-də isLocalOnlyPath() təsnifatı olmadan daxil etməyin. Loopback icrası hər hansı bir auth yoxlamasından əvvəl şərtsiz baş verir — tunel vasitəsilə sızan JWT prosesin yaranmasına səbəb ola bilməz. docs/security/ROUTE_GUARD_TIERS.md-ə baxın.
16. Heç vaxt commit mesajlarında AI assistant, LLM və ya avtomatlaşdırma hesabını kreditə salan Co-Authored-By əlavələrini daxil etməyin (məsələn, "Claude", "GPT", "Copilot", "Bot" sözlərini ehtiva edən adlar; anthropic.com / openai.com / bot-aid olan noreply.github.com ünvanlarında olan emaillər). Belə əlavələr commitləri GitHub-da bot hesabına aid edir və PR tarixində real müəllifi (diegosouzapw) gizlədir. İnsan əməkdaşları — o cümlədən upstream PR müəllifləri və OmniRoute-a köçürülən issue məruzəçiləri — standart Co-authored-by: Name <email> əlavələri ilə kreditə salına BİLƏRLƏR və SALINMALIDIRLAR; upstream-port iş axınları (/port-upstream-features, /port-upstream-issues) bundan asılıdır.