OmniRoute/docs/i18n/id/CLAUDE.md

# CLAUDE.md (Bahasa Indonesia)

🌐 **Languages:** 🇺🇸 [English](../../../CLAUDE.md) · 🇸🇦 [ar](../ar/CLAUDE.md) · 🇦🇿 [az](../az/CLAUDE.md) · 🇧🇬 [bg](../bg/CLAUDE.md) · 🇧🇩 [bn](../bn/CLAUDE.md) · 🇨🇿 [cs](../cs/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) · 🇮🇩 [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)

---

File ini memberikan panduan untuk Claude Code (claude.ai/code) saat bekerja dengan kode di repositori ini.

## Memulai dengan Cepat

```bash
npm install                    # Instal deps (secara otomatis menghasilkan .env dari .env.example)
npm run dev                    # Server dev di http://localhost:20128
npm run build                  # Build produksi (Next.js 16 standalone)
npm run lint                   # ESLint (0 kesalahan yang diharapkan; peringatan sudah ada sebelumnya)
npm run typecheck:core         # Pemeriksaan TypeScript (harus bersih)
npm run typecheck:noimplicit:core  # Pemeriksaan ketat (tidak ada implicit any)
npm run test:coverage          # Unit tests + coverage gate (75/75/75/70 — pernyataan/garis/fungsi/cabang)
npm run check                  # lint + test digabungkan
npm run check:cycles           # Deteksi ketergantungan melingkar
```

### Menjalankan Tes

```bash
# File tes tunggal (penguji native Node.js — sebagian besar tes)
node --import tsx/esm --test tests/unit/your-file.test.ts

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

# Semua suite
npm run test:all
```

Untuk matriks tes lengkap, lihat `CONTRIBUTING.md` → "Menjalankan Tes". Untuk arsitektur mendalam, lihat `AGENTS.md`.

---

## Proyek Sekilas

**OmniRoute** — proxy/router AI terpadu. Satu endpoint, 160+ penyedia LLM, auto-fallback.

| Lapisan       | Lokasi                  | Tujuan                                                                      |
| ------------- | ----------------------- | --------------------------------------------------------------------------- |
| API Routes    | `src/app/api/v1/`       | Next.js App Router — titik masuk                                            |
| Handlers      | `open-sse/handlers/`    | Pemrosesan permintaan (chat, embeddings, dll)                               |
| Executors     | `open-sse/executors/`   | Pengiriman HTTP spesifik penyedia                                           |
| Translators   | `open-sse/translator/`  | Konversi format (OpenAI↔Claude↔Gemini)                                      |
| Transformer   | `open-sse/transformer/` | API Respons ↔ Penyelesaian Chat                                             |
| Services      | `open-sse/services/`    | Routing combo, batasan laju, caching, dll                                   |
| Database      | `src/lib/db/`           | Modul domain SQLite (45+ file, 55 migrasi)                                  |
| Domain/Policy | `src/domain/`           | Mesin kebijakan, aturan biaya, logika fallback                              |
| MCP Server    | `open-sse/mcp-server/`  | 37 alat (30 dasar + 3 memori + 4 keterampilan), 3 transportasi, ~13 lingkup |
| A2A Server    | `src/lib/a2a/`          | Protokol agen JSON-RPC 2.0                                                  |
| Skills        | `src/lib/skills/`       | Kerangka keterampilan yang dapat diperluas                                  |
| Memory        | `src/lib/memory/`       | Memori percakapan yang persisten                                            |

Monorepo: `src/` (aplikasi Next.js 16), `open-sse/` (workspace mesin streaming), `electron/` (aplikasi desktop), `tests/`, `bin/` (titik masuk CLI).

---

## Jalur Permintaan

```
Klien → /v1/chat/completions (rute Next.js)
  → CORS → validasi Zod → otentikasi? → pemeriksaan kebijakan → penjaga injeksi prompt
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → pemeriksaan cache → batasan laju → routing combo?
      → resolveComboTargets() → handleSingleModel() per target
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → coba lagi dengan backoff
    → terjemahan respons → aliran SSE atau JSON
    → Jika API Respons: responsesTransformer.ts TransformStream
```

Rute API mengikuti pola yang konsisten: `Rute → CORS preflight → validasi body Zod → Otentikasi opsional (extractApiKey/isValidApiKey) → penegakan kebijakan kunci API → Delegasi Handler (open-sse)`. Tidak ada middleware global Next.js — intersepsi bersifat spesifik rute.

**Routing combo** (`open-sse/services/combo.ts`): 14 strategi (prioritas, berbobot, isi-pertama, round-robin, P2C, acak, paling-sedikit-digunakan, dioptimalkan-biaya, sadar-reset, acak-ketat, otomatis, lkgp, dioptimalkan-konteks, relay-konteks). Setiap target memanggil `handleSingleModel()` yang membungkus `handleChatCore()` dengan penanganan kesalahan per-target dan pemeriksaan pemutus sirkuit. Lihat `docs/routing/AUTO-COMBO.md` untuk penilaian Auto-Combo 9-faktor dan `docs/architecture/RESILIENCE_GUIDE.md` untuk 3 lapisan ketahanan.

---

## Status Runtime Ketahanan

OmniRoute memiliki tiga mekanisme kegagalan sementara yang terkait tetapi berbeda. Jaga agar ruang lingkup mereka terpisah saat melakukan debug perilaku routing. Lihat
[diagram ketahanan 3-lapisan](./docs/diagrams/exported/resilience-3layers.svg)
(sumber: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd))
untuk peta sekilas.

### Pemutus Sirkuit Penyedia

**Ruang Lingkup**: seluruh penyedia, misalnya `glm`, `openai`, `anthropic`.

**Tujuan**: menghentikan pengiriman lalu lintas ke penyedia yang terus-menerus gagal di tingkat upstream/layanan, sehingga satu penyedia yang tidak sehat tidak memperlambat setiap permintaan.

**Implementasi**:

- Kelas inti: `src/shared/utils/circuitBreaker.ts`
- Pengaturan gate/eksekusi chat: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- API status runtime: `src/app/api/monitoring/health/route.ts`
- Pembungkus bersama: `open-sse/services/accountFallback.ts`
- Tabel status yang dipersistenkan: `domain_circuit_breakers`

**Status**:

- `CLOSED`: lalu lintas normal diizinkan.
- `OPEN`: penyedia diblokir sementara; pemanggil mendapatkan respons pemutus-sirkuit-penyedia-terbuka
  atau routing combo melewati ke target lain.
- `HALF_OPEN`: waktu tunggu reset telah berlalu; izinkan permintaan probe. Keberhasilan menutup
  pemutus, kegagalan membukanya lagi.

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

- Penyedia OAuth: ambang `3`, waktu tunggu reset `60s`.
- Penyedia kunci API: ambang `5`, waktu tunggu reset `30s`.
- Penyedia lokal: ambang `2`, waktu tunggu reset `15s`.

Hanya status kegagalan tingkat penyedia yang harus memicu pemutus penyedia:

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

Jangan memicu pemutus seluruh-penyedia untuk kesalahan akun/kunci/model normal seperti kebanyakan
kasus `401`, `403`, atau `429`. Itu biasanya termasuk dalam cooldown koneksi atau penguncian model. Kunci API penyedia generik `403` harus dapat dipulihkan kecuali diklasifikasikan
sebagai kesalahan penyedia/akun terminal.

Pemutus menggunakan pemulihan malas, bukan timer latar belakang. Ketika `OPEN` kedaluwarsa, pembacaan seperti
`getStatus()`, `canExecute()`, dan `getRetryAfterMs()` menyegarkan status menjadi
`HALF_OPEN`, sehingga dasbor dan pembangun kandidat combo tidak terus mengecualikan penyedia yang kedaluwarsa selamanya.

### Cooldown Koneksi

**Ruang Lingkup**: satu koneksi/akun/kunci penyedia.

**Tujuan**: sementara melewatkan satu kunci/akun yang buruk sambil memungkinkan koneksi lain untuk
penyedia yang sama terus melayani permintaan.

**Implementasi**:

- Jalur tulis/perbarui: `src/sse/services/auth.ts::markAccountUnavailable()`
- Pemilihan/filtering akun: `src/sse/services/auth.ts::getProviderCredentials...`
- Perhitungan cooldown: `open-sse/services/accountFallback.ts::checkFallbackError()`
- Pengaturan: `src/lib/resilience/settings.ts`

Bidang penting pada koneksi penyedia:

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

Selama pemilihan akun, koneksi dilewati sementara:

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

Cooldown juga bersifat malas: ketika `rateLimitedUntil` berada di masa lalu, koneksi menjadi
layak lagi. Pada penggunaan yang berhasil, `clearAccountError()` menghapus `testStatus`,
`rateLimitedUntil`, bidang kesalahan, dan `backoffLevel`.

Perilaku default cooldown koneksi:

- Cooldown dasar OAuth: `5s`.
- Cooldown dasar kunci API: `3s`.
- Kunci API `429` harus lebih memilih petunjuk coba lagi upstream (`Retry-After`, header reset, atau
  teks reset yang dapat dianalisis) jika tersedia.
- Kegagalan yang dapat dipulihkan berulang menggunakan backoff eksponensial:

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

Penjaga anti-thundering-herd mencegah kegagalan bersamaan pada koneksi yang sama dari
berulang kali memperpanjang cooldown atau menggandakan `backoffLevel`.

Status terminal bukanlah cooldown. `banned`, `expired`, dan `credits_exhausted` dimaksudkan untuk tetap tidak tersedia hingga kredensial/pengaturan berubah atau operator meresetnya. Jangan menimpa status terminal dengan status cooldown sementara.

### Penguncian Model

**Ruang Lingkup**: penyedia + koneksi + model.

**Tujuan**: menghindari menonaktifkan seluruh koneksi ketika hanya satu model yang tidak tersedia atau
terbatas kuota untuk koneksi tersebut.

Contoh:

- Penyedia kuota per-model yang mengembalikan `429`.
- Penyedia lokal yang mengembalikan `404` untuk satu model yang hilang.
- Kegagalan izin mode/model spesifik penyedia seperti mode Grok yang dipilih.

Penguncian model berada di `open-sse/services/accountFallback.ts` dan memungkinkan koneksi yang sama
terus melayani model lain.

### Panduan Debugging

- Jika semua kunci untuk penyedia dilewati, periksa status pemutus penyedia dan setiap
  koneksi `rateLimitedUntil`/`testStatus`.
- Jika penyedia tampak secara permanen dikecualikan setelah jendela reset, periksa apakah kode
  membaca `state` mentah alih-alih menggunakan `getStatus()`/`canExecute()`.
- Jika satu kunci penyedia gagal tetapi yang lain seharusnya berfungsi, lebih baik menggunakan cooldown koneksi daripada
  pemutus penyedia.
- Jika hanya satu model yang gagal, lebih baik menggunakan penguncian model daripada cooldown koneksi.
- Jika suatu status seharusnya pulih sendiri, itu harus memiliki cap waktu/reset waktu depan dan jalur
  baca yang menyegarkan status yang kedaluwarsa. Status permanen memerlukan perubahan kredensial
  atau konfigurasi secara manual.

## Konvensi Kunci

### Gaya Kode

- **2 spasi**, titik koma, tanda kutip ganda, lebar 100 karakter, koma trailing es5 (ditegakkan oleh lint-staged melalui Prettier)
- **Impor**: eksternal → internal (`@/`, `@omniroute/open-sse`) → relatif
- **Penamaan**: file=camelCase/kebab, komponen=PascalCase, konstanta=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = kesalahan di mana saja; `no-explicit-any` = peringatan di `open-sse/` dan `tests/`
- **TypeScript**: `strict: false`, target ES2022, module esnext, resolusi bundler. Utamakan tipe eksplisit.

### Basis Data

- **Selalu** melalui modul domain `src/lib/db/` — **jangan pernah** menulis SQL mentah di rute atau pengendali
- **Jangan pernah** menambahkan logika ke `src/lib/localDb.ts` (hanya lapisan re-ekspor)
- **Jangan pernah** barrel-import dari `localDb.ts` — impor modul `db/` tertentu sebagai gantinya
- Singleton DB: `getDbInstance()` dari `src/lib/db/core.ts` (jurnal WAL)
- Migrasi: `src/lib/db/migrations/` — file SQL versi, idempotent, dijalankan dalam transaksi

### Penanganan Kesalahan

- coba/tangkap dengan tipe kesalahan spesifik, log dengan konteks pino
- Jangan pernah menelan kesalahan dalam aliran SSE — gunakan sinyal abort untuk pembersihan
- Kembalikan kode status HTTP yang tepat (4xx/5xx)

### Keamanan

- **Jangan pernah** menggunakan `eval()`, `new Function()`, atau eval implisit
- Validasi semua input dengan skema Zod
- Enkripsi kredensial saat tidak aktif (AES-256-GCM)
- Daftar penolakan header upstream: `src/shared/constants/upstreamHeaders.ts` — jaga sanitasi, skema Zod, dan pengujian unit tetap selaras saat mengedit
- **Kredensial upstream publik** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + kunci Web Firebase yang diambil dari CLI publik): **HARUS** disematkan melalui `resolvePublicCred()` dari `open-sse/utils/publicCreds.ts` — **jangan pernah** sebagai literal string. Lihat `docs/security/PUBLIC_CREDS.md` untuk pola yang wajib.
- **Respon kesalahan** (HTTP / SSE / eksekutor / pengendali MCP): **HARUS** diarahkan melalui `buildErrorBody()` atau `sanitizeErrorMessage()` dari `open-sse/utils/error.ts` — **jangan pernah** menempatkan `err.stack` atau `err.message` mentah dalam tubuh respon. Lihat `docs/security/ERROR_SANITIZATION.md`.
- **Perintah shell yang dibangun dari variabel**: saat memanggil `exec()`/`spawn()` dengan skrip yang membutuhkan nilai runtime, kirimkan melalui opsi `env` (secara otomatis di-escape shell) — **jangan pernah** menginterpolasi string jalur yang tidak tepercaya/eksternal ke dalam tubuh skrip. Referensi: `src/mitm/cert/install.ts::updateNssDatabases`.
- **Perpustakaan aman secara default** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): lebih suka Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink daripada implementasi kustom kapan pun menambahkan permukaan yang sensitif terhadap keamanan baru.

---

## Skenario Modifikasi Umum

### Menambahkan Penyedia Baru

1. Daftarkan di `src/shared/constants/providers.ts` (divalidasi Zod saat dimuat)
2. Tambahkan eksekutor di `open-sse/executors/` jika logika kustom diperlukan (perluas `BaseExecutor`)
3. Tambahkan penerjemah di `open-sse/translator/` jika format bukan OpenAI
4. Tambahkan konfigurasi OAuth di `src/lib/oauth/constants/oauth.ts` jika berbasis OAuth — jika CLI upstream mengirimkan client_id/secret publik, sematkan melalui `resolvePublicCred()` (lihat `docs/security/PUBLIC_CREDS.md`), **jangan pernah** sebagai literal
5. Daftarkan model di `open-sse/config/providerRegistry.ts`
6. Tulis pengujian di `tests/unit/` (sertakan pernyataan bentuk publicCreds jika Anda menambahkan default yang disematkan baru)

### Menambahkan Rute API Baru

1. Buat direktori di bawah `src/app/api/v1/your-route/`
2. Buat `route.ts` dengan pengendali `GET`/`POST`
3. Ikuti pola: CORS → validasi tubuh Zod → otentikasi opsional → delegasi pengendali
4. Pengendali masuk di `open-sse/handlers/` (impor dari sana, bukan inline)
5. Respon kesalahan menggunakan `buildErrorBody()` / `errorResponse()` dari `open-sse/utils/error.ts` (otomatis disanitasi — jangan pernah menempatkan `err.stack` atau `err.message` mentah dalam tubuh). Lihat `docs/security/ERROR_SANITIZATION.md`.
6. Tambahkan pengujian — termasuk setidaknya satu pernyataan bahwa respon kesalahan tidak membocorkan jejak tumpukan (`!body.error.message.includes("at /")`)

### Menambahkan Modul DB Baru

1. Buat `src/lib/db/yourModule.ts` — impor `getDbInstance` dari `./core.ts`
2. Ekspor fungsi CRUD untuk tabel domain Anda
3. Tambahkan migrasi di `src/lib/db/migrations/` jika tabel baru diperlukan
4. Re-ekspor dari `src/lib/localDb.ts` (tambahkan ke daftar re-ekspor saja)
5. Tulis pengujian

### Menambahkan Alat MCP Baru

1. Tambahkan definisi alat di `open-sse/mcp-server/tools/` dengan skema input Zod + pengendali asinkron
2. Daftarkan dalam set alat (terhubung oleh `createMcpServer()`)
3. Tetapkan ke ruang lingkup yang sesuai
4. Tulis pengujian (panggilan alat dicatat ke tabel `mcp_audit`)

### Menambahkan Keterampilan A2A Baru

1. Buat keterampilan di `src/lib/a2a/skills/` (5 sudah ada: smart-routing, quota-management, provider-discovery, cost-analysis, health-report)
2. Keterampilan menerima konteks tugas (pesan, metadata) → mengembalikan hasil terstruktur
3. Daftarkan di `A2A_SKILL_HANDLERS` di `src/lib/a2a/taskExecution.ts`
4. Ekspos di `src/app/.well-known/agent.json/route.ts` (Kartu Agen)
5. Tulis pengujian di `tests/unit/`
6. Dokumentasikan di tabel keterampilan `docs/frameworks/A2A-SERVER.md`

### Menambahkan Agen Cloud Baru

1. Buat kelas agen di `src/lib/cloudAgent/agents/` yang memperluas `CloudAgentBase` (3 sudah ada: codex-cloud, devin, jules)
2. Implementasikan `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources`
3. Daftarkan di `src/lib/cloudAgent/registry.ts`
4. Tambahkan penanganan OAuth/kredensial jika diperlukan (`src/lib/oauth/providers/`)
5. Pengujian + dokumentasikan di `docs/frameworks/CLOUD_AGENT.md`

### Menambahkan Guardrail / Eval / Keterampilan / Acara Webhook Baru

- Guardrail: `src/lib/guardrails/` → dokumen: `docs/security/GUARDRAILS.md`
- Suite Eval: `src/lib/evals/` → dokumen: `docs/frameworks/EVALS.md`
- Keterampilan (sandbox): `src/lib/skills/` → dokumen: `docs/frameworks/SKILLS.md`
- Acara Webhook: `src/lib/webhookDispatcher.ts` → dokumen: `docs/frameworks/WEBHOOKS.md`

## Dokumentasi Referensi

Untuk setiap perubahan yang tidak sepele, baca penjelasan mendalam yang sesuai terlebih dahulu:

| Area                                          | Dok                                                               |
| --------------------------------------------- | ----------------------------------------------------------------- |
| Navigasi repo                                 | `docs/architecture/REPOSITORY_MAP.md`                             |
| Arsitektur                                    | `docs/architecture/ARCHITECTURE.md`                               |
| Referensi teknik                              | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| Auto-Combo (skor 9 faktor, 14 strategi)       | `docs/routing/AUTO-COMBO.md`                                      |
| Ketahanan (3 mekanisme)                       | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| Pemutaran penalaran                           | `docs/routing/REASONING_REPLAY.md`                                |
| Kerangka keterampilan                         | `docs/frameworks/SKILLS.md`                                       |
| Sistem memori (FTS5 + Qdrant)                 | `docs/frameworks/MEMORY.md`                                       |
| Agen cloud                                    | `docs/frameworks/CLOUD_AGENT.md`                                  |
| Pengaman (PII / injeksi / visi)               | `docs/security/GUARDRAILS.md`                                     |
| Kredensial publik hulu (Gemini/dll.)          | `docs/security/PUBLIC_CREDS.md`                                   |
| Sanitasi pesan kesalahan                      | `docs/security/ERROR_SANITIZATION.md`                             |
| Evaluasi                                      | `docs/frameworks/EVALS.md`                                        |
| Kepatuhan / audit                             | `docs/security/COMPLIANCE.md`                                     |
| Webhook                                       | `docs/frameworks/WEBHOOKS.md`                                     |
| Jalur otorisasi                               | `docs/architecture/AUTHZ_GUIDE.md`                                |
| Stealth (TLS / sidik jari)                    | `docs/security/STEALTH_GUIDE.md`                                  |
| Protokol agen (A2A / ACP / Cloud)             | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| Server MCP                                    | `docs/frameworks/MCP-SERVER.md`                                   |
| Server A2A                                    | `docs/frameworks/A2A-SERVER.md`                                   |
| Referensi API + OpenAPI                       | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| Katalog penyedia (dihasilkan secara otomatis) | `docs/reference/PROVIDER_REFERENCE.md`                            |
| Alur rilis                                    | `docs/ops/RELEASE_CHECKLIST.md`                                   |

---

## Pengujian

| Apa                     | Perintah                                                               |
| ----------------------- | ---------------------------------------------------------------------- |
| Uji unit                | `npm run test:unit`                                                    |
| File tunggal            | `node --import tsx/esm --test tests/unit/file.test.ts`                 |
| Vitest (MCP, autoCombo) | `npm run test:vitest`                                                  |
| E2E (Playwright)        | `npm run test:e2e`                                                     |
| Protokol E2E (MCP+A2A)  | `npm run test:protocols:e2e`                                           |
| Ekosistem               | `npm run test:ecosystem`                                               |
| Gerbang cakupan         | `npm run test:coverage` (75/75/75/70 — pernyataan/garis/fungsi/cabang) |
| Laporan cakupan         | `npm run coverage:report`                                              |

**Aturan PR**: Jika Anda mengubah kode produksi di `src/`, `open-sse/`, `electron/`, atau `bin/`, Anda harus menyertakan atau memperbarui pengujian dalam PR yang sama.

**Preferensi lapisan pengujian**: unit pertama → integrasi (multi-modul atau status DB) → e2e (UI/workflow saja). Kodekan reproduksi bug sebagai pengujian otomatis sebelum atau bersamaan dengan perbaikan.

**Kebijakan cakupan Copilot**: Ketika PR mengubah kode produksi dan cakupan di bawah 75% (pernyataan/garis/fungsi) atau 70% (cabang), jangan hanya melaporkan — tambahkan atau perbarui pengujian, jalankan kembali gerbang cakupan, lalu minta konfirmasi. Sertakan perintah yang dijalankan, file pengujian yang diubah, dan hasil cakupan akhir dalam laporan PR.

---

## Alur Kerja Git

```bash
# Jangan pernah melakukan commit langsung ke main
git checkout -b feat/your-feature
git commit -m "feat: deskripsikan perubahan Anda"
git push -u origin feat/your-feature
```

**Awalan cabang**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**Format commit** (Conventional Commits): `feat(db): tambahkan circuit breaker` — ruang lingkup: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**Hook Husky**:

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

---

## Lingkungan

- **Runtime**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
- **TypeScript**: 5.9+, target ES2022, module esnext, resolution bundler
- **Alias jalur**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **Port default**: 20128 (API + dashboard di port yang sama)
- **Direktori data**: variabel env `DATA_DIR`, default ke `~/.omniroute/`
- **Variabel env kunci**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- Setup: `cp .env.example .env` lalu hasilkan `JWT_SECRET` (`openssl rand -base64 48`) dan `API_KEY_SECRET` (`openssl rand -hex 32`)

---

## Aturan Keras

1. Jangan pernah melakukan commit rahasia atau kredensial
2. Jangan pernah menambahkan logika ke `localDb.ts`
3. Jangan pernah menggunakan `eval()` / `new Function()` / eval tersirat
4. Jangan pernah melakukan commit langsung ke `main`
5. Jangan pernah menulis SQL mentah di rute — gunakan modul `src/lib/db/`
6. Jangan pernah menelan kesalahan secara diam-diam di aliran SSE
7. Selalu validasi input dengan skema Zod
8. Selalu sertakan pengujian saat mengubah kode produksi
9. Cakupan harus tetap ≥75% (pernyataan, garis, fungsi) / ≥70% (cabang). Saat ini terukur: ~82%.
10. Jangan pernah melewati hook Husky (`--no-verify`, `--no-gpg-sign`) tanpa persetujuan operator yang eksplisit.
11. Jangan pernah menyematkan client_id/secret OAuth upstream publik atau kunci Web Firebase sebagai literal string — selalu melalui `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). Lihat `docs/security/PUBLIC_CREDS.md`.
12. Jangan pernah mengembalikan `err.stack` / `err.message` mentah dalam respons HTTP / SSE / eksekutor — selalu rute melalui `buildErrorBody()` atau `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). Lihat `docs/security/ERROR_SANITIZATION.md`.
13. Jangan pernah melakukan interpolasi string jalur eksternal atau nilai runtime ke dalam skrip shell yang diteruskan ke `exec()`/`spawn()` — teruskan melalui opsi `env` sebagai gantinya. Referensi: `src/mitm/cert/install.ts::updateNssDatabases`.
14. Jangan pernah mengabaikan peringatan CodeQL / Secret-Scanning tanpa (a) terlebih dahulu memeriksa dokumen pola di atas untuk melihat apakah pembantu berlaku, dan (b) mencatat justifikasi teknis dalam komentar pengabaian. Preseden: `js/stack-trace-exposure` yang muncul di callsites yang sudah rute melalui `sanitizeErrorMessage()` adalah batasan CodeQL yang diketahui (pembersih kustom tidak dikenali) — abaikan sebagai `false positive` yang merujuk pada `docs/security/ERROR_SANITIZATION.md`.
15. Jangan pernah mengekspos rute yang memunculkan proses anak (`/api/mcp/`, `/api/cli-tools/runtime/`) tanpa klasifikasi `isLocalOnlyPath()` di `src/server/authz/routeGuard.ts`. Penegakan loopback terjadi tanpa syarat sebelum pemeriksaan otentikasi — JWT yang bocor melalui terowongan tidak dapat memicu pemunculan proses. Lihat `docs/security/ROUTE_GUARD_TIERS.md`.
16. Jangan pernah menyertakan trailer `Co-Authored-By` yang memberi kredit kepada asisten AI, LLM, atau akun otomatisasi (mis. nama yang mengandung "Claude", "GPT", "Copilot", "Bot"; email di `anthropic.com` / `openai.com` / alamat `noreply.github.com` milik bot). Trailer semacam itu mengarahkan atribusi commit ke akun bot di GitHub, menyembunyikan penulis sebenarnya (`diegosouzapw`) dalam riwayat PR. Kolaborator manusia — termasuk penulis PR upstream dan pelapor issue yang di-port ke OmniRoute — DAPAT dan HARUS dikreditkan dengan trailer standar `Co-authored-by: Name <email>`; alur kerja upstream-port (`/port-upstream-features`, `/port-upstream-issues`) bergantung pada ini.