main

2026-05-20 19:33:02 +03:00
commit f4bca8449e
30 changed files with 4152 additions and 0 deletions
@@ -0,0 +1,60 @@
+# 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