OmniRoute/docs/i18n/fi/CLAUDE.md

CLAUDE.md (Suomi)

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇷 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

---

Tämä tiedosto tarjoaa ohjeita Claude Code (claude.ai/code) käytettäessä koodia tässä repositoriossa.

Nopeasti alkuun

npm install                    # Asenna riippuvuudet (automaattisesti luo .env .env.example:sta)
npm run dev                    # Kehityspalvelin osoitteessa http://localhost:20128
npm run build                  # Tuotantorakennus (Next.js 16 standalone)
npm run lint                   # ESLint (0 virhettä odotettavissa; varoitukset ovat ennestään olemassa)
npm run typecheck:core         # TypeScript-tarkistus (pitäisi olla puhdas)
npm run typecheck:noimplicit:core  # Tiukka tarkistus (ei implisiittistä any)
npm run test:coverage          # Yksikkötestit + kattavuusportti (75/75/75/70 — lauseet/rivit/funktiot/haarat)
npm run check                  # lint + test yhdistettynä
npm run check:cycles           # Havaitse sykliset riippuvuudet

Testien suorittaminen

# Yksittäinen testitiedosto (Node.js:n natiivinen testirunner — suurin osa testeistä)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP-palvelin, autoCombo, välimuisti)
npm run test:vitest

# Kaikki testisarjat
npm run test:all

Koko testimatriisin näkemiseksi katso CONTRIBUTING.md → "Testien suorittaminen". Syvällistä arkkitehtuuria varten katso AGENTS.md.

---

Projekti lyhyesti

OmniRoute — yhtenäinen AI-proxy/reititin. Yksi päätepiste, yli 160 LLM-toimittajaa, automaattinen varajärjestelmä.

Kerros	Sijainti	Tarkoitus
API-reitit	src/app/api/v1/	Next.js App Router — sisäänkäynnit
Käsittelijät	open-sse/handlers/	Pyyntöjen käsittely (keskustelu, upotukset jne.)
Suorittajat	open-sse/executors/	Toimittajakohtainen HTTP-jakelu
Kääntäjät	open-sse/translator/	Muotojen muunnos (OpenAI↔Claude↔Gemini)
Muuntaja	open-sse/transformer/	Vastaukset API ↔ Keskustelun täydentäminen
Palvelut	open-sse/services/	Combo-reititys, nopeusrajoitukset, välimuisti jne.
Tietokanta	src/lib/db/	SQLite-alueen moduulit (yli 45 tiedostoa, 55 migraatiota)
Alue/Politiikka	src/domain/	Politiikkamoottori, kustannussäännöt, varajärjestelmä
MCP-palvelin	open-sse/mcp-server/	37 työkalua (30 perus + 3 muisti + 4 taitoa), 3 kuljetusta, ~13 laajuutta
A2A-palvelin	src/lib/a2a/	JSON-RPC 2.0 agenttiprotokolla
Taidot	src/lib/skills/	Laajennettavissa oleva taitokehys
Muisti	src/lib/memory/	Kestävä keskustelumuisti

Monorepo: src/ (Next.js 16 -sovellus), open-sse/ (suoratoistoalustatyötila), electron/ (työpöytäsovellus), tests/, bin/ (CLI-sisäänkäynti).

Pyyntöputki

Asiakas → /v1/chat/completions (Next.js-reitti)
  → CORS → Zod-validointi → auth? → politiikan tarkistus → kehotteen injektoinnin suoja
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → välimuistin tarkistus → nopeusrajoitus → yhdistelmäreittaus?
      → resolveComboTargets() → handleSingleModel() per kohde
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → yritä uudelleen w/ backoff
    → vastausten käännös → SSE-virta tai JSON
    → Jos Responses API: responsesTransformer.ts TransformStream

API-reitit noudattavat johdonmukaista kaavaa: Reitti → CORS-esivalmistelu → Zod-kehon validointi → Valinnainen auth (extractApiKey/isValidApiKey) → API-avaimen politiikan täytäntöönpano → Käsittelijän delegointi (open-sse). Ei globaalia Next.js-välikkää — keskeytys on reitti-spesifinen.

Yhdistelmäreittaus (open-sse/services/combo.ts): 14 strategiaa (prioriteetti, painotettu, täytä-ensin, vuorotellen, P2C, satunnainen, vähiten käytetty, kustannusoptimoitu, reset-tieto, tiukka-satunnainen, automaattinen, lkgp, konteksti-optimoitu, konteksti-väylä). Jokainen kohde kutsuu handleSingleModel(), joka käärii handleChatCore()-funktion kohdekohtaisella virheenkäsittelyllä ja piirikytkin tarkistuksilla. Katso docs/routing/AUTO-COMBO.md 9-tekijän Auto-Combo-pisteytykselle ja docs/architecture/RESILIENCE_GUIDE.md 3-resilienssikerrokselle.

---

Resilienssin Suorituskykytila

OmniRoute:lla on kolme liittyvää mutta erilaista tilapäisen epäonnistumisen mekanismia. Pidä niiden alueet erillään reitityskäyttäytymisen vianetsinnässä. Katso 3-kerroksinen resilienssikaavio (lähde: docs/diagrams/resilience-3layers.mmd) nopeaa karttaa varten.

Palveluntarjoajan Piirikytkin

Alue: koko palveluntarjoaja, esim. glm, openai, anthropic.

Tarkoitus: lopettaa liikenteen lähettäminen palveluntarjoajalle, joka epäonnistuu toistuvasti ylävirrassa/palvelutasolla, jotta yksi epäterveellinen palveluntarjoaja ei hidasta jokaista pyyntöä.

Toteutus:

• Ydinluokka: src/shared/utils/circuitBreaker.ts
• Chat-portti/suorituskykykaapeli: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
• Suorituskykytila API: src/app/api/monitoring/health/route.ts
• Jaetut kääreet: open-sse/services/accountFallback.ts
• Kestävän tilan taulukko: domain_circuit_breakers

Tilat:

• CLOSED: normaali liikenne on sallittu.
• OPEN: palveluntarjoaja on tilapäisesti estetty; kutsujat saavat palveluntarjoaja-piirikytkin-avoin -vastauksen tai yhdistelmäreittaus ohittaa toiseen kohteeseen.
• HALF_OPEN: nollaus-aika on kulunut; salli koepyyntö. Onnistuminen sulkee kytkimen, epäonnistuminen avaa sen uudelleen.

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

• OAuth-palveluntarjoajat: kynnys 3, nollausaika 60s.
• API-avaimen palveluntarjoajat: kynnys 5, nollausaika 30s.
• Paikalliset palveluntarjoajat: kynnys 2, nollausaika 15s.

Vain palveluntarjoajatasoiset epäonnistumistilat saavat aktivoida palveluntarjoajan kytkimen:

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

Älä aktivoi koko palveluntarjoajan kytkintä normaaleille tili/avain/malli-virheille, kuten useimmille 401, 403 tai 429 tapauksille. Ne kuuluvat yleensä yhteyden jäähdytysaikaan tai mallin lukitsemiseen. Yleinen API-avaimen palveluntarjoajan 403 pitäisi olla palautettavissa, ellei sitä luokitella terminaaliseksi palveluntarjoaja/tilivirheeksi.

Kytkin käyttää laiskaa palautumista, ei taustakelloa. Kun OPEN vanhenee, lukemiset kuten getStatus(), canExecute(), ja getRetryAfterMs() päivittävät tilan HALF_OPEN:ksi, jotta koontinäytöt ja yhdistelmäehdokkaat eivät jatkuvasti sulje vanhentunutta palveluntarjoajaa.

Yhteyden Jäähdytys

Alue: yksi palveluntarjoajan yhteys/tili/avain.

Tarkoitus: ohittaa tilapäisesti yksi huono avain/tili samalla kun sallitaan muiden yhteyksien saman palveluntarjoajan jatkaa pyyntöjen palvelemista.

Toteutus:

• Kirjoitus/päivityspolku: src/sse/services/auth.ts::markAccountUnavailable()
• Tilin valinta/suodatus: src/sse/services/auth.ts::getProviderCredentials...
• Jäähdytyksen laskenta: open-sse/services/accountFallback.ts::checkFallbackError()
• Asetukset: src/lib/resilience/settings.ts

Tärkeitä kenttiä palveluntarjoajan yhteyksissä:

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

Tilivalinnan aikana yhteys ohitetaan, kun:

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

Jäähdytykset ovat myös laiskoja: kun rateLimitedUntil on menneisyydessä, yhteys tulee uudelleen kelpoiseksi. Onnistuneessa käytössä clearAccountError() tyhjentää testStatus, rateLimitedUntil, virhekentät ja backoffLevel.

Oletusarvoinen yhteyden jäähdytys käyttäytyminen:

• OAuth-perusjäähdytys: 5s.
• API-avaimen perusjäähdytys: 3s.
• API-avaimen 429 pitäisi suosia ylävirran uudelleenyritysohjeita (Retry-After, nollausotsikot tai parsittava nollusteksti) kun saatavilla.
• Toistuvat palautettavat epäonnistumiset käyttävät eksponentiaalista taaksepäin:

baseCooldownMs * 2 ** failureIndex;

Anti-thundering-herd-suoja estää samanaikaisia epäonnistumisia samalla yhteydellä toistuvasti pidentämästä jäähdytystä tai kaksinkertaistamasta backoffLevel:ia.

Terminologiset tilat eivät ole jäähdytyksiä. banned, expired, ja credits_exhausted on tarkoitettu pysymään saatavilla, kunnes tunnistetiedot/asetukset muuttuvat tai operaattori nollaa ne. Älä ylikirjoita terminologisia tiloja tilapäisellä jäähdytystilalla.

Mallin Lukitus

Alue: palveluntarjoaja + yhteys + malli.

Tarkoitus: välttää koko yhteyden estämistä, kun vain yksi malli on saatavilla tai kiintiörajoitettu tälle yhteydelle.

Esimerkkejä:

• Per-malli kiintiöpalveluntarjoajat, jotka palauttavat 429.
• Paikalliset palveluntarjoajat, jotka palauttavat 404 yhdelle puuttuvasta mallista.
• Palveluntarjoajakohtaiset tila/mallilupa epäonnistumiset, kuten valitut Grok-tilat.

Mallin lukitus sijaitsee open-sse/services/accountFallback.ts ja sallii saman yhteyden jatkaa muiden mallien palvelemista.

Vianetsintäohjeet

• Jos kaikki avaimet palveluntarjoajalle ohitetaan, tarkista sekä palveluntarjoajan kytkimen tila että jokaisen yhteyden rateLimitedUntil/testStatus.
• Jos palveluntarjoaja näyttää pysyvästi suljetulta nollausikkunan jälkeen, tarkista, lukevatko koodi raakaa state:a sen sijaan, että käyttäisivät getStatus()/canExecute().
• Jos yksi palveluntarjoajan avain epäonnistuu, mutta muiden pitäisi toimia, suosii yhteyden jäähdytystä palveluntarjoajan kytkimen yli.
• Jos vain yksi malli epäonnistuu, suosii mallin lukitusta yhteyden jäähdytyksen yli.
• Jos tilan pitäisi palautua itsestään, sillä pitäisi olla tuleva aikaleima/nollausaika ja lukupolku, joka päivittää vanhentuneen tilan. Pysyvät tilat vaativat manuaalisia tunnistetietoja tai konfiguraatiomuutoksia.

Avain Konventiot

Koodityyli

• 2 välilyöntiä, puolipisteet, kaksoisviittaukset, 100 merkin leveys, es5 loppupisteet (pakotettu lint-stagedin kautta Prettierillä)
• Tuonnit: ulkoiset → sisäiset (@/, @omniroute/open-sse) → suhteelliset
• Nimeäminen: tiedostot=camelCase/kebab, komponentit=PascalCase, vakioarvot=UPPER_SNAKE
• ESLint: no-eval, no-implied-eval, no-new-func = virhe kaikkialla; no-explicit-any = varoitus open-sse/ ja tests/
• TypeScript: strict: false, kohde ES2022, moduuli esnext, resoluutio bundler. Suosi eksplisiittisiä tyyppejä.

Tietokanta

• Aina käytä src/lib/db/ alueen moduuleja — älä koskaan kirjoita raakaa SQL:ta reiteille tai käsittelijöille
• Älä koskaan lisää logiikkaa src/lib/localDb.ts (vain uudelleenvienti kerros)
• Älä koskaan barrel-importoi localDb.ts — tuo spesifisiä db/ moduuleja sen sijaan
• DB singleton: getDbInstance() src/lib/db/core.ts (WAL lokitus)
• Migraatiot: src/lib/db/migrations/ — versioidut SQL-tiedostot, idempotentit, suoritetaan transaktioissa

Virheiden käsittely

• try/catch tietyillä virhetyypeillä, lokita pino kontekstilla
• Älä koskaan niele virheitä SSE-virroissa — käytä keskeytyssignaaleja siivoukseen
• Palauta oikeat HTTP-tilakoodit (4xx/5xx)

Turvallisuus

• Älä koskaan käytä eval(), new Function(), tai implikoitua evalia
• Vahvista kaikki syötteet Zod-skeemoilla
• Salaa tunnistetiedot levossa (AES-256-GCM)
• Ylöspäin suuntautuvan otsikon estolista: src/shared/constants/upstreamHeaders.ts — pidä puhdistus, Zod-skeemat ja yksikkötestit synkronoituna muokkaamisen aikana
• Julkiset ylöspäin suuntautuvat tunnistetiedot (Gemini/Antigravity/Windsurf-tyylinen OAuth client_id/salaisuus + Firebase Web -avaimet, jotka on saatu julkisista CLI:stä): ON upotettava resolvePublicCred() kautta open-sse/utils/publicCreds.ts — älä koskaan merkkijonolitteraalina. Katso docs/security/PUBLIC_CREDS.md pakollisesta mallista.
• Virhevastaukset (HTTP / SSE / suorittaja / MCP-käsittelijä): ON ohjattava buildErrorBody() tai sanitizeErrorMessage() kautta open-sse/utils/error.ts — älä koskaan laita raakaa err.stack tai err.message vastauskehoon. Katso docs/security/ERROR_SANITIZATION.md.
• Shell-komennot, jotka on rakennettu muuttujista: kun kutsut exec()/spawn() skriptiä, joka tarvitsee ajonaikaisia arvoja, siirrä ne env-vaihtoehdon kautta (shell-escape automaattisesti) — älä koskaan merkkijonointerpoloi luotettomia/ulkopuolisia polkuja skriptin kehoon. Viite: src/mitm/cert/install.ts::updateNssDatabases.
• Oletusarvoisesti turvalliset kirjastot (tldrsec/awesome-secure-defaults): suosi Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink yli mukautettujen toteutusten aina, kun lisäät uusia turvallisuuteen liittyviä pintoja.

---

Yleiset Muokkausskenaariot

Uuden Palveluntarjoajan Lisääminen

1. Rekisteröi src/shared/constants/providers.ts (Zod-vahvistettu latauksessa)
2. Lisää suorittaja open-sse/executors/ jos tarvitaan mukautettua logiikkaa (laajenna BaseExecutor)
3. Lisää kääntäjä open-sse/translator/ jos ei-OpenAI-muoto
4. Lisää OAuth-konfiguraatio src/lib/oauth/constants/oauth.ts jos perustuu OAuth:iin — jos ylöspäin suuntautuva CLI toimittaa julkisen client_id/salaisuuden, upota resolvePublicCred() kautta (katso docs/security/PUBLIC_CREDS.md), älä koskaan litteraalina
5. Rekisteröi mallit open-sse/config/providerRegistry.ts
6. Kirjoita testit tests/unit/ (sisällytä publicCreds-muodon vahvistus, jos lisäsit uuden upotetun oletuksen)

Uuden API-reitin Lisääminen

1. Luo hakemisto src/app/api/v1/your-route/
2. Luo route.ts GET/POST käsittelijöillä
3. Noudata kaavaa: CORS → Zod-kehon vahvistus → valinnainen todennus → käsittelijän delegointi
4. Käsittelijä menee open-sse/handlers/ (tuo sieltä, ei inline)
5. Virhevastaukset käyttävät buildErrorBody() / errorResponse() open-sse/utils/error.ts (automaattisesti puhdistettu — älä koskaan laita err.stack tai err.message raakana kehoon). Katso docs/security/ERROR_SANITIZATION.md.
6. Lisää testit — mukaan lukien vähintään yksi vahvistus, että virhevastaukset eivät vuoda pinojälkiä (!body.error.message.includes("at /"))

Uuden DB-moduulin Lisääminen

1. Luo src/lib/db/yourModule.ts — tuo getDbInstance ./core.ts:stä
2. Vie CRUD-toiminnot alueen taulukoillesi
3. Lisää migraatio src/lib/db/migrations/ jos uusia tauluja tarvitaan
4. Uudelleenvienti src/lib/localDb.ts (lisää vain uudelleenvientiluetteloon)
5. Kirjoita testit

Uuden MCP-työkalun Lisääminen

1. Lisää työkalun määritelmä open-sse/mcp-server/tools/ Zod-syöteskeeman + asynkronisen käsittelijän kanssa
2. Rekisteröi työkalusarjaan (kytketty createMcpServer() kautta)
3. Määritä sopiville alueille
4. Kirjoita testit (työkalun kutsu lokitetaan mcp_audit tauluun)

Uuden A2A-taidon Lisääminen

1. Luo taito src/lib/a2a/skills/ (5 on jo olemassa: älykäs-reititys, kiintiöhallinta, palveluntarjoajan-haku, kustannusanalyysi, terveysraportti)
2. Taito saa tehtäväkontekstin (viestit, metatiedot) → palauttaa rakenteellisen tuloksen
3. Rekisteröi A2A_SKILL_HANDLERS src/lib/a2a/taskExecution.ts tiedostossa
4. Altista src/app/.well-known/agent.json/route.ts (Agent Card)
5. Kirjoita testit tests/unit/
6. Dokumentoi docs/frameworks/A2A-SERVER.md taitotaulukossa

Uuden Pilviagentin Lisääminen

1. Luo agenttiluokka src/lib/cloudAgent/agents/ laajentamalla CloudAgentBase (3 on jo olemassa: codex-cloud, devin, jules)
2. Toteuta createTask, getStatus, approvePlan, sendMessage, listSources
3. Rekisteröi src/lib/cloudAgent/registry.ts
4. Lisää OAuth/tunnistetietojen käsittely tarvittaessa (src/lib/oauth/providers/)
5. Testit + dokumentoi docs/frameworks/CLOUD_AGENT.md

Uuden Guardrail / Eval / Taito / Webhook-tapahtuman Lisääminen

• Guardrail: src/lib/guardrails/ → dokumentaatio: docs/security/GUARDRAILS.md
• Eval-sarja: src/lib/evals/ → dokumentaatio: docs/frameworks/EVALS.md
• Taito (sandbox): src/lib/skills/ → dokumentaatio: docs/frameworks/SKILLS.md
• Webhook-tapahtuma: src/lib/webhookDispatcher.ts → dokumentaatio: docs/frameworks/WEBHOOKS.md

Viiteasiakirja

Mikäli teet ei-triviaalia muutosta, lue ensin vastaava syväsukellus:

Alue	Asiakirja
Repo-navigointi	docs/architecture/REPOSITORY_MAP.md
Arkkitehtuuri	docs/architecture/ARCHITECTURE.md
Insinööriviite	docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (9-tekijän pisteytys, 14 strategiaa)	docs/routing/AUTO-COMBO.md
Kestävyys (3 mekanismia)	docs/architecture/RESILIENCE_GUIDE.md
Perustelujen toisto	docs/routing/REASONING_REPLAY.md
Taitojen kehys	docs/frameworks/SKILLS.md
Muistijärjestelmä (FTS5 + Qdrant)	docs/frameworks/MEMORY.md
Pilviagentit	docs/frameworks/CLOUD_AGENT.md
Suojakaiteet (PII / injektio / visio)	docs/security/GUARDRAILS.md
Julkiset ylävirran tunnistetiedot (Gemini/ym.)	docs/security/PUBLIC_CREDS.md
Virheilmoitusten puhdistus	docs/security/ERROR_SANITIZATION.md
Arvioinnit	docs/frameworks/EVALS.md
Vaatimustenmukaisuus / auditointi	docs/security/COMPLIANCE.md
Webhookit	docs/frameworks/WEBHOOKS.md
Valtuutusputki	docs/architecture/AUTHZ_GUIDE.md
Piilottelu (TLS / sormenjälki)	docs/security/STEALTH_GUIDE.md
Agenttiprotokollat (A2A / ACP / Pilvi)	docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP-palvelin	docs/frameworks/MCP-SERVER.md
A2A-palvelin	docs/frameworks/A2A-SERVER.md
API-viite + OpenAPI	docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Palveluntarjoajan luettelo (automaattisesti luotu)	docs/reference/PROVIDER_REFERENCE.md
Julkaisuprosessi	docs/ops/RELEASE_CHECKLIST.md

---

Testaus

Mikä	Komento
Yksikkötestit	npm run test:unit
Yksi tiedosto	node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo)	npm run test:vitest
E2E (Playwright)	npm run test:e2e
Protokolla E2E (MCP+A2A)	npm run test:protocols:e2e
Ekosysteemi	npm run test:ecosystem
Peittoportti	npm run test:coverage (75/75/75/70 — lauseet/rivit/funktiot/haarat)
Peittoraportti	npm run coverage:report

PR-sääntö: Jos muutat tuotantokoodia kansioissa src/, open-sse/, electron/ tai bin/, sinun on sisällytettävä tai päivitettävä testit samaan PR:ään.

Testikerroksen mieltymys: yksikkö ensin → integraatio (moni-moduuli tai DB-tila) → e2e (UI/työnkulku vain). Koodivirheiden toistot on koodattava automatisoiduiksi testeiksi ennen tai rinnakkain korjauksen kanssa.

Copilot-peittopolitiikka: Kun PR muuttaa tuotantokoodia ja peitto on alle 75% (lauseet/rivit/funktiot) tai 70% (haarat), älä vain raportoi — lisää tai päivitä testit, suorita peittoportti uudelleen ja pyydä sitten vahvistusta. Sisällytä suoritettavat komennot, muutetut testitiedostot ja lopullinen peittotulos PR-raporttiin.

---

Git-työprosessi

# Älä koskaan tee suoria sitoumuksia päähaaraan
git checkout -b feat/your-feature
git commit -m "feat: kuvaa muutoksesi"
git push -u origin feat/your-feature

Haaraetuliitteet: feat/, fix/, refactor/, docs/, test/, chore/

Sitoutumismuoto (Conventional Commits): feat(db): lisää piiri katkaisin — laajuudet: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky-koukut:

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

---

Ympäristö

• Suoritusaika: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES-moduulit
• TypeScript: 5.9+, kohde ES2022, moduuli esnext, resoluutio bundler
• Polkualias: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
• Oletusportti: 20128 (API + dashboard samalla portilla)
• Tietohakemisto: DATA_DIR ympäristömuuttuja, oletuksena ~/.omniroute/
• Avain ympäristömuuttujat: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
• Asetus: cp .env.example .env ja sitten luo JWT_SECRET (openssl rand -base64 48) ja API_KEY_SECRET (openssl rand -hex 32)

---

Tiukat säännöt

1. Älä koskaan sitoudu salaisuuksia tai tunnistetietoja
2. Älä koskaan lisää logiikkaa localDb.ts
3. Älä koskaan käytä eval() / new Function() / implisiittistä eval
4. Älä koskaan tee suoria sitoumuksia main-haaraan
5. Älä koskaan kirjoita raakaa SQL:ta reitteihin — käytä src/lib/db/ moduuleja
6. Älä koskaan hiljaa niele virheitä SSE-virroissa
7. Varmista aina syötteet Zod-skeemoilla
8. Sisällytä aina testit, kun muutat tuotantokoodia
9. Peiton on pysyttävä ≥75% (lauseet, rivit, funktiot) / ≥70% (haarat). Nykyinen mittaus: ~82%.
10. Älä koskaan ohita Husky-koukkuja (--no-verify, --no-gpg-sign) ilman nimenomaista operaattorin hyväksyntää.
11. Älä koskaan upota julkisia ylävirran OAuth client_id/salaisuutta tai Firebase Web -avaimia merkkijonolittereinä — käytä aina resolvePublicCred() (open-sse/utils/publicCreds.ts). Katso docs/security/PUBLIC_CREDS.md.
12. Älä koskaan palauta raakaa err.stack / err.message HTTP / SSE / suorittimen vastauksissa — ohjaa aina buildErrorBody() tai sanitizeErrorMessage() kautta (open-sse/utils/error.ts). Katso docs/security/ERROR_SANITIZATION.md.
13. Älä koskaan merkkijonointerpoloi ulkoisia polkuja tai suoritusaikaisia arvoja shell-skripteihin, jotka annetaan exec()/spawn() — siirrä sen sijaan env-vaihtoehdon kautta. Viite: src/mitm/cert/install.ts::updateNssDatabases.
14. Älä koskaan hylkää CodeQL / Secret-Scanning -ilmoitusta ilman (a) ensin tarkistamalla yllä olevat kaaviodokumentit nähdäksesi, soveltuuko apuri, ja (b) kirjaamalla tekninen perustelu hylkäyskommenttiin. Ennakkotapaus: js/stack-trace-exposure, joka nostettiin kutsupaikoissa, jotka jo ohjaavat sanitizeErrorMessage() kautta, on tunnettu CodeQL-rajoitus (räätälöityjä puhdistimia ei tunnisteta) — hylkää false positive viitaten docs/security/ERROR_SANITIZATION.md.
15. Älä koskaan paljasta reittejä, jotka käynnistävät lapsiprosesseja (/api/mcp/, /api/cli-tools/runtime/) ilman isLocalOnlyPath() luokittelua src/server/authz/routeGuard.ts. Loopback-valvonta tapahtuu ehdottomasti ennen mitään todennustarkistusta — vuotanut JWT tunnelin kautta ei voi laukaista prosessin käynnistämistä. Katso docs/security/ROUTE_GUARD_TIERS.md.
16. Älä koskaan sisällytä Co-Authored-By-liitteitä, jotka antavat kunnian tekoälyavustajalle, LLM:lle tai automaatiotilille (esim. nimet, joissa esiintyy "Claude", "GPT", "Copilot", "Bot"; sähköpostit osoitteissa anthropic.com / openai.com / bottien omistamissa noreply.github.com-osoitteissa). Tällaiset liitteet ohjaavat commit-attribuution bottitilille GitHubissa, piilottaen oikean kirjoittajan (diegosouzapw) PR-historiassa. Inhimilliset avustajat — mukaan lukien upstream-PR:n kirjoittajat ja issue-raportoijat, joita portataan OmniRouteen — VOIVAT ja PITÄISI saada kunnian vakiomuotoisilla Co-authored-by: Name <email>-liitteillä; upstream-port-työnkulut (/port-upstream-features, /port-upstream-issues) riippuvat tästä.