OmniRoute/docs/i18n/gu/CLAUDE.md

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

🌐 Languages: 🇺🇸 English · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇪🇸 es · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇱 he · 🇮🇳 hi · 🇭🇺 hu · 🇮🇩 id · 🇮🇩 in · 🇮🇹 it · 🇯🇵 ja · 🇰🇷 ko · 🇮🇳 mr · 🇲🇾 ms · 🇳🇱 nl · 🇳🇴 no · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇸🇰 sk · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇻🇳 vi · 🇨🇳 zh-CN

---

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

ઝડપી શરૂઆત

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           # વર્તુળની નિર્ભરતા શોધો

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

# એકલ પરીક્ષા ફાઇલ (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/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.

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

(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

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

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

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

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

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

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

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

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): નવા સુરક્ષા-સંવેદનશીલ સપાટી ઉમેરતી વખતે કસ્ટમ અમલના બદલે 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 વર્કફ્લો

# ક્યારેય સીધા મુખ્યમાં કમિટ ન કરો
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) આના પર નિર્ભર છે.