Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
431 lines (320 loc) · 38.8 KB

CONTRIBUTING.md

File metadata and controls

431 lines (320 loc) · 38.8 KB
Raw

Contributing to OmniRoute (ਪੰਜਾਬੀ)

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

ਯੋਗਦਾਨ ਪਾਉਣ ਵਿੱਚ ਤੁਹਾਡੀ ਦਿਲਚਸਪੀ ਲਈ ਧੰਨਵਾਦ! ਇਸ ਗਾਈਡ ਵਿੱਚ ਸ਼ੁਰੂਆਤ ਕਰਨ ਲਈ ਲੋੜੀਂਦੀ ਹਰ ਚੀਜ਼ ਸ਼ਾਮਲ ਹੈ।

ਹਰ ਤਬਦੀਲੀ ਲਈ ਅਧਿਕਾਰਤ ਵਰਕਫ਼ਲੋ ਵਾਸਤੇ, ਯੋਗਦਾਨ ਗੋਲਡਨ ਪਾਥ ਤੋਂ ਸ਼ੁਰੂ ਕਰੋ। ਇਹ ਪ੍ਰੋਵਾਈਡਰ, ਰਾਊਟਿੰਗ, UI/UX, i18n, CLI, ਡੇਟਾਬੇਸ ਅਤੇ ਬਿਲਡ/ਡਿਪਲੌਇ ਤਬਦੀਲੀਆਂ ਨੂੰ ਉਹਨਾਂ ਦੇ ਕੌਂਟ੍ਰੈਕਟਾਂ, ਕੇਂਦਰਿਤ ਟੈਸਟਾਂ, CI ਕਵਰੇਜ ਅਤੇ ਰੀਕਨਸਿਲੀਏਸ਼ਨ ਕਦਮਾਂ ਨਾਲ ਮੈਪ ਕਰਦਾ ਹੈ।

ਡਿਵੈਲਪਮੈਂਟ ਸੈੱਟਅੱਪ

ਪੂਰਵ-ਲੋੜਾਂ

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

npm v11+ ਵਰਤੋਂਕਾਰ (Node 24+): npm install ਤੋਂ ਬਾਅਦ ਪੁਸ਼ਟੀ ਕਰੋ ਕਿ ਨੇਟਿਵ ਮੌਡਿਊਲ ਇੰਸਟਾਲ ਹੋਏ ਹਨ: node -e "require('better-sqlite3')". ਜੇ ਇਹ MODULE_NOT_FOUND ਨਾਲ ਅਸਫਲ ਹੁੰਦਾ ਹੈ, ਤਾਂ npm approve-scripts better-sqlite3 && npm install ਚਲਾਓ। ਵੇਖੋ ਸਮੱਸਿਆ-ਨਿਵਾਰਣ।

  • Git

ਕਲੋਨ ਅਤੇ ਇੰਸਟਾਲ ਕਰੋ

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

ਇਨਵਾਇਰਨਮੈਂਟ ਵੇਰੀਏਬਲ

# ਟੈਂਪਲੇਟ ਤੋਂ ਆਪਣੀ .env ਫ਼ਾਈਲ ਬਣਾਓ
cp .env.example .env

# ਲੋੜੀਂਦੇ ਸੀਕ੍ਰੇਟ ਬਣਾਓ
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 ਸਾਈਨਿੰਗ ਸੀਕ੍ਰੇਟ
INITIAL_PASSWORD CHANGEME ਪਹਿਲੇ ਲੌਗਇਨ ਦਾ ਪਾਸਵਰਡ
APP_LOG_LEVEL info ਲੌਗ ਵੇਰਵੇ ਦਾ ਪੱਧਰ

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

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

ਸੈਟਿੰਗ ਦਾ ਸਥਾਨ ਟੌਗਲ ਵੇਰਵਾ
ਸੈਟਿੰਗਾਂ → ਉੱਨਤ ਡੀਬੱਗ ਮੋਡ ਡੀਬੱਗ ਰਿਕਵੈਸਟ ਲੌਗ ਸਮਰੱਥ ਕਰੋ (UI)
ਸੈਟਿੰਗਾਂ → ਆਮ ਸਾਈਡਬਾਰ ਦਿੱਖ ਸਾਈਡਬਾਰ ਭਾਗ ਦਿਖਾਓ/ਲੁਕਾਓ

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

ਲੋਕਲ ਤੌਰ 'ਤੇ ਚਲਾਉਣਾ

# ਡਿਵੈਲਪਮੈਂਟ ਮੋਡ (ਹੌਟ ਰੀਲੋਡ)
npm run dev

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

# ਯੋਗਦਾਨਕਰਤਾ ਤਬਦੀਲੀਆਂ ਲਈ ਤੇਜ਼ ਕੇਵਲ-ਬੈਕਐਂਡ/API ਕੰਪਾਇਲ
npm run build:contributor

# ਰਿਲੀਜ਼ ਬਿਲਡ (ਸਾਫ਼ ਰੀਬਿਲਡ + HEAD ਸੈਂਟੀਨਲ — ਡਿਪਲੌਇ ਲਈ ਲਾਜ਼ਮੀ)
npm run build:release   # rm -rf .build dist && build + dist/BUILD_SHA ਲਿਖਦਾ ਹੈ

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

ਯੋਗਦਾਨਕਰਤਾ ਬਿਲਡ ਸਿਰਫ਼ ਕੰਪਾਇਲ ਪ੍ਰਮਾਣਿਕਤਾ ਕਰਦਾ ਹੈ: ਇਹ ਸਟੈਂਡਅਲੋਨ ਡਿਸਟ੍ਰੀਬਿਊਸ਼ਨ ਨੂੰ ਅਸੈਂਬਲ ਨਹੀਂ ਕਰਦਾ ਜਾਂ ਵਿਕਲਪਿਕ ਨੇਟਿਵ ਪੈਕੇਜਿੰਗ ਐਸੈੱਟ ਨਹੀਂ ਬਣਾਉਂਦਾ। ਜਦੋਂ ਤੁਹਾਨੂੰ ਭੇਜੇ ਜਾਣ ਯੋਗ ਬੰਡਲ ਦੀ ਪ੍ਰਮਾਣਿਕਤਾ ਕਰਨ ਦੀ ਲੋੜ ਹੋਵੇ, ਤਾਂ ਨਿਯਮਤ ਪ੍ਰੋਡਕਸ਼ਨ ਬਿਲਡ ਵਰਤੋ।

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

ਡਾਇਰੈਕਟਰੀ ਸਮੱਗਰੀ ਟ੍ਰੈਕ ਕੀਤੀ ਗਈ
src/ ਐਪਲੀਕੇਸ਼ਨ ਸਰੋਤ (TypeScript / TSX) ਹਾਂ
.build/ ਵਿਚਕਾਰਲੇ ਨਤੀਜੇ — next build ਆਉਟਪੁੱਟ (gitignored, distDir = .build/next) ਨਹੀਂ
dist/ ਭੇਜੇ ਜਾਣ ਯੋਗ ਬੰਡਲ — assembleStandalone ਦੁਆਰਾ ਅਸੈਂਬਲ ਕੀਤਾ ਗਿਆ (gitignored) ਨਹੀਂ

ਬਿਲਡ ਪਾਈਪਲਾਈਨ ਇੱਕੋ ਪਾਸ ਵਿੱਚ ਚੱਲਦੀ ਹੈ:

npm run build
  └─ next build → .build/next/standalone  (Next.js ਆਉਟਪੁੱਟ)
  └─ assembleStandalone()                 (ਸਟੈਂਡਅਲੋਨ + ਸਟੈਟਿਕ + ਪਬਲਿਕ + ਨੇਟਿਵ ਐਸੈੱਟ ਕਾਪੀ ਕਰਦਾ ਹੈ)
       └─ ਆਉਟਪੁੱਟ: dist/                   (server.js, .next/static/, public/, node_modules/)

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

npm run build:contributor ਕੇਵਲ-ਬੈਕਐਂਡ ਬਿਲਡ ਪ੍ਰੋਫ਼ਾਈਲ ਵਰਤਦਾ ਹੈ। ਬਿਲਡ ਕਰਦੇ ਸਮੇਂ ਇਹ ਅਸਥਾਈ ਤੌਰ 'ਤੇ ਡੈਸ਼ਬੋਰਡ UI ਫ਼ਾਈਲਾਂ ਨੂੰ ਸਟੱਬ ਕਰਦਾ ਹੈ, API ਰੂਟ ਹੈਂਡਲਰਾਂ ਨੂੰ ਬਰਕਰਾਰ ਰੱਖਦਾ ਹੈ ਅਤੇ ਬਿਲਡ ਤੋਂ ਬਾਅਦ ਮੂਲ ਫ਼ਾਈਲਾਂ ਮੁੜ-ਬਹਾਲ ਕਰਦਾ ਹੈ। ਡੈਸ਼ਬੋਰਡ UI ਨੂੰ ਪ੍ਰਭਾਵਿਤ ਕਰਨ ਵਾਲੀਆਂ ਤਬਦੀਲੀਆਂ ਜਾਂ ਪੂਰੀ ਰਿਲੀਜ਼ ਪ੍ਰਮਾਣਿਕਤਾ ਲਈ npm run build ਵਰਤੋ; ਯੋਗਦਾਨਕਰਤਾ ਪ੍ਰੋਫ਼ਾਈਲ ਰਿਲੀਜ਼ ਬਿਲਡ ਦਾ ਬਦਲ ਨਹੀਂ ਹੈ।

VPS ਡਿਪਲੌਇ ਨੋਟ: ਰਿਮੋਟ ਇਮੇਜ ਡਾਇਰੈਕਟਰੀ /usr/lib/node_modules/omniroute/app/ ਵਿੱਚ ਕੋਈ ਤਬਦੀਲੀ ਨਹੀਂ ਹੈ। ਡਿਪਲੌਇ ਸਕਿੱਲਜ਼ dist/ ਦੀ ਸਮੱਗਰੀ ਨੂੰ ਇਸ ਵਿੱਚ rsync ਕਰਦੀਆਂ ਹਨ। ਸਿਰਫ਼ ਰਿਪੋਜ਼ਟਰੀ ਅੰਦਰਲਾ ਬਿਲਡ ਆਉਟਪੁੱਟ ਪਾਥ ਬਦਲਿਆ ਹੈ (app/ → dist/)।

ਡਿਫ਼ਾਲਟ URL:

  • ਡੈਸ਼ਬੋਰਡ: http://localhost:20128/dashboard
  • API: http://localhost:20128/v1

Git ਵਰਕਫ਼ਲੋ

⚠️ ਕਦੇ ਵੀ ਸਿੱਧਾ main ਵਿੱਚ ਕਮਿਟ ਨਾ ਕਰੋ। ਹਮੇਸ਼ਾ ਫੀਚਰ ਬ੍ਰਾਂਚਾਂ ਦੀ ਵਰਤੋਂ ਕਰੋ।

PR ਬੇਸ: ਸਰਗਰਮ release/vX.Y.Z ਬ੍ਰਾਂਚ ਨੂੰ ਟਾਰਗੇਟ ਕਰੋ (main ਨੂੰ ਨਹੀਂ)। ਹਰ ਬ੍ਰਾਂਚ ਲਈ ਰਿਲੀਜ਼ + ਸ਼ਿਪ ਕਰਨ ਵੇਲੇ ਟੈਗ ਵਾਲੇ ਮਾਡਲ ਲਈ docs/ops/BRANCHING_MODEL.md ਵੇਖੋ।

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

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।

ਟੈਸਟ ਚਲਾਉਣਾ

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

  • ਉਹ ਟੈਸਟ ਫ਼ਾਈਲਾਂ ਚਲਾਓ ਜੋ ਤੁਹਾਡੀ ਤਬਦੀਲੀ ਨੂੰ ਕਵਰ ਕਰਦੀਆਂ ਹਨ: node --import tsx/esm --test tests/unit/<file>.test.ts
  • npm run lint ਚਲਾਓ
  • ਜਦੋਂ ਵੀ ਪ੍ਰੋਡਕਸ਼ਨ ਕੋਡ ਬਦਲਦਾ ਹੈ, ਉਸੇ PR ਵਿੱਚ ਆਟੋਮੇਟਡ ਟੈਸਟ ਸ਼ਾਮਲ ਜਾਂ ਅੱਪਡੇਟ ਕਰੋ
  • ਜਦੋਂ ਪ੍ਰੋਡਕਸ਼ਨ ਕੋਡ ਬਦਲਿਆ ਹੋਵੇ, ਤਾਂ 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 ਸਟ੍ਰੀਮਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਨੂੰ ਕਦੇ ਵੀ ਚੁੱਪਚਾਪ ਨਾ ਨਿਗਲੋ" ਨੂੰ ਅਮਲ ਵਿੱਚ ਲਿਆਉਂਦਾ ਹੈ):

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

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

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

    } 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 ਐਪ ਰਾਊਟਰ
│   ├── (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 ਸਕੋਪ, 19 ਰਾਊਟਿੰਗ ਰਣਨੀਤੀਆਂ
│   ├── utils/              # ਸਰਕਟ ਬ੍ਰੇਕਰ, ਸੈਨਿਟਾਈਜ਼ਰ, ਪ੍ਰਮਾਣੀਕਰਨ ਸਹਾਇਕ
│   └── validation/         # Zod v4 ਸਕੀਮਾਂ
└── sse/                    # SSE ਪ੍ਰੌਕਸੀ ਪਾਈਪਲਾਈਨ

open-sse/                   # @omniroute/open-sse ਵਰਕਸਪੇਸ
├── executors/              # 89 ਐਗਜ਼ੀਕਿਊਟਰ ਲਾਗੂਕਰਨ ਮੋਡੀਊਲ
├── 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 ਹਵਾਲਾ, env vars, 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 ਵਿੱਚ ਦਸਤਾਵੇਜ਼ਬੱਧ ਹੈ।

ਹੈਂਡਲਰਾਂ/ਐਗਜ਼ਿਕਿਊਟਰਾਂ ਦੇ ਅੰਦਰ, ਕਲਾਇੰਟ ਤੱਕ ਪਹੁੰਚਣ ਵਾਲੇ ਤਰੁੱਟੀ ਸੁਨੇਹੇ open-sse/utils/error.ts ਤੋਂ buildErrorBody() / sanitizeErrorMessage() ਰਾਹੀਂ ਜਾਣੇ ਲਾਜ਼ਮੀ ਹਨ — ਕਿਸੇ Response ਬਾਡੀ ਵਿੱਚ ਕਦੇ ਵੀ ਕੱਚਾ err.stack ਜਾਂ err.message ਨਾ ਪਾਓ। 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 ਵੇਖੋ), ਕਦੇ ਵੀ ਲਿਟਰਲ ਵਜੋਂ ਨਹੀਂ
  • ਤਰੁੱਟੀ ਜਵਾਬ buildErrorBody() / sanitizeErrorMessage() ਰਾਹੀਂ ਜਾਂਦੇ ਹਨ — ਜਵਾਬ ਬਾਡੀਆਂ ਵਿੱਚ ਕੋਈ ਕੱਚਾ ਸਟੈਕ ਟਰੇਸ ਨਹੀਂ (docs/security/ERROR_SANITIZATION.md ਵੇਖੋ)
  • ਸ਼ੈੱਲ ਕਮਾਂਡਾਂ (exec / spawn) ਰਨਟਾਈਮ ਮੁੱਲਾਂ ਨੂੰ ਸਟਰਿੰਗ ਇੰਟਰਪੋਲੇਸ਼ਨ ਰਾਹੀਂ ਨਹੀਂ, ਸਗੋਂ env ਰਾਹੀਂ ਪਾਸ ਕਰਦੀਆਂ ਹਨ
  • ਸਾਰੇ ਇਨਪੁੱਟ Zod ਸਕੀਮਿਆਂ ਨਾਲ ਪ੍ਰਮਾਣਿਤ ਕੀਤੇ ਗਏ ਹਨ
  • ਉਪਭੋਗਤਾ-ਸਾਹਮਣੇ ਵਾਲੀਆਂ ਤਬਦੀਲੀਆਂ ਲਈ changelog.d/{features|fixes|maintenance}/<PR>-<slug>.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 ਵੇਖੋ
  • ਕਮਿਟ ਸੁਨੇਹਿਆਂ ਵਿੱਚ ਕੋਈ Co-Authored-By ਟ੍ਰੇਲਰ ਨਹੀਂ — ਕਮਿਟ ਸਿਰਫ਼ ਰਿਪੋਜ਼ਟਰੀ ਮਾਲਕ ਦੀ Git ਪਛਾਣ ਹੇਠ ਦਿਖਾਈ ਦੇਣੇ ਚਾਹੀਦੇ ਹਨ (ਸਖ਼ਤ ਨਿਯਮ #16)

ਰਿਲੀਜ਼ ਕਰਨਾ

ਰਿਲੀਜ਼ਾਂ ਦਾ ਪ੍ਰਬੰਧਨ /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 ਕਰਦੀਆਂ ਹਨ।

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