OmniRoute/docs/i18n/gu/CLAUDE.md

# CLAUDE.md (ગુજરાતી)

🌐 **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) · 🇮🇱 [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)

---

આ ફાઇલ claude.ai/code સાથે કોડ પર કામ કરતી વખતે માર્ગદર્શન પ્રદાન કરે છે.

## ઝડપી શરૂઆત

```bash
npm install                    # deps સ્થાપિત કરો (.auto-generates .env from .env.example)
npm run dev                    # ડેવ સર્વર http://localhost:20128 પર
npm run build                  # ઉત્પાદન બિલ્ડ (Next.js 16 standalone)
npm run lint                   # ESLint (0 ભૂલો અપેક્ષિત; ચેતવણીઓ પૂર્વ-અસ્તિત્વમાં છે)
npm run typecheck:core         # TypeScript ચેક (સફળ હોવું જોઈએ)
npm run typecheck:noimplicit:core  # કડક ચેક (કોઈ પણ નમ્ર નથી)
npm run test:coverage          # યુનિટ પરીક્ષાઓ + કવરેજ ગેટ (75/75/75/70 — નિવેદનો/લાઇનો/ફંક્શન/શાખાઓ)
npm run check                  # lint + પરીક્ષા સંયુક્ત
npm run check:cycles           # વર્તુળની નિર્ભરતા શોધો
```

### પરીક્ષાઓ ચલાવવી

```bash
# એકલ પરીક્ષા ફાઇલ (Node.js નેટિવ પરીક્ષા રનર — સૌથી વધુ પરીક્ષાઓ)
node --import tsx/esm --test tests/unit/your-file.test.ts

# Vitest (MCP સર્વર, autoCombo, કેશ)
npm run test:vitest

# તમામ સૂટ
npm run test:all
```

પૂર્ણ પરીક્ષા મેટ્રિક્સ માટે, `CONTRIBUTING.md` → "પરીક્ષાઓ ચલાવવી" જુઓ. ઊંડા આર્કિટેક્ચર માટે, `AGENTS.md` જુઓ.

---

## પ્રોજેક્ટ એક નજરમાં

**OmniRoute** — એકીકૃત AI પ્રોક્સી/રાઉટર. એક એન્ડપોઈન્ટ, 160+ LLM પ્રદાતાઓ, ઓટો-ફોલબેક.

| સ્તર          | સ્થાન                   | ઉદ્દેશ્ય                                                        |
| ------------- | ----------------------- | --------------------------------------------------------------- |
| API Routes    | `src/app/api/v1/`       | Next.js એપ્લિકેશન રાઉટર — પ્રવેશ બિંદુઓ                         |
| Handlers      | `open-sse/handlers/`    | વિનંતી પ્રક્રિયા (ચેટ, એમ્બેડિંગ્સ, વગેરે)                      |
| Executors     | `open-sse/executors/`   | પ્રદાતા-વિશિષ્ટ HTTP વિતરણ                                      |
| Translators   | `open-sse/translator/`  | ફોર્મેટ રૂપાંતરણ (OpenAI↔Claude↔Gemini)                         |
| Transformer   | `open-sse/transformer/` | પ્રતિસાદ API ↔ ચેટ પૂર્ણતાઓ                                     |
| Services      | `open-sse/services/`    | કોમ્બો રાઉટિંગ, દર મર્યાદાઓ, કેશિંગ, વગેરે                      |
| Database      | `src/lib/db/`           | SQLite ડોમેન મોડ્યુલ (45+ ફાઇલો, 55 માઇગ્રેશન)                  |
| Domain/Policy | `src/domain/`           | નીતિ એન્જિન, ખર્ચના નિયમો, ફોલબેક લોજિક                         |
| MCP Server    | `open-sse/mcp-server/`  | 37 સાધનો (30 આધાર + 3 મેમરી + 4 કુશળતાઓ), 3 પરિવહન, ~13 સ્કોપ્સ |
| A2A Server    | `src/lib/a2a/`          | JSON-RPC 2.0 એજન્ટ પ્રોટોકોલ                                    |
| Skills        | `src/lib/skills/`       | વિસ્તરણશીલ કુશળતા ફ્રેમવર્ક                                     |
| Memory        | `src/lib/memory/`       | સતત સંવાદ મેમરી                                                 |

મોનોરેપો: `src/` (Next.js 16 એપ્લિકેશન), `open-sse/` (સ્ટ્રીમિંગ એન્જિન કાર્યસ્થળ), `electron/` (ડેસ્કટોપ એપ્લિકેશન), `tests/`, `bin/` (CLI પ્રવેશ બિંદુ).

## વિનંતી પાઇપલાઇન

```
Client → /v1/chat/completions (Next.js માર્ગ)
  → CORS → Zod માન્યતા → auth? → નીતિ ચકાસણી → પ્રોમ્પ્ટ ઇન્જેક્શન ગાર્ડ
  → handleChatCore() [open-sse/handlers/chatCore.ts]
    → કેશ ચકાસણી → દર મર્યાદા → કોમ્બો રૂટિંગ?
      → resolveComboTargets() → handleSingleModel() પ્રતિ લક્ષ્ય
    → translateRequest() → getExecutor() → executor.execute()
      → fetch() upstream → retry w/ backoff
    → પ્રતિસાદ અનુવાદ → SSE સ્ટ્રીમ અથવા JSON
    → જો Responses API: responsesTransformer.ts TransformStream
```

API માર્ગો એક સંગ્રહિત પેટર્નનું પાલન કરે છે: `Route → CORS preflight → Zod body validation → વૈકલ્પિક auth (extractApiKey/isValidApiKey) → API કી નીતિ અમલ → Handler delegation (open-sse)` . કોઈ વૈશ્વિક Next.js માધ્યમ નથી — અવરોધન માર્ગ-વિશિષ્ટ છે.

**કોમ્બો રૂટિંગ** (`open-sse/services/combo.ts`): 14 વ્યૂહો (પ્રાથમિકતા, વજનદાર, ફીલ-ફર્સ્ટ, રાઉન્ડ-રોબિન, P2C, રેન્ડમ, ઓછા-વપરાયેલી, ખર્ચ-ઓપ્ટિમાઇઝ્ડ, રીસેટ-જાણકાર, કડક-રેન્ડમ, ઓટો, lkgp, સંદર્ભ-ઓપ્ટિમાઇઝ્ડ, સંદર્ભ-રિલે). દરેક લક્ષ્ય `handleSingleModel()` ને કૉલ કરે છે જે `handleChatCore()` ને પ્રતિ-લક્ષ્ય ભૂલ હેન્ડલિંગ અને સર્કિટ બ્રેકર ચકાસણીઓ સાથે લપેટે છે. 9-ફેક્ટ ઓટો-કોમ્બો સ્કોરિંગ માટે `docs/routing/AUTO-COMBO.md` જુઓ અને 3 રેસિલિયન્સ સ્તરો માટે `docs/architecture/RESILIENCE_GUIDE.md` જુઓ.

---

## રેસિલિયન્સ રનટાઇમ સ્ટેટ

OmniRoute પાસે ત્રણ સંબંધિત પરંતુ અલગ તાત્કાલિક-અસફળતા મિકેનિઝમ છે. રૂટિંગ વર્તન ડિબગ કરતી વખતે તેમના વ્યાપને અલગ રાખો. એક નજરમાં નકશો માટે [3-સ્તરીય રેસિલિયન્સ આકૃતિ](./docs/diagrams/exported/resilience-3layers.svg) જુઓ (સ્ત્રોત: [docs/diagrams/resilience-3layers.mmd](./docs/diagrams/resilience-3layers.mmd)).

### પ્રદાતા સર્કિટ બ્રેકર

**વ્યાપ**: સમગ્ર પ્રદાતા, ઉદાહરણ તરીકે `glm`, `openai`, `anthropic`.

**ઉદ્દેશ**: એક પ્રદાતા તરફ ટ્રાફિક મોકલવાનું રોકવું જે વારંવાર upstream/service સ્તરે નિષ્ફળ થઈ રહ્યું છે, જેથી એક અસ્વસ્થ પ્રદાતા દરેક વિનંતીને ધીમું ન કરે.

**અમલ**:

- કોર વર્ગ: `src/shared/utils/circuitBreaker.ts`
- ચેટ ગેટ/કાર્યકારી વાયરિંગ: `src/sse/handlers/chatHelpers.ts`, `src/sse/handlers/chat.ts`
- રનટાઇમ સ્થિતિ API: `src/app/api/monitoring/health/route.ts`
- શેર કરેલ રેપર્સ: `open-sse/services/accountFallback.ts`
- પર્સિસ્ટેડ સ્ટેટ ટેબલ: `domain_circuit_breakers`

**સ્થિતિઓ**:

- `CLOSED`: સામાન્ય ટ્રાફિકની મંજૂરી છે.
- `OPEN`: પ્રદાતા તાત્કાલિક બ્લોક કરવામાં આવ્યો છે; કૉલર્સને પ્રદાતા-સર્કિટ-ઓપન પ્રતિસાદ મળે છે અથવા કોમ્બો રૂટિંગ બીજા લક્ષ્ય પર જતી રહે છે.
- `HALF_OPEN`: રીસેટ ટાઇમઆઉટ પસાર થઈ ગયો છે; એક પ્રોબ વિનંતીની મંજૂરી આપો. સફળતા બ્રેકર બંધ કરે છે, નિષ્ફળતા તેને ફરીથી ખોલે છે.

**ડિફોલ્ટ્સ** (`open-sse/config/constants.ts`):

- OAuth પ્રદાતા: થ્રેશોલ્ડ `3`, રીસેટ ટાઇમઆઉટ `60s`.
- API-કી પ્રદાતા: થ્રેશોલ્ડ `5`, રીસેટ ટાઇમઆઉટ `30s`.
- સ્થાનિક પ્રદાતા: થ્રેશોલ્ડ `2`, રીસેટ ટાઇમઆઉટ `15s`.

ફક્ત પ્રદાતા-સ્તરીય નિષ્ફળતા સ્થિતિઓ જ પ્રદાતા બ્રેકરને ટ્રિપ કરવી જોઈએ:

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

સામાન્ય ખાતા/કી/મોડલ ભૂલો જેવી કે મોટાભાગની `401`, `403`, અથવા `429` કેસો માટે સમગ્ર-પ્રદાતા બ્રેકર ટ્રિપ ન કરો. તે સામાન્ય રીતે કનેક્શન કૂલડાઉન અથવા મોડલ લોકઆઉટમાં આવે છે. એક સામાન્ય API-કી પ્રદાતા `403` પુનઃપ્રાપ્ય હોવું જોઈએ જો તે ટર્મિનલ પ્રદાતા/ખાતાની ભૂલ તરીકે વર્ગીકૃત ન કરવામાં આવે.

બ્રેકર આલસ્ય પુનઃપ્રાપ્તિનો ઉપયોગ કરે છે, પૃષ્ઠભૂમિ ટાઇમર નથી. જ્યારે `OPEN` સમાપ્ત થાય છે, ત્યારે `getStatus()`, `canExecute()`, અને `getRetryAfterMs()` જેવી વાંચનોએ રાજ્યને `HALF_OPEN` માં રિફ્રેશ કરે છે, જેથી ડેશબોર્ડ અને કોમ્બો ઉમેદવાર બિલ્ડર્સ એક સમાપ્ત પ્રદાતા ને સદાય માટે બહાર ન રાખે.

### કનેક્શન કૂલડાઉન

**વ્યાપ**: એક પ્રદાતા કનેક્શન/ખાતું/કી.

**ઉદ્દેશ**: એક ખરાબ કી/ખાતાને તાત્કાલિક છોડી દેવું જ્યારે સમાન પ્રદાતા માટે અન્ય કનેક્શનને વિનંતીઓ સેવા આપવા માટે ચાલુ રહેવા દેવું.

**અમલ**:

- લખવા/અપડેટ પાથ: `src/sse/services/auth.ts::markAccountUnavailable()`
- ખાતા પસંદગી/ફિલ્ટરિંગ: `src/sse/services/auth.ts::getProviderCredentials...`
- કૂલડાઉન ગણતરી: `open-sse/services/accountFallback.ts::checkFallbackError()`
- સેટિંગ્સ: `src/lib/resilience/settings.ts`

પ્રદાતા કનેક્શનો પર મહત્વપૂર્ણ ક્ષેત્રો:

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

ખાતા પસંદગી દરમિયાન, એક કનેક્શન છોડી દેવામાં આવે છે જ્યારે:

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

કૂલડાઉન પણ આલસ્ય છે: જ્યારે `rateLimitedUntil` ભૂતકાળમાં હોય છે, ત્યારે કનેક્શન ફરીથી યોગ્ય બની જાય છે. સફળ ઉપયોગ પર, `clearAccountError()` `testStatus`, `rateLimitedUntil`, ભૂલ ક્ષેત્રો, અને `backoffLevel`ને સાફ કરે છે.

ડિફોલ્ટ કનેક્શન કૂલડાઉન વર્તન:

- OAuth આધાર કૂલડાઉન: `5s`.
- API-કી આધાર કૂલડાઉન: `3s`.
- API-કી `429` ઉપલબ્ધ હોય ત્યારે upstream પુનઃપ્રાપ્તિ સૂચનો (`Retry-After`, રીસેટ હેડર્સ, અથવા પાર્સેબલ રીસેટ ટેક્સ્ટ) પસંદ કરવું જોઈએ.
- પુનરાવર્તિત પુનઃપ્રાપ્ય નિષ્ફળતાઓ એક્સપોનેન્શિયલ બેકઓફનો ઉપયોગ કરે છે:

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

એન્ટી-થન્ડરિંગ-હર્ડ ગાર્ડ સમાન કનેક્શન પર સમાન નિષ્ફળતાઓને પુનરાવર્તિત રીતે કૂલડાઉન વધારવા અથવા `backoffLevel`ને ડબલ-ઇન્ક્રિમેન્ટ કરવા રોકે છે.

ટર્મિનલ સ્થિતિઓ કૂલડાઉન નથી. `banned`, `expired`, અને `credits_exhausted`ને પ્રમાણપત્રો/સેટિંગ્સ બદલાય ત્યાં સુધી ઉપલબ્ધ રહેવું જોઈએ અથવા એક ઓપરેટર તેમને ફરીથી સેટ કરે છે. ટર્મિનલ સ્થિતિઓને તાત્કાલિક કૂલડાઉન સ્થિતિ સાથેOverwrite ન કરો.

### મોડલ લોકઆઉટ

**વ્યાપ**: પ્રદાતા + કનેક્શન + મોડલ.

**ઉદ્દેશ**: જ્યારે માત્ર એક મોડલ ઉપલબ્ધ નથી અથવા તે ક્વોટા-મર્યાદિત છે ત્યારે સમગ્ર કનેક્શનને બંધ કરવાનું ટાળવું.

ઉદાહરણો:

- પ્રતિ-મોડલ ક્વોટા પ્રદાતા `429` પાછા આપે છે.
- સ્થાનિક પ્રદાતા એક ગુમ થયેલ મોડલ માટે `404` પાછા આપે છે.
- પ્રદાતા-વિશિષ્ટ મોડ/મોડલ પરવાનગીની નિષ્ફળતાઓ જેમ કે પસંદ કરેલ ગ્રોક મોડ્સ.

મોડલ લોકઆઉટ `open-sse/services/accountFallback.ts` માં રહે છે અને સમાન કનેક્શનને અન્ય મોડલ સેવા આપવા દે છે.

### ડિબગિંગ માર્ગદર્શન

- જો પ્રદાતા માટે તમામ કી છોડી દેવામાં આવે છે, તો પ્રદાતા બ્રેકર સ્થિતિ અને દરેક કનેક્શનના `rateLimitedUntil`/`testStatus`ને તપાસો.
- જો એક પ્રદાતા પુનઃસેટ વિન્ડો પછી કાયમીExcluded લાગે છે, તો તપાસો કે શું કોડ કાચા `state`ને વાંચી રહ્યું છે તેના બદલે `getStatus()`/`canExecute()` નો ઉપયોગ કરી રહ્યું છે.
- જો એક પ્રદાતા કી નિષ્ફળ જાય પરંતુ અન્ય કાર્ય કરવા જોઈએ, તો પ્રદાતા બ્રેકર કરતાં કનેક્શન કૂલડાઉનને પસંદ કરો.
- જો માત્ર એક મોડલ નિષ્ફળ જાય, તો કનેક્શન કૂલડાઉન કરતાં મોડલ લોકઆઉટને પસંદ કરો.
- જો એક રાજ્ય સ્વયં-પુનઃપ્રાપ્તિ કરવું જોઈએ, તો તેમાં ભવિષ્યની ટાઇમસ્ટેમ્પ/રીસેટ ટાઇમઆઉટ અને એક વાંચન પાથ હોવો જોઈએ જે સમાપ્ત રાજ્યને રિફ્રેશ કરે. કાયમી સ્થિતિઓ માટે મેન્યુઅલ પ્રમાણપત્ર અથવા કન્ફિગ ફેરફારોની જરૂર છે.

## મુખ્ય પરંપરાઓ

### કોડ શૈલી

- **2 જગ્યા**, સેમિકોલન, ડબલ કોટ્સ, 100 અક્ષર પહોળાઈ, es5 ટ્રેઇલિંગ કોમ્મા (lint-staged દ્વારા Prettier દ્વારા અમલમાં)
- **આયાતો**: બાહ્ય → આંતરિક (`@/`, `@omniroute/open-sse`) → સંબંધિત
- **નામકરણ**: ફાઇલો=camelCase/kebab, ઘટકો=PascalCase, સ્થિરતા=UPPER_SNAKE
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = દરેક જગ્યાએ ભૂલ; `no-explicit-any` = `open-sse/` અને `tests/` માં ચેતવણી
- **TypeScript**: `strict: false`, લક્ષ્ય ES2022, મોડ્યુલ esnext, રિઝોલ્યુશન bundler. સ્પષ્ટ પ્રકારોને પ્રાથમિકતા આપો.

### ડેટાબેસ

- **હંમેશા** `src/lib/db/` ડોમેન મોડ્યુલ્સ દ્વારા જાઓ — **ક્યારેય** રૂા SQL રાઉટ્સ અથવા હેન્ડલર્સમાં ન લખો
- **ક્યારેય** `src/lib/localDb.ts` માં લોજિક ઉમેરશો નહીં (ફક્ત પુનઃ-નિકાસ સ્તર)
- **ક્યારેય** `localDb.ts` માં બેરલ-આયાત ન કરો — તેના બદલે ચોક્કસ `db/` મોડ્યુલ્સ આયાત કરો
- DB સિંગલટન: `getDbInstance()` `src/lib/db/core.ts` માંથી (WAL જર્નલિંગ)
- માઇગ્રેશન: `src/lib/db/migrations/` — સંસ્કરણવાળા SQL ફાઇલો, આઇડેમ્પોટન્ટ, ટ્રાન્ઝેક્શનમાં ચલાવો

### ભૂલ સંભાળવું

- ચોક્કસ ભૂલ પ્રકારો સાથે try/catch, pino સંદર્ભ સાથે લોગ કરો
- SSE સ્ટ્રીમમાં ભૂલો ક્યારેય ન છુપાવો — સફાઈ માટે abort સંકેતોનો ઉપયોગ કરો
- યોગ્ય HTTP સ્થિતિ કોડ્સ પરત કરો (4xx/5xx)

### સુરક્ષા

- **ક્યારેય** `eval()`, `new Function()`, અથવા IMPLIED eval નો ઉપયોગ ન કરો
- Zod સ્કીમા સાથે તમામ ઇનપુટને માન્ય બનાવો
- આરામ પર ક્રેડેંશિયલ્સને એન્ક્રિપ્ટ કરો (AES-256-GCM)
- અપસ્ટ્રીમ હેડર ડિનાયલિસ્ટ: `src/shared/constants/upstreamHeaders.ts` — સંપાદન કરતી વખતે સાફ, Zod સ્કીમા, અને યુનિટ ટેસ્ટને સમન્વયિત રાખો
- **જાહેર અપસ્ટ્રીમ ક્રેડેંશિયલ્સ** (Gemini/Antigravity/Windsurf-શૈલી OAuth client_id/secret + Firebase વેબ કી જાહેર CLIsમાંથી કાઢી લેવામાં આવી): **જરૂરી** છે `resolvePublicCred()` દ્વારા એમ્બેડ કરવું `open-sse/utils/publicCreds.ts` માં — **ક્યારેય** સ્ટ્રિંગ લિટરલ તરીકે નહીં. ફરજિયાત પેટર્ન માટે `docs/security/PUBLIC_CREDS.md` જુઓ.
- **ભૂલ પ્રતિસાદ** (HTTP / SSE / executor / MCP હેન્ડલર): **જરૂરી** છે `buildErrorBody()` અથવા `sanitizeErrorMessage()` દ્વારા માર્ગદર્શન આપવું `open-sse/utils/error.ts` માં — **ક્યારેય** કાચા `err.stack` અથવા `err.message` ને પ્રતિસાદના શરીરમાં ન મૂકો. `docs/security/ERROR_SANITIZATION.md` જુઓ.
- **ચલનશીલ કમાન્ડ્સ જે ચર સાથે બનાવવામાં આવે છે**: જ્યારે `exec()`/`spawn()` ને સ્ક્રિપ્ટ સાથે કૉલ કરો જે રનટાઇમ મૂલ્યોની જરૂર છે, ત્યારે તેમને `env` વિકલ્પ દ્વારા પસાર કરો (સ્વચાલિત રીતે શેલ-એસ્કેપ્ડ) — **ક્યારેય** વિશ્વાસ ન કરાતા/બાહ્ય પાથને સ્ક્રિપ્ટના શરીરમાં સ્ટ્રિંગ-ઇન્ટરપોલેટ ન કરો. સંદર્ભ: `src/mitm/cert/install.ts::updateNssDatabases`.
- **સુરક્ષિત-દ્વારા-ડિફોલ્ટ લાઇબ્રેરીઝ** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): નવા સુરક્ષા-સંવેદનશીલ સપાટી ઉમેરતી વખતે કસ્ટમ અમલના બદલે Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tinkને પ્રાથમિકતા આપો.

---

## સામાન્ય ફેરફાર પરિસ્થિતિઓ

### નવા પ્રદાતા ઉમેરવો

1. `src/shared/constants/providers.ts` માં નોંધણી કરો (લોડ પર Zod-માન્ય)
2. જો કસ્ટમ લોજિકની જરૂર હોય તો `open-sse/executors/` માં એક્ઝિક્યુટર ઉમેરો ( `BaseExecutor` ને વિસ્તૃત કરો)
3. જો નોન-ઓપનએઆઈ ફોર્મેટ હોય તો `open-sse/translator/` માં અનુવાદક ઉમેરો
4. જો OAuth આધારિત હોય તો `src/lib/oauth/constants/oauth.ts` માં OAuth કન્ફિગ ઉમેરો — જો અપસ્ટ્રીમ CLI જાહેર client_id/secret મોકલે, તો `resolvePublicCred()` દ્વારા એમ્બેડ કરો (જુઓ `docs/security/PUBLIC_CREDS.md`), **ક્યારેય** લિટરલ તરીકે નહીં
5. `open-sse/config/providerRegistry.ts` માં મોડલ્સ નોંધણી કરો
6. `tests/unit/` માં ટેસ્ટ લખો (જો તમે નવા એમ્બેડેડ ડિફોલ્ટ ઉમેર્યા હોય તો જાહેરCreds આકારની પુષ્ટિનો સમાવેશ કરો)

### નવા API માર્ગ ઉમેરવો

1. `src/app/api/v1/your-route/` હેઠળ ડિરેક્ટરી બનાવો
2. `GET`/`POST` હેન્ડલર્સ સાથે `route.ts` બનાવો
3. પેટર્ન અનુસરો: CORS → Zod શરીર માન્યતા → વૈકલ્પિક ઓથ → હેન્ડલર ડેલિગેશન
4. હેન્ડલર `open-sse/handlers/` માં જાય છે (ત્યાંથી આયાત કરો, ઇનલાઇન નહીં)
5. ભૂલ પ્રતિસાદો `buildErrorBody()` / `errorResponse()` નો ઉપયોગ કરે છે `open-sse/utils/error.ts` માં (સ્વચાલિત રીતે સાફ — ક્યારેય `err.stack` અથવા `err.message` કાચા શરીરમાં ન મૂકો). `docs/security/ERROR_SANITIZATION.md` જુઓ.
6. ટેસ્ટ ઉમેરો — જેમાં ઓછામાં ઓછું એક પુષ્ટિ છે કે ભૂલ પ્રતિસાદ સ્ટેક ટ્રેસને લીક નથી કરતી (`!body.error.message.includes("at /")`)

### નવા DB મોડ્યુલ ઉમેરવો

1. `src/lib/db/yourModule.ts` બનાવો — `./core.ts` માંથી `getDbInstance` આયાત કરો
2. તમારા ડોમેન ટેબલ માટે CRUD ફંક્શન નિકાસ કરો
3. જો નવી ટેબલની જરૂર હોય તો `src/lib/db/migrations/` માં માઇગ્રેશન ઉમેરો
4. `src/lib/localDb.ts` માંથી પુનઃ-નિકાસ કરો (ફક્ત પુનઃ-નિકાસ યાદીમાં ઉમેરો)
5. ટેસ્ટ લખો

### નવા MCP ટૂલ ઉમેરવો

1. Zod ઇનપુટ સ્કીમા + અસિંક હેન્ડલર સાથે `open-sse/mcp-server/tools/` માં ટૂલ વ્યાખ્યા ઉમેરો
2. ટૂલ સેટમાં નોંધણી કરો ( `createMcpServer()` દ્વારા વાયરડ)
3. યોગ્ય સ્કોપ(ઓ)ને સોંપો
4. ટેસ્ટ લખો (ટૂલ કૉલને `mcp_audit` ટેબલમાં લોગ કરવામાં આવે છે)

### નવા A2A સ્કિલ ઉમેરવો

1. `src/lib/a2a/skills/` માં સ્કિલ બનાવો (5 પહેલાથી જ છે: સ્માર્ટ-રાઉટિંગ, ક્વોટા-મૅનેજમેન્ટ, પ્રદાતા-ખોજ, ખર્ચ-વિશ્લેષણ, આરોગ્ય-રિપોર્ટ)
2. સ્કિલ કાર્ય સંદર્ભ (સંદેશા, મેટાડેટા) પ્રાપ્ત કરે છે → રચિત પરિણામ પરત કરે છે
3. `src/lib/a2a/taskExecution.ts` માં `A2A_SKILL_HANDLERS` માં નોંધણી કરો
4. `src/app/.well-known/agent.json/route.ts` માં બહાર પાડો (એજન્ટ કાર્ડ)
5. `tests/unit/` માં ટેસ્ટ લખો
6. `docs/frameworks/A2A-SERVER.md` સ્કિલ ટેબલમાં દસ્તાવેજ કરો

### નવા ક્લાઉડ એજન્ટ ઉમેરવો

1. `src/lib/cloudAgent/agents/` માં `CloudAgentBase` ને વિસ્તૃત કરતી એજન્ટ ક્લાસ બનાવો (3 પહેલાથી જ છે: codex-cloud, devin, jules)
2. `createTask`, `getStatus`, `approvePlan`, `sendMessage`, `listSources` અમલમાં લાવો
3. `src/lib/cloudAgent/registry.ts` માં નોંધણી કરો
4. જો જરૂર હોય તો OAuth/ક્રેડેંશિયલ્સ સંભાળવું (`src/lib/oauth/providers/`)
5. ટેસ્ટ + `docs/frameworks/CLOUD_AGENT.md` માં દસ્તાવેજ

### નવા ગાર્ડરેલ / ઇવલ / સ્કિલ / વેબહૂક ઇવેન્ટ ઉમેરવો

- ગાર્ડરેલ: `src/lib/guardrails/` → દસ્તાવેજ: `docs/security/GUARDRAILS.md`
- ઇવલ સ્યુટ: `src/lib/evals/` → દસ્તાવેજ: `docs/frameworks/EVALS.md`
- સ્કિલ (સેન્ડબોક્સ): `src/lib/skills/` → દસ્તાવેજ: `docs/frameworks/SKILLS.md`
- વેબહૂક ઇવેન્ટ: `src/lib/webhookDispatcher.ts` → દસ્તાવેજ: `docs/frameworks/WEBHOOKS.md`

## સંદર્ભ દસ્તાવેજ

કોઈપણ નોન-ટ્રિવિયલ ફેરફાર માટે, પહેલા મેળ ખાતા ડીપ-ડાઈવ વાંચો:

| વિસ્તાર                                      | દસ્તાવેજ                                                          |
| -------------------------------------------- | ----------------------------------------------------------------- |
| રેપો નેવિગેશન                                | `docs/architecture/REPOSITORY_MAP.md`                             |
| આર્કિટેક્ચર                                  | `docs/architecture/ARCHITECTURE.md`                               |
| એન્જિનિયરિંગ સંદર્ભ                          | `docs/architecture/CODEBASE_DOCUMENTATION.md`                     |
| ઓટો-કોમ્બો (9-ફેક્ટર સ્કોરિંગ, 14 વ્યૂહો)    | `docs/routing/AUTO-COMBO.md`                                      |
| રેઝિલિયન્સ (3 મિકેનિઝમ)                      | `docs/architecture/RESILIENCE_GUIDE.md`                           |
| રીઝનિંગ રિપ્લે                               | `docs/routing/REASONING_REPLAY.md`                                |
| સ્કિલ્સ ફ્રેમવર્ક                            | `docs/frameworks/SKILLS.md`                                       |
| મેમરી સિસ્ટમ (FTS5 + Qdrant)                 | `docs/frameworks/MEMORY.md`                                       |
| ક્લાઉડ એજન્ટ્સ                               | `docs/frameworks/CLOUD_AGENT.md`                                  |
| ગાર્ડરેલ્સ (PII / ઇન્જેક્શન / વિઝન)          | `docs/security/GUARDRAILS.md`                                     |
| જાહેર અપસ્ટ્રીમ ક્રેડેન્શિયલ્સ (Gemini/etc.) | `docs/security/PUBLIC_CREDS.md`                                   |
| ભૂલ સંદેશા સાફ કરવા                          | `docs/security/ERROR_SANITIZATION.md`                             |
| ઇવલ્સ                                        | `docs/frameworks/EVALS.md`                                        |
| અનુરૂપતા / ઓડિટ                              | `docs/security/COMPLIANCE.md`                                     |
| વેબહૂક્સ                                     | `docs/frameworks/WEBHOOKS.md`                                     |
| અધિકૃતતા પાઇપલાઇન                            | `docs/architecture/AUTHZ_GUIDE.md`                                |
| સ્ટેલ્થ (TLS / ફિંગરપ્રિન્ટ)                 | `docs/security/STEALTH_GUIDE.md`                                  |
| એજન્ટ પ્રોટોકોલ્સ (A2A / ACP / ક્લાઉડ)       | `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md`                        |
| MCP સર્વર                                    | `docs/frameworks/MCP-SERVER.md`                                   |
| A2A સર્વર                                    | `docs/frameworks/A2A-SERVER.md`                                   |
| API સંદર્ભ + OpenAPI                         | `docs/reference/API_REFERENCE.md` + `docs/reference/openapi.yaml` |
| પ્રદાતા કૅટલોગ (ઓટો-જનરેટેડ)                 | `docs/reference/PROVIDER_REFERENCE.md`                            |
| રિલીઝ પ્રવાહ                                 | `docs/ops/RELEASE_CHECKLIST.md`                                   |

---

## પરીક્ષણ

| શું                      | આદેશ                                                              |
| ------------------------ | ----------------------------------------------------------------- |
| યુનિટ પરીક્ષણ            | `npm run test:unit`                                               |
| એકલ ફાઇલ                 | `node --import tsx/esm --test tests/unit/file.test.ts`            |
| વિટેસ્ટ (MCP, autoCombo) | `npm run test:vitest`                                             |
| E2E (પ્લેવિરાઇટ)         | `npm run test:e2e`                                                |
| પ્રોટોકોલ E2E (MCP+A2A)  | `npm run test:protocols:e2e`                                      |
| ઇકોસિસ્ટમ                | `npm run test:ecosystem`                                          |
| કવરેજ ગેટ                | `npm run test:coverage` (75/75/75/70 — નિવેદનો/લાઇન/ફંક્શન/શાખાઓ) |
| કવરેજ રિપોર્ટ            | `npm run coverage:report`                                         |

**PR નિયમ**: જો તમે `src/`, `open-sse/`, `electron/`, અથવા `bin/` માં ઉત્પાદન કોડ બદલો છો, તો તમારે તે જ PR માં પરીક્ષણો સામેલ કરવા અથવા અપડેટ કરવા જોઈએ.

**પરીક્ષણ સ્તર પ્રાથમિકતા**: યુનિટ પહેલા → ઇન્ટિગ્રેશન (મલ્ટી-મોડ્યુલ અથવા DB રાજ્ય) → E2E (UI/વર્કફ્લો માત્ર). બગ પુનરાવૃત્તિઓને સ્વચાલિત પરીક્ષણો તરીકે કોડ કરો પહેલા અથવા સુધારણા સાથે.

**કોપાઇલોટ કવરેજ નીતિ**: જ્યારે PR ઉત્પાદન કોડને બદલે છે અને કવરેજ 75% (નિવેદનો/લાઇન/ફંક્શન) અથવા 70% (શાખાઓ) ની નીચે છે, તો ફક્ત રિપોર્ટ ન કરો — પરીક્ષણો ઉમેરો અથવા અપડેટ કરો, કવરેજ ગેટ ફરી ચલાવો, પછી પુષ્ટિ માટે પૂછો. PR રિપોર્ટમાં ચલાવેલ આદેશો, બદલાયેલ પરીક્ષણ ફાઇલો, અને અંતિમ કવરેજ પરિણામ સામેલ કરો.

---

## Git વર્કફ્લો

```bash
# ક્યારેય સીધા મુખ્યમાં કમિટ ન કરો
git checkout -b feat/your-feature
git commit -m "feat: તમારા ફેરફારનું વર્ણન કરો"
git push -u origin feat/your-feature
```

**બ્રાંચ પ્રિફિક્સ**: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`

**કમિટ ફોર્મેટ** (પરંપરાગત કમિટ્સ): `feat(db): સર્કિટ બ્રેકર ઉમેરો` — સ્કોપ્સ: `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`, `a2a`, `memory`, `skills`

**હસ્કી હૂક્સ**:

- **પ્રિ-કમિટ**: lint-staged + `check-docs-sync` + `check:any-budget:t11`
- **પ્રિ-પુશ**: `npm run test:unit`

---

## પર્યાવરણ

- **રનટાઇમ**: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES Modules
- **ટાઇપસ્ક્રિપ્ટ**: 5.9+, લક્ષ્ય ES2022, મોડ્યુલ esnext, રિઝોલ્યુશન બંડલર
- **પાથ એલિયાસ**: `@/*` → `src/`, `@omniroute/open-sse` → `open-sse/`, `@omniroute/open-sse/*` → `open-sse/*`
- **ડિફોલ્ટ પોર્ટ**: 20128 (API + ડેશબોર્ડ એક જ પોર્ટ પર)
- **ડેટા ડિરેક્ટરી**: `DATA_DIR` env var, ડિફોલ્ટ `~/.omniroute/`
- **કી env vars**: `PORT`, `JWT_SECRET`, `API_KEY_SECRET`, `INITIAL_PASSWORD`, `REQUIRE_API_KEY`, `APP_LOG_LEVEL`
- સેટઅપ: `cp .env.example .env` પછી `JWT_SECRET` (`openssl rand -base64 48`) અને `API_KEY_SECRET` (`openssl rand -hex 32`) જનરેટ કરો

---

## કઠોર નિયમો

1. ક્યારેય ગુપ્તતા અથવા પ્રમાણપત્રો કમિટ ન કરો
2. ક્યારેય `localDb.ts` માં લોજિક ઉમેરો ન કરો
3. ક્યારેય `eval()` / `new Function()` / સૂચિત eval નો ઉપયોગ ન કરો
4. ક્યારેય સીધા `main` માં કમિટ ન કરો
5. ક્યારેય રૂટમાં કાચા SQL ન લખો — `src/lib/db/` મોડ્યુલનો ઉપયોગ કરો
6. ક્યારેય SSE સ્ટ્રીમમાં ભૂલને મૌન રીતે નાશ ન કરો
7. હંમેશા Zod સ્કીમા સાથે ઇનપુટને માન્ય બનાવો
8. ઉત્પાદન કોડ બદલતા સમયે હંમેશા પરીક્ષણો સામેલ કરો
9. કવરેજ ≥75% (નિવેદનો, લાઇન, ફંક્શન) / ≥70% (શાખાઓ) રહેવું જોઈએ. વર્તમાન માપવામાં આવેલ: ~82%.
10. સ્પષ્ટ ઓપરેટર મંજૂરી વિના હસ્કી હૂક્સ (`--no-verify`, `--no-gpg-sign`) ને ક્યારેય બાયપાસ ન કરો.
11. ક્યારેય જાહેર અપસ્ટ્રીમ OAuth client_id/secret અથવા Firebase વેબ કી ને સ્ટ્રિંગ લિટરલ તરીકે એમ્બેડ ન કરો — હંમેશા `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`) દ્વારા જાઓ. જુઓ `docs/security/PUBLIC_CREDS.md`.
12. ક્યારેય HTTP / SSE / એક્ઝિક્યુટર પ્રતિસાદોમાં કાચા `err.stack` / `err.message` પાછા ન કરો — હંમેશા `buildErrorBody()` અથવા `sanitizeErrorMessage()` (`open-sse/utils/error.ts`) મારફતે રૂટ કરો. જુઓ `docs/security/ERROR_SANITIZATION.md`.
13. ક્યારેય બાહ્ય પાથ અથવા રનટાઇમ મૂલ્યોને `exec()`/`spawn()` ને પસાર કરવામાં આવેલા શેલ સ્ક્રિપ્ટોમાં સ્ટ્રિંગ-ઇન્ટરપોલેટ ન કરો — તેના બદલે `env` વિકલ્પ મારફતે પસાર કરો. સંદર્ભ: `src/mitm/cert/install.ts::updateNssDatabases`.
14. ક્યારેય CodeQL / Secret-Scanning એલર્ટને (a) પ્રથમ ઉપર દર્શાવેલ પેટર્ન દસ્તાવેજો તપાસ્યા વિના નકારી નાંખો કે શું સહાયક લાગુ પડે છે, અને (b) નકારી નાખવાના ટિપ્પણમાં ટેકનિકલ ન્યાયને નોંધો. નમૂનો: `js/stack-trace-exposure` જે કૉલસાઇટ્સ પર ઉઠાવવામાં આવ્યું છે જે પહેલાથી જ `sanitizeErrorMessage()` મારફતે રૂટ કરે છે તે એક જાણીતી CodeQL મર્યાદા છે (કસ્ટમ સેનિટાઇઝર્સ માન્ય નથી) — `docs/security/ERROR_SANITIZATION.md` ને સંદર્ભિત કરીને `false positive` તરીકે નકારી નાખો.
15. ક્યારેય બાળકોની પ્રક્રિયાઓને શરૂ કરતી રૂટ્સને ( `/api/mcp/`, `/api/cli-tools/runtime/`) `src/server/authz/routeGuard.ts` માં `isLocalOnlyPath()` વર્ગીકરણ વિના સામેલ ન કરો. લૂપબેક અમલમાં કોઈપણ ઓથ ચેક પહેલાં શરત વિના થાય છે — ટનલ દ્વારા લીક થયેલ JWT પ્રક્રિયા શરૂ કરવા માટે પ્રેરણા આપી શકતું નથી. જુઓ `docs/security/ROUTE_GUARD_TIERS.md`.
16. ક્યારેય `Co-Authored-By` ટ્રેલર્સને સામેલ ન કરો જે AI સહાયક, LLM અથવા સ્વચાલિત ખાતાને શ્રેય આપે છે (દા.ત. "Claude", "GPT", "Copilot", "Bot" ધરાવતા નામો; `anthropic.com` / `openai.com` / બોટની માલિકીના `noreply.github.com` સરનામા પરના ઈમેઈલો). આવા ટ્રેલર્સ GitHub પર બોટ ખાતામાં કમિટ એટ્રિબ્યુશન રૂટ કરે છે, PR ઇતિહાસમાં વાસ્તવિક લેખકને (`diegosouzapw`) છુપાવે છે. માનવ સહયોગીઓ — upstream PR લેખકો અને OmniRoute પર પોર્ટ થતા issue રિપોર્ટરો સહિત — પ્રમાણભૂત `Co-authored-by: Name <email>` ટ્રેલર્સ સાથે શ્રેય મેળવી શકે છે અને જોઈએ; upstream-port વર્કફ્લો (`/port-upstream-features`, `/port-upstream-issues`) આના પર નિર્ભર છે.