OmniRoute/docs/i18n/sw/CLAUDE.md

CLAUDE.md (Kiswahili)

🌐 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 · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

---

Hii faili inatoa mwongozo kwa Claude Code (claude.ai/code) unapofanya kazi na msimbo katika hifadhi hii.

Mwanzo wa Haraka

npm install                    # Sakinisha deps (inasanifisha .env kutoka .env.example)
npm run dev                    # Seva ya maendeleo katika http://localhost:20128
npm run build                  # Ujenzi wa uzalishaji (Next.js 16 standalone)
npm run lint                   # ESLint (makosa 0 yanatarajiwa; onyo ni ya awali)
npm run typecheck:core         # Ukaguzi wa TypeScript (inapaswa kuwa safi)
npm run typecheck:noimplicit:core  # Ukaguzi mkali (hakuna implicit any)
npm run test:coverage          # Jaribio la kitengo + lango la kufunika (75/75/75/70 — taarifa/mstari/funzioni/matengo)
npm run check                  # lint + jaribio pamoja
npm run check:cycles           # Gundua utegemezi wa mzunguko

Kuendesha Majaribio

# Faili moja la jaribio (mwanzo wa jaribio la asili la Node.js — majaribio mengi)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# Suite zote
npm run test:all

Kwa matrix kamili ya majaribio, angalia CONTRIBUTING.md → "Kuendesha Majaribio". Kwa usanifu wa kina, angalia AGENTS.md.

---

Mradi kwa Muonekano

OmniRoute — proxy/router ya AI iliyounganishwa. Kipengele kimoja, watoa huduma 160+, auto-fallback.

Tabaka	Mahali	Kusudi
API Routes	src/app/api/v1/	Next.js App Router — maeneo ya kuingia
Handlers	open-sse/handlers/	Usindikaji wa maombi (chat, embeddings, nk)
Executors	open-sse/executors/	Usambazaji wa HTTP maalum kwa mtoa huduma
Translators	open-sse/translator/	Mabadiliko ya muundo (OpenAI↔Claude↔Gemini)
Transformer	open-sse/transformer/	API za majibu ↔ Kukamilisha Chat
Services	open-sse/services/	Uelekeo wa combo, mipaka ya viwango, caching, nk
Database	src/lib/db/	Moduli za eneo la SQLite (faili 45+, uhamasishaji 55)
Domain/Policy	src/domain/	Injini ya sera, sheria za gharama, mantiki ya fallback
MCP Server	open-sse/mcp-server/	Zana 37 (30 msingi + 3 kumbukumbu + 4 ujuzi), usafirishaji 3, ~13 maeneo
A2A Server	src/lib/a2a/	Itifaki ya wakala ya JSON-RPC 2.0
Skills	src/lib/skills/	Mfumo wa ujuzi unaoweza kupanuliwa
Memory	src/lib/memory/	Kumbukumbu ya mazungumzo ya kudumu

Monorepo: src/ (programu ya Next.js 16), open-sse/ (nafasi ya injini ya utiririshaji), electron/ (programu ya desktop), tests/, bin/ (kiingilio cha CLI).

---

Mchakato wa Ombi

Client → /v1/chat/completions (Njia ya Next.js)
  → CORS → Uthibitisho wa Zod → uthibitisho? → ukaguzi wa sera → ulinzi wa kuingiza maelekezo
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → ukaguzi wa cache → kikomo cha kiwango → mwelekeo wa combo?
      → resolveComboTargets() → handleSingleModel() kwa kila lengo
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → jaribu tena w/ backoff
    → tafsiri ya majibu → mkondo wa SSE au JSON
    → Ikiwa ni API za Majibu: responsesTransformer.ts TransformStream

Njia za API zinafuata muundo thabiti: Njia → CORS preflight → Uthibitisho wa Zod → Uthibitisho wa hiari (extractApiKey/isValidApiKey) → Utekelezaji wa sera ya ufunguo wa API → Delegation ya Handler (open-sse). Hakuna middleware ya kimataifa ya Next.js — kukatiza ni maalum kwa njia.

Mwelekeo wa combo (open-sse/services/combo.ts): mikakati 14 (kipaumbele, uzito, kujaza-kwanza, mzunguko, P2C, nasibu, inayotumika kidogo, iliyoboreshwa kwa gharama, inayojua kurekebisha, nasibu kali, auto, lkgp, iliyoboreshwa kwa muktadha, relay ya muktadha). Kila lengo linaita handleSingleModel() ambayo inazunguka handleChatCore() na usimamizi wa makosa ya kila lengo na ukaguzi wa circuit breaker. Tazama docs/routing/AUTO-COMBO.md kwa alama za Auto-Combo za sababu 9 na docs/architecture/RESILIENCE_GUIDE.md kwa tabaka 3 za uhimilivu.

---

Hali ya Uhimilivu wa Wakati

OmniRoute ina mitambo mitatu inayohusiana lakini tofauti ya kushindwa kwa muda. Hifadhi upeo wao tofauti unapofanya ufuatiliaji wa tabia ya mwelekeo. Tazama chati ya uhimilivu ya tabaka 3 (chanzo: docs/diagrams/resilience-3layers.mmd) kwa ramani ya haraka.

Mzigo wa Circuit wa Mtoa

Upeo: mtoa mzima, mfano glm, openai, anthropic.

Madhumuni: kusitisha kutuma trafiki kwa mtoa ambaye anashindwa mara kwa mara katika ngazi ya upstream/service, ili mtoa mmoja asiye na afya usichelewesha kila ombi.

Utekelezaji:

• Darasa kuu: src/shared/utils/circuitBreaker.ts
• Nyaya za lango la mazungumzo/utekelezaji: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
• API ya hali ya wakati: src/app/api/monitoring/health/route.ts
• Vifungashio vya pamoja: open-sse/services/accountFallback.ts
• Jedwali la hali lililohifadhiwa: domain_circuit_breakers

Hali:

• CLOSED: trafiki ya kawaida inaruhusiwa.
• OPEN: mtoa amezuiwa kwa muda; wito hupata jibu la mtoa-circuit-open au mwelekeo wa combo unakosa lengo lingine.
• HALF_OPEN: muda wa kurekebisha umepita; ruhusu ombi la uchunguzi. Mafanikio yanakamilisha breaker, kushindwa kunafungua tena.

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

• Watoa wa OAuth: kigezo 3, muda wa kurekebisha 60s.
• Watoa wa ufunguo wa API: kigezo 5, muda wa kurekebisha 30s.
• Watoa wa ndani: kigezo 2, muda wa kurekebisha 15s.

Ni lazima tu hali za kushindwa za kiwango cha mtoa zifanye kazi ya breaker ya mtoa:

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

Usiweke breaker ya mtoa mzima kwa makosa ya kawaida ya akaunti/ufunguo/model kama vile mambo mengi ya 401, 403, au 429. Hayo kwa kawaida yanahusiana na kupoa kwa muunganisho au kufungwa kwa mfano. Mtoa wa ufunguo wa API wa jumla 403 unapaswa kuwa na uwezo wa kupona isipokuwa ikitambulika kama kosa la mwisho la mtoa/akaunti.

Breaker hutumia urejeleaji wa polepole, sio kipima muda cha nyuma. Wakati OPEN inakoma, kusoma kama getStatus(), canExecute(), na getRetryAfterMs() kunarejesha hali kuwa HALF_OPEN, ili dashibodi na wajenzi wa wagombea wa combo wasiendelee kuondoa mtoa aliyeisha muda milele.

Kupoa kwa Muunganisho

Upeo: muunganisho mmoja wa mtoa/akaunti/ufunguo.

Madhumuni: kupita kwa muda ufunguo mmoja mbaya/akaunti huku ikiruhusu muunganisho mingine kwa mtoa huyo kuendelea kutumikia maombi.

Utekelezaji:

• Njia ya kuandika/update: src/sse/services/auth.ts::markAccountUnavailable()
• Uchaguzi wa akaunti/kuchuja: src/sse/services/auth.ts::getProviderCredentials...
• Hesabu ya kupoa: open-sse/services/accountFallback.ts::checkFallbackError()
• Mipangilio: src/lib/resilience/settings.ts

Sehemu muhimu kwenye muunganisho wa mtoa:

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

Wakati wa uchaguzi wa akaunti, muunganisho unakosa wakati:

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

Kupoa pia ni polepole: wakati rateLimitedUntil iko nyuma, muunganisho unakuwa unaweza tena. Kwa matumizi ya mafanikio, clearAccountError() inafuta testStatus, rateLimitedUntil, sehemu za makosa, na backoffLevel.

Tabia ya msingi ya kupoa muunganisho:

• Msingi wa kupoa wa OAuth: 5s.
• Msingi wa kupoa wa ufunguo wa API: 3s.
• Ufunguo wa API 429 unapaswa kupendelea vidokezo vya kujaribu tena vya upstream (Retry-After, vichwa vya kurekebisha, au maandiko ya kurekebisha yanayoweza kuchambuliwa) inapopatikana.
• Kushindwa kwa kurudi nyuma mara kwa mara hutumia urejeleaji wa kuongezeka:

baseCooldownMs * 2 ** failureIndex;

Mlinzi wa kuzuia thundering-herd unazuia kushindwa kwa wakati mmoja kwenye muunganisho huo huo kutoka kuongeza muda wa kupoa mara kwa mara au kuongezeka mara mbili kwa backoffLevel.

Hali za mwisho si kupoa. banned, expired, na credits_exhausted zinakusudiwa kubaki zisipatikane hadi kuhifadhi au mipangilio kubadilika au opereta akizirekebisha. Usifute hali za mwisho kwa hali ya kupoa ya muda.

Kufungwa kwa Mfano

Upeo: mtoa + muunganisho + mfano.

Madhumuni: kuepuka kuzima muunganisho mzima wakati mfano mmoja tu haupatikani au umewekwa kikomo kwa muunganisho huo.

Mifano:

• Watoa wa quota kwa mfano wanaorejelea 429.
• Watoa wa ndani wanaorejelea 404 kwa mfano mmoja uliokosekana.
• Kushindwa kwa ruhusa ya mfano/mode maalum wa mtoa kama vile modes za Grok zilizochaguliwa.

Kufungwa kwa mfano kunaishi katika open-sse/services/accountFallback.ts na inaruhusu muunganisho huo huo kuendelea kutumikia mifano mingine.

Mwongozo wa Ufuatiliaji

• Ikiwa funguo zote za mtoa zimeachwa, angalia hali ya breaker ya mtoa na kila muunganisho wa rateLimitedUntil/testStatus.
• Ikiwa mtoa anaonekana kuondolewa milele baada ya dirisha la kurekebisha, angalia ikiwa msimbo unasoma state halisi badala ya kutumia getStatus()/canExecute().
• Ikiwa funguo moja ya mtoa inashindwa lakini zingine zinapaswa kufanya kazi, pendelea kupoa kwa muunganisho badala ya breaker ya mtoa.
• Ikiwa mfano mmoja tu unashindwa, pendelea kufungwa kwa mfano badala ya kupoa kwa muunganisho.
• Ikiwa hali inapaswa kujiokoa yenyewe, inapaswa kuwa na alama ya wakati wa baadaye/muda wa kurekebisha na njia ya kusoma inayorejesha hali iliyokwisha muda. Hali za kudumu zinahitaji mabadiliko ya mikopo au mipangilio kwa mkono.

Misingi Muhimu

Mtindo wa Kanuni

• Spaces 2, semicolons, double quotes, upana wa herufi 100, es5 trailing commas (inasimamiwa na lint-staged kupitia Prettier)
• Maaliko: nje → ndani (@/, @omniroute/open-sse) → ya uhusiano
• Majina: faili=camelCase/kebab, vipengele=PascalCase, constants=UPPER_SNAKE
• ESLint: no-eval, no-implied-eval, no-new-func = kosa kila mahali; no-explicit-any = onyo katika open-sse/ na tests/
• TypeScript: strict: false, lengo ES2022, moduli esnext, resolution bundler. Prefer explicit types.

Hifadhidata

• Daima pitia moduli za eneo src/lib/db/ — kamwe usiandike SQL safi katika njia au wakala
• Kamwe usiongeze mantiki katika src/lib/localDb.ts (safi ya re-export tu)
• Kamwe usi-import barrel kutoka localDb.ts — badala yake, import moduli maalum za db/
• DB singleton: getDbInstance() kutoka src/lib/db/core.ts (WAL journaling)
• Migrations: src/lib/db/migrations/ — faili za SQL zenye toleo, idempotent, zitekelezwe katika muamala

Kushughulikia Makosa

• jaribu/catch na aina maalum za makosa, log na muktadha wa pino
• Kamwe usifanye makosa katika SSE streams — tumia ishara za kukatisha kwa usafishaji
• Rudisha msimamo sahihi wa HTTP (4xx/5xx)

Usalama

• Kamwe usitumie eval(), new Function(), au eval iliyodhaniwa
• Thibitisha kila ingizo kwa kutumia Zod schemas
• Ficha akidi wakati wa kupumzika (AES-256-GCM)
• Orodha ya vichwa vya juu ya denylist: src/shared/constants/upstreamHeaders.ts — panua sanitize, Zod schemas, na vipimo vya kitengo vinavyolingana unapohariri
• Akidi za umma za juu (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web keys zilizochukuliwa kutoka kwa CLIs za umma): LAZIMA ziwe zimeingizwa kupitia resolvePublicCred() kutoka open-sse/utils/publicCreds.ts — kamwe kama maandiko ya herufi. Tazama docs/security/PUBLIC_CREDS.md kwa muundo wa lazima.
• Majibu ya makosa (HTTP / SSE / executor / MCP handler): LAZIMA ipitie buildErrorBody() au sanitizeErrorMessage() kutoka open-sse/utils/error.ts — kamwe usiweke raw err.stack au raw err.message katika mwili wa majibu. Tazama docs/security/ERROR_SANITIZATION.md.
• Amri za shell zilizojengwa kutoka kwa mabadiliko: unapoitisha exec()/spawn() na skripti inayohitaji thamani za wakati wa kukimbia, zipitisheni kupitia chaguo la env (imekimbizwa kiotomatiki) — kamwe usiingize mabadiliko yasiyoaminika/ya nje katika mwili wa skripti. Rejelea: src/mitm/cert/install.ts::updateNssDatabases.
• Maktaba salama kwa default (tldrsec/awesome-secure-defaults): pendelea Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink kuliko utekelezaji wa kawaida kila wakati unapoongeza uso mpya wa usalama.

---

Mifano ya Marekebisho ya Kawaida

Kuongeza Mtoa Huduma Mpya

1. Jisajili katika src/shared/constants/providers.ts (Zod-validated wakati wa kupakia)
2. Ongeza mtendaji katika open-sse/executors/ ikiwa mantiki maalum inahitajika (panua BaseExecutor)
3. Ongeza mtafsiri katika open-sse/translator/ ikiwa si muundo wa OpenAI
4. Ongeza usanidi wa OAuth katika src/lib/oauth/constants/oauth.ts ikiwa ni msingi wa OAuth — ikiwa CLI ya juu inatoa client_id/secret ya umma, ingiza kupitia resolvePublicCred() (tazama docs/security/PUBLIC_CREDS.md), kamwe kama maandiko
5. Jisajili mifano katika open-sse/config/providerRegistry.ts
6. Andika vipimo katika tests/unit/ (jumuisha uthibitisho wa umbo la publicCreds ikiwa umeongeza default mpya iliyounganishwa)

Kuongeza Njia Mpya ya API

1. Unda directory chini ya src/app/api/v1/your-route/
2. Unda route.ts na wakala wa GET/POST
3. Fuata muundo: CORS → uthibitisho wa mwili wa Zod → uthibitisho wa hiari → ugawaji wa wakala
4. Wakala huenda katika open-sse/handlers/ (import kutoka hapo, si inline)
5. Majibu ya makosa yanatumia buildErrorBody() / errorResponse() kutoka open-sse/utils/error.ts (imekimbizwa kiotomatiki — kamwe usiweke raw err.stack au raw err.message katika mwili). Tazama docs/security/ERROR_SANITIZATION.md.
6. Ongeza vipimo — ikiwa ni pamoja na angalau uthibitisho mmoja kwamba majibu ya makosa hayavuji nyaraka za stack (!body.error.message.includes("at /"))

Kuongeza Moduli Mpya ya DB

1. Unda src/lib/db/yourModule.ts — import getDbInstance kutoka ./core.ts
2. Export kazi za CRUD kwa ajili ya jedwali lako la eneo
3. Ongeza uhamasishaji katika src/lib/db/migrations/ ikiwa jedwali mpya zinahitajika
4. Re-export kutoka src/lib/localDb.ts (ongeza kwenye orodha ya re-export tu)
5. Andika vipimo

Kuongeza Zana Mpya ya MCP

1. Ongeza ufafanuzi wa zana katika open-sse/mcp-server/tools/ na muundo wa ingizo la Zod + wakala wa async
2. Jisajili katika seti ya zana (imeunganishwa na createMcpServer())
3. Teua kwa upeo unaofaa
4. Andika vipimo (kuitisha zana kunarekodiwa kwenye jedwali la mcp_audit)

Kuongeza Ujuzi Mpya wa A2A

1. Unda ujuzi katika src/lib/a2a/skills/ (5 tayari zipo: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Ujuzi unapata muktadha wa kazi (jumbe, metadata) → unarudisha matokeo yaliyoandaliwa
3. Jisajili katika A2A_SKILL_HANDLERS katika src/lib/a2a/taskExecution.ts
4. Funua katika src/app/.well-known/agent.json/route.ts (Kadi ya Wakala)
5. Andika vipimo katika tests/unit/
6. Andika katika docs/frameworks/A2A-SERVER.md jedwali la ujuzi

Kuongeza Wakala Mpya wa Cloud

1. Unda darasa la wakala katika src/lib/cloudAgent/agents/ ukipanua CloudAgentBase (3 tayari zipo: codex-cloud, devin, jules)
2. Tekeleza createTask, getStatus, approvePlan, sendMessage, listSources
3. Jisajili katika src/lib/cloudAgent/registry.ts
4. Ongeza usimamizi wa OAuth/akidi ikiwa inahitajika (src/lib/oauth/providers/)
5. Vipimo + andika katika docs/frameworks/CLOUD_AGENT.md

Kuongeza Guardrail Mpya / Eval / Ujuzi / Tukio la Webhook

• Guardrail: src/lib/guardrails/ → docs: docs/security/GUARDRAILS.md
• Eval suite: src/lib/evals/ → docs: docs/frameworks/EVALS.md
• Ujuzi (sandbox): src/lib/skills/ → docs: docs/frameworks/SKILLS.md
• Tukio la Webhook: src/lib/webhookDispatcher.ts → docs: docs/frameworks/WEBHOOKS.md

Hati ya Marejeleo

Kwa mabadiliko yoyote yasiyo ya kawaida, soma uchambuzi unaofanana kwanza:

Eneo	Hati
Usafiri wa repo	docs/architecture/REPOSITORY_MAP.md
Muktadha	docs/architecture/ARCHITECTURE.md
Marejeleo ya uhandisi	docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (alama 9, mikakati 14)	docs/routing/AUTO-COMBO.md
Ustahimilivu (mekaniki 3)	docs/architecture/RESILIENCE_GUIDE.md
Kurudi kwa mantiki	docs/routing/REASONING_REPLAY.md
Mfumo wa ujuzi	docs/frameworks/SKILLS.md
Mfumo wa kumbukumbu (FTS5 + Qdrant)	docs/frameworks/MEMORY.md
Wakala wa wingu	docs/frameworks/CLOUD_AGENT.md
Miongozo (PII / sindikizo / maono)	docs/security/GUARDRAILS.md
Akreditivu za umma za juu (Gemini/n.k.)	docs/security/PUBLIC_CREDS.md
Usafi wa ujumbe wa makosa	docs/security/ERROR_SANITIZATION.md
Tathmini	docs/frameworks/EVALS.md
Uzingatiaji / ukaguzi	docs/security/COMPLIANCE.md
Webhooks	docs/frameworks/WEBHOOKS.md
Mchakato waidhinisha	docs/architecture/AUTHZ_GUIDE.md
Usiri (TLS / alama ya vidole)	docs/security/STEALTH_GUIDE.md
Itifaki za wakala (A2A / ACP / Wingu)	docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
Seva ya MCP	docs/frameworks/MCP-SERVER.md
Seva ya A2A	docs/frameworks/A2A-SERVER.md
Marejeleo ya API + OpenAPI	docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Katalogi ya wasambazaji (iliyoundwa kiotomatiki)	docs/reference/PROVIDER_REFERENCE.md
Mchakato wa kutolewa	docs/ops/RELEASE_CHECKLIST.md

---

Kupima

Nini	Amri
Vipimo vya kitengo	npm run test:unit
Faili moja	node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo)	npm run test:vitest
E2E (Playwright)	npm run test:e2e
Protokali E2E (MCP+A2A)	npm run test:protocols:e2e
Mfumo	npm run test:ecosystem
Lango la kufunika	npm run test:coverage (75/75/75/70 — taarifa/mstari/funzo/mat branch)
Ripoti ya kufunika	npm run coverage:report

Kanuni ya PR: Ikiwa unabadilisha msimbo wa uzalishaji katika src/, open-sse/, electron/, au bin/, lazima uweke au uboreshe vipimo katika PR hiyo hiyo.

Upendeleo wa tabaka la mtihani: kitengo kwanza → uunganisho (moduli nyingi au hali ya DB) → e2e (UI/mchakato tu). Fanya urekebishaji wa bug kama vipimo vya kiotomatiki kabla au pamoja na suluhisho.

Sera ya kufunika ya Copilot: Wakati PR inabadilisha msimbo wa uzalishaji na kufunika iko chini ya 75% (taarifa/mstari/funzo) au 70% (mata branch), usiweke tu ripoti — ongeza au boresha vipimo, rudisha lango la kufunika, kisha omba uthibitisho. Jumuisha amri zilizotekelezwa, faili za mtihani zilizobadilishwa, na matokeo ya mwisho ya kufunika katika ripoti ya PR.

---

Mchakato wa Git

# Kamwe usiweke moja kwa moja kwenye main
git checkout -b feat/your-feature
git commit -m "feat: eleza mabadiliko yako"
git push -u origin feat/your-feature

Viambatisho vya tawi: feat/, fix/, refactor/, docs/, test/, chore/

Muundo wa commit (Conventional Commits): feat(db): ongeza circuit breaker — maeneo: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky hooks:

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

---

Mazingira

• Muda wa kukimbia: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, Moduli za ES
• TypeScript: 5.9+, lengo ES2022, moduli esnext, ufumbuzi wa bundler
• Majina ya njia: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
• Bandari ya kawaida: 20128 (API + dashibodi kwenye bandari moja)
• Direktori ya data: DATA_DIR env var, inarudiwa kwa ~/.omniroute/
• Vigezo muhimu vya env: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
• Mipangilio: cp .env.example .env kisha tengeneza JWT_SECRET (openssl rand -base64 48) na API_KEY_SECRET (openssl rand -hex 32)

---

Kanuni Ngumu

1. Kamwe usiweke siri au akidi
2. Kamwe usiongeze mantiki kwenye localDb.ts
3. Kamwe usitumie eval() / new Function() / eval iliyodhaniwa
4. Kamwe usiweke moja kwa moja kwenye main
5. Kamwe usiandike SQL safi katika njia — tumia moduli za src/lib/db/
6. Kamwe usinyamaze makosa kwa kimya katika SSE streams
7. Daima thibitisha ingizo kwa kutumia Zod schemas
8. Daima jumuisha vipimo unapobadilisha msimbo wa uzalishaji
9. Kufunika lazima kubaki ≥75% (taarifa, mistari, funzo) / ≥70% (mata branch). Kiwango cha sasa kilichopimwa: ~82%.
10. Kamwe usipite Husky hooks (--no-verify, --no-gpg-sign) bila idhini ya wazi ya opereta.
11. Kamwe usiweke funguo za umma za OAuth client_id/secret au funguo za Firebase Web kama maandiko ya maandiko — daima pitia resolvePublicCred() (open-sse/utils/publicCreds.ts). Tazama docs/security/PUBLIC_CREDS.md.
12. Kamwe usirudishe raw err.stack / err.message katika HTTP / SSE / majibu ya mtendaji — daima pitia kupitia buildErrorBody() au sanitizeErrorMessage() (open-sse/utils/error.ts). Tazama docs/security/ERROR_SANITIZATION.md.
13. Kamwe usiingize njia za nje au thamani za kukimbia katika scripts za shell zinazopitishwa kwa exec()/spawn() — pitisha kupitia chaguo la env badala yake. Kumbuka: src/mitm/cert/install.ts::updateNssDatabases.
14. Kamwe usikatae arifa za CodeQL / Secret-Scanning bila (a) kwanza kuangalia hati za muundo hapo juu kuona kama msaidizi anatumika, na (b) kurekodi sababu ya kiufundi katika maoni ya kukataa. Kiwango: js/stack-trace-exposure kilichoinuliwa kwenye maeneo ya wito ambayo tayari yanapitia sanitizeErrorMessage() ni ukomo unaojulikana wa CodeQL (wasafishaji wa kawaida hawatambuliwi) — kataa kama false positive ukirejelea docs/security/ERROR_SANITIZATION.md.
15. Kamwe usifichue njia zinazozalisha michakato ya watoto (/api/mcp/, /api/cli-tools/runtime/) bila uainishaji wa isLocalOnlyPath() katika src/server/authz/routeGuard.ts. Utekelezaji wa loopback unafanyika bila masharti kabla ya ukaguzi wowote wa uthibitisho — JWT iliyovuja kupitia tunnel haiwezi kuanzisha uzalishaji wa mchakato. Tazama docs/security/ROUTE_GUARD_TIERS.md.
16. Usijumuishe kamwe trailers Co-Authored-By zinazompa sifa msaidizi wa AI, LLM, au akaunti ya automation (mfano majina yenye "Claude", "GPT", "Copilot", "Bot"; barua pepe katika anthropic.com / openai.com / anwani za noreply.github.com zinazomilikiwa na bots). Trailers kama hizi huelekeza attribution ya commit kwa akaunti ya bot katika GitHub, zikificha mwandishi halisi (diegosouzapw) katika historia ya PR. Washirikiano wa kibinadamu — pamoja na waandishi wa PR za upstream na waripoti wa issues wanaohamishwa kwenda OmniRoute — WANAWEZA na WANAPASWA kupewa sifa kwa trailers za kawaida Co-authored-by: Name <email>; mtiririko wa kazi wa upstream-port (/port-upstream-features, /port-upstream-issues) hutegemea hii.