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:

# Однократно, на чистом ноуте с работающим 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:

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, если есть наши патчи)

Альтернативы рассмотренные

Прямая зависимость от github:garrytan/gbrain — отвергнуто из-за рисков блокировки и breaking changes
Свой fork на git.zetit.ru с активной разработкой — overkill, мы не планируем существенно дорабатывать gbrain
npm-publish gbrain в свой private npm registry — gbrain не публикуется в npm как пакет; нужен install via bun + workspace

3.2 KiB Raw Permalink Blame History Unescape Escape