OmniRoute/docs/i18n/cs/CLAUDE.md

# CLAUDE.md (Čeština)

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

---

Tento soubor poskytuje pokyny pro Claude Code (claude.ai/code) při práci s kódem v tomto repozitáři.

## Rychlý start

```bash
npm install                    # Nainstalujte závislosti (automaticky vygeneruje .env z .env.example)
npm run dev                    # Vývojový server na http://localhost:20128
npm run build                  # Produkční build (Next.js 16 standalone)
npm run lint                   # ESLint (0 chyb očekáváno; varování jsou předchozí)
npm run typecheck:core         # Kontrola TypeScriptu (mělo by být čisté)
npm run typecheck:noimplicit:core  # Přísná kontrola (žádné implicitní any)
npm run test:coverage          # Jednotkové testy + pokrytí (75/75/75/70 — prohlášení/řádky/funkce/větve)
npm run check                  # lint + testy dohromady
npm run check:cycles           # Detekce cyklických závislostí
```

### Spouštění testů

```bash
# Jediný testovací soubor (nativní testovací běžec Node.js — většina testů)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# Všechny sady
npm run test:all
```

Pro plnou testovací matici viz `CONTRIBUTING.md` → "Spouštění testů". Pro hlubokou architekturu viz `AGENTS.md`.

---

## Projekt na první pohled

**OmniRoute** — jednotný AI proxy/router. Jeden koncový bod, 160+ poskytovatelů LLM, automatické zálohování.

| Vrstva        | Umístění                | Účel                                                                            |
| ------------- | ----------------------- | ------------------------------------------------------------------------------- |
| API Routes    | `src/app/api/v1/`       | Next.js App Router — vstupní body                                               |
| Handlers      | `open-sse/handlers/`    | Zpracování požadavků (chat, embeddings, atd.)                                   |
| Executors     | `open-sse/executors/`   | HTTP dispatch specifický pro poskytovatele                                      |
| Translators   | `open-sse/translator/`  | Konverze formátu (OpenAI↔Claude↔Gemini)                                         |
| Transformer   | `open-sse/transformer/` | API odpovědí ↔ Dokončení chatu                                                  |
| Services      | `open-sse/services/`    | Kombinované směrování, limity rychlosti, caching, atd.                          |
| Database      | `src/lib/db/`           | SQLite doménové moduly (45+ souborů, 55 migrací)                                |
| Domain/Policy | `src/domain/`           | Engin politiky, pravidla nákladů, logika zálohování                             |
| MCP Server    | `open-sse/mcp-server/`  | 37 nástrojů (30 základních + 3 paměť + 4 dovednosti), 3 transporty, ~13 rozsahů |
| A2A Server    | `src/lib/a2a/`          | JSON-RPC 2.0 agent protokol                                                     |
| Skills        | `src/lib/skills/`       | Rozšiřitelný rámec dovedností                                                   |
| Memory        | `src/lib/memory/`       | Trvalá konverzační paměť                                                        |

Monorepo: `src/` (Next.js 16 aplikace), `open-sse/` (pracovní prostor streamovacího enginu), `electron/` (desktopová aplikace), `tests/`, `bin/` (CLI vstupní bod).

---

## Pipeline požadavků

```
Klient → /v1/chat/completions (Next.js route)
  → CORS → Zod validace → auth? → kontrola politiky → ochrana proti injekci promptu
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → kontrola cache → limit rychlosti → combo routing?
      → resolveComboTargets() → handleSingleModel() pro každý cíl
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → opakování s backoff
    → překlad odpovědi → SSE stream nebo JSON
    → Pokud Responses API: responsesTransformer.ts TransformStream
```

API trasy následují konzistentní vzor: `Route → CORS preflight → Zod validace těla → Volitelná autentizace (extractApiKey/isValidApiKey) → Vynucení politiky API klíče → Delegace handleru (open-sse)`. Žádný globální Next.js middleware — interceptace je specifická pro trasu.

**Combo routing** (`open-sse/services/combo.ts`): 14 strategií (priorita, vážené, fill-first, round-robin, P2C, náhodné, nejméně používané, optimalizované podle nákladů, reset-aware, strict-random, auto, lkgp, optimalizované podle kontextu, kontext-relay). Každý cíl volá `handleSingleModel()`, který obaluje `handleChatCore()` s chybovým zpracováním a kontrolami obvodu pro každý cíl. Viz `docs/routing/AUTO-COMBO.md` pro 9-faktorové hodnocení Auto-Combo a `docs/architecture/RESILIENCE_GUIDE.md` pro 3 vrstvy odolnosti.

---

## Stav běhu odolnosti

OmniRoute má tři související, ale odlišné mechanismy dočasného selhání. Udržujte jejich rozsah oddělený při ladění chování routování. Viz
[diagram odolnosti ve 3 vrstvách](./docs/diagrams/exported/resilience-3layers.svg)
(zdroj: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))
pro rychlý přehled.

### Obvod poskytovatele

**Rozsah**: celý poskytovatel, např. `glm`, `openai`, `anthropic`.

**Účel**: zastavit posílání provozu k poskytovateli, který opakovaně selhává na úrovni upstream/služby, aby jeden nezdravý poskytovatel nezpomalil každý požadavek.

**Implementace**:

- Hlavní třída: `src/shared/utils/circuitBreaker.ts`
- Chat gate/execution wiring: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- API stavu běhu: `src/app/api/monitoring/health/route.ts`
- Sdílené obaly: `open-sse/services/accountFallback.ts`
- Tabulka trvalého stavu: `domain_circuit_breakers`

**Stavy**:

- `CLOSED`: normální provoz je povolen.
- `OPEN`: poskytovatel je dočasně zablokován; volající dostanou odpověď provider-circuit-open
  nebo combo routing přeskočí na jiný cíl.
- `HALF_OPEN`: resetovací timeout uplynul; povolit zkušební požadavek. Úspěch uzavírá
  obvod, selhání jej znovu otevírá.

**Výchozí hodnoty** (`open-sse/config/constants.ts`):

- OAuth poskytovatelé: práh `3`, resetovací timeout `60s`.
- API-klíč poskytovatelé: práh `5`, resetovací timeout `30s`.
- Lokální poskytovatelé: práh `2`, resetovací timeout `15s`.

Pouze stavy selhání na úrovni poskytovatele by měly spustit obvod poskytovatele:

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

Nespouštějte obvod celého poskytovatele pro normální chyby účtu/klíče/modelu jako většina
případů `401`, `403` nebo `429`. Ty obvykle patří do cooldownu připojení nebo uzamčení modelu. Obecný API-klíč poskytovatel `403` by měl být obnovitelný, pokud není klasifikován
jako terminální chyba poskytovatele/účtu.

Obvod používá lenivou obnovu, ne pozadí časovač. Když `OPEN` vyprší, čtení jako
`getStatus()`, `canExecute()`, a `getRetryAfterMs()` obnoví stav na
`HALF_OPEN`, takže panely a stavitelé kandidátů na combo nebudou navždy vylučovat vypršeného poskytovatele.

### Cooldown připojení

**Rozsah**: jedno připojení/účet/klíč poskytovatele.

**Účel**: dočasně přeskočit jeden špatný klíč/účet, zatímco ostatní připojení pro
stejného poskytovatele mohou pokračovat v obsluze požadavků.

**Implementace**:

- Cesta zápisu/aktualizace: `src/sse/services/auth.ts::markAccountUnavailable()`
- Výběr/filtrování účtu: `src/sse/services/auth.ts::getProviderCredentials...`
- Výpočet cooldownu: `open-sse/services/accountFallback.ts::checkFallbackError()`
- Nastavení: `src/lib/resilience/settings.ts`

Důležitá pole na připojeních poskytovatele:

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

Během výběru účtu je připojení přeskočeno, pokud:

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

Cooldowny jsou také lenivé: když je `rateLimitedUntil` v minulosti, připojení se opět stává
způsobilým. Při úspěšném použití `clearAccountError()` vymaže `testStatus`,
`rateLimitedUntil`, chybová pole a `backoffLevel`.

Výchozí chování cooldownu připojení:

- Základní cooldown OAuth: `5s`.
- Základní cooldown API-klíče: `3s`.
- API-klíč `429` by měl preferovat upstream retry hints (`Retry-After`, resetovací hlavičky, nebo
  parsovatelný reset text) když jsou k dispozici.
- Opakované obnovitelné selhání používá exponenciální backoff:

```ts
baseCooldownMs * 2 ** failureIndex;
```

Ochrana proti thundering-herd zabraňuje souběžným selháním na stejném připojení v
opakovaném prodlužování cooldownu nebo dvojitému zvyšování `backoffLevel`.

Terminální stavy nejsou cooldowny. `banned`, `expired`, a `credits_exhausted` jsou
určeny k tomu, aby zůstaly nedostupné, dokud se nezmění pověření/nastavení nebo je operátor
neobnoví. Nepřepisujte terminální stavy do přechodného stavu cooldownu.

### Uzamčení modelu

**Rozsah**: poskytovatel + připojení + model.

**Účel**: vyhnout se deaktivaci celého připojení, když je k dispozici pouze jeden model
nebo je omezený kvótou pro toto připojení.

Příklady:

- Poskytovatelé s kvótou na model vracející `429`.
- Lokální poskytovatelé vracející `404` pro jeden chybějící model.
- Chyby oprávnění specifické pro poskytovatele/model, jako jsou vybrané režimy Grok.

Uzamčení modelu žije v `open-sse/services/accountFallback.ts` a umožňuje stejnému
připojení pokračovat v obsluze dalších modelů.

### Pokyny pro ladění

- Pokud jsou všechny klíče pro poskytovatele přeskočeny, zkontrolujte jak stav obvodu poskytovatele, tak
  `rateLimitedUntil`/`testStatus` každého připojení.
- Pokud se zdá, že je poskytovatel trvale vyloučen po resetovacím okně, zkontrolujte, zda kód
  čte surový `state` místo používání `getStatus()`/`canExecute()`.
- Pokud jeden klíč poskytovatele selže, ale ostatní by měly fungovat, preferujte cooldown připojení před
  obvodem poskytovatele.
- Pokud selže pouze jeden model, preferujte uzamčení modelu před cooldownem připojení.
- Pokud by se měl stav sám obnovit, měl by mít budoucí časové razítko/resetovací timeout a
  čtecí cestu, která obnovuje vypršený stav. Trvalé stavy vyžadují ruční změny pověření
  nebo konfigurace.

## Klíčové konvence

### Styl kódu

- **2 mezery**, středníky, dvojité uvozovky, šířka 100 znaků, es5 koncové čárky (vynuceno lint-staged pomocí Prettier)
- **Importy**: externí → interní (`@/`, `@omniroute/open-sse`) → relativní
- **Pojmenování**: soubory=camelCase/kebab, komponenty=PascalCase, konstanty=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = chyba všude; `no-explicit-any` = varování v `open-sse/` a `tests/`
- **TypeScript**: `strict: false`, cíl ES2022, modul esnext, rozlišení bundler. Preferujte explicitní typy.

### Databáze

- **Vždy** procházejte doménovými moduly `src/lib/db/` — **nikdy** nepíšete surové SQL v trasách nebo obslužných funkcích
- **Nikdy** nepřidávejte logiku do `src/lib/localDb.ts` (pouze vrstva pro opětovný export)
- **Nikdy** neprovádějte barrel-import z `localDb.ts` — místo toho importujte konkrétní moduly `db/`
- DB singleton: `getDbInstance()` z `src/lib/db/core.ts` (WAL žurnálování)
- Migrace: `src/lib/db/migrations/` — verzované SQL soubory, idempotentní, prováděné v transakcích

### Zpracování chyb

- try/catch se specifickými typy chyb, logování s kontextem pino
- Nikdy nezapomínejte na chyby ve SSE streamech — použijte signály pro zrušení pro úklid
- Vraťte správné HTTP status kódy (4xx/5xx)

### Bezpečnost

- **Nikdy** nepoužívejte `eval()`, `new Function()`, nebo implicitní eval
- Ověřte všechny vstupy pomocí Zod schémat
- Šifrujte přihlašovací údaje v klidu (AES-256-GCM)
- Seznam zakázaných hlaviček upstream: `src/shared/constants/upstreamHeaders.ts` — udržujte sanitaci, Zod schémata a jednotkové testy v souladu při úpravách
- **Veřejné přihlašovací údaje upstream** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web klíče extrahované z veřejných CLI): **MUSÍ** být vloženy pomocí `resolvePublicCred()` z `open-sse/utils/publicCreds.ts` — **nikdy** jako literály. Viz `docs/security/PUBLIC_CREDS.md` pro povinný vzor.
- **Odpovědi na chyby** (HTTP / SSE / executor / MCP obslužná funkce): **MUSÍ** procházet `buildErrorBody()` nebo `sanitizeErrorMessage()` z `open-sse/utils/error.ts` — **nikdy** nevkládejte surové `err.stack` nebo `err.message` do těla odpovědi. Viz `docs/security/ERROR_SANITIZATION.md`.
- **Shell příkazy vytvořené z proměnných**: při volání `exec()`/`spawn()` se skriptem, který potřebuje hodnoty za běhu, předávejte je pomocí možnosti `env` (automaticky shell-escaped) — **nikdy** neprovádějte interpolaci neověřených/externalních cest do těla skriptu. Odkaz: `src/mitm/cert/install.ts::updateNssDatabases`.
- **Knihovny zabezpečené podle výchozího nastavení** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): preferujte Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink před vlastními implementacemi při přidávání nových bezpečnostně citlivých povrchů.

---

## Běžné scénáře úprav

### Přidání nového poskytovatele

1. Zaregistrujte v `src/shared/constants/providers.ts` (ověřeno Zod při načítání)
2. Přidejte executor v `open-sse/executors/`, pokud je potřeba vlastní logika (rozšiřte `BaseExecutor`)
3. Přidejte překladač v `open-sse/translator/`, pokud není ve formátu OpenAI
4. Přidejte OAuth konfiguraci v `src/lib/oauth/constants/oauth.ts`, pokud je založena na OAuth — pokud upstream CLI dodává veřejný client_id/secret, vložte pomocí `resolvePublicCred()` (viz `docs/security/PUBLIC_CREDS.md`), **nikdy** jako literál
5. Zaregistrujte modely v `open-sse/config/providerRegistry.ts`
6. Napište testy v `tests/unit/` (zahrňte ověření tvaru publicCreds, pokud jste přidali nový vložený výchozí)

### Přidání nové API trasy

1. Vytvořte adresář pod `src/app/api/v1/your-route/`
2. Vytvořte `route.ts` s obslužnými funkcemi `GET`/`POST`
3. Dodržujte vzor: CORS → Zod ověření těla → volitelná autentizace → delegace obslužné funkce
4. Obslužná funkce jde do `open-sse/handlers/` (importujte odtud, ne inline)
5. Odpovědi na chyby používají `buildErrorBody()` / `errorResponse()` z `open-sse/utils/error.ts` (automaticky sanitizováno — nikdy nevkládejte `err.stack` nebo `err.message` surově do těla). Viz `docs/security/ERROR_SANITIZATION.md`.
6. Přidejte testy — včetně alespoň jednoho ověření, že odpovědi na chyby neunikají stopy (`!body.error.message.includes("at /")`)

### Přidání nového DB modulu

1. Vytvořte `src/lib/db/yourModule.ts` — importujte `getDbInstance` z `./core.ts`
2. Exportujte CRUD funkce pro vaše doménové tabulky
3. Přidejte migraci v `src/lib/db/migrations/`, pokud jsou potřeba nové tabulky
4. Znovu exportujte z `src/lib/localDb.ts` (přidejte pouze do seznamu pro opětovný export)
5. Napište testy

### Přidání nového MCP nástroje

1. Přidejte definici nástroje v `open-sse/mcp-server/tools/` s Zod vstupním schématem + asynchronní obslužnou funkcí
2. Zaregistrujte v sadě nástrojů (propojeno pomocí `createMcpServer()`)
3. Přiřaďte k příslušným rozsahům
4. Napište testy (vyvolání nástroje je zaznamenáno do tabulky `mcp_audit`)

### Přidání nové A2A dovednosti

1. Vytvořte dovednost v `src/lib/a2a/skills/` (5 již existuje: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Dovednost přijímá kontext úkolu (zprávy, metadata) → vrací strukturovaný výsledek
3. Zaregistrujte v `A2A_SKILL_HANDLERS` v `src/lib/a2a/taskExecution.ts`
4. Exponujte v `src/app/.well-known/agent.json/route.ts` (Agent Card)
5. Napište testy v `tests/unit/`
6. Dokumentujte v `docs/frameworks/A2A-SERVER.md` tabulka dovedností

### Přidání nového cloudového agenta

1. Vytvořte třídu agenta v `src/lib/cloudAgent/agents/` rozšiřující `CloudAgentBase` (3 již existují: codex-cloud, devin, jules)
2. Implementujte `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`
3. Zaregistrujte v `src/lib/cloudAgent/registry.ts`
4. Přidejte zpracování OAuth/přihlašovacích údajů, pokud je potřeba (`src/lib/oauth/providers/`)
5. Testy + dokumentujte v `docs/frameworks/CLOUD_AGENT.md`

### Přidání nového guardrail / eval / dovednosti / webhook události

- Guardrail: `src/lib/guardrails/` → dokumentace: `docs/security/GUARDRAILS.md`
- Eval suite: `src/lib/evals/` → dokumentace: `docs/frameworks/EVALS.md`
- Dovednost (sandbox): `src/lib/skills/` → dokumentace: `docs/frameworks/SKILLS.md`
- Webhook událost: `src/lib/webhookDispatcher.ts` → dokumentace: `docs/frameworks/WEBHOOKS.md`

## Referenční dokumentace

Před jakoukoli netriviální změnou si nejprve přečtěte odpovídající podrobnou analýzu:

| Oblast                                           | Dokument                                                          |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| Navigace repozitářem                             | `docs/architecture/REPOSITORY_MAP.md`                             |
| Architektura                                     | `docs/architecture/ARCHITECTURE.md`                               |
| Odkaz na inženýrství                             | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| Auto-Combo (9-faktorové hodnocení, 14 strategií) | `docs/routing/AUTO-COMBO.md`                                      |
| Odolnost (3 mechanismy)                          | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| Opakování uvažování                              | `docs/routing/REASONING_REPLAY.md`                                |
| Rámec dovedností                                 | `docs/frameworks/SKILLS.md`                                       |
| Systém paměti (FTS5 + Qdrant)                    | `docs/frameworks/MEMORY.md`                                       |
| Cloudoví agenti                                  | `docs/frameworks/CLOUD_AGENT.md`                                  |
| Ochranné prvky (PII / injekce / vize)            | `docs/security/GUARDRAILS.md`                                     |
| Veřejné přihlašovací údaje (Gemini atd.)         | `docs/security/PUBLIC_CREDS.md`                                   |
| Sanitizace chybových zpráv                       | `docs/security/ERROR_SANITIZATION.md`                             |
| Hodnocení                                        | `docs/frameworks/EVALS.md`                                        |
| Soulad / audit                                   | `docs/security/COMPLIANCE.md`                                     |
| Webhooky                                         | `docs/frameworks/WEBHOOKS.md`                                     |
| Autorizační pipeline                             | `docs/architecture/AUTHZ_GUIDE.md`                                |
| Stealth (TLS / otisk)                            | `docs/security/STEALTH_GUIDE.md`                                  |
| Protokoly agentů (A2A / ACP / Cloud)             | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| MCP server                                       | `docs/frameworks/MCP-SERVER.md`                                   |
| A2A server                                       | `docs/frameworks/A2A-SERVER.md`                                   |
| Odkaz na API + OpenAPI                           | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| Katalog poskytovatelů (automaticky generovaný)   | `docs/reference/PROVIDER_REFERENCE.md`                            |
| Tok vydání                                       | `docs/ops/RELEASE_CHECKLIST.md`                                   |

## Testování

| Co                      | Příkaz                                                             |
| ----------------------- | ------------------------------------------------------------------ |
| Jednotkové testy        | `npm run test:unit`                                                |
| Jediný soubor           | `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`                                       |
| Ekosystém               | `npm run test:ecosystem`                                           |
| Brána pokrytí           | `npm run test:coverage` (75/75/75/70 — příkazy/řádky/funkce/větve) |
| Zpráva o pokrytí        | `npm run coverage:report`                                          |

**Pravidlo PR**: Pokud změníte produkční kód v `src/`, `open-sse/`, `electron/` nebo `bin/`, musíte zahrnout nebo aktualizovat testy ve stejném PR.

**Preferovaný testovací vrstvy**: jednotkové testy první → integrace (více modulů nebo stav DB) → e2e (pouze UI/workflow). Kódování reprodukcí chyb jako automatizovaných testů před nebo spolu s opravou.

**Politika pokrytí Copilot**: Když PR změní produkční kód a pokrytí je pod 75% (příkazy/řádky/funkce) nebo 70% (větve), nehlaste pouze — přidejte nebo aktualizujte testy, znovu spusťte bránu pokrytí a poté požádejte o potvrzení. Zahrňte provedené příkazy, změněné testovací soubory a konečný výsledek pokrytí do zprávy PR.

---

## Git Workflow

```bash
# Nikdy neprovádějte commit přímo do main
git checkout -b feat/your-feature
git commit -m "feat: popište svou změnu"
git push -u origin feat/your-feature
```

**Předpony větví**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**Formát commitu** (Conventional Commits): `feat(db): přidat circuit breaker` — rozsahy: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**Husky hooky**:

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

---

## Prostředí

- **Runtime**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES moduly
- **TypeScript**: 5.9+, cíl ES2022, modul esnext, rozlišení bundler
- **Cestovní aliasy**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **Výchozí port**: 20128 (API + dashboard na stejném portu)
- **Adresář dat**: `DATA_DIR` env var, výchozí hodnota `~/.omniroute/`
- **Klíčové env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- Nastavení: `cp .env.example .env` poté vygenerujte `JWT_SECRET` (`openssl rand -base64 48`) a `API_KEY_SECRET` (`openssl rand -hex 32`)

---

## Přísná pravidla

1. Nikdy neprovádějte commit tajemství nebo přihlašovacích údajů
2. Nikdy nepřidávejte logiku do `localDb.ts`
3. Nikdy nepoužívejte `eval()` / `new Function()` / implicitní eval
4. Nikdy neprovádějte commit přímo do `main`
5. Nikdy nepíšete surový SQL v trasách — používejte moduly `src/lib/db/`
6. Nikdy tiše nezachycujte chyby ve SSE streamech
7. Vždy validujte vstupy pomocí Zod schémat
8. Vždy zahrňte testy při změně produkčního kódu
9. Pokrytí musí zůstat ≥75% (příkazy, řádky, funkce) / ≥70% (větve). Aktuálně měřeno: ~82%.
10. Nikdy neobcházejte Husky hooky (`--no-verify`, `--no-gpg-sign`) bez explicitního schválení operátora.
11. Nikdy nezahrnujte veřejné upstream OAuth client_id/secret nebo Firebase Web klíče jako řetězcové literály — vždy používejte `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). Viz `docs/security/PUBLIC_CREDS.md`.
12. Nikdy nevracejte surový `err.stack` / `err.message` v HTTP / SSE / odpovědích executorů — vždy procházejte přes `buildErrorBody()` nebo `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). Viz `docs/security/ERROR_SANITIZATION.md`.
13. Nikdy neprovádějte interpolaci řetězců externích cest nebo runtime hodnot do shell skriptů předávaných do `exec()`/`spawn()` — předávejte je místo toho přes možnost `env`. Odkaz: `src/mitm/cert/install.ts::updateNssDatabases`.
14. Nikdy neignorujte upozornění CodeQL / Secret-Scanning bez (a) nejprve zkontrolování dokumentace vzoru výše, abyste zjistili, zda se pomocník vztahuje, a (b) zaznamenání technického odůvodnění do komentáře o zamítnutí. Precedent: `js/stack-trace-exposure` vznesený na místech volání, která již procházejí přes `sanitizeErrorMessage()`, je známé omezení CodeQL (vlastní sanitizátory nejsou rozpoznány) — zamítněte jako `false positive` s odkazem na `docs/security/ERROR_SANITIZATION.md`.
15. Nikdy nezveřejňujte trasy, které spouštějí podřízené procesy (`/api/mcp/`, `/api/cli-tools/runtime/`) bez klasifikace `isLocalOnlyPath()` v `src/server/authz/routeGuard.ts`. Vynucení loopbacku probíhá bezpodmínečně před jakýmkoli ověřením — uniklý JWT přes tunel nemůže spustit proces. Viz `docs/security/ROUTE_GUARD_TIERS.md`.
16. Nikdy nezahrnujte `Co-Authored-By` přílohy, které připisují AI asistenta, LLM nebo automatizovaný účet (např. jména obsahující "Claude", "GPT", "Copilot", "Bot"; e-maily na `anthropic.com` / `openai.com` / adresách `noreply.github.com` vlastněných boty). Takové přílohy směrují přiřazení commitů na účet bota na GitHubu, čímž skrývají skutečného autora (`diegosouzapw`) v historii PR. Lidští spolupracovníci — včetně autorů upstream PR a hlasatelů issues přenášených do OmniRoute — MOHOU a MĚLI BY být uvedeni standardními přílohami `Co-authored-by: Name <email>`; upstream-port pracovní postupy (`/port-upstream-features`, `/port-upstream-issues`) na tom závisí.