development-flow

development-flow

Multi-repo development

Кожен service і package залишається окремим Git repository зі своїми доступами, CI та release. Для локальної роботи їх об’єднують scripts, а не спільна Git-історія.

Репозиторії

Репозиторій	Вміст
contracts / @it-monkeys/contracts	Frontend-safe types, DTO, schemas, HTTP/RMQ contracts
backend-common / @it-monkeys/backend-common	Backend middleware, RMQ, errors, logging, Mongo schemas і repositories
stack	Поточні login, users, roles і Stack-модулі
family-application-api	Cluster API для frontend та Electron
stack-electron-gateway	Stateful socket runtime Electron
stack-electron	Нова desktop-програма
family-golden	Перший новий Family-сервіс
family-platform	Локальні clone, status, pull, link, unlink, build і test scripts

family-platform не містить source інших репозиторіїв і не надає до них доступ. Profile визначає бажаний набір, а Git provider перевіряє реальні права користувача. Недоступний repository script пропускає без падіння всього bootstrap.

Локальні packages

Під час розробки packages підключаються через npm link:

cd D:\work\family-platform
fnm use 24.19.0
npm run packages:link

Команда збирає та зв’язує contracts → backend-common → family-application-api/family-golden. Нижче той самий порядок вручну:

# contracts
cd D:\work\family-platform\repos\contracts
npm run build
npm link
 
# backend package
cd D:\work\family-platform\repos\backend-common
npm link @it-monkeys/contracts --no-save
npm run build
npm link
 
# service
cd D:\work\family-platform\repos\family-golden
npm link @it-monkeys/contracts --no-save
npm link @it-monkeys/backend-common --no-save

Link змінює лише локальний node_modules. Імпорти, package.json і Git-історія не змінюються. Перед release package перевіряється через npm pack.

Local Docker не використовує host links: він сам збирає поточні contracts і backend-common у tarballs та встановлює їх у services. Release Docker після публікації packages встановлює зафіксовані версії через npm ci.

Під час одночасної розробки npx tsc --watch запускається в окремому terminal кожного package. Після зміни contracts він оновлює dist, який бачать linked backend package і service.

Готова зміна:

1. Package проходить tests і публікує нову точну версію.
2. Сервіс прибирає link і встановлює цю версію.
3. Сервіс комітить package.json і lockfile та проходить власні tests.

Private package в Electron

Contracts встановлюються під час build Electron. Registry token потрібен лише npm ci; у source, bundle та installer він не потрапляє.

У repository комітиться тільки .npmrc:

@it-monkeys:registry=https://npm.pkg.github.com

Локально розробник використовує власний GitHub token з read:packages у user-level npm config або працює через npm link.

Для ручного build розробник встановлює package через свій user-level npm token з read:packages. Token у Electron environment, bundle або installer не записуємо.

Types зникають після TypeScript build. Runtime enums або schemas збираються разом із Electron як звичайна dependency; доступ до registry на комп’ютері оператора не потрібен.

Contracts, які потрапляють у Electron або frontend, не містять secrets, partner credentials, server config чи backend-only implementation: desktop bundle можна розпакувати незалежно від приватності Git repository.

Відкладений Partner API package

@it-monkeys/partner-api поки не створюємо. До рішення повертаємося під час розробки нового Electron, коли однакові partner HTTP clients почнуть дублюватися між Electron main і family-* сервісами.

Package буде не deployable service, а спільною runtime-бібліотекою: request/response types, формування й перевірка HTTP-запитів, parsing, login/relogin, робота із сесією та тести. Зберігання сесій підключається через інтерфейс: Family-сервіс використовує Redis adapter, Electron main — memory adapter.

Переносимо тільки код із двома споживачами. GWT legacy та інші server-only запити залишаються у відповідному family-* сервісі; Electron-only запити — в Electron. Package не містить Nest, Mongo, Redis implementation, canonical adapters або бізнес-логіку.

До початку нового Electron partner API залишається локально у Family-сервісах, без додаткового package і поточного рефакторингу.

Scripts family-platform

Script	Задача
bootstrap.ps1 -Profile golden	Клонувати доступні repositories profile
status.ps1	Показати branch і зміни кожного repository
pull.ps1	Оновити лише clean repositories
link.ps1 -Target family-golden	Build і link потрібних packages у правильному порядку
unlink.ps1 -Target family-golden	Прибрати links і відновити lockfile dependencies
build.ps1 -Profile golden	Зібрати packages, потім services
test.ps1 -Profile golden	Запустити package, contract та service tests

Publish поки виконується вручну в repository конкретного package:

npm version patch
npm publish
git push --follow-tags

family-platform лише готує і перевіряє локальне середовище.