Подготовить HY2XS к production-сборке

docs/02-build-layer-and-package.md

@@ -0,0 +1,134 @@
+# Build layer and package
+
+## Цель документа
+
+Зафиксировать локальный слой сборки и формат итогового install package.
+
+## Базовое решение
+
+В baseline builder остаётся **shell-first** для packaging-слоя.
+
+То есть:
+- основной packaging pipeline — **sh/bash**
+- оркестратор при этом пишется на **Bun + TypeScript**
+- builder локально компилирует оркестратор в готовый install-артефакт
+- target machine не должна сама собирать или доустанавливать JS/TS toolchain
+
+Причина простая: packaging можно держать простым, а оркестратор — typed и модульным.
+
+## Где работает builder
+
+Production builder работает на отдельном build host:
+- Debian 12
+- amd64 / x86_64
+- bash
+- доступ к интернету для apt и скачивания toolchain
+
+В текущей production-модели сборка выполняется **на Debian 12 amd64**, а не на Windows/macOS dev-машине.
+
+Builder не является частью target install flow: на target server приезжает уже готовый install package, без JS/TS/Go build step.
+
+## Что хранится в репозитории проекта
+
+Минимум:
+- исходники оркестратора на **Bun + TypeScript**
+- shell packaging scripts
+- шаблоны конфигов
+- systemd unit templates
+- docs
+- **наш fork HY2XS admin**
+- шаблоны для `post-install.env`
+- package metadata
+
+## Что делает builder
+
+1. Проверяет структуру проекта.
+2. Собирает / подготавливает HY2XS admin.
+3. Компилирует оркестратор из Bun/TypeScript в install-артефакт.
+4. Копирует артефакты UI в package staging directory.
+5. Кладёт entrypoint, templates, docs и service files.
+6. Формирует итоговый install package.
+7. При необходимости считает manifest/checksum.
+8. Выдаёт один переносимый результат для target machine.
+
+## Что builder не делает
+
+- не ставит Hysteria2 на локальной машине «для продакшена»
+- не превращается в CI/CD платформу
+- не генерирует update pipeline
+- не делает uninstall manifests
+- не готовит миграции между старыми инсталляциями
+
+## Рекомендуемая структура
+
+```text
+project/
+├── tools/
+│   └── build/
+│       ├── build.sh
+│       ├── README.ru.md
+│       └── lib/
+├── orchestrator/
+│   ├── package.json
+│   ├── bun.lock
+│   ├── tsconfig.json
+│   └── src/
+├── package/
+│   ├── install.sh
+│   ├── orchestrator/
+│   ├── templates/
+│   └── systemd/
+├── ui/
+│   └── hy2xs-admin-fork/
+├── docs/
+└── dist/
+```
+
+## Формат итогового пакета
+
+Итоговый пакет должен содержать:
+
+- install-only orchestrator artifact
+- bundled HY2XS admin
+- unit templates
+- config templates
+- docs / examples
+- manifest версии проекта
+
+Итоговый пакет **не должен** содержать:
+- builder scripts
+- исходную локальную build-среду
+- временные каталоги сборки
+- мусор CI
+- target-side dependency install step для оркестратора
+
+## Production builder bootstrap
+
+`tools/build/build.sh` должен быть самодостаточным для Debian 12 amd64:
+
+1. Проверяет ОС и архитектуру.
+2. Проверяет структуру репозитория и lock-файлы.
+3. Доставляет отсутствующие системные build-зависимости через `apt-get`.
+4. Проверяет версии Go, Bun, Node.js и pnpm.
+5. При несовпадении версий скачивает управляемый локальный toolchain в `.toolchain/`.
+6. Собирает только Linux amd64 артефакты.
+7. Записывает версии toolchain в metadata пакета.
+
+## Отношение к Hysteria2
+
+Сам бинарь Hysteria2 **не вендорится** в install package как baseline-правило.
+
+Причина:
+- ядро Hysteria рассматривается как stable upstream component
+- целевая установка должна брать его с official upstream на момент развёртывания
+
+## Инварианты
+
+Система считается правильной, если:
+
+1. builder запускается на Debian 12 amd64 build host, не как target-side build step
+2. пакет можно перенести на чистый Debian 12
+3. на сервере нет отдельного build step
+4. bundled UI уже находится внутри пакета
+5. оркестратор authored as Bun/TypeScript, но на target приходит как готовый install-артефакт
+6. Hysteria2 подтягивается install layer'ом с upstream, а не собирается на target из исходников