diegosouzapw--omniroute/docs/i18n/mr/CLAUDE.md

CLAUDE.md (मराठी)

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

---

या फाइलमध्ये या रेपॉजिटरीमध्ये कोडवर काम करताना Claude Code (claude.ai/code) साठी मार्गदर्शन दिले आहे.

जलद प्रारंभ

npm install                    # निर्भरता स्थापित करा (.auto-generates .env from .env.example)
npm run dev                    # विकास सर्व्हर http://localhost:20128 वर
npm run build                  # उत्पादन बिल्ड (Next.js 16 स्वतंत्र)
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 मार्ग	src/app/api/v1/	Next.js अॅप राउटर — प्रवेश बिंदू
हँडलर्स	open-sse/handlers/	विनंती प्रक्रिया (चॅट, एम्बेडिंग, इ.)
कार्यान्वयक	open-sse/executors/	प्रदाता-विशिष्ट HTTP वितरण
भाषांतरक	open-sse/translator/	स्वरूप रूपांतरण (OpenAI↔Claude↔Gemini)
ट्रान्सफार्मर	open-sse/transformer/	प्रतिसाद API ↔ चॅट पूर्णता
सेवा	open-sse/services/	कॉम्बो राउटिंग, दर मर्यादा, कॅशिंग, इ.
डेटाबेस	src/lib/db/	SQLite डोमेन मॉड्यूल (45+ फाइल, 55 स्थलांतर)
डोमेन/नीती	src/domain/	नीती इंजिन, खर्च नियम, फॉलबॅक लॉजिक
MCP सर्व्हर	open-sse/mcp-server/	37 साधने (30 बेस + 3 मेमरी + 4 कौशल्य), 3 वाहने, ~13 स्कोप्स
A2A सर्व्हर	src/lib/a2a/	JSON-RPC 2.0 एजंट प्रोटोकॉल
कौशल्य	src/lib/skills/	विस्तारणीय कौशल्य फ्रेमवर्क
मेमरी	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() अपस्ट्रीम → retry w/ backoff
    → प्रतिसाद भाषांतर → SSE प्रवाह किंवा JSON
    → जर प्रतिसाद API: responsesTransformer.ts TransformStream

API मार्ग एक सुसंगत नमुना अनुसरण करतात: Route → CORS प्रीफ्लाइट → Zod शरीर प्रमाणीकरण → वैकल्पिक auth (extractApiKey/isValidApiKey) → API की धोरण अंमलबजावणी → हँडलर प्रतिनिधित्व (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.

उद्दिष्ट: अपस्ट्रीम/सेवा स्तरावर वारंवार अपयशी ठरलेल्या प्रदात्याकडे ट्रॅफिक पाठवणे थांबवणे, त्यामुळे एक अस्वस्थ प्रदाता प्रत्येक विनंतीला मंदावणार नाही.

अंमलबजावणी:

• मुख्य वर्ग: 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-key प्रदाते: थ्रेशोल्ड 5, रीसेट टाइमआउट 30s.
• स्थानिक प्रदाते: थ्रेशोल्ड 2, रीसेट टाइमआउट 15s.

फक्त प्रदाता-स्तरीय अपयश स्थिती प्रदाता ब्रेकरला ट्रिप करायला हवी:

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

सामान्य खाते/की/मॉडेल त्रुटी जसे की बहुतेक 401, 403, किंवा 429 प्रकरणांसाठी संपूर्ण प्रदाता ब्रेकरला ट्रिप करू नका. त्या सामान्यतः कनेक्शन कूलडाऊन किंवा मॉडेल लॉकआउटमध्ये असतात. एक सामान्य API-key प्रदाता 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-key बेस कूलडाऊन: 3s.
• API-key 429 उपलब्ध असल्यास अपस्ट्रीम पुनर्प्रयत्न संकेत (Retry-After, रीसेट हेडर, किंवा पार्स करण्यायोग्य रीसेट मजकूर) प्राधान्य द्यावे.
• पुनरावृत्ती होणाऱ्या पुनर्प्राप्त होणाऱ्या अपयशांवर गुणाकार बॅकऑफ वापरला जातो:

baseCooldownMs * 2 ** failureIndex;

अँटी-थंडरिंग-हर्ड गार्ड एकाच कनेक्शनवरील समांतर अपयशांना कूलडाऊन वाढविण्यासाठी किंवा backoffLevel द्विगुणित करण्यापासून प्रतिबंधित करतो.

टर्मिनल स्थिती कूलडाऊन नाहीत. banned, expired, आणि credits_exhausted क्रेडेन्शियल्स/सेटिंग्ज बदलल्याशिवाय किंवा ऑपरेटरने त्यांना रीसेट केल्याशिवाय अनुपलब्ध राहण्याचा उद्देश आहे. तात्पुरत्या कूलडाऊन स्थितीसह टर्मिनल स्थिती ओव्हरराइट करू नका.

मॉडेल लॉकआउट

व्याप्ती: प्रदाता + कनेक्शन + मॉडेल.

उद्दिष्ट: एकाच कनेक्शनसाठी फक्त एक मॉडेल अनुपलब्ध किंवा कोटा-सीमित असताना संपूर्ण कनेक्शन बंद करणे टाळणे.

उदाहरणे:

• प्रति-मॉडेल कोटा प्रदाते 429 परत करत आहेत.
• स्थानिक प्रदाते एक गहाळ मॉडेलसाठी 404 परत करत आहेत.
• प्रदाता-विशिष्ट मोड/मॉडेल परवानगी अपयश जसे की निवडलेले Grok मोड.

मॉडेल लॉकआउट open-sse/services/accountFallback.ts मध्ये राहते आणि त्याच कनेक्शनला इतर मॉडेल्स सेवा देण्याची परवानगी देते.

डिबगिंग मार्गदर्शन

• जर प्रदाता साठी सर्व की वगळल्या गेल्या असतील, तर प्रदाता ब्रेकर स्थिती आणि प्रत्येक कनेक्शनच्या rateLimitedUntil/testStatus तपासा.
• जर रीसेट विंडो नंतर प्रदाता कायमचा वगळलेला दिसत असेल, तर तपासा की कोड कच्चा 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, रिझोल्यूशन बंडलर. स्पष्ट प्रकारांना प्राधान्य द्या.

डेटाबेस

• सर्व वेळ 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, पिनो संदर्भासह लॉग करा
• 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 / कार्यान्वयन / 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. जर नॉन-OpenAI फॉरमॅट असेल तर 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
सार्वजनिक अपस्ट्रीम प्रमाणपत्र (जेमिनी/इ.)	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
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
कव्हरेज गेट	npm run test:coverage (75/75/75/70 — विधान/रेषा/कार्ये/शाखा)
कव्हरेज रिपोर्ट	npm run coverage:report

PR नियम: जर तुम्ही src/, open-sse/, electron/, किंवा bin/ मध्ये उत्पादन कोड बदलला, तर तुम्हाला त्या PR मध्ये चाचण्या समाविष्ट करणे किंवा अद्यतनित करणे आवश्यक आहे.

चाचणी स्तर प्राधान्य: युनिट प्रथम → एकत्रीकरण (बहु-मॉड्यूल किंवा DB स्थिती) → e2e (UI/कार्यप्रवाह फक्त). बग पुनरुत्पादनांना स्वयंचलित चाचण्यांमध्ये कोडित करा, दुरुस्तीसह किंवा आधी.

Copilot कव्हरेज धोरण: जेव्हा PR उत्पादन कोड बदलतो आणि कव्हरेज 75% (विधान/रेषा/कार्ये) किंवा 70% (शाखा) खाली असते, तेव्हा फक्त अहवाल देऊ नका — चाचण्या जोडा किंवा अद्यतनित करा, कव्हरेज गेट पुन्हा चालवा, नंतर पुष्टीसाठी विचारा. चालवलेले कमांड, बदललेले चाचणी फाइल्स, आणि अंतिम कव्हरेज परिणाम PR अहवालात समाविष्ट करा.

---

Git कार्यप्रवाह

# मुख्य शाखेत थेट कमिट करू नका
git checkout -b feat/your-feature
git commit -m "feat: describe your change"
git push -u origin feat/your-feature

शाखा उपसर्ग: feat/, fix/, refactor/, docs/, test/, chore/

कमिट स्वरूप (परंपरागत कमिट्स): feat(db): add circuit breaker — स्कोप: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills

Husky हुक्स:

• pre-commit: lint-staged + check-docs-sync + check:any-budget:t11
• pre-push: npm run test:unit

---

वातावरण

• रनटाइम: Node.js ≥20.20.2 <21 || ≥22.22.2 <23 || ≥24 <25, ES मॉड्यूल
• TypeScript: 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() / implied eval वापरू नका
4. कधीही थेट main मध्ये कमिट करू नका
5. कधीही मार्गांमध्ये कच्चा SQL लिहू नका — src/lib/db/ मॉड्यूल वापरा
6. कधीही SSE प्रवाहांमध्ये चुकांना गुपचूप गिळून टाका
7. नेहमी Zod स्कीमासह इनपुटची पडताळणी करा
8. उत्पादन कोड बदलताना नेहमी चाचण्या समाविष्ट करा
9. कव्हरेज ≥75% (विधान, रेषा, कार्ये) / ≥70% (शाखा) राहिले पाहिजे. वर्तमान मोजलेले: ~82%.
10. स्पष्ट ऑपरेटर मंजुरीशिवाय Husky हुक्स (--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. AI सहाय्यक, LLM किंवा स्वयंचलित खात्याला श्रेय देणारे Co-Authored-By ट्रेलर्स कधीही समाविष्ट करू नका (उदा. "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) यावर अवलंबून आहेत.