# Contributing to OmniRoute (සිංහල)

🌐 **Languages:** 🇺🇸 [English](../../../CONTRIBUTING.md) · 🇪🇹 [am](../am/CONTRIBUTING.md) · 🇸🇦 [ar](../ar/CONTRIBUTING.md) · 🇦🇿 [az](../az/CONTRIBUTING.md) · 🇧🇬 [bg](../bg/CONTRIBUTING.md) · 🇧🇩 [bn](../bn/CONTRIBUTING.md) · 🇧🇦 [bs](../bs/CONTRIBUTING.md) · 🇨🇿 [cs](../cs/CONTRIBUTING.md) · 🇩🇰 [da](../da/CONTRIBUTING.md) · 🇩🇪 [de](../de/CONTRIBUTING.md) · 🇬🇷 [el](../el/CONTRIBUTING.md) · 🇪🇸 [es](../es/CONTRIBUTING.md) · 🇪🇪 [et](../et/CONTRIBUTING.md) · 🇮🇷 [fa](../fa/CONTRIBUTING.md) · 🇫🇮 [fi](../fi/CONTRIBUTING.md) · 🇫🇷 [fr](../fr/CONTRIBUTING.md) · 🇮🇪 [ga](../ga/CONTRIBUTING.md) · 🇮🇳 [gu](../gu/CONTRIBUTING.md) · 🇳🇬 [ha](../ha/CONTRIBUTING.md) · 🇮🇱 [he](../he/CONTRIBUTING.md) · 🇮🇳 [hi](../hi/CONTRIBUTING.md) · 🇭🇷 [hr](../hr/CONTRIBUTING.md) · 🇭🇺 [hu](../hu/CONTRIBUTING.md) · 🇦🇲 [hy](../hy/CONTRIBUTING.md) · 🇮🇩 [id](../id/CONTRIBUTING.md) · 🇳🇬 [ig](../ig/CONTRIBUTING.md) · 🇮🇹 [it](../it/CONTRIBUTING.md) · 🇯🇵 [ja](../ja/CONTRIBUTING.md) · 🇬🇪 [ka](../ka/CONTRIBUTING.md) · 🇰🇭 [km](../km/CONTRIBUTING.md) · 🇮🇳 [kn](../kn/CONTRIBUTING.md) · 🇰🇷 [ko](../ko/CONTRIBUTING.md) · 🇱🇹 [lt](../lt/CONTRIBUTING.md) · 🇱🇻 [lv](../lv/CONTRIBUTING.md) · 🇮🇳 [ml](../ml/CONTRIBUTING.md) · 🇮🇳 [mr](../mr/CONTRIBUTING.md) · 🇲🇾 [ms](../ms/CONTRIBUTING.md) · 🇲🇹 [mt](../mt/CONTRIBUTING.md) · 🇲🇲 [my](../my/CONTRIBUTING.md) · 🇳🇵 [ne](../ne/CONTRIBUTING.md) · 🇳🇱 [nl](../nl/CONTRIBUTING.md) · 🇳🇴 [no](../no/CONTRIBUTING.md) · 🇮🇳 [or](../or/CONTRIBUTING.md) · 🇮🇳 [pa](../pa/CONTRIBUTING.md) · 🇵🇭 [phi](../phi/CONTRIBUTING.md) · 🇵🇱 [pl](../pl/CONTRIBUTING.md) · 🇵🇹 [pt](../pt/CONTRIBUTING.md) · 🇧🇷 [pt-BR](../pt-BR/CONTRIBUTING.md) · 🇷🇴 [ro](../ro/CONTRIBUTING.md) · 🇷🇺 [ru](../ru/CONTRIBUTING.md) · 🇸🇰 [sk](../sk/CONTRIBUTING.md) · 🇸🇮 [sl](../sl/CONTRIBUTING.md) · 🇷🇸 [sr](../sr/CONTRIBUTING.md) · 🇸🇪 [sv](../sv/CONTRIBUTING.md) · 🇰🇪 [sw](../sw/CONTRIBUTING.md) · 🇮🇳 [ta](../ta/CONTRIBUTING.md) · 🇮🇳 [te](../te/CONTRIBUTING.md) · 🇹🇭 [th](../th/CONTRIBUTING.md) · 🇹🇷 [tr](../tr/CONTRIBUTING.md) · 🇺🇦 [uk-UA](../uk-UA/CONTRIBUTING.md) · 🇵🇰 [ur](../ur/CONTRIBUTING.md) · 🇺🇿 [uz](../uz/CONTRIBUTING.md) · 🇻🇳 [vi](../vi/CONTRIBUTING.md) · 🇳🇬 [yo](../yo/CONTRIBUTING.md) · 🇨🇳 [zh-CN](../zh-CN/CONTRIBUTING.md) · 🇹🇼 [zh-TW](../zh-TW/CONTRIBUTING.md)

---

දායක වීමට ඔබ දක්වන උනන්දුවට ස්තුතියි! ආරම්භ කිරීමට ඔබට අවශ්ය සියල්ල මෙම මාර්ගෝපදේශය ආවරණය කරයි.

එක් එක් වෙනස්කම සඳහා වන නිල කාර්ය ප්රවාහය සඳහා,
[දායකත්ව ප්රධාන මාර්ගය](docs/ops/CONTRIBUTION_GOLDEN_PATH.md) වෙතින් ආරම්භ කරන්න. එය provider, routing,
UI/UX, i18n, CLI, database, සහ build/deploy වෙනස්කම් ඒවායේ ගිවිසුම්, ඉලක්කගත පරීක්ෂණ, CI
ආවරණය, සහ ප්රතිසන්ධාන පියවර සමඟ සිතියම්ගත කරයි.

---

## සංවර්ධන සැකසුම

### පූර්ව අවශ්යතා

- **Node.js** `>=22.22.2 <23`, හෝ `>=24.0.0 <27` (නිර්දේශිත: 24 LTS)
- **npm** 10+

> **Node 24 සහිත Windows:** වත්මන් 24 LTS patch නිකුතුව භාවිත කරන්න (අවම වශයෙන් 24.20.0).
> පැරණි නිකුතු මඟින් `--test-force-exit` ක්රියාවලිය වසා දැමූ පසු සාර්ථක පරීක්ෂණවලින් අනතුරුව
> ක්රියාවලිය අසාමාන්ය ලෙස අවසන් විය හැක. Node හි [Windows libuv fix](https://github.com/nodejs/node/pull/61999) මඟින්
> මෙම runtime බිඳවැටීම විසඳයි; පරීක්ෂණ assertions සහ runner exit checks සක්රීයව තබන්න.

> **npm v11+ පරිශීලකයන් (Node 24+):** `npm install` පසුව, native modules ස්ථාපනය වී ඇති බව තහවුරු කරන්න:
> `node -e "require('better-sqlite3')"`. එය `MODULE_NOT_FOUND` සමඟ අසාර්ථක වන්නේ නම්,
> `npm approve-scripts better-sqlite3 && npm install` ධාවනය කරන්න. [ගැටලු නිරාකරණය](docs/guides/TROUBLESHOOTING.md#npm-v11-better-sqlite3-not-installed-cannot-find-module) බලන්න.

- **Git**

### ක්ලෝන කිරීම සහ ස්ථාපනය

```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install
```

### පරිසර විචල්ය

```bash
# අච්චුවෙන් ඔබේ .env සාදන්න
cp .env.example .env

# අවශ්ය secrets ජනනය කරන්න
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env
```

සංවර්ධනය සඳහා ප්රධාන විචල්ය:

| විචල්යය                | සංවර්ධන පෙරනිමිය         | විස්තරය                  |
| ---------------------- | ------------------------ | ------------------------ |
| `PORT`                 | `20128`                  | සේවාදායක port            |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | frontend සඳහා මූලික URL  |
| `JWT_SECRET`           | (ඉහත ජනනය කරන්න)         | JWT අත්සන් කිරීමේ secret |
| `INITIAL_PASSWORD`     | `CHANGEME`               | පළමු login මුරපදය        |
| `APP_LOG_LEVEL`        | `info`                   | Log විස්තරාත්මක මට්ටම    |

### Dashboard සැකසුම්

Dashboard මඟින් පරිසර විචල්ය හරහාද සැකසිය හැකි විශේෂාංග සඳහා UI toggle සපයයි:

| සැකසුම් ස්ථානය      | Toggle             | විස්තරය                              |
| ------------------- | ------------------ | ------------------------------------ |
| Settings → Advanced | Debug Mode         | Debug request logs සක්රීය කරන්න (UI) |
| Settings → General  | Sidebar Visibility | Sidebar කොටස් පෙන්වන්න/සඟවන්න        |

මෙම සැකසුම් database තුළ ගබඩා වන අතර restart කිරීමෙන් පසුවද පවතී. සැකසූ විට, ඒවා env var පෙරනිමි අගයන් අභිබවා යයි.

### දේශීයව ධාවනය කිරීම

```bash
# සංවර්ධන මාදිලිය (hot reload)
npm run dev

# Production build
npm run build    # next build → .build/next/ then assembleStandalone → dist/
npm run start

# දායකයන්ගේ වෙනස්කම් සඳහා වේගවත් backend/API-only compile කිරීම
npm run build:contributor

# Release build (පිරිසිදු rebuild + HEAD sentinel — deploy සඳහා අවශ්ය)
npm run build:release   # rm -rf .build dist && build + writes dist/BUILD_SHA

# සාමාන්ය port configuration
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
```

දායකයන්ගේ build මඟින් compile-only වලංගුකරණය සිදු කරයි: එය standalone
distribution එක assemble කිරීම හෝ විකල්ප native packaging assets build කිරීම සිදු නොකරයි.
deploy කළ හැකි bundle එක වලංගු කිරීමට අවශ්ය විට සාමාන්ය production build භාවිත කරන්න.

### Build ප්රතිදාන සැලැස්ම

| නාමාවලිය  | අන්තර්ගතය                                                                 | Tracked |
| --------- | ------------------------------------------------------------------------- | ------- |
| `src/`    | Application source (TypeScript / TSX)                                     | Yes     |
| `.build/` | Intermediates — `next build` output (gitignored, `distDir = .build/next`) | No      |
| `dist/`   | Shippable bundle — assembled by `assembleStandalone` (gitignored)         | No      |

Build pipeline එක එක් පියවරකින් සමන්විත වේ:

```
npm run build
  └─ next build → .build/next/standalone  (Next.js output)
  └─ assembleStandalone()                 (copies standalone + static + public + native assets)
       └─ output: dist/                   (server.js, .next/static/, public/, node_modules/)
```

`npm run build:release` මඟින් පළමුව නාමාවලි දෙකම පිරිසිදු කර, deploy integrity sentinel එකක් ලෙස
`dist/BUILD_SHA` (= `git rev-parse --short HEAD`) ලියයි.

`npm run build:contributor` backend-only build profile එක භාවිත කරයි. එය build කරන අතරතුර
dashboard UI files තාවකාලිකව stub කර, API route handlers තබාගෙන, build එකෙන් පසුව
මුල් files ප්රතිස්ථාපනය කරයි. Dashboard UI වෙත බලපාන වෙනස්කම් සඳහා හෝ සම්පූර්ණ
release validation සඳහා `npm run build` භාවිත කරන්න; contributor profile එක release build එකට
ආදේශකයක් නොවේ.

> **VPS deploy සටහන:** remote image directory `/usr/lib/node_modules/omniroute/app/`
> වෙනස් නොවේ. Deploy skills මඟින් `dist/` හි අන්තර්ගතය එයට rsync කරයි.
> වෙනස් වී ඇත්තේ repository තුළ ඇති build output path එක පමණි (`app/` → `dist/`).

පෙරනිමි URLs:

- **Dashboard**: `http://localhost:20128/dashboard`
- **API**: `http://localhost:20128/v1`

---

## Git කාර්ය ප්රවාහය

> ⚠️ **කිසිවිටෙකත් සෘජුව `main` වෙත commit නොකරන්න.** සෑමවිටම feature branches භාවිත කරන්න.
>
> **PR පදනම:** සක්රිය `release/vX.Y.Z` branch එක ඉලක්ක කරන්න (`main` නොවේ).
> එක්-branch-එකකට-release + නිකුත් කිරීමේදී-tag යෙදීමේ ආකෘතිය සඳහා
> [`docs/ops/BRANCHING_MODEL.md`](docs/ops/BRANCHING_MODEL.md) බලන්න.

```bash
# සක්රිය release අග්රයෙන් branch එක සාදන්න (උදාහරණය: release/v3.8.49)
git fetch origin
git checkout -b feat/your-feature-name origin/release/v3.8.49
# ... වෙනස්කම් සිදු කරන්න ...
git commit -m "feat: describe your change"
git push -u origin feat/your-feature-name
# base = release/v3.8.49 ලෙස Pull Request එකක් විවෘත කරන්න
```

### Branch නම් කිරීම

| Prefix      | අරමුණ                             |
| ----------- | --------------------------------- |
| `feat/`     | නව විශේෂාංග                       |
| `fix/`      | දෝෂ නිවැරදි කිරීම්                |
| `refactor/` | කේතය ප්රතිව්යුහගත කිරීම           |
| `docs/`     | ලේඛන වෙනස්කම්                     |
| `test/`     | පරීක්ෂණ එක් කිරීම්/නිවැරදි කිරීම් |
| `chore/`    | මෙවලම්, CI, dependencies          |

### Commit පණිවිඩ

[Conventional Commits](https://www.conventionalcommits.org/) අනුගමනය කරන්න:

```
feat: provider ඇමතුම් සඳහා circuit breaker එකක් එක් කරන්න
fix: JWT secret සත්යාපනයේ අන්ත අවස්ථාව විසඳන්න
docs: PII ආරක්ෂාව සමඟ SECURITY.md යාවත්කාලීන කරන්න
test: observability unit tests එක් කරන්න
refactor(db): rate limit වගු ඒකාබද්ධ කරන්න
```

Scopes (v3.8): `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`, `cloud-agent`, `guardrails`, `compression`, `auto-combo`, `resilience`, `providers`, `executors`, `translator`, `domain`, `authz`.

---

## පරීක්ෂණ ධාවනය කිරීම

```bash
# සියලු පරීක්ෂණ (ඒකක + vitest + පරිසර පද්ධති + e2e)
npm run test:all

# තනි පරීක්ෂණ ගොනුවක් (Node.js ස්වදේශීය පරීක්ෂණ ධාවකය — බොහෝ පරීක්ෂණ මෙය භාවිත කරයි)
node --import tsx/esm --test tests/unit/your-file.test.ts

# ඔබේ වෙනස්කමෙන් බලපෑමට ලක් වූ ඒකක පරීක්ෂණ පමණි (CI සීමාවට සමාන TIA තේරීම්කාරකය, #8084)
npm run test:scoped            # අවසන් commit එකේ (හෝ වැඩ කරන tree එකේ) වෙනස්කම්
npm run test:scoped:staged     # stage කළ වෙනස්කම් පමණි — pre-commit ධාවනයක් සමඟ හොඳින් ගැළපේ
npm run test:scoped:full       # පළමුව import-graph සිතියම නැවත ගොඩනඟයි (ගොනු එක් කිරීමෙන්/ගෙනයාමෙන් පසු)
# Exit 1 + "සම්පූර්ණ කට්ටලය ධාවනය කරන්න" යන්නෙන් අදහස් වන්නේ කේන්ද්රීය ගොනුවක් (tsconfig, package.json, …) හෝ
# සිතියම්ගත නොකළ මූලාශ්රයක් වෙනස් වී ඇති බවයි — තේරීම්කාරකය ආරක්ෂිත ලෙස අසමත් වන අතර කිසි විටෙක නිහඬව මඟ නොහරියි.

# Vitest (MCP සේවාදායකය, autoCombo, cache)
npm run test:vitest

# E2E පරීක්ෂණ (Playwright අවශ්යයි)
npm run test:e2e

# Protocol සේවාලාභී E2E (MCP transports, A2A)
npm run test:protocols:e2e

# පරිසර පද්ධති අනුකූලතා පරීක්ෂණ
npm run test:ecosystem

# ආවරණ සීමාව: ප්රකාශ/පේළි/ශ්රිත/ශාඛා 60%
npm run test:coverage
npm run coverage:report

# Lint + ආකෘති පරීක්ෂාව
npm run lint
npm run check

# සීමා කළ සැබෑ-upstream සංයෝජන මූලික සත්යාපන පරීක්ෂණය (VPS ප්රවේශය + සැබෑ සැපයුම්කරු credits අවශ්යයි)
# සැබෑ සැපයුම්කරුවන් වෙත ප්රවේශ වේ — සුළු පිරිවැයක් දරයි. CI තුළ කිසි විටෙක ධාවනය නොවේ. සීමාව නොමැති විට නිසි ලෙස මඟ හරියි.
# අවශ්ය වන්නේ: ssh root@192.168.0.15 ප්රවේශය (VPS වෙතින් read-only DB snapshot එකක් ලබාගනී).
RUN_COMBO_LIVE=1 npm run test:combo:live

# Phase-3 VPS සජීවී මූලික සත්යාපන පරීක්ෂණය — සරල Node ESM scripts, සජීවී .15 සේවාදායකයට ඍජුව ප්රවේශ වේ.
# අවශ්ය වන්නේ: ssh root@192.168.0.15 ප්රවේශය (SSH sqlite හරහා සංයෝජන සාදා/ඉවත් කරයි).
# සැබෑ සැපයුම්කරුවන් වෙත ප්රවේශ වේ (සුළු පිරිවැයක්). __live_test__* සංයෝජන පමණක් සාදා/මකයි. CI තුළ කිසි විටෙක ධාවනය නොවේ.
# .15 හි REQUIRE_API_KEY=false බැවින් API key එකක් අවශ්ය නොවන නමුත්, සකසා ඇත්නම් COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY භාවිත කරයි.
npm run test:combo:live:vps              # HTTP අවස්ථා 7ක් (ප්රමුඛතාව/round-robin/බරිත/පිරිවැය/fusion/ස්වයංක්රීය + සෞඛ්යය)
npm run test:combo:live:vps:failover     # සැබෑ හරස්-සැපයුම්කරු failover අවස්ථාවක් එක් කරයි (මුළු ගණන 8)
```

ආවරණ සටහන්:

- `npm run test:coverage` ප්රධාන ඒකක පරීක්ෂණ කට්ටලය සඳහා මූලාශ්ර ආවරණය මනින අතර, `tests/**` බැහැර කර, `open-sse/**` ඇතුළත් කරයි
- Pull request මඟින් ප්රකාශ/පේළි/ශ්රිත/ශාඛා සඳහා ආවරණ සීමාව **60%+** ලෙස පවත්වාගත යුතුය
- PR එකක් `src/`, `open-sse/`, `electron/`, හෝ `bin/` තුළ නිෂ්පාදන කේතය වෙනස් කරන්නේ නම්, එම PR එක තුළම ස්වයංක්රීය පරීක්ෂණ එක් කිරීම හෝ යාවත්කාලීන කිරීම කළ යුතුය
- `npm run coverage:report` නවතම ආවරණ ධාවනයෙන් ගොනුවෙන්-ගොනුවට සවිස්තර වාර්තාව මුද්රණය කරයි
- `npm run test:coverage:legacy` ඓතිහාසික සැසඳීම සඳහා පැරණි මිනුම සුරකියි
- අදියර අනුව ආවරණය වැඩිදියුණු කිරීමේ මාර්ග සිතියම සඳහා `docs/ops/COVERAGE_PLAN.md` බලන්න

### Pull Request අවශ්යතා

PR එකක් විවෘත කිරීමට පෙර, ඔබ වෙනස් කළ දේ සඳහා ඉලක්කගත ක්රියාවලිය ධාවනය කිරීමට
[දායකත්ව Golden Path](docs/ops/CONTRIBUTION_GOLDEN_PATH.md) භාවිත කරන්න. සම්පූර්ණ ඒකක පරීක්ෂණ කට්ටලය (CI shards 4ක්), Vitest, **60%+** ආවරණ සීමාව සහ
නිෂ්පාදන build එක CI හි වගකීම වේ — ඒවා දේශීයව ධාවනය කිරීමෙන් PR
පරීක්ෂාවන් දැනටමත් ලබා නොදෙන අමතර තොරතුරක් නොලැබෙන අතර, කුඩා යන්ත්රවලදී එය host එකේ ධාරිතාව සම්පූර්ණයෙන් භාවිත කළ හැකිය (#8084):

- ඔබේ වෙනස ආවරණය කරන පරීක්ෂණ ගොනු ධාවනය කරන්න: `node --import tsx/esm --test tests/unit/<file>.test.ts`
- `npm run lint` ධාවනය කරන්න
- නිෂ්පාදන කේතය වෙනස් වන සෑම විටම එම PR එක තුළම ස්වයංක්රීය පරීක්ෂණ ඇතුළත් කරන්න හෝ යාවත්කාලීන කරන්න
- `node:test` ගොනු තුළ, සෑම ඉහළ මට්ටමේ `await` එකක්ම (`await import(...)` වැනි) පළමු `test()` / `describe()` එකට පෙර තබන්න: `--test-force-exit` යටතේ, ඊට පසු ලියාපදිංචි කරන පරීක්ෂණ නිහඬව කිසි විටෙක ධාවනය නොවිය හැකිය (#18045; `npm run check:test-tla-order` මඟින් බලාත්මක කරයි)
- නිෂ්පාදන කේතය වෙනස් වූ විට, වෙනස් කළ හෝ එක් කළ පරීක්ෂණ ගොනු PR විස්තරයට ඇතුළත් කරන්න
- ව්යාපෘති රහස් CI තුළ වින්යාස කර ඇති විට PR එකේ SonarQube ප්රතිඵලය පරීක්ෂා කරන්න

වත්මන් පරීක්ෂණ තත්ත්වය: පහත දෑ ආවරණය කරන **ඒකක පරීක්ෂණ ගොනු 122ක්**:

- සැපයුම්කරු පරිවර්තක සහ ආකෘති පරිවර්තනය
- අනුපාත සීමා කිරීම, circuit breaker සහ ප්රත්යස්ථතාව
- අර්ථකථන cache, idempotency සහ ප්රගති නිරීක්ෂණය
- දත්ත සමුදා මෙහෙයුම් සහ schema (DB modules 21ක්)
- OAuth ප්රවාහ සහ සත්යාපනය
- API endpoint වලංගුකරණය (Zod v4)
- MCP සේවාදායක මෙවලම් සහ scope බලාත්මක කිරීම
- Memory සහ Skills පද්ධති

---

## කේත ශෛලිය

- **ESLint** — commit කිරීමට පෙර `npm run lint` ධාවනය කරන්න
- **Prettier** — commit කිරීමේදී `lint-staged` හරහා ස්වයංක්රීයව ආකෘතිගත කෙරේ (හිස්තැන් 2ක්, අර්ධවිරාම, ද්විත්ව උද්ධෘත ලකුණු, අක්ෂර 100ක පළල, es5 trailing commas)
- **TypeScript** — සියලුම `src/` කේත `.ts`/`.tsx` භාවිත කරයි; `open-sse/` විසින් `.ts`/`.js` භාවිත කරයි; TSDoc (`@param`, `@returns`, `@throws`) මඟින් ලේඛනගත කරන්න
- **`eval()` භාවිත නොකරන්න** — ESLint මඟින් `no-eval`, `no-implied-eval`, `no-new-func` බලාත්මක කරයි
- **Zod වලංගුකරණය** — සියලුම API ආදාන වලංගුකරණය සඳහා Zod v4 schemas භාවිත කරන්න
- **නාමකරණය**: ගොනු = camelCase/kebab-case, සංරචක = PascalCase, නියතයන් = UPPER_SNAKE

### දෝෂ හැසිරවීම / හිස් catch blocks

කිසිවිටෙකත් පැහැදිලි කිරීමකින් තොරව `catch` එකක් තබන්න එපා. එය කාණ්ඩ දෙකෙන් එකකට වර්ගීකරණය කරන්න (මෙය
"SSE streams තුළ දෝෂ කිසිවිටෙකත් නිහඬව නොසලකා හරින්න" යන දැඩි රීතිය ක්රියාත්මක කරයි):

- **චේතනාන්විත (අපගේම best-effort පිරිසිදු කිරීම/ටෙලිමෙට්රි)** — මෙහි අසාර්ථක වීමක් අපේක්ෂිත සහ
  හානිකර නොවන දෙයකි; තනි පේළියක හේතු දැක්වීමේ comment එකක් එක් කරන්න, logging නොකරන්න (සෑම request එකකදීම logging කිරීමෙන්
  ඇතිවන අනවශ්ය ඝෝෂාව මෙම සම්මුතිය මඟින් වළක්වයි).

  ```ts
  } catch {} // client විසන්ධි වූ පසු දැනටමත් වැසූ controller එකක් වසා දැමීමට උත්සාහ කිරීම අපේක්ෂිතය
  ```

- **Log කළ යුතුය (බාහිර/caller විසින් සපයන ලද කේතය, හෝ නොසලකා හැරීමෙන් control flow වෙනස් වේ)** — stream එක
  බිඳ දැමීමට කිසිවිටෙකත් ඉඩ නොදෙමින් catch එක තබා ගන්න, නමුත් අසාර්ථකත්වය සොයාගත හැකි වන පරිදි සන්දර්භානුකූල `console.debug`/`warn` එකක්
  නිකුත් කරන්න.

  ```ts
  } catch (e) {
    console.debug("[STREAM] onFailure callback දෝෂය:", e);
  }
  ```

යොදා ඇති උදාහරණ සඳහා `open-sse/utils/stream.ts` සහ `open-sse/utils/streamHandler.ts` බලන්න.

---

## ව්යාපෘති ව්යුහය

```
src/                        # TypeScript (.ts / .tsx)
├── app/                    # Next.js 16 App Router
│   ├── (dashboard)/        # උපකරණ පුවරු පිටු (කොටස් 23)
│   ├── api/                # API මාර්ග (නාමාවලි 51)
│   └── login/              # සත්යාපන පිටු (.tsx)
├── domain/                 # ප්රතිපත්ති එන්ජිම (policyEngine, comboResolver, costRules, ආදිය)
├── lib/                    # මූලික ව්යාපාරික තර්කනය (.ts)
│   ├── a2a/                # Agent-to-Agent v0.3 ප්රොටෝකෝල සේවාදායකය
│   ├── acp/                # Agent Communication Protocol ලේඛනය
│   ├── compliance/         # අනුකූලතා ප්රතිපත්ති එන්ජිම
│   ├── db/                 # SQLite වසම් මොඩියුල + සංක්රමණ 130
│   ├── memory/             # ස්ථිර සංවාද මතකය
│   ├── oauth/              # OAuth සපයන්නන්, සේවා සහ උපයෝගිතා
│   ├── skills/             # විස්තීරණය කළ හැකි කුසලතා රාමුව
│   ├── usage/              # භාවිත ලුහුබැඳීම සහ පිරිවැය ගණනය කිරීම
│   └── localDb.ts          # නැවත-නිර්යාත ස්තරය පමණි — මෙහි කිසිවිටෙක තර්කනය එක් නොකරන්න
├── middleware/              # ඉල්ලීම් මධ්යස්ථ මෘදුකාංගය (promptInjectionGuard)
├── mitm/                   # MITM ප්රොක්සිය (සහතික, DNS, ඉලක්ක මාර්ගගත කිරීම)
├── shared/
│   ├── components/         # React සංරචක (.tsx)
│   ├── constants/          # සපයන්නන්ගේ නිර්වචන (329), MCP විෂය පථ, මාර්ගගත කිරීමේ උපායමාර්ග 20
│   ├── utils/              # පරිපථ බිඳිනය, පිරිසිදුකාරකය, සත්යාපන සහායක
│   └── validation/         # Zod v4 ස්කීමා
└── sse/                    # SSE ප්රොක්සි නල මාර්ගය

open-sse/                   # @omniroute/open-sse වැඩබිම
├── executors/              # ක්රියාත්මක කිරීමේ මොඩියුල 150 (ක්රියාත්මක කිරීමේ පන්ති + එක් එක් සපයන්නා සඳහා සහායක)
├── handlers/               # ඉල්ලීම් හසුරුවන්නන් 11 (කතාබස්, ප්රතිචාර, කාවැද්දීම්, රූප, ආදිය)
├── mcp-server/             # MCP සේවාදායකය (අද්විතීය මෙවලම් 110, ප්රවාහන 3, විෂය පථ 33)
├── services/               # ඉහළ මට්ටමේ සේවා 178 (combo, autoCombo, rateLimitManager, ආදිය)
├── translator/             # ආකෘති පරිවර්තක (OpenAI ↔ Claude ↔ Gemini ↔ Responses ↔ Ollama)
├── transformer/            # Responses API පරිණාමකය
└── utils/                  # උපයෝගිතා මොඩියුල 22 (ප්රවාහ, TLS, ප්රොක්සි, ලොග්කරණය)

electron/                   # Electron ඩෙස්ක්ටොප් යෙදුම (බහු-වේදිකා)

tests/
├── unit/                   # Node.js පරීක්ෂණ ධාවකය (පරීක්ෂණ ගොනු 1,574)
├── integration/            # ඒකාබද්ධතා පරීක්ෂණ
├── e2e/                    # Playwright පරීක්ෂණ
├── security/               # ආරක්ෂක පරීක්ෂණ
├── translator/             # පරිවර්තකයට විශේෂිත පරීක්ෂණ
└── load/                   # භාර පරීක්ෂණ

docs/
├── adr/                     # ගෘහනිර්මාණ තීරණ වාර්තා
├── architecture/            # පද්ධති ගෘහනිර්මාණය සහ ප්රත්යාස්ථතාව
├── comparison/              # OmniRoute සහ විකල්ප අතර සැසඳීම
├── compression/             # සම්පීඩන මාර්ගෝපදේශ සහ නීති
├── dev/                     # සංවර්ධන මාර්ගෝපදේශ
├── diagrams/                # ගෘහනිර්මාණ රූපසටහන්
├── frameworks/              # MCP, A2A, OpenCode, Memory, Skills
├── guides/                  # පරිශීලක මාර්ගෝපදේශය, Docker, පිහිටුවීම, දෝෂ නිරාකරණය
├── i18n/                    # ජාත්යන්තරකරණය කළ README පරිවර්තන
├── marketing/               # අලෙවිකරණ ද්රව්ය
├── ops/                     # යෙදවීම, ප්රොක්සි, ආවරණය, නිකුතු
├── providers/               # සපයන්නාට විශේෂිත ලේඛන
├── reference/               # API යොමුව, පරිසර විචල්ය, CLI මෙවලම්, නොමිලේ මට්ටම්
├── releases/                # නිකුතු සටහන්
├── routing/                 # ස්වයංක්රීය-සංයෝජන එන්ජිම, තර්කන නැවත ධාවනය
├── screenshots/             # උපකරණ පුවරු තිර රූ
├── security/                # ආරක්ෂණ සීමා, අනුකූලතාව, රහස්යභාවය, ටෝකන
└── specs/                   # සැලසුම් පිරිවිතර
```

---

## නව සපයන්නෙකු එක් කිරීම

### පියවර 1: සපයන්නාගේ නියත ලියාපදිංචි කරන්න

`src/shared/constants/providers.ts` වෙත එක් කරන්න — මොඩියුලය පූරණය වන විට Zod මඟින් වලංගු කෙරේ.

### පියවර 2: ක්රියාත්මක කරන්නෙකු එක් කරන්න (අභිරුචි තර්කනය අවශ්ය නම්)

මූලික ක්රියාත්මක කරන්නා විස්තාරණය කරමින් `open-sse/executors/your-provider.ts` තුළ ක්රියාත්මක කරන්නෙකු සාදන්න.

### පියවර 3: පරිවර්තකයෙකු එක් කරන්න (OpenAI නොවන ආකෘතියක් නම්)

`open-sse/translator/` තුළ ඉල්ලීම්/ප්රතිචාර පරිවර්තක සාදන්න.

### පියවර 4: OAuth වින්යාසය එක් කරන්න (OAuth-පාදක නම්)

`src/lib/oauth/constants/oauth.ts` තුළ OAuth අක්තපත්ර සහ `src/lib/oauth/services/` තුළ සේවාව එක් කරන්න.

ඉහළ මට්ටමේ සපයන්නා එහි පොදු CLI / බ්රවුසර බණ්ඩලය තුළ පොදු OAuth client_id/secret එකක් හෝ Firebase Web API යතුරක් බෙදා හරින්නේ නම්, එය තන්තු ලිටරලයක් ලෙස කේතයට **ඇතුළත් නොකරන්න**. `open-sse/utils/publicCreds.ts` වෙතින් `resolvePublicCred()` භාවිත කර `EMBEDDED_DEFAULTS` වෙත ආවරණය කළ බයිට් ප්රවේශයක් එක් කරන්න. සම්පූර්ණ අනිවාර්ය කාර්ය ප්රවාහය [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md) තුළ ලේඛනගත කර ඇත.

හසුරුවන්නන්/ක්රියාත්මක කරන්නන් තුළ, සේවාලාභියා වෙත ළඟා වන දෝෂ පණිවිඩ `open-sse/utils/error.ts` වෙතින් වන `buildErrorBody()` / `sanitizeErrorMessage()` හරහා යැවිය යුතුය — අමු `err.stack` හෝ `err.message` කිසිවිටෙක Response බොඩියක නොතබන්න. [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md) බලන්න.

### පියවර 5: ආකෘති ලියාපදිංචි කරන්න

`open-sse/config/providerRegistry.ts` තුළ ආකෘති නිර්වචන එක් කරන්න.

### පියවර 6: පරීක්ෂණ එක් කරන්න

අවම වශයෙන් පහත දෑ ආවරණය වන පරිදි `tests/unit/` තුළ ඒකක පරීක්ෂණ ලියන්න:

- සපයන්නා ලියාපදිංචි කිරීම
- ඉල්ලීම්/ප්රතිචාර පරිවර්තනය
- දෝෂ හැසිරවීම

---

## Pull Request පිරික්සුම් ලැයිස්තුව

- [ ] පරීක්ෂණ සමත් වේ (`npm test`)
- [ ] Linting සමත් වේ (`npm run lint`)
- [ ] Build කිරීම සාර්ථක වේ (`npm run build`)
- [ ] නව public functions සහ interfaces සඳහා TypeScript types එක් කර ඇත
- [ ] Hardcode කළ secrets හෝ fallback values නොමැත
- [ ] Public upstream credentials, literals ලෙස නොව `resolvePublicCred()` හරහා embed කර ඇත ([`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md) බලන්න)
- [ ] Error responses, `buildErrorBody()` / `sanitizeErrorMessage()` හරහා යොමු වේ — response bodies තුළ raw stack traces නොමැත ([`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md) බලන්න)
- [ ] Shell commands (`exec` / `spawn`), string interpolation හරහා නොව `env` හරහා runtime values ලබා දෙයි
- [ ] සියලු inputs, Zod schemas සමඟ validate කර ඇත
- [ ] පරිශීලකයාට පෙනෙන වෙනස්කම් සඳහා `changelog.d/{features|fixes|maintenance}/<PR>-<slug>.md` යටතේ Changelog **fragment** එකක් එක් කර ඇත ([`changelog.d/README.md`](./changelog.d/README.md) බලන්න) — `CHANGELOG.md` සෘජුව සංස්කරණය **නොකරන්න**; release අවස්ථාවේදී fragments එකතු කෙරෙන අතර PR අතර කිසිවිටෙක ගැටුම් ඇති නොවේ
- [ ] Documentation යාවත්කාලීන කර ඇත (අදාළ නම්)
- [ ] නව CodeQL / Secret-Scanning alerts කිසිවක් විවෘත කර නැත, නැතහොත් අදාළ `docs/security/` ලේඛනය සඳහන් කරන තාක්ෂණික සාධාරණීකරණයක් සමඟ ඒ සෑම එකක්ම ඉවත දමා ඇත
- [ ] Child processes ආරම්භ කරන routes (`/api/mcp/`, `/api/cli-tools/runtime/`), `src/server/authz/routeGuard.ts` තුළ `isLocalOnlyPath()` ලෙස වර්ගීකරණය කර ඇත — [දැඩි රීතිය #15](docs/security/ROUTE_GUARD_TIERS.md) බලන්න
- [ ] Commit messages තුළ AI/bot `Co-authored-by` trailers නොමැත (දැඩි රීතිය #16) — නැවත භාවිත කරන ලද කාර්යයේ මානව සහයෝගිතාකරුවන්ට සම්මත `Co-authored-by: Name <email>` trailers මඟින් ගෞරවය ලබා දී ඇත

---

## නිකුත් කිරීම්

නිකුත් කිරීම් `/generate-release` කාර්ය ප්රවාහය හරහා කළමනාකරණය කෙරේ. නව GitHub Release එකක් නිර්මාණය කළ විට, පැකේජය GitHub Actions හරහා **ස්වයංක්රීයව npm වෙත ප්රකාශයට පත් කෙරේ**.

VPS යෙදවීම් සඳහා, `npm run build` වෙනුවට `npm run build:release` භාවිත කරන්න — එය පිරිසිදු
නැවත ගොඩනැගීමක් සිදු කර, බණ්ඩලය `dist/` තුළ සකස් කර, `dist/BUILD_SHA` සෙන්ටිනලය ලියයි.
ඉන්පසු `dist/` දුරස්ථ `app/` නාමාවලියට rsync කරන `/deploy-vps-*-cc` කුසලතා භාවිත කරන්න.

---

## උපකාර ලබා ගැනීම

- **ගෘහ නිර්මාණ ශිල්පය**: [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) බලන්න
- **API යොමුව**: [`docs/reference/API_REFERENCE.md`](docs/reference/API_REFERENCE.md) බලන්න
- **ආරක්ෂක ලේඛන**: [`docs/security/CLI_TOKEN.md`](docs/security/CLI_TOKEN.md), [`docs/security/ROUTE_GUARD_TIERS.md`](docs/security/ROUTE_GUARD_TIERS.md), [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md), [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md)
- **මෙහෙයුම් ලේඛන**: [`docs/ops/SQLITE_RUNTIME.md`](docs/ops/SQLITE_RUNTIME.md)
- **ගැටලු**: [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)