zuevav
61 lines
3.2 KiB
Markdown
61 lines
3.2 KiB
Markdown
# ADR-0001: Vendored gbrain через git mirror
|
||
|
||
**Дата:** 2026-05-20
|
||
**Статус:** Принято
|
||
|
||
## Контекст
|
||
|
||
gbrain (https://github.com/garrytan/gbrain) — активно развивающийся проект:
|
||
- 60+ коммитов за последние 2 месяца
|
||
- v0.26 (текущая) ввела breaking change: переход с bearer tokens на OAuth 2.1
|
||
- Public API субпакетов (`gbrain/operations`, `gbrain/pglite-engine`) меняется
|
||
|
||
Дополнительные факторы:
|
||
- GitHub аккаунт zuevav был ограничен в апреле 2026, доступ к публичным репозиториям через `bun install -g github:garrytan/gbrain` может неожиданно ломаться
|
||
- ZBrain зависит от стабильности gbrain в production
|
||
- При следующей блокировке аккаунта мы не сможем переустановить или обновить gbrain
|
||
|
||
## Решение
|
||
|
||
Не зависеть от GitHub в runtime/install path. Зеркалить gbrain в свой git:
|
||
|
||
```bash
|
||
# Однократно, на чистом ноуте с работающим GitHub доступом:
|
||
git clone --mirror https://github.com/garrytan/gbrain.git
|
||
cd gbrain.git
|
||
git remote set-url --push origin git@git.zetit.ru:zuevav/gbrain-mirror.git
|
||
git push --mirror
|
||
```
|
||
|
||
Bootstrap-скрипт клонит из git.zetit.ru:
|
||
|
||
```bash
|
||
GBRAIN_REPO="https://git.zetit.ru/zuevav/gbrain-mirror.git" \
|
||
GBRAIN_VERSION="v0.26.5" \
|
||
bash scripts/bootstrap-vm.sh
|
||
```
|
||
|
||
## Последствия
|
||
|
||
### Плюсы
|
||
- Независимость от GitHub доступности и блокировок аккаунтов
|
||
- Управляемое обновление gbrain (через `git fetch upstream && review && push to mirror`)
|
||
- Возможность hotfix'ов локально, если upstream сломан (как форк, но в общем git)
|
||
- Защита от supply chain атак (мы видим diff перед обновлением)
|
||
|
||
### Минусы
|
||
- Нужно вручную обновлять mirror (раз в месяц-два)
|
||
- Лишний шаг в setup
|
||
- Расхождение с upstream если хотфикс не запушим обратно
|
||
|
||
### Митигация
|
||
- Раз в месяц: проверка upstream'а, review diff, push to mirror
|
||
- Все наши изменения (если потребуются) — в отдельной ветке `zetit/*`, чтобы не мерджились с upstream
|
||
- Tag'ируем версии в нашем mirror'е (`v0.26.5-zetit-1`, если есть наши патчи)
|
||
|
||
## Альтернативы рассмотренные
|
||
|
||
1. **Прямая зависимость от github:garrytan/gbrain** — отвергнуто из-за рисков блокировки и breaking changes
|
||
2. **Свой fork на git.zetit.ru с активной разработкой** — overkill, мы не планируем существенно дорабатывать gbrain
|
||
3. **npm-publish gbrain в свой private npm registry** — gbrain не публикуется в npm как пакет; нужен install via bun + workspace
|