OmniRoute/docs/i18n/hu/CLAUDE.md

CLAUDE.md (Magyar)

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

---

Ez a fájl útmutatást nyújt a Claude Code (claude.ai/code) számára, amikor a kóddal dolgozik ebben a tárolóban.

Gyors kezdés

npm install                    # Függőségek telepítése (automatikusan generálja a .env fájlt a .env.example-ból)
npm run dev                    # Fejlesztői szerver a http://localhost:20128 címen
npm run build                  # Termelési build (Next.js 16 önálló)
npm run lint                   # ESLint (0 hiba várható; figyelmeztetések már meglévők)
npm run typecheck:core         # TypeScript ellenőrzés (tiszta kell legyen)
npm run typecheck:noimplicit:core  # Szigorú ellenőrzés (nincs implicit any)
npm run test:coverage          # Egységtesztek + lefedettségi küszöb (75/75/75/70 — állítások/sorok/funkciók/ágak)
npm run check                  # lint + teszt kombinálva
npm run check:cycles           # Körkörös függőségek észlelése

Tesztek futtatása

# Egyetlen tesztfájl (Node.js natív tesztfuttató — a legtöbb teszt)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# Minden tesztcsomag
npm run test:all

A teljes tesztmátrixért lásd a CONTRIBUTING.md → "Tesztek futtatása" részt. A mély architektúráért lásd az AGENTS.md-t.

---

Projekt áttekintése

OmniRoute — egységes AI proxy/router. Egy végpont, 160+ LLM szolgáltató, automatikus visszaesés.

Réteg	Helyszín	Cél
API Útvonalak	src/app/api/v1/	Next.js App Router — belépési pontok
Kezelők	open-sse/handlers/	Kérés feldolgozás (chat, beágyazások, stb.)
Végrehajtók	open-sse/executors/	Szolgáltató-specifikus HTTP küldés
Fordítók	open-sse/translator/	Formátum átalakítás (OpenAI↔Claude↔Gemini)
Átalakító	open-sse/transformer/	Válaszok API ↔ Chat Befejezések
Szolgáltatások	open-sse/services/	Kombinált útvonalak, sebességkorlátok, gyorsítótárazás, stb.
Adatbázis	src/lib/db/	SQLite domain modulok (45+ fájl, 55 migráció)
Domain/Szabály	src/domain/	Szabálymotor, költségszabályok, visszaesési logika
MCP Szerver	open-sse/mcp-server/	37 eszköz (30 alap + 3 memória + 4 készség), 3 szállítás, ~13 hatókör
A2A Szerver	src/lib/a2a/	JSON-RPC 2.0 ügynök protokoll
Készségek	src/lib/skills/	Kiterjeszthető készségkeretrendszer
Memória	src/lib/memory/	Tartós beszélgetési memória

Monorepo: src/ (Next.js 16 alkalmazás), open-sse/ (streaming engine munkaterület), electron/ (asztali alkalmazás), tests/, bin/ (CLI belépési pont).

Kérés Pipeline

Client → /v1/chat/completions (Next.js útvonal)
  → CORS → Zod validáció → auth? → irányelv ellenőrzés → prompt injekció védelem
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → cache ellenőrzés → sebességkorlátozás → combo routing?
      → resolveComboTargets() → handleSingleModel() célonként
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → újrapróbálkozás visszatartással
    → válasz fordítás → SSE stream vagy JSON
    → Ha Responses API: responsesTransformer.ts TransformStream

Az API útvonalak következetes mintát követnek: Útvonal → CORS előzetes ellenőrzés → Zod testtartalom validáció → Opcionális auth (extractApiKey/isValidApiKey) → API kulcs irányelv érvényesítése → Handler delegálás (open-sse). Nincs globális Next.js middleware — az elfogás útvonal-specifikus.

Combo routing (open-sse/services/combo.ts): 14 stratégia (prioritás, súlyozott, fill-first, round-robin, P2C, véletlenszerű, legkevésbé használt, költségoptimalizált, reset-tudatos, szigorú-véletlenszerű, automatikus, lkgp, kontextus-optimalizált, kontextus-relais). Minden cél hívja a handleSingleModel()-t, amely a handleChatCore()-t körülveszi célonkénti hibakezeléssel és áramkör megszakító ellenőrzésekkel. Lásd a docs/routing/AUTO-COMBO.md-t a 9-faktoros Auto-Combo pontozásért és a docs/architecture/RESILIENCE_GUIDE.md-t a 3 ellenállási rétegért.

---

Ellenállás Futási Állapot

Az OmniRoute három kapcsolódó, de különálló ideiglenes hiba mechanizmust tartalmaz. Tartsd a hatókörüket külön, amikor a routing viselkedést hibakeresed. Lásd a 3-rétegű ellenállás diagramot (forrás: docs/diagrams/resilience-3layers.mmd) egy pillantásra való térképhez.

Szolgáltató Áramkör Megszakító

Hatókör: egész szolgáltató, pl. glm, openai, anthropic.

Cél: megállítani a forgalom küldését egy szolgáltatóhoz, amely folyamatosan hibázik a upstream/szolgáltatás szinten, így egy egészségtelen szolgáltató nem lassítja le minden kérdést.

Megvalósítás:

• Alap osztály: src/shared/utils/circuitBreaker.ts
• Chat kapu/végrehajtási vezetékezés: src/sse/handlers/chatHelpers.ts, src/sse/handlers/chat.ts
• Futási állapot API: src/app/api/monitoring/health/route.ts
• Megosztott burkolók: open-sse/services/accountFallback.ts
• Megtartott állapot tábla: domain_circuit_breakers

Állapotok:

• CLOSED: normál forgalom engedélyezett.
• OPEN: a szolgáltató ideiglenesen blokkolva van; a hívók szolgáltató-áramkör-nyitott választ kapnak vagy a combo routing átugrik egy másik célra.
• HALF_OPEN: a reset időtúllépés eltelt; engedélyez egy próba kérést. A siker bezárja a megszakítót, a hiba újra megnyitja.

Alapértelmezések (open-sse/config/constants.ts):

• OAuth szolgáltatók: küszöb 3, reset időtúllépés 60s.
• API-kulcs szolgáltatók: küszöb 5, reset időtúllépés 30s.
• Helyi szolgáltatók: küszöb 2, reset időtúllépés 15s.

Csak a szolgáltató szintű hiba állapotoknak kell aktiválniuk a szolgáltató megszakítót:

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

Ne aktiváld a teljes szolgáltató megszakítót normál fiók/kulcs/modell hibák miatt, mint a legtöbb 401, 403, vagy 429 eset. Ezek általában a kapcsolat lehűléséhez vagy a modell lezárásához tartoznak. Egy általános API-kulcs szolgáltató 403-nak helyreállíthatónak kell lennie, hacsak nem minősül végső szolgáltató/fiók hibának.

A megszakító lusta helyreállítást használ, nem háttéridőzítőt. Amikor az OPEN lejár, az olyan olvasások, mint a getStatus(), canExecute(), és getRetryAfterMs() frissítik az állapotot HALF_OPEN-ra, így a műszerfalak és a combo jelölt építők nem zárják ki folyamatosan az lejárt szolgáltatót.

Kapcsolat Lehűlés

Hatókör: egy szolgáltató kapcsolat/fiók/kulcs.

Cél: ideiglenesen kihagyni egy rossz kulcsot/fiókot, miközben lehetővé teszi, hogy más kapcsolatok ugyanazon szolgáltató számára továbbra is kiszolgálják a kéréseket.

Megvalósítás:

• Írás/frissítés útvonal: src/sse/services/auth.ts::markAccountUnavailable()
• Fiók kiválasztás/szűrés: src/sse/services/auth.ts::getProviderCredentials...
• Lehűlés számítás: open-sse/services/accountFallback.ts::checkFallbackError()
• Beállítások: src/lib/resilience/settings.ts

Fontos mezők a szolgáltató kapcsolatokon:

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

A fiók kiválasztásakor egy kapcsolatot kihagynak, amikor:

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

A lehűlések is lusták: amikor a rateLimitedUntil a múltban van, a kapcsolat újra jogosulttá válik. Sikeres használat esetén a clearAccountError() törli a testStatus, rateLimitedUntil, hiba mezőket és a backoffLevel-t.

Alapértelmezett kapcsolat lehűlés viselkedés:

• OAuth alap lehűlés: 5s.
• API-kulcs alap lehűlés: 3s.
• API-kulcs 429 esetén előnyben kell részesíteni az upstream újrapróbálkozási utasításokat (Retry-After, reset fejlécek, vagy elemezhető reset szöveg), ha elérhető.
• Ismételt helyreállítható hibák exponenciális visszatartást használnak:

baseCooldownMs * 2 ** failureIndex;

Az anti-thundering-herd védelem megakadályozza, hogy a ugyanazon kapcsolaton belüli egyidejű hibák folyamatosan meghosszabbítsák a lehűlést vagy duplán növeljék a backoffLevel-t.

A végső állapotok nem lehűlések. A banned, expired, és credits_exhausted állapotoknak elérhetetlennek kell maradniuk, amíg a hitelesítési adatok/beállítások meg nem változnak, vagy egy operátor nem állítja vissza őket. Ne írj felül végső állapotokat átmeneti lehűlési állapottal.

Modell Lezárás

Hatókör: szolgáltató + kapcsolat + modell.

Cél: elkerülni, hogy egy egész kapcsolat le legyen tiltva, amikor csak egy modell nem elérhető vagy kvóta-korlátozott az adott kapcsolathoz.

Példák:

• Modellenkénti kvóta szolgáltatók, amelyek 429-et adnak vissza.
• Helyi szolgáltatók, amelyek 404-et adnak vissza egy hiányzó modell miatt.
• Szolgáltató-specifikus mód/modell engedélyezési hibák, mint például a kiválasztott Grok módok.

A modell lezárás az open-sse/services/accountFallback.ts-ben található, és lehetővé teszi, hogy ugyanaz a kapcsolat továbbra is kiszolgálja a többi modellt.

Hibakeresési Útmutató

• Ha egy szolgáltató összes kulcsa ki van hagyva, ellenőrizd a szolgáltató megszakító állapotát és minden kapcsolat rateLimitedUntil/testStatus-át.
• Ha egy szolgáltató véglegesen kizártnak tűnik a reset ablak után, ellenőrizd, hogy a kód nyers state-et olvas-e ahelyett, hogy a getStatus()/canExecute()-t használná.
• Ha egy szolgáltató kulcs hibázik, de másoknak működniük kellene, előnyben részesítsd a kapcsolat lehűlést a szolgáltató megszakítóval szemben.
• Ha csak egy modell hibázik, előnyben részesítsd a modell lezárást a kapcsolat lehűléssel szemben.
• Ha egy állapotnak önmagát kell helyreállítania, jövőbeli időbélyeggel/reset időtúllépéssel kell rendelkeznie, és egy olvasási útnak, amely frissíti a lejárt állapotot. A végleges állapotok kézi hitelesítési vagy konfigurációs változtatásokat igényelnek.

Kulcsfontosságú Konvenciók

Kód Stílus

• 2 szóköz, pontosvesszők, dupla idézőjelek, 100 karakter szélesség, es5 végső vesszők (lint-staged által a Prettier-en keresztül érvényesítve)
• Importok: külső → belső (@/, @omniroute/open-sse) → relatív
• Elnevezés: fájlok=camelCase/kebab, komponensek=PascalCase, konstansok=UPPER_SNAKE
• ESLint: no-eval, no-implied-eval, no-new-func = hiba mindenhol; no-explicit-any = figyelmeztetés az open-sse/ és tests/ mappákban
• TypeScript: strict: false, cél ES2022, modul esnext, felbontás bundler. Előnyben részesítjük a kifejezett típusokat.

Adatbázis

• Mindig a src/lib/db/ domain modulokon keresztül haladjunk — soha ne írj nyers SQL-t az útvonalakban vagy kezelőkben
• Soha ne adj logikát a src/lib/localDb.ts fájlhoz (csak újraexportáló réteg)
• Soha ne barrel-importálj a localDb.ts-ből — inkább importáld a konkrét db/ modulokat
• DB singleton: getDbInstance() a src/lib/db/core.ts-ből (WAL naplózás)
• Migrációk: src/lib/db/migrations/ — verziózott SQL fájlok, idempotens, tranzakciókban futnak

Hiba Kezelés

• try/catch specifikus hibatípusokkal, naplózás pino kontextussal
• Soha ne nyelj el hibákat SSE stream-ekben — használj abort jelzéseket a takarításhoz
• Térj vissza megfelelő HTTP státuszkódokkal (4xx/5xx)

Biztonság

• Soha ne használd az eval(), new Function(), vagy implikált eval-t
• Érvényesítsd az összes bemenetet Zod sémákkal
• Titkosítsd a hitelesítő adatokat nyugalomban (AES-256-GCM)
• Felsőbb szintű fejléc tiltólista: src/shared/constants/upstreamHeaders.ts — tartsd a tisztítást, Zod sémákat és egységteszteket összhangban a szerkesztés során
• Nyilvános felsőbb szintű hitelesítő adatok (Gemini/Antigravity/Windsurf-stílusú OAuth client_id/secret + Firebase Web kulcsok, amelyeket nyilvános CLI-kből nyerünk ki): KÖTELEZŐ beágyazni a resolvePublicCred() segítségével az open-sse/utils/publicCreds.ts-ből — soha ne string literálként. Lásd a docs/security/PUBLIC_CREDS.md-t a kötelező mintáért.
• Hiba válaszok (HTTP / SSE / végrehajtó / MCP kezelő): KÖTELEZŐ átirányítani a buildErrorBody() vagy sanitizeErrorMessage() segítségével az open-sse/utils/error.ts-ből — soha ne tedd a nyers err.stack vagy err.message-t a válasz törzsbe. Lásd a docs/security/ERROR_SANITIZATION.md-t.
• Shell parancsok változókból: amikor exec()/spawn()-t hívsz egy olyan szkripttel, amely futási értékeket igényel, add át őket az env opcióval (automatikusan shell-escaped) — soha ne interpolálj megbízhatatlan/external útvonalakat a szkript törzsébe. Hivatkozás: src/mitm/cert/install.ts::updateNssDatabases.
• Biztonságos alapértelmezett könyvtárak (tldrsec/awesome-secure-defaults): előnyben részesítjük a Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink használatát a saját megvalósításokkal szemben, amikor új biztonságérzékeny felületeket adunk hozzá.

---

Gyakori Módosítási Szenáriók

Új Szolgáltató Hozzáadása

1. Regisztrálj a src/shared/constants/providers.ts-ben (Zod-érvényesítve betöltéskor)
2. Adj hozzá végrehajtót az open-sse/executors/-ban, ha egyedi logikára van szükség (bővítsd a BaseExecutor-t)
3. Adj hozzá fordítót az open-sse/translator/-ban, ha nem OpenAI formátum
4. Adj hozzá OAuth konfigurációt a src/lib/oauth/constants/oauth.ts-ban, ha OAuth-alapú — ha a felsőbb CLI nyilvános client_id/secret-et szállít, ágyazd be a resolvePublicCred() segítségével (lásd a docs/security/PUBLIC_CREDS.md-t), soha ne literálként
5. Regisztráld a modelleket a open-sse/config/providerRegistry.ts-ben
6. Írj teszteket a tests/unit/-ban (tartalmazza a publicCreds forma állítást, ha új beágyazott alapértelmezettet adtál hozzá)

Új API Útvonal Hozzáadása

1. Hozz létre egy könyvtárat a src/app/api/v1/your-route/ alatt
2. Hozz létre route.ts-t GET/POST kezelőkkel
3. Kövesd a mintát: CORS → Zod törzs érvényesítés → opcionális hitelesítés → kezelő delegálás
4. A kezelő az open-sse/handlers/-ban van (onnan importálj, ne inline)
5. A hiba válaszok használják a buildErrorBody() / errorResponse()-t az open-sse/utils/error.ts-ből (automatikusan tisztítva — soha ne tedd a err.stack vagy err.message nyers formáját a törzsbe). Lásd a docs/security/ERROR_SANITIZATION.md-t.
6. Adj hozzá teszteket — beleértve legalább egy állítást, hogy a hiba válaszok ne szivárogjanak stack trace-eket (!body.error.message.includes("at /"))

Új DB Modul Hozzáadása

1. Hozz létre src/lib/db/yourModule.ts — importáld a getDbInstance-t a ./core.ts-ből
2. Exportáld a CRUD funkciókat a domain tábláidhoz
3. Adj hozzá migrációt a src/lib/db/migrations/-ban, ha új táblákra van szükség
4. Újraexportálás a src/lib/localDb.ts-ből (csak a re-export listához add hozzá)
5. Írj teszteket

Új MCP Eszköz Hozzáadása

1. Adj eszköz definíciót az open-sse/mcp-server/tools/-ban Zod bemeneti séma + aszinkron kezelő
2. Regisztráld az eszközkészletben (a createMcpServer() által vezérelve)
3. Rendeld hozzá a megfelelő hatókörökhöz
4. Írj teszteket (az eszköz hívás naplózva a mcp_audit táblába)

Új A2A Képesség Hozzáadása

1. Hozz létre képességet a src/lib/a2a/skills/-ban (5 már létezik: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. A képesség feladatkörnyezetet kap (üzenetek, metaadatok) → strukturált eredményt ad vissza
3. Regisztráld az A2A_SKILL_HANDLERS-ben a src/lib/a2a/taskExecution.ts-ben
4. Tedd elérhetővé a src/app/.well-known/agent.json/route.ts-ban (Agent Card)
5. Írj teszteket a tests/unit/-ban
6. Dokumentáld a docs/frameworks/A2A-SERVER.md képesség táblázatban

Új Felhő Ügynök Hozzáadása

1. Hozz létre ügynök osztályt a src/lib/cloudAgent/agents/-ban, amely kiterjeszti a CloudAgentBase-t (3 már létezik: codex-cloud, devin, jules)
2. Implementáld a createTask, getStatus, approvePlan, sendMessage, listSources funkciókat
3. Regisztráld a src/lib/cloudAgent/registry.ts-ben
4. Adj hozzá OAuth/hitelesítő adatkezelést, ha szükséges (src/lib/oauth/providers/)
5. Tesztek + dokumentáció a docs/frameworks/CLOUD_AGENT.md-ban

Új Guardrail / Eval / Képesség / Webhook esemény Hozzáadása

• Guardrail: src/lib/guardrails/ → dokumentáció: docs/security/GUARDRAILS.md
• Eval csomag: src/lib/evals/ → dokumentáció: docs/frameworks/EVALS.md
• Képesség (sandbox): src/lib/skills/ → dokumentáció: docs/frameworks/SKILLS.md
• Webhook esemény: src/lib/webhookDispatcher.ts → dokumentáció: docs/frameworks/WEBHOOKS.md

Referencia Dokumentáció

Bármilyen nem triviális változtatás előtt olvasd el a megfelelő mélyreható anyagot:

Terület	Dokumentum
Repo navigáció	docs/architecture/REPOSITORY_MAP.md
Architektúra	docs/architecture/ARCHITECTURE.md
Mérnöki referencia	docs/architecture/CODEBASE_DOCUMENTATION.md
Auto-Combo (9-faktoros pontozás, 14 stratégia)	docs/routing/AUTO-COMBO.md
Ellenállás (3 mechanizmus)	docs/architecture/RESILIENCE_GUIDE.md
Érvelés újrajátszása	docs/routing/REASONING_REPLAY.md
Készségek keretrendszere	docs/frameworks/SKILLS.md
Memória rendszer (FTS5 + Qdrant)	docs/frameworks/MEMORY.md
Felhő ügynökök	docs/frameworks/CLOUD_AGENT.md
Védőkorlátok (PII / injekció / látás)	docs/security/GUARDRAILS.md
Nyilvános upstream hitelesítések (Gemini/stb.)	docs/security/PUBLIC_CREDS.md
Hibaüzenetek tisztítása	docs/security/ERROR_SANITIZATION.md
Értékelések	docs/frameworks/EVALS.md
Megfelelőség / audit	docs/security/COMPLIANCE.md
Webhookok	docs/frameworks/WEBHOOKS.md
Engedélyezési folyamat	docs/architecture/AUTHZ_GUIDE.md
Rejtőzködés (TLS / ujjlenyomat)	docs/security/STEALTH_GUIDE.md
Ügynök protokollok (A2A / ACP / Felhő)	docs/frameworks/AGENT_PROTOCOLS_GUIDE.md
MCP szerver	docs/frameworks/MCP-SERVER.md
A2A szerver	docs/frameworks/A2A-SERVER.md
API referencia + OpenAPI	docs/reference/API_REFERENCE.md + docs/reference/openapi.yaml
Szolgáltató katalógus (automatikusan generált)	docs/reference/PROVIDER_REFERENCE.md
Kiadási folyamat	docs/ops/RELEASE_CHECKLIST.md

Tesztelés

Mi	Parancs
Egységtesztek	npm run test:unit
Egyetlen fájl	node --import tsx/esm --test tests/unit/file.test.ts
Vitest (MCP, autoCombo)	npm run test:vitest
E2E (Playwright)	npm run test:e2e
Protokoll E2E (MCP+A2A)	npm run test:protocols:e2e
Ökoszisztéma	npm run test:ecosystem
Lefedettségi küszöb	npm run test:coverage (75/75/75/70 — állítások/sorok/funkciók/ágak)
Lefedettségi jelentés	npm run coverage:report

PR szabály: Ha megváltoztatod a termelési kódot a src/, open-sse/, electron/ vagy bin/ mappákban, akkor teszteket kell hozzáadnod vagy frissítened ugyanabban a PR-ben.

Teszt réteg preferencia: egység először → integráció (több modul vagy DB állapot) → e2e (UI/munkafolyamat csak). A hibák reprodukálását automatizált tesztekké kell alakítani a javítás előtt vagy annak mellett.

Copilot lefedettségi irányelv: Amikor egy PR megváltoztatja a termelési kódot és a lefedettség 75% alatt van (állítások/sorok/funkciók) vagy 70% alatt (ágak), ne csak jelentsd — adj hozzá vagy frissíts teszteket, futtasd újra a lefedettségi küszöböt, majd kérj megerősítést. A PR jelentésben tüntesd fel a futtatott parancsokat, a megváltozott tesztfájlokat és a végső lefedettségi eredményt.

---

Git Munkafolyamat

# Soha ne kötelezz közvetlenül a main-re
git checkout -b feat/your-feature
git commit -m "feat: írd le a változtatásodat"
git push -u origin feat/your-feature

Ág előtagok: feat/, fix/, refactor/, docs/, test/, chore/

Kötelezési formátum (Hagyományos Kötelezések): feat(db): add circuit breaker — területek: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky hook-ok:

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

---

Környezet

• Futtatás: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
• TypeScript: 5.9+, cél ES2022, modul esnext, felbontás bundler
• Útvonal aliasok: @/* → src/, @omniroute/open-sse → open-sse/, @omniroute/open-sse/* → open-sse/*
• Alapértelmezett port: 20128 (API + dashboard ugyanazon a porton)
• Adatkönyvtár: DATA_DIR környezeti változó, alapértelmezett: ~/.omniroute/
• Kulcs környezeti változók: PORT, JWT_SECRET, API_KEY_SECRET, INITIAL_PASSWORD, REQUIRE_API_KEY, APP_LOG_LEVEL
• Beállítás: cp .env.example .env, majd generálj JWT_SECRET-et (openssl rand -base64 48) és API_KEY_SECRET-et (openssl rand -hex 32)

---

Kemény Szabályok

1. Soha ne kötelezz titkokat vagy hitelesítő adatokat
2. Soha ne adj hozzá logikát a localDb.ts-hez
3. Soha ne használd az eval() / new Function() / implikált eval
4. Soha ne kötelezz közvetlenül a main-re
5. Soha ne írj nyers SQL-t az útvonalakban — használd a src/lib/db/ modulokat
6. Soha ne nyelj el csendben hibákat az SSE folyamokban
7. Mindig érvényesítsd a bemeneteket Zod sémákkal
8. Mindig tartalmazz teszteket, amikor megváltoztatod a termelési kódot
9. A lefedettségnek ≥75%-on (állítások, sorok, funkciók) / ≥70%-on (ágak) kell maradnia. Jelenlegi mért: ~82%.
10. Soha ne kerüld meg a Husky hook-okat (--no-verify, --no-gpg-sign) kifejezett operátori jóváhagyás nélkül.
11. Soha ne ágyazz be nyilvános upstream OAuth client_id/secret vagy Firebase Web kulcsokat szöveges literálokként — mindig a resolvePublicCred()-en keresztül járj el (open-sse/utils/publicCreds.ts). Lásd: docs/security/PUBLIC_CREDS.md.
12. Soha ne térj vissza nyers err.stack / err.message értékekkel HTTP / SSE / végrehajtó válaszokban — mindig a buildErrorBody() vagy sanitizeErrorMessage() (open-sse/utils/error.ts) útvonalon keresztül járj el. Lásd: docs/security/ERROR_SANITIZATION.md.
13. Soha ne interpolálj külső útvonalakat vagy futási értékeket shell szkriptekbe, amelyeket az exec()/spawn()-nak adsz át — inkább az env opcióval add át. Hivatkozás: src/mitm/cert/install.ts::updateNssDatabases.
14. Soha ne utasíts el egy CodeQL / Secret-Scanning riasztást anélkül, hogy (a) először ellenőriznéd a fenti mintázat dokumentációját, hogy lássad, alkalmazható-e a segédprogram, és (b) rögzítenéd a technikai indoklást az elutasító megjegyzésben. Precedens: js/stack-trace-exposure emelt a hívási helyeken, amelyek már a sanitizeErrorMessage()-en keresztül haladnak, egy ismert CodeQL korlátozás (egyedi szűrők nem ismertek) — utasítsd el false positive-ként, hivatkozva a docs/security/ERROR_SANITIZATION.md-ra.
15. Soha ne tedd közzé azokat az útvonalakat, amelyek gyermek folyamatokat indítanak (/api/mcp/, /api/cli-tools/runtime/) anélkül, hogy a isLocalOnlyPath() osztályozás szerepelne a src/server/authz/routeGuard.ts-ben. A hurok visszahatása feltétel nélkül megtörténik bármilyen hitelesítési ellenőrzés előtt — a csatornán keresztül kiszivárgott JWT nem indíthat folyamatot. Lásd: docs/security/ROUTE_GUARD_TIERS.md.
16. Soha ne tartalmazz Co-Authored-By trailer-eket, amelyek AI-asszisztenst, LLM-et vagy automatizálási fiókot ismernek el (pl. "Claude", "GPT", "Copilot", "Bot" tartalmú nevek; anthropic.com / openai.com / bot tulajdonú noreply.github.com címeken lévő e-mailek). Az ilyen trailer-ek a commit-attribúciót a bot fiókhoz irányítják a GitHubon, elrejtve a valódi szerzőt (diegosouzapw) a PR-történetben. Az emberi közreműködők — beleértve az upstream PR-szerzőket és az OmniRoute-ba portolt issue-bejelentőket — szabványos Co-authored-by: Name <email> trailer-ekkel jóváírhatók és JÓVÁ KELL ÍRNI; az upstream-port munkafolyamatok (/port-upstream-features, /port-upstream-issues) ettől függenek.