# HY2XS production builder

## Назначение

[`build.sh`](build.sh) собирает переносимый установочный пакет HY2XS для production-развёртывания.

Итоговый архив создаётся в [`dist`](../../dist) и предназначен для установки на чистый Debian 12 amd64 без сборки на целевом сервере.

## Поддерживаемая среда сборки

Builder поддерживает только:

- Debian 12;
- amd64 / x86_64;
- bash;
- доступ к интернету для установки build-зависимостей и toolchain.

Windows/macOS не являются production build host. На Windows можно править исходники, но финальную сборку нужно выполнять на Debian 12 amd64.

## Что builder делает сам

При запуске builder:

1. Проверяет ОС и архитектуру build host.
2. Проверяет структуру репозитория.
3. Доставляет отсутствующие системные build-зависимости через `apt-get`.
4. Проверяет и при необходимости скачивает локальный toolchain:
   - Go `1.21.13`;
   - Bun `1.1.45`;
   - Node.js `20.19.0`;
   - pnpm `9.15.9`.
5. Собирает install-only orchestrator под Linux amd64.
6. Собирает bundled HY2XS admin под Linux amd64.
7. Формирует metadata и checksums.
8. Создаёт архив install package.
9. Проверяет состав итогового архива.

## Запуск

Из корня репозитория:

```bash
./tools/build/build.sh
```

С явной версией пакета:

```bash
PACKAGE_VERSION=0.1.0 ./tools/build/build.sh
```

С явным build id:

```bash
PACKAGE_VERSION=0.1.0 BUILD_ID=prod-20260425-001 ./tools/build/build.sh
```

## Локальный toolchain

Builder ставит управляемый toolchain в [`.toolchain`](../../.toolchain) и не требует ручной установки Go/Bun/Node/pnpm в систему.

Если нужная версия уже установлена глобально, builder может использовать её. Если версия не совпадает, будет скачана локальная версия.

## Важные ограничения

- Builder не ставит HY2XS на сервер.
- Builder не выполняет target install.
- Builder не собирает ничего на target machine.
- Builder не вендорит бинарь Hysteria2 в пакет: Hysteria2 скачивается install layer'ом с official upstream.
- Итоговый пакет не должен содержать build scripts, `.toolchain` или временные каталоги.

## Результат

После успешной сборки появится архив:

```bash
dist/hy2xs-install-<version>.tar.gz
```

Его нужно перенести на target Debian 12 amd64, распаковать и запустить [`install.sh`](../../package/install.sh) от root.

## Диагностика

Если сборка падает:

1. Проверьте, что host — Debian 12 amd64.
2. Проверьте доступ к `go.dev`, `github.com`, `nodejs.org`, npm registry и apt repositories.
3. Удалите [`.toolchain`](../../.toolchain) и повторите запуск, если toolchain скачался повреждённым.
4. Проверьте lock-файлы [`bun.lock`](../../orchestrator/bun.lock), [`pnpm-lock.yaml`](../../apps/frontend/pnpm-lock.yaml), [`go.sum`](../../apps/go.sum).