OmniRoute/docs/i18n/ka/CONTRIBUTING.md

Contributing to OmniRoute (ქართული)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 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)
პარამეტრები → ზოგადი	გვერდითი ზოლის ხილვადობა	გვერდითი ზოლის სექციების ჩვენება/დამალვა

ეს პარამეტრები მონაცემთა ბაზაში ინახება და ხელახლა გაშვების შემდეგაც ნარჩუნდება; დაყენებისას ისინი გარემოს ცვლადების ნაგულისხმევ მნიშვნელობებს ანაცვლებს.

ლოკალურად გაშვება

# დეველოპმენტის რეჟიმი (ცხელი გადატვირთვა)
npm run dev

# საწარმოო აგება
npm run build    # next build → .build/next/, შემდეგ assembleStandalone → dist/
npm run start

# სწრაფი, მხოლოდ ბეკენდის/API-ის კომპილაცია კონტრიბუტორის ცვლილებებისთვის
npm run build:contributor

# რელიზის აგება (სუფთა ხელახალი აგება + HEAD sentinel — აუცილებელია განთავსებისთვის)
npm run build:release   # rm -rf .build dist && აგება + წერს 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()                 (აკოპირებს standalone + static + public + ნატიურ რესურსებს)
       └─ შედეგი: dist/                   (server.js, .next/static/, public/, node_modules/)

npm run build:release დამატებით ჯერ ორივე დირექტორიას ასუფთავებს და განთავსების მთლიანობის sentinel-ის სახით წერს dist/BUILD_SHA-ს (= git rev-parse --short HEAD).

npm run build:contributor მხოლოდ ბეკენდის აგების პროფილს იყენებს. აგებისას ის დროებით ანაცვლებს მართვის პანელის UI ფაილებს დროებითი ჩანაცვლებებით, ინარჩუნებს API მარშრუტების დამმუშავებლებს და აგების შემდეგ აღადგენს თავდაპირველ ფაილებს. გამოიყენეთ npm run build იმ ცვლილებებისთვის, რომლებიც გავლენას ახდენს მართვის პანელის UI-ზე, ან რელიზის სრული ვალიდაციისთვის; კონტრიბუტორის პროფილი რელიზის აგებას არ ანაცვლებს.

VPS-ზე განთავსების შენიშვნა: დისტანციური იმიჯის დირექტორია /usr/lib/node_modules/omniroute/app/ უცვლელია. განთავსების უნარები dist/-ის შიგთავსს მასში rsync-ით ასინქრონებს. შეიცვალა მხოლოდ რეპოზიტორიაში არსებული აგების შედეგის გზა (app/ → dist/).

ნაგულისხმევი URL-ები:

• მართვის პანელი: http://localhost:20128/dashboard
• API: http://localhost:20128/v1

---

Git-ის სამუშაო პროცესი

⚠️ არასოდეს შეიტანოთ commit პირდაპირ 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: აღწერეთ თქვენი ცვლილება"
git push -u origin feat/your-feature-name
# გახსენით Pull Request, სადაც base = release/v3.8.49

განშტოებების დასახელება

პრეფიქსი	დანიშნულება
feat/	ახალი ფუნქციები
fix/	შეცდომების გამოსწორება
refactor/	კოდის რესტრუქტურიზაცია
docs/	დოკუმენტაციის ცვლილებები
test/	ტესტების დამატება/შესწორება
chore/	ინსტრუმენტები, CI, დამოკიდებულებები

Commit-შეტყობინებები

დაიცავით Conventional Commits-ის წესები:

feat: პროვაიდერის გამოძახებებისთვის circuit breaker-ის დამატება
fix: JWT საიდუმლოს ვალიდაციის განსაკუთრებული შემთხვევის მოგვარება
docs: SECURITY.md-ის განახლება PII-ის დაცვით
test: დაკვირვებადობის მოდულური ტესტების დამატება
refactor(db): სიხშირის შეზღუდვის ცხრილების გაერთიანება

არეები (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.

---

ტესტების გაშვება

# ყველა ტესტი (unit + vitest + ecosystem + e2e)
npm run test:all

# ერთი სატესტო ფაილი (Node.js-ის ჩაშენებული ტესტების გამშვები — ტესტების უმეტესობა ამას იყენებს)
node --import tsx/esm --test tests/unit/your-file.test.ts

# მხოლოდ თქვენი ცვლილებით დაზარალებული მოდულური ტესტები (იგივე TIA სელექტორი, რაც CI ბარიერში, #8084)
npm run test:scoped            # ბოლო commit-ში (ან სამუშაო ხეში) შეტანილი ცვლილებები
npm run test:scoped:staged     # მხოლოდ staged ცვლილებები — კარგად ერწყმის pre-commit გაშვებას
npm run test:scoped:full       # ჯერ ხელახლა ააგეთ import-graph რუკა (ფაილების დამატების/გადაადგილების შემდეგ)
# Exit 1 + "run the full suite" ნიშნავს, რომ შეიცვალა ცენტრალური ფაილი (tsconfig, package.json, …) ან
# რუკაზე არარსებული საწყისი კოდი — სელექტორი უსაფრთხოდ ასრულებს მუშაობას შეცდომით და არასოდეს გამოტოვებს ტესტებს შეუმჩნევლად.

# Vitest (MCP სერვერი, autoCombo, cache)
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

# Lint + ფორმატირების შემოწმება
npm run lint
npm run check

# ბარიერით დაცული რეალურ upstream-ზე combo-ს smoke-ტესტი (საჭიროებს VPS-ზე წვდომას + რეალური პროვაიდერის კრედიტებს)
# მიმართავს რეალურ პროვაიდერებს — მცირე ხარჯთანაა დაკავშირებული. არასოდეს ეშვება CI-ში. ბარიერის გარეშე უპრობლემოდ გამოიტოვება.
# საჭიროა: ssh root@192.168.0.15 წვდომა (VPS-იდან იყენებს DB-ის მხოლოდ წაკითხვად snapshot-ს).
RUN_COMBO_LIVE=1 npm run test:combo:live

# მე-3 ფაზის VPS-ის ცოცხალი smoke-ტესტი — ჩვეულებრივი Node ESM სკრიპტები, რომლებიც პირდაპირ ცოცხალ .15 სერვერს მიმართავენ.
# საჭიროა: ssh root@192.168.0.15 წვდომა (combo-ები იქმნება/იშლება SSH sqlite-ის მეშვეობით).
# მიმართავს რეალურ პროვაიდერებს (მცირე ხარჯი). ქმნის/შლის მხოლოდ __live_test__* combo-ებს. არასოდეს ეშვება CI-ში.
# .15-ზე REQUIRE_API_KEY=false, ამიტომ API გასაღები საჭირო არ არის, თუმცა დაყენების შემთხვევაში ითვალისწინებს COMBO_LIVE_BASE_URL / COMBO_LIVE_API_KEY-ს.
npm run test:combo:live:vps              # 7 HTTP სცენარი (priority/round-robin/weighted/cost/fusion/auto + health)
npm run test:combo:live:vps:failover     # ამატებს პროვაიდერებს შორის რეალურ failover სცენარს (სულ 8)

დაფარვის შენიშვნები:

• npm run test:coverage ზომავს საწყისი კოდის დაფარვას ძირითადი მოდულური ტესტების ნაკრებისთვის, გამორიცხავს tests/**-ს და მოიცავს open-sse/**-ს
• Pull Request-ებმა დებულებების/სტრიქონების/ფუნქციების/განშტოებების დაფარვის ბარიერი 60%+-ზე უნდა შეინარჩუნონ
• თუ PR ცვლის საწარმოო კოდს src/, open-sse/, electron/ ან bin/-ში, იმავე PR-ში უნდა დაემატოს ან განახლდეს ავტომატიზებული ტესტები
• npm run coverage:report ბეჭდავს ბოლო დაფარვის გაშვების დეტალურ, ფაილების მიხედვით დაყოფილ ანგარიშს
• npm run test:coverage:legacy ისტორიული შედარებისთვის ინარჩუნებს ძველ მეტრიკას
• დაფარვის ეტაპობრივი გაუმჯობესების სამოქმედო გეგმისთვის იხილეთ docs/ops/COVERAGE_PLAN.md

Pull Request-ის მოთხოვნები

PR-ის გახსნამდე გამოიყენეთ Contribution Golden Path, რათა თქვენი ცვლილებისთვის მიზნობრივი ციკლი გაუშვათ. მოდულური ტესტების სრული ნაკრები (CI-ის 4 shard), Vitest, 60%+ დაფარვის ბარიერი და საწარმოო build CI-ის პასუხისმგებლობაა — მათი ლოკალურად გაშვება არ იძლევა დამატებით ინფორმაციას, რომელსაც PR-ის შემოწმებები უკვე არ მოგაწვდით, ხოლო შედარებით სუსტ კომპიუტერებზე შეიძლება სისტემა სრულად დატვირთოს (#8084):

• გაუშვით სატესტო ფაილები, რომლებიც თქვენს ცვლილებას ფარავს: node --import tsx/esm --test tests/unit/<file>.test.ts
• გაუშვით npm run lint
• საწარმოო კოდის ცვლილებისას იმავე PR-ში დაამატეთ ან განაახლეთ ავტომატიზებული ტესტები
• საწარმოო კოდის ცვლილებისას PR-ის აღწერაში მიუთითეთ შეცვლილი ან დამატებული სატესტო ფაილები
• თუ პროექტის საიდუმლოები CI-ში კონფიგურირებულია, შეამოწმეთ PR-ის SonarQube შედეგი

ტესტების მიმდინარე სტატუსი: 122 მოდულური სატესტო ფაილი, რომლებიც ფარავს:

• პროვაიდერის ტრანსლატორებსა და ფორმატის გარდაქმნას
• სიხშირის შეზღუდვას, circuit breaker-სა და მდგრადობას
• სემანტიკურ cache-ს, idempotency-სა და პროგრესის თვალყურის დევნებას
• მონაცემთა ბაზის ოპერაციებსა და სქემას (21 DB მოდული)
• OAuth ნაკადებსა და ავთენტიფიკაციას
• API endpoint-ების ვალიდაციას (Zod v4)
• MCP სერვერის ინსტრუმენტებსა და არეების აღსრულებას
• Memory და Skills სისტემებს

---

კოდის სტილი

• 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 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-ის ფარგლები, მარშრუტიზაციის 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, მეხსიერება, უნარები
├── 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-ზეა დაფუძნებული)

დაამატეთ OAuth-ის ავტორიზაციის მონაცემები src/lib/oauth/constants/oauth.ts-ში, ხოლო სერვისი — src/lib/oauth/services/-ში.

თუ ზედა დონის პროვაიდერი საჯარო OAuth client_id/საიდუმლოს ან Firebase Web API გასაღებს თავის საჯარო CLI-ში / ბრაუზერის პაკეტში ავრცელებს, არ ჩასვათ ის სტრიქონულ ლიტერალად. გამოიყენეთ resolvePublicCred() ფაილიდან open-sse/utils/publicCreds.ts და დაამატეთ შენიღბული ბაიტური ჩანაწერი EMBEDDED_DEFAULTS-ში. სრული სავალდებულო სამუშაო პროცესი აღწერილია docs/security/PUBLIC_CREDS.md-ში.

დამმუშავებლებსა/შემსრულებლებში კლიენტამდე მისული შეცდომის შეტყობინებები უნდა დამუშავდეს buildErrorBody() / sanitizeErrorMessage() ფუნქციებით ფაილიდან open-sse/utils/error.ts — არასოდეს ჩასვათ დაუმუშავებელი err.stack ან err.message Response-ის სხეულში. იხილეთ docs/security/ERROR_SANITIZATION.md.

ნაბიჯი 5: მოდელების რეგისტრაცია

დაამატეთ მოდელების განსაზღვრებები open-sse/config/providerRegistry.ts-ში.

ნაბიჯი 6: ტესტების დამატება

დაწერეთ ერთეულოვანი ტესტები tests/unit/-ში, რომლებიც მინიმუმ შემდეგს მოიცავს:

• პროვაიდერის რეგისტრაცია
• მოთხოვნის/პასუხის ტრანსლაცია
• შეცდომების დამუშავება

---

Pull Request-ის საკონტროლო სია

• ტესტები წარმატებით სრულდება (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 პირდაპირ; ფრაგმენტები გაერთიანდება გამოშვებისას და Pull Request-ებს შორის კონფლიქტს არასოდეს წარმოქმნის
• დოკუმენტაცია განახლებულია (თუ საჭიროა)
• არ არის გახსნილი CodeQL-ის / Secret-Scanning-ის ახალი გაფრთხილებები, ან თითოეული მათგანი უარყოფილია ტექნიკური დასაბუთებით, რომელიც შესაბამის docs/security/ დოკუმენტს მიუთითებს
• მარშრუტები, რომლებიც შვილობილ პროცესებს უშვებს (/api/mcp/, /api/cli-tools/runtime/), კლასიფიცირებულია როგორც isLocalOnlyPath() ფაილში src/server/authz/routeGuard.ts — იხილეთ მკაცრი წესი #15
• commit-ის შეტყობინებებში არ არის Co-Authored-By ტრეილერები — commit-ები მხოლოდ რეპოზიტორიის მფლობელის Git-ის იდენტობის ქვეშ უნდა გამოჩნდეს (მკაცრი წესი #16)

---

რელიზების გამოშვება

რელიზები იმართება /generate-release სამუშაო პროცესის მეშვეობით. ახალი GitHub Release-ის შექმნისას პაკეტი GitHub Actions-ის მეშვეობით ავტომატურად ქვეყნდება npm-ზე.

VPS-ზე განთავსებისთვის გამოიყენეთ npm run build:release (npm run build-ის ნაცვლად) — ის ასრულებს სუფთა ხელახალ აგებას, კრებს პაკეტს dist/-ში და ქმნის dist/BUILD_SHA საკონტროლო ფაილს. შემდეგ გამოიყენეთ /deploy-vps-*-cc უნარები, რომლებიც rsync-ის მეშვეობით dist/-ს დისტანციურ app/ დირექტორიაში ასინქრონებენ.

---

დახმარების მიღება

• არქიტექტურა: იხილეთ docs/architecture/ARCHITECTURE.md
• API-ის ცნობარი: იხილეთ docs/reference/API_REFERENCE.md
• უსაფრთხოების დოკუმენტაცია: docs/security/CLI_TOKEN.md, docs/security/ROUTE_GUARD_TIERS.md, docs/security/ERROR_SANITIZATION.md, docs/security/PUBLIC_CREDS.md
• ოპერაციების დოკუმენტაცია: docs/ops/SQLITE_RUNTIME.md
• საკითხები: github.com/diegosouzapw/OmniRoute/issues
• ADR-ები: არქიტექტურული გადაწყვეტილებების ჩანაწერებისთვის იხილეთ docs/adr/