# 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) · 🇵🇭 [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) · 🇱🇰 [si](../si/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) ਤੋਂ ਸ਼ੁਰੂ ਕਰੋ। ਇਹ ਪ੍ਰੋਵਾਈਡਰ, ਰਾਊਟਿੰਗ,
UI/UX, i18n, CLI, ਡੇਟਾਬੇਸ ਅਤੇ ਬਿਲਡ/ਡਿਪਲੌਇ ਤਬਦੀਲੀਆਂ ਨੂੰ ਉਹਨਾਂ ਦੇ ਕੌਂਟ੍ਰੈਕਟਾਂ, ਕੇਂਦਰਿਤ ਟੈਸਟਾਂ, CI
ਕਵਰੇਜ ਅਤੇ ਰੀਕਨਸਿਲੀਏਸ਼ਨ ਕਦਮਾਂ ਨਾਲ ਮੈਪ ਕਰਦਾ ਹੈ।

---

## ਵਿਕਾਸ ਸੈਟਅੱਪ

### ਪੂਰਵ-ਲੋੜਾਂ

- **Node.js** `>=22.22.2 <23`, ਜਾਂ `>=24.0.0 <27` (ਸਿਫ਼ਾਰਸ਼ੀ: 24 LTS)
- **npm** 10+

> **Node 24 ਨਾਲ Windows:** ਮੌਜੂਦਾ 24 LTS ਪੈਚ ਰਿਲੀਜ਼ (ਘੱਟੋ-ਘੱਟ 24.20.0) ਵਰਤੋ।
> ਪਹਿਲੀਆਂ ਰਿਲੀਜ਼ਾਂ ਸਫਲ ਟੈਸਟਾਂ ਤੋਂ ਬਾਅਦ `--test-force-exit` ਪ੍ਰਕਿਰਿਆ ਬੰਦ ਕਰਨ ਵੇਲੇ
> ਅਬੋਰਟ ਹੋ ਸਕਦੀਆਂ ਹਨ। Node ਦਾ [Windows libuv fix](https://github.com/nodejs/node/pull/61999) ਇਸ
> ਰਨਟਾਈਮ ਕ੍ਰੈਸ਼ ਨੂੰ ਠੀਕ ਕਰਦਾ ਹੈ; ਟੈਸਟ 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` ਚਲਾਓ। ਵੇਖੋ
> [Troubleshooting](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`                  | ਸਰਵਰ ਪੋਰਟ             |
| `NEXT_PUBLIC_BASE_URL` | `http://localhost:20128` | ਫਰੰਟਐਂਡ ਲਈ ਬੇਸ URL    |
| `JWT_SECRET`           | (ਉੱਪਰ ਤਿਆਰ ਕਰੋ)          | JWT ਸਾਈਨਿੰਗ secret    |
| `INITIAL_PASSWORD`     | `CHANGEME`               | ਪਹਿਲੇ ਲੌਗਇਨ ਦਾ ਪਾਸਵਰਡ |
| `APP_LOG_LEVEL`        | `info`                   | ਲੌਗ ਵੇਰਵੇ ਦਾ ਪੱਧਰ     |

### ਡੈਸ਼ਬੋਰਡ ਸੈਟਿੰਗਾਂ

ਡੈਸ਼ਬੋਰਡ ਉਹਨਾਂ ਫੀਚਰਾਂ ਲਈ UI ਟੌਗਲ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ ਜਿਨ੍ਹਾਂ ਨੂੰ ਵਾਤਾਵਰਣ ਵੈਰੀਏਬਲਾਂ ਰਾਹੀਂ ਵੀ ਕੌਂਫਿਗਰ ਕੀਤਾ ਜਾ ਸਕਦਾ ਹੈ:

| ਸੈਟਿੰਗ ਟਿਕਾਣਾ       | ਟੌਗਲ               | ਵੇਰਵਾ                           |
| ------------------- | ------------------ | ------------------------------- |
| Settings → Advanced | Debug Mode         | ਡੀਬੱਗ ਰਿਕਵੈਸਟ ਲੌਗ ਚਾਲੂ ਕਰੋ (UI) |
| Settings → General  | Sidebar Visibility | ਸਾਈਡਬਾਰ ਸੈਕਸ਼ਨ ਦਿਖਾਓ/ਲੁਕਾਓ      |

ਇਹ ਸੈਟਿੰਗਾਂ ਡਾਟਾਬੇਸ ਵਿੱਚ ਸਟੋਰ ਹੁੰਦੀਆਂ ਹਨ ਅਤੇ ਰੀਸਟਾਰਟ ਤੋਂ ਬਾਅਦ ਵੀ ਕਾਇਮ ਰਹਿੰਦੀਆਂ ਹਨ। ਸੈਟ ਕੀਤੇ ਜਾਣ ’ਤੇ ਇਹ env var ਡਿਫ਼ਾਲਟਾਂ ਨੂੰ ਓਵਰਰਾਈਡ ਕਰਦੀਆਂ ਹਨ।

### ਲੋਕਲ ਤੌਰ ’ਤੇ ਚਲਾਉਣਾ

```bash
# ਵਿਕਾਸ ਮੋਡ (hot reload)
npm run dev

# ਪ੍ਰੋਡਕਸ਼ਨ ਬਿਲਡ
npm run build    # next build → .build/next/ ਫਿਰ assembleStandalone → dist/
npm run start

# ਯੋਗਦਾਨਕਰਤਾਵਾਂ ਦੇ ਬਦਲਾਵਾਂ ਲਈ ਤੇਜ਼ backend/API-only compile
npm run build:contributor

# ਰਿਲੀਜ਼ ਬਿਲਡ (ਸਾਫ਼ rebuild + HEAD sentinel — deploy ਲਈ ਲੋੜੀਂਦਾ)
npm run build:release   # rm -rf .build dist ਅਤੇ build + dist/BUILD_SHA ਲਿਖਦਾ ਹੈ

# ਆਮ ਪੋਰਟ ਕੌਂਫਿਗਰੇਸ਼ਨ
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
```

ਯੋਗਦਾਨਕਰਤਾ ਬਿਲਡ ਸਿਰਫ਼ compile-only validation ਕਰਦਾ ਹੈ: ਇਹ standalone
distribution ਨੂੰ assemble ਨਹੀਂ ਕਰਦਾ ਅਤੇ optional native packaging assets ਵੀ build ਨਹੀਂ ਕਰਦਾ। ਜਦੋਂ ਤੁਹਾਨੂੰ
shippable bundle ਦੀ ਜਾਂਚ ਕਰਨੀ ਹੋਵੇ, ਤਾਂ ਆਮ ਪ੍ਰੋਡਕਸ਼ਨ ਬਿਲਡ ਵਰਤੋ।

### ਬਿਲਡ ਆਉਟਪੁੱਟ ਲੇਆਉਟ

| ਡਾਇਰੈਕਟਰੀ | ਸਮੱਗਰੀ                                                                      | ਟ੍ਰੈਕ ਕੀਤੀ |
| --------- | --------------------------------------------------------------------------- | ---------- |
| `src/`    | ਐਪਲੀਕੇਸ਼ਨ ਸਰੋਤ (TypeScript / TSX)                                           | ਹਾਂ        |
| `.build/` | ਵਿਚਕਾਰਲੇ ਨਤੀਜੇ — `next build` ਆਉਟਪੁੱਟ (gitignored, `distDir = .build/next`) | ਨਹੀਂ       |
| `dist/`   | Shippable bundle — `assembleStandalone` ਦੁਆਰਾ assembled (gitignored)        | ਨਹੀਂ       |

ਬਿਲਡ ਪਾਈਪਲਾਈਨ ਇੱਕੋ pass ਹੈ:

```
npm run build
  └─ next build → .build/next/standalone  (Next.js ਆਉਟਪੁੱਟ)
  └─ assembleStandalone()                 (standalone + static + public + native assets ਕਾਪੀ ਕਰਦਾ ਹੈ)
       └─ output: dist/                   (server.js, .next/static/, public/, node_modules/)
```

`npm run build:release` ਪਹਿਲਾਂ ਦੋਵੇਂ ਡਾਇਰੈਕਟਰੀਆਂ ਨੂੰ ਵੀ ਸਾਫ਼ ਕਰਦਾ ਹੈ ਅਤੇ
`dist/BUILD_SHA` (= `git rev-parse --short HEAD`) ਨੂੰ deploy integrity sentinel ਵਜੋਂ ਲਿਖਦਾ ਹੈ।

`npm run build:contributor` backend-only build profile ਵਰਤਦਾ ਹੈ। ਇਹ build ਦੇ ਦੌਰਾਨ
dashboard UI files ਨੂੰ ਅਸਥਾਈ ਤੌਰ ’ਤੇ stub ਕਰਦਾ ਹੈ, API route handlers ਨੂੰ ਕਾਇਮ ਰੱਖਦਾ ਹੈ,
ਅਤੇ build ਤੋਂ ਬਾਅਦ ਅਸਲ files ਨੂੰ ਮੁੜ ਬਹਾਲ ਕਰਦਾ ਹੈ। ਡੈਸ਼ਬੋਰਡ UI ’ਤੇ ਅਸਰ ਪਾਉਣ ਵਾਲੇ ਬਦਲਾਵਾਂ ਜਾਂ ਪੂਰੀ
release validation ਲਈ `npm run build` ਵਰਤੋ; contributor profile release build ਦਾ ਬਦਲ ਨਹੀਂ ਹੈ।

> **VPS deploy ਨੋਟ:** ਰਿਮੋਟ image directory `/usr/lib/node_modules/omniroute/app/`
> ਵਿੱਚ ਕੋਈ ਬਦਲਾਅ ਨਹੀਂ ਹੁੰਦਾ। deploy skills `dist/` ਦੀ ਸਮੱਗਰੀ ਨੂੰ ਇਸ ਵਿੱਚ rsync ਕਰਦੀਆਂ ਹਨ।
> ਸਿਰਫ਼ ਰਿਪੋਜ਼ਟਰੀ ਅੰਦਰਲਾ build output path ਬਦਲਿਆ ਹੈ (`app/` → `dist/`)।

ਡਿਫ਼ਾਲਟ URLs:

- **ਡੈਸ਼ਬੋਰਡ**: `http://localhost:20128/dashboard`
- **API**: `http://localhost:20128/v1`

---

## Git ਵਰਕਫ਼ਲੋ

> ⚠️ **ਕਦੇ ਵੀ ਸਿੱਧਾ `main` ਵਿੱਚ ਕਮਿਟ ਨਾ ਕਰੋ।** ਹਮੇਸ਼ਾ ਫੀਚਰ ਬ੍ਰਾਂਚਾਂ ਦੀ ਵਰਤੋਂ ਕਰੋ।
>
> **PR ਬੇਸ:** ਸਰਗਰਮ `release/vX.Y.Z` ਬ੍ਰਾਂਚ ਨੂੰ ਟਾਰਗੇਟ ਕਰੋ (`main` ਨੂੰ ਨਹੀਂ)। ਹਰ ਬ੍ਰਾਂਚ ਲਈ ਰਿਲੀਜ਼ + ਸ਼ਿਪ ਕਰਨ ਵੇਲੇ ਟੈਗ ਵਾਲੇ ਮਾਡਲ ਲਈ
> [`docs/ops/BRANCHING_MODEL.md`](docs/ops/BRANCHING_MODEL.md) ਵੇਖੋ।

```bash
# ਸਰਗਰਮ ਰਿਲੀਜ਼ ਟਿਪ ਤੋਂ ਬ੍ਰਾਂਚ ਬਣਾਓ (ਉਦਾਹਰਨ: 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 ਨਾਲ ਇੱਕ ਪੁੱਲ ਰਿਕਵੇਸਟ ਖੋਲ੍ਹੋ
```

### ਬ੍ਰਾਂਚ ਨਾਮਕਰਨ

| ਪ੍ਰੀਫਿਕਸ    | ਉਦੇਸ਼                  |
| ----------- | ---------------------- |
| `feat/`     | ਨਵੀਆਂ ਵਿਸ਼ੇਸ਼ਤਾਵਾਂ     |
| `fix/`      | ਬੱਗ ਸੁਧਾਰ              |
| `refactor/` | ਕੋਡ ਦੀ ਮੁੜ-ਸੰਰਚਨਾ      |
| `docs/`     | ਦਸਤਾਵੇਜ਼ੀ ਤਬਦੀਲੀਆਂ     |
| `test/`     | ਟੈਸਟ ਜੋੜਨਾ/ਸੁਧਾਰਨਾ     |
| `chore/`    | ਟੂਲਿੰਗ, CI, ਨਿਰਭਰਤਾਵਾਂ |

### ਕਮਿਟ ਸੁਨੇਹੇ

[Conventional Commits](https://www.conventionalcommits.org/) ਦੀ ਪਾਲਣਾ ਕਰੋ:

```
feat: add circuit breaker for provider calls
fix: resolve JWT secret validation edge case
docs: update SECURITY.md with PII protection
test: add observability unit tests
refactor(db): consolidate rate limit tables
```

ਸਕੋਪ (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            # ਆਖਰੀ ਕਮਿਟ ਵਿੱਚ ਤਬਦੀਲੀਆਂ (ਜਾਂ ਵਰਕਿੰਗ ਟ੍ਰੀ ਵਿੱਚ)
npm run test:scoped:staged     # ਸਿਰਫ਼ ਸਟੇਜ ਕੀਤੀਆਂ ਤਬਦੀਲੀਆਂ — ਪ੍ਰੀ-ਕਮਿਟ ਰਨ ਨਾਲ ਚੰਗੀ ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਦਾ ਹੈ
npm run test:scoped:full       # ਪਹਿਲਾਂ ਇੰਪੋਰਟ-ਗ੍ਰਾਫ ਮੈਪ ਮੁੜ ਬਣਾਓ (ਫ਼ਾਈਲਾਂ ਜੋੜਨ/ਮੂਵ ਕਰਨ ਤੋਂ ਬਾਅਦ)
# Exit 1 + "ਪੂਰਾ ਸੂਟ ਚਲਾਓ" ਦਾ ਮਤਲਬ ਹੈ ਕਿ ਕੋਈ ਹੱਬ ਫ਼ਾਈਲ (tsconfig, package.json, …) ਜਾਂ ਕੋਈ
# ਬਿਨਾਂ ਮੈਪ ਕੀਤਾ ਸਰੋਤ ਬਦਲਿਆ ਹੈ — ਚੋਣਕਾਰ ਸੁਰੱਖਿਅਤ ਢੰਗ ਨਾਲ ਅਸਫਲ ਹੁੰਦਾ ਹੈ, ਇਹ ਕਦੇ ਵੀ ਚੁੱਪਚਾਪ ਟੈਸਟ ਨਹੀਂ ਛੱਡਦਾ।

# Vitest (MCP ਸਰਵਰ, autoCombo, ਕੈਸ਼)
npm run test:vitest

# E2E ਟੈਸਟ (Playwright ਦੀ ਲੋੜ ਹੈ)
npm run test:e2e

# ਪ੍ਰੋਟੋਕੋਲ ਕਲਾਇੰਟ E2E (MCP ਟ੍ਰਾਂਸਪੋਰਟ, A2A)
npm run test:protocols:e2e

# ਇਕੋਸਿਸਟਮ ਅਨੁਕੂਲਤਾ ਟੈਸਟ
npm run test:ecosystem

# ਕਵਰੇਜ ਗੇਟ: ਸਟੇਟਮੈਂਟਾਂ/ਲਾਈਨਾਂ/ਫੰਕਸ਼ਨਾਂ/ਬ੍ਰਾਂਚਾਂ ਲਈ 60%
npm run test:coverage
npm run coverage:report

# ਲਿੰਟ + ਫਾਰਮੈਟ ਜਾਂਚ
npm run lint
npm run check

# ਗੇਟ ਕੀਤਾ ਅਸਲੀ-ਅੱਪਸਟ੍ਰੀਮ ਕਾਂਬੋ ਸਮੋਕ ਟੈਸਟ (VPS ਪਹੁੰਚ + ਅਸਲੀ ਪ੍ਰਦਾਤਾ ਕ੍ਰੈਡਿਟਾਂ ਦੀ ਲੋੜ ਹੈ)
# ਅਸਲੀ ਪ੍ਰਦਾਤਿਆਂ ਨੂੰ ਵਰਤਦਾ ਹੈ — ਥੋੜ੍ਹਾ ਖਰਚਾ ਹੁੰਦਾ ਹੈ। CI ਵਿੱਚ ਕਦੇ ਨਹੀਂ ਚੱਲਦਾ। ਗੇਟ ਤੋਂ ਬਿਨਾਂ ਸਾਫ਼-ਸੁਥਰੇ ਢੰਗ ਨਾਲ ਛੱਡ ਦਿੱਤਾ ਜਾਂਦਾ ਹੈ।
# ਲੋੜ: ssh root@192.168.0.15 ਪਹੁੰਚ (VPS ਤੋਂ ਸਿਰਫ਼-ਪੜ੍ਹਨਯੋਗ DB ਸਨੈਪਸ਼ਾਟ ਸਰੋਤ ਵਜੋਂ ਵਰਤਦਾ ਹੈ)।
RUN_COMBO_LIVE=1 npm run test:combo:live

# ਫੇਜ਼-3 VPS ਲਾਈਵ ਸਮੋਕ — ਸਧਾਰਨ Node ESM ਸਕ੍ਰਿਪਟਾਂ, ਲਾਈਵ .15 ਸਰਵਰ ਨੂੰ ਸਿੱਧਾ ਵਰਤਦੀਆਂ ਹਨ।
# ਲੋੜ: ssh root@192.168.0.15 ਪਹੁੰਚ (ਕਾਂਬੋ SSH sqlite ਰਾਹੀਂ ਬਣਾਏ/ਹਟਾਏ ਜਾਂਦੇ ਹਨ)।
# ਅਸਲੀ ਪ੍ਰਦਾਤਿਆਂ ਨੂੰ ਵਰਤਦਾ ਹੈ (ਥੋੜ੍ਹਾ ਖਰਚਾ)। ਸਿਰਫ਼ __live_test__* ਕਾਂਬੋ ਬਣਾਉਂਦਾ/ਮਿਟਾਉਂਦਾ ਹੈ। CI ਵਿੱਚ ਕਦੇ ਨਹੀਂ ਚੱਲਦਾ।
# .15 ਉੱਤੇ REQUIRE_API_KEY=false ਹੈ, ਇਸ ਲਈ API ਕੁੰਜੀ ਦੀ ਲੋੜ ਨਹੀਂ, ਪਰ ਜੇ COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY ਸੈੱਟ ਹੋਣ ਤਾਂ ਉਨ੍ਹਾਂ ਦੀ ਪਾਲਣਾ ਕਰਦਾ ਹੈ।
npm run test:combo:live:vps              # 7 HTTP ਦ੍ਰਿਸ਼ (ਤਰਜੀਹ/ਰਾਊਂਡ-ਰੌਬਿਨ/ਭਾਰਿਤ/ਲਾਗਤ/ਫਿਊਜ਼ਨ/ਆਟੋ + ਸਿਹਤ)
npm run test:combo:live:vps:failover     # ਇੱਕ ਅਸਲੀ ਕਰਾਸ-ਪ੍ਰਦਾਤਾ ਫੇਲਓਵਰ ਦ੍ਰਿਸ਼ ਜੋੜਦਾ ਹੈ (ਕੁੱਲ 8)
```

ਕਵਰੇਜ ਨੋਟ:

- `npm run test:coverage` ਮੁੱਖ ਯੂਨਿਟ ਟੈਸਟ ਸੂਟ ਲਈ ਸਰੋਤ ਕਵਰੇਜ ਮਾਪਦਾ ਹੈ, `tests/**` ਨੂੰ ਬਾਹਰ ਰੱਖਦਾ ਹੈ ਅਤੇ `open-sse/**` ਨੂੰ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ
- ਪੁੱਲ ਰਿਕਵੈਸਟਾਂ ਲਈ ਸਟੇਟਮੈਂਟਾਂ/ਲਾਈਨਾਂ/ਫੰਕਸ਼ਨਾਂ/ਬ੍ਰਾਂਚਾਂ ਦਾ ਕਵਰੇਜ ਗੇਟ **60%+** ਉੱਤੇ ਕਾਇਮ ਰਹਿਣਾ ਲਾਜ਼ਮੀ ਹੈ
- ਜੇ ਕੋਈ PR `src/`, `open-sse/`, `electron/`, ਜਾਂ `bin/` ਵਿੱਚ ਪ੍ਰੋਡਕਸ਼ਨ ਕੋਡ ਬਦਲਦਾ ਹੈ, ਤਾਂ ਉਸੇ PR ਵਿੱਚ ਆਟੋਮੇਟਡ ਟੈਸਟ ਜੋੜਨੇ ਜਾਂ ਅੱਪਡੇਟ ਕਰਨੇ ਲਾਜ਼ਮੀ ਹਨ
- `npm run coverage:report` ਤਾਜ਼ਾ ਕਵਰੇਜ ਰਨ ਤੋਂ ਵਿਸਤ੍ਰਿਤ ਫ਼ਾਈਲ-ਦਰ-ਫ਼ਾਈਲ ਰਿਪੋਰਟ ਪ੍ਰਿੰਟ ਕਰਦਾ ਹੈ
- `npm run test:coverage:legacy` ਇਤਿਹਾਸਕ ਤੁਲਨਾ ਲਈ ਪੁਰਾਣੇ ਮੈਟ੍ਰਿਕ ਨੂੰ ਸੰਭਾਲ ਕੇ ਰੱਖਦਾ ਹੈ
- ਪੜਾਅਵਾਰ ਕਵਰੇਜ ਸੁਧਾਰ ਰੋਡਮੈਪ ਲਈ `docs/ops/COVERAGE_PLAN.md` ਵੇਖੋ

### ਪੁੱਲ ਰਿਕਵੈਸਟ ਦੀਆਂ ਲੋੜਾਂ

PR ਖੋਲ੍ਹਣ ਤੋਂ ਪਹਿਲਾਂ, ਆਪਣੀਆਂ ਤਬਦੀਲੀਆਂ ਲਈ ਕੇਂਦ੍ਰਿਤ ਚੱਕਰ ਚਲਾਉਣ ਵਾਸਤੇ
[ਯੋਗਦਾਨ ਗੋਲਡਨ ਪਾਥ](docs/ops/CONTRIBUTION_GOLDEN_PATH.md) ਦੀ ਵਰਤੋਂ ਕਰੋ।
ਪੂਰਾ ਯੂਨਿਟ ਸੂਟ (4 CI ਸ਼ਾਰਡ), Vitest, **60%+** ਕਵਰੇਜ ਗੇਟ ਅਤੇ
ਪ੍ਰੋਡਕਸ਼ਨ ਬਿਲਡ CI ਦੀ ਜ਼ਿੰਮੇਵਾਰੀ ਹਨ — ਇਨ੍ਹਾਂ ਨੂੰ ਸਥਾਨਕ ਤੌਰ 'ਤੇ ਚਲਾਉਣ ਨਾਲ ਅਜਿਹਾ ਕੋਈ ਵਾਧੂ ਸੰਕੇਤ ਨਹੀਂ ਮਿਲਦਾ ਜੋ PR
ਜਾਂਚਾਂ ਤੁਹਾਨੂੰ ਪਹਿਲਾਂ ਹੀ ਨਾ ਦੇਣ, ਅਤੇ ਛੋਟੀਆਂ ਮਸ਼ੀਨਾਂ ਉੱਤੇ ਇਹ ਹੋਸਟ ਨੂੰ ਪੂਰੀ ਤਰ੍ਹਾਂ ਵਿਅਸਤ ਕਰ ਸਕਦਾ ਹੈ (#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 ਯੂਨਿਟ ਟੈਸਟ ਫ਼ਾਈਲਾਂ**, ਜੋ ਇਹਨਾਂ ਨੂੰ ਕਵਰ ਕਰਦੀਆਂ ਹਨ:

- ਪ੍ਰਦਾਤਾ ਅਨੁਵਾਦਕ ਅਤੇ ਫਾਰਮੈਟ ਰੂਪਾਂਤਰਨ
- ਰੇਟ ਸੀਮਿਤ ਕਰਨਾ, ਸਰਕਿਟ ਬ੍ਰੇਕਰ ਅਤੇ ਲਚੀਲਾਪਣ
- ਸਿਮੈਂਟਿਕ ਕੈਸ਼, ਆਈਡੈਂਪੋਟੈਂਸੀ ਅਤੇ ਪ੍ਰਗਤੀ ਟ੍ਰੈਕਿੰਗ
- ਡਾਟਾਬੇਸ ਕਾਰਵਾਈਆਂ ਅਤੇ ਸਕੀਮਾ (21 DB ਮੋਡੀਊਲ)
- OAuth ਫ਼ਲੋ ਅਤੇ ਪ੍ਰਮਾਣੀਕਰਨ
- API ਐਂਡਪੌਇੰਟ ਪ੍ਰਮਾਣੀਕਰਨ (Zod v4)
- MCP ਸਰਵਰ ਟੂਲ ਅਤੇ ਸਕੋਪ ਲਾਗੂਕਰਨ
- ਮੈਮੋਰੀ ਅਤੇ ਸਕਿਲਜ਼ ਸਿਸਟਮ

---

## ਕੋਡ ਸ਼ੈਲੀ

- **ESLint** — ਕਮਿਟ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ `npm run lint` ਚਲਾਓ
- **Prettier** — ਕਮਿਟ ਵੇਲੇ `lint-staged` ਰਾਹੀਂ ਸਵੈਚਲਿਤ ਤੌਰ 'ਤੇ ਫਾਰਮੈਟ ਕੀਤਾ ਜਾਂਦਾ ਹੈ (2 ਸਪੇਸਾਂ, ਸੈਮੀਕੋਲਨ, ਦੋਹਰੇ ਹਵਾਲਾ-ਚਿੰਨ੍ਹ, 100 ਅੱਖਰ ਚੌੜਾਈ, es5 ਟ੍ਰੇਲਿੰਗ ਕਾਮੇ)
- **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 ਸਕੀਮਾਂ ਵਰਤੋ
- **ਨਾਮਕਰਨ**: ਫ਼ਾਈਲਾਂ = camelCase/kebab-case, ਕੰਪੋਨੈਂਟ = PascalCase, ਕਾਂਸਟੈਂਟ = UPPER_SNAKE

### ਗਲਤੀ ਸੰਭਾਲਣਾ / ਖਾਲੀ catch ਬਲਾਕ

ਕਿਸੇ ਵੀ `catch` ਨੂੰ ਬਿਨਾਂ ਵਿਆਖਿਆ ਦੇ ਕਦੇ ਨਾ ਛੱਡੋ। ਇਸਨੂੰ ਹੇਠ ਲਿਖੀਆਂ ਦੋ ਸ਼੍ਰੇਣੀਆਂ ਵਿੱਚੋਂ ਇੱਕ ਵਿੱਚ ਵਰਗੀਕ੍ਰਿਤ ਕਰੋ (ਇਹ ਸਖ਼ਤ ਨਿਯਮ "SSE ਸਟ੍ਰੀਮਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਨੂੰ ਕਦੇ ਵੀ ਚੁੱਪਚਾਪ ਨਾ ਨਿਗਲੋ" ਨੂੰ ਅਮਲ ਵਿੱਚ ਲਿਆਉਂਦਾ ਹੈ):

- **ਜਾਣਬੁੱਝ ਕੇ (ਸਾਡੀ ਆਪਣੀ ਸਰਵੋਤਮ-ਯਤਨ ਸਫ਼ਾਈ/ਟੈਲੀਮੈਟਰੀ)** — ਇੱਥੇ ਅਸਫਲਤਾ ਦੀ ਉਮੀਦ ਹੁੰਦੀ ਹੈ ਅਤੇ ਇਹ ਨੁਕਸਾਨ-ਰਹਿਤ ਹੈ; ਇੱਕ-ਲਾਈਨ ਦਾ ਤਰਕਸੰਗਤ ਕਮੈਂਟ ਸ਼ਾਮਲ ਕਰੋ, ਕੋਈ ਲੌਗਿੰਗ ਨਹੀਂ (ਹਰ ਬੇਨਤੀ 'ਤੇ ਲੌਗਿੰਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੇ ਸ਼ੋਰ ਤੋਂ ਇਹ ਰਵਾਇਤ ਬਚਾਉਂਦੀ ਹੈ)।

  ```ts
  } catch {} // ਕਲਾਇੰਟ ਦੇ ਡਿਸਕਨੈਕਟ ਹੋਣ ਤੋਂ ਬਾਅਦ ਪਹਿਲਾਂ ਹੀ ਬੰਦ ਕੰਟਰੋਲਰ ਨੂੰ ਬੰਦ ਕਰਨਾ ਉਮੀਦ ਅਨੁਸਾਰ ਹੈ
  ```

- **ਲੌਗ ਕਰਨਾ ਚਾਹੀਦਾ ਹੈ (ਬਾਹਰੀ/ਕਾਲਰ ਵੱਲੋਂ ਦਿੱਤਾ ਕੋਡ, ਜਾਂ ਜਿੱਥੇ ਗਲਤੀ ਨੂੰ ਨਿਗਲਣਾ ਕੰਟਰੋਲ ਫ਼ਲੋ ਬਦਲਦਾ ਹੈ)** — `catch` ਨੂੰ ਰੱਖੋ (ਇਸਨੂੰ ਕਦੇ ਵੀ ਸਟ੍ਰੀਮ ਤੋੜਨ ਨਾ ਦਿਓ), ਪਰ ਸੰਦਰਭ-ਸਹਿਤ `console.debug`/`warn` ਜਾਰੀ ਕਰੋ ਤਾਂ ਜੋ ਅਸਫਲਤਾ ਦਾ ਪਤਾ ਲਗਾਇਆ ਜਾ ਸਕੇ।

  ```ts
  } catch (e) {
    console.debug("[STREAM] onFailure ਕਾਲਬੈਕ ਗਲਤੀ:", 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()` ਰਾਹੀਂ ਜਾਣੇ ਲਾਜ਼ਮੀ ਹਨ — ਕਿਸੇ Response ਬਾਡੀ ਵਿੱਚ ਕਦੇ ਵੀ ਕੱਚਾ `err.stack` ਜਾਂ `err.message` ਨਾ ਪਾਓ। [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md) ਵੇਖੋ।

### ਕਦਮ 5: ਮਾਡਲ ਰਜਿਸਟਰ ਕਰੋ

`open-sse/config/providerRegistry.ts` ਵਿੱਚ ਮਾਡਲ ਪਰਿਭਾਸ਼ਾਵਾਂ ਸ਼ਾਮਲ ਕਰੋ।

### ਕਦਮ 6: ਟੈਸਟ ਸ਼ਾਮਲ ਕਰੋ

`tests/unit/` ਵਿੱਚ ਯੂਨਿਟ ਟੈਸਟ ਲਿਖੋ, ਜੋ ਘੱਟੋ-ਘੱਟ ਹੇਠਾਂ ਦਿੱਤਿਆਂ ਨੂੰ ਕਵਰ ਕਰਨ:

- ਪ੍ਰਦਾਤਾ ਰਜਿਸਟ੍ਰੇਸ਼ਨ
- ਬੇਨਤੀ/ਜਵਾਬ ਅਨੁਵਾਦ
- ਤਰੁੱਟੀ ਸੰਭਾਲ

---

## ਪੁੱਲ ਰਿਕਵੇਸਟ ਚੈੱਕਲਿਸਟ

- [ ] ਟੈਸਟ ਪਾਸ ਹੁੰਦੇ ਹਨ (`npm test`)
- [ ] ਲਿੰਟਿੰਗ ਪਾਸ ਹੁੰਦੀ ਹੈ (`npm run lint`)
- [ ] ਬਿਲਡ ਸਫਲ ਹੁੰਦਾ ਹੈ (`npm run build`)
- [ ] ਨਵੇਂ ਪਬਲਿਕ ਫੰਕਸ਼ਨਾਂ ਅਤੇ ਇੰਟਰਫੇਸਾਂ ਲਈ TypeScript ਟਾਈਪਾਂ ਜੋੜੀਆਂ ਗਈਆਂ ਹਨ
- [ ] ਕੋਈ ਹਾਰਡਕੋਡ ਕੀਤੇ ਸੀਕ੍ਰੇਟ ਜਾਂ ਫਾਲਬੈਕ ਮੁੱਲ ਨਹੀਂ ਹਨ
- [ ] ਪਬਲਿਕ ਅੱਪਸਟ੍ਰੀਮ ਕ੍ਰੈਡੈਂਸ਼ਲ `resolvePublicCred()` ਰਾਹੀਂ ਐਂਬੈੱਡ ਕੀਤੇ ਗਏ ਹਨ ([`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md) ਵੇਖੋ), ਕਦੇ ਵੀ ਲਿਟਰਲ ਵਜੋਂ ਨਹੀਂ
- [ ] ਗਲਤੀ ਜਵਾਬ `buildErrorBody()` / `sanitizeErrorMessage()` ਰਾਹੀਂ ਭੇਜੇ ਜਾਂਦੇ ਹਨ — ਜਵਾਬ ਬਾਡੀਆਂ ਵਿੱਚ ਕੋਈ ਕੱਚਾ ਸਟੈਕ ਟ੍ਰੇਸ ਨਹੀਂ ਹੈ ([`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md) ਵੇਖੋ)
- [ ] ਸ਼ੈੱਲ ਕਮਾਂਡਾਂ (`exec` / `spawn`) ਰਨਟਾਈਮ ਮੁੱਲ ਸਟ੍ਰਿੰਗ ਇੰਟਰਪੋਲੇਸ਼ਨ ਰਾਹੀਂ ਨਹੀਂ, ਸਗੋਂ `env` ਰਾਹੀਂ ਪਾਸ ਕਰਦੀਆਂ ਹਨ
- [ ] ਸਾਰੇ ਇਨਪੁੱਟ Zod ਸਕੀਮਿਆਂ ਨਾਲ ਪ੍ਰਮਾਣਿਤ ਕੀਤੇ ਗਏ ਹਨ
- [ ] ਵਰਤੋਂਕਾਰਾਂ ਨੂੰ ਪ੍ਰਭਾਵਿਤ ਕਰਨ ਵਾਲੀਆਂ ਤਬਦੀਲੀਆਂ ਲਈ `changelog.d/{features|fixes|maintenance}/<PR>-<slug>.md` ਅਧੀਨ ਚੇਂਜਲੌਗ **ਫ੍ਰੈਗਮੈਂਟ** ਜੋੜਿਆ ਗਿਆ ਹੈ ([`changelog.d/README.md`](./changelog.d/README.md) ਵੇਖੋ) — `CHANGELOG.md` ਨੂੰ ਸਿੱਧੇ ਤੌਰ 'ਤੇ ਸੰਪਾਦਿਤ **ਨਾ** ਕਰੋ; ਫ੍ਰੈਗਮੈਂਟ ਰਿਲੀਜ਼ ਸਮੇਂ ਇਕੱਠੇ ਕੀਤੇ ਜਾਂਦੇ ਹਨ ਅਤੇ PRs ਵਿਚਕਾਰ ਕਦੇ ਟਕਰਾਅ ਨਹੀਂ ਕਰਦੇ
- [ ] ਦਸਤਾਵੇਜ਼ ਅੱਪਡੇਟ ਕੀਤੇ ਗਏ ਹਨ (ਜੇ ਲਾਗੂ ਹੋਵੇ)
- [ ] ਕੋਈ ਨਵੀਂ CodeQL / Secret-Scanning ਚੇਤਾਵਨੀ ਨਹੀਂ ਖੋਲ੍ਹੀ ਗਈ, ਜਾਂ ਹਰ ਇੱਕ ਨੂੰ ਸੰਬੰਧਿਤ `docs/security/` ਦਸਤਾਵੇਜ਼ ਦਾ ਹਵਾਲਾ ਦਿੰਦੇ ਤਕਨੀਕੀ ਤਰਕ ਨਾਲ ਖਾਰਜ ਕੀਤਾ ਗਿਆ ਹੈ
- [ ] ਚਾਈਲਡ ਪ੍ਰੋਸੈਸ ਸ਼ੁਰੂ ਕਰਨ ਵਾਲੇ ਰੂਟ (`/api/mcp/`, `/api/cli-tools/runtime/`) `src/server/authz/routeGuard.ts` ਵਿੱਚ `isLocalOnlyPath()` ਵਜੋਂ ਵਰਗੀਕ੍ਰਿਤ ਕੀਤੇ ਗਏ ਹਨ — [ਸਖ਼ਤ ਨਿਯਮ #15](docs/security/ROUTE_GUARD_TIERS.md) ਵੇਖੋ
- [ ] ਕਮਿਟ ਸੁਨੇਹਿਆਂ ਵਿੱਚ ਕੋਈ AI/ਬੌਟ `Co-authored-by` ਟ੍ਰੇਲਰ ਨਹੀਂ ਹਨ (ਸਖ਼ਤ ਨਿਯਮ #16) — ਜਿਨ੍ਹਾਂ ਮਨੁੱਖੀ ਸਹਿਯੋਗੀਆਂ ਦੇ ਕੰਮ ਦੀ ਮੁੜ ਵਰਤੋਂ ਕੀਤੀ ਗਈ ਹੈ, ਉਨ੍ਹਾਂ ਨੂੰ ਮਿਆਰੀ `Co-authored-by: Name <email>` ਟ੍ਰੇਲਰਾਂ ਨਾਲ ਸਿਹਰਾ ਦਿੱਤਾ ਗਿਆ ਹੈ

---

## ਰਿਲੀਜ਼ ਕਰਨਾ

ਰਿਲੀਜ਼ਾਂ ਦਾ ਪ੍ਰਬੰਧਨ `/generate-release` ਵਰਕਫ਼ਲੋ ਰਾਹੀਂ ਕੀਤਾ ਜਾਂਦਾ ਹੈ। ਜਦੋਂ ਕੋਈ ਨਵੀਂ GitHub Release ਬਣਾਈ ਜਾਂਦੀ ਹੈ, ਤਾਂ GitHub Actions ਰਾਹੀਂ ਪੈਕੇਜ **ਆਪਣੇ-ਆਪ npm 'ਤੇ ਪ੍ਰਕਾਸ਼ਿਤ ਹੋ ਜਾਂਦਾ ਹੈ**।

VPS ਡਿਪਲੌਇਆਂ ਲਈ, `npm run build` ਦੀ ਬਜਾਏ `npm run build:release` ਵਰਤੋ — ਇਹ ਇੱਕ ਸਾਫ਼
ਰੀਬਿਲਡ ਕਰਦਾ ਹੈ, ਬੰਡਲ ਨੂੰ `dist/` ਵਿੱਚ ਤਿਆਰ ਕਰਦਾ ਹੈ, ਅਤੇ `dist/BUILD_SHA` ਸੈਂਟੀਨਲ ਲਿਖਦਾ ਹੈ।
ਫਿਰ `/deploy-vps-*-cc` ਸਕਿਲਾਂ ਦੀ ਵਰਤੋਂ ਕਰੋ, ਜੋ `dist/` ਨੂੰ ਰਿਮੋਟ `app/` ਡਾਇਰੈਕਟਰੀ ਨਾਲ rsync ਕਰਦੀਆਂ ਹਨ।

---

## ਮਦਦ ਪ੍ਰਾਪਤ ਕਰਨਾ

- **ਆਰਕੀਟੈਕਚਰ**: [`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)