# 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.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 на момент развёртывания

Дополнительно:
- версия Hysteria2 фиксируется в metadata install package (`metadata/hysteria.version`);
- URL артефакта и SHA256 фиксируются в metadata install package (`metadata/hysteria.url`, `metadata/hysteria.sha256`);
- runtime `reconfigure` не обновляет и не откатывает бинарник Hysteria2;
- install flow валидирует SHA256 и фактическую версию установленного бинарника.

## Инварианты

Система считается правильной, если:

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 из исходников