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

hy2xs_implementation_plan-no_git/00-README.txt

@@ -0,0 +1,41 @@
+HY2XS implementation plan
+
+Назначение
+Этот пакет фиксирует полный план реализации системы HY2XS на основе ранее согласованных docs, но уже в прикладной форме: что именно делать, в каком порядке, как разложить проект и какие границы у каждого слоя.
+
+Зафиксированные решения
+1. Название всей системы: HY2XS.
+2. Название панели: HY2XS admin.
+3. Серверный транспорт: ванильная Hysteria2 из official upstream во время установки.
+4. UI: собственный fork H UI внутри проекта, поставляется вместе с пакетом.
+5. Оркестратор: install-only, только под чистый Debian 12.
+6. Стек оркестратора: Bun + TypeScript.
+7. Builder layer: отдельно, локально, вне сервера.
+8. Update / rollback / uninstall: вне scope.
+9. UI переводим на русский или русский/английский, если двуязычность реализуется быстро и без раздувания scope.
+10. Из UI вырезаем ссылки на оригинальный репозиторий, встроенный update-flow и любое поведение, завязанное на внешний upstream H UI.
+11. Telegram-бот, backend выдачи доступа, remote profiles и похожий access layer — вне scope этого плана.
+
+Состав плана
+01-scope-and-boundaries.txt
+02-target-repo-structure.txt
+03-builder-layer.txt
+04-runtime-package-layout.txt
+05-orchestrator-install-flow.txt
+06-hysteria-runtime-layer.txt
+07-hy2xs-admin-fork-plan.txt
+08-localization-and-rebranding.txt
+09-access-layer-out-of-scope.txt
+10-post-install-env-and-config-policy.txt
+11-testing-acceptance-and-smoke.txt
+12-phased-roadmap.txt
+13-task-breakdown-checklist.txt
+
+Что считать результатом
+Результат этой работы — не абстрактные рассуждения, а один репозиторий/проект HY2XS, внутри которого:
+- есть локальный builder;
+- есть install-only orchestrator на Bun/TypeScript;
+- есть встроенный fork HY2XS admin;
+- есть шаблоны и unit-файлы;
+- есть единый пакет для переноса на чистый Debian 12;
+- сервер после установки готов к работе с Hysteria2, UI и базовым server environment.

hy2xs_implementation_plan-no_git/01-scope-and-boundaries.txt

@@ -0,0 +1,46 @@
+HY2XS: scope and boundaries
+
+1. Что входит в реализацию
+- Локальный builder layer.
+- Итоговый install package.
+- Install-only orchestrator для чистого Debian 12.
+- Оркестратор на Bun + TypeScript.
+- Vanilla Hysteria2 runtime, скачиваемая с official upstream во время установки.
+- Встроенный fork панели HY2XS admin.
+- Systemd unit-файлы.
+- Базовый nftables baseline.
+- post-install.env.
+- Документация и acceptance checks.
+
+2. Что не входит в реализацию
+- Telegram-бот.
+- Backend/контур для remote profiles и выдачи ключей.
+- Update manager.
+- Rollback manager.
+- Uninstall.
+- Поддержка грязных или давно живущих серверов.
+- Target-side build.
+- Docker baseline.
+- Multi-node и cluster-архитектура.
+- Port hopping в первой версии.
+- Автоматическая миграция старых H UI состояний.
+- Полноценная собственная клиентская программа.
+
+3. Что считаем правильной эксплуатационной моделью
+- Сборка выполняется локально.
+- На сервер переносится только готовый пакет.
+- Сервер выполняет только первичную установку и базовую настройку.
+- Если сервер сломан или состояние стало непрозрачным, штатный путь — переустановка ОС и повторный install.
+
+4. Источники истины по слоям
+- Runtime transport: Hysteria2 config + runtime state.
+- UI layer: наш fork HY2XS admin.
+- Install facts: /etc/hysteria/post-install.env.
+- Install logic: исходники оркестратора на Bun/TypeScript + собранный install-артефакт.
+
+5. Главные архитектурные запреты
+- Не скачивать HY2XS admin с внешнего upstream на target.
+- Не компилировать UI на target.
+- Не выполнять `bun install` / transpile / compile оркестратора на target.
+- Не пытаться сделать оркестратор инструментом полного жизненного цикла.
+- Не смешивать install baseline и access platform в одном scope.

hy2xs_implementation_plan-no_git/02-target-repo-structure.txt

@@ -0,0 +1,95 @@
+HY2XS: target repo structure
+
+Цель
+Структура должна жёстко разделять builder, runtime package, fork UI, документацию и server-side install logic.
+
+Рекомендуемая структура
+
+project/
+├── README.md
+├── docs/
+│   ├── architecture/
+│   ├── implementation/
+│   └── operations/
+├── builder/
+│   ├── build.sh
+│   ├── lib/
+│   │   ├── common.sh
+│   │   ├── package.sh
+│   │   ├── ui.sh
+│   │   └── verify.sh
+│   ├── manifests/
+│   │   └── package.manifest
+│   └── output/
+├── package/
+│   ├── install.sh
+│   ├── orchestrator/
+│   │   └── hy2xs-orchestrator
+│   ├── templates/
+│   │   ├── hysteria/
+│   │   ├── nftables/
+│   │   └── env/
+│   ├── systemd/
+│   │   ├── hysteria-server.service
+│   │   └── hy2xs-admin.service
+│   ├── ui/
+│   │   └── hy2xs-admin/
+│   ├── docs/
+│   └── metadata/
+│       ├── package.version
+│       ├── package.build_id
+│       └── checksums.txt
+├── orchestrator/
+│   ├── package.json
+│   ├── bun.lock
+│   ├── tsconfig.json
+│   ├── src/
+│   │   ├── cli.ts
+│   │   ├── commands/
+│   │   │   └── install.ts
+│   │   ├── steps/
+│   │   │   ├── preflight.ts
+│   │   │   ├── deps.ts
+│   │   │   ├── filesystem.ts
+│   │   │   ├── hysteria.ts
+│   │   │   ├── ui.ts
+│   │   │   ├── systemd.ts
+│   │   │   ├── firewall.ts
+│   │   │   ├── env.ts
+│   │   │   └── smoke.ts
+│   │   ├── lib/
+│   │   └── types/
+│   └── dist/
+├── ui/
+│   └── hy2xs-admin-fork/
+│       ├── upstream-base/
+│       ├── app/
+│       ├── assets/
+│       ├── locales/
+│       │   ├── ru/
+│       │   └── en/
+│       ├── branding/
+│       ├── patches/
+│       └── BUILD_NOTES.md
+├── examples/
+│   └── post-install.env.example
+└── dist/
+    └── hy2xs-install-<version>.tar.gz
+
+Что важно
+1. builder/ и orchestrator/ разделены.
+2. package/ — staging area и состав будущего install package.
+3. orchestrator/ — исходники install-only оркестратора на Bun/TypeScript.
+4. package/orchestrator/ — уже собранный install-артефакт, а не исходники для target-side build.
+5. ui/hy2xs-admin-fork/ — постоянный исходник нашего форка.
+6. dist/ — только финальные артефакты.
+
+Минимальная допустимая упрощённая структура
+Если хочешь не раздувать проект на старте, можно сократить до:
+- builder/
+- orchestrator/
+- package/
+- ui/hy2xs-admin-fork/
+- docs/
+- dist/
+Но логическое разделение всё равно должно сохраниться.

hy2xs_implementation_plan-no_git/03-builder-layer.txt

@@ -0,0 +1,64 @@
+HY2XS: builder layer plan
+
+Цель builder layer
+На Debian 12 amd64 build host собрать один чистый install package, который можно перенести на чистый Debian 12 без target-side build.
+
+Технологический выбор
+Baseline packaging: shell-first.
+- Основной packaging pipeline: sh/bash.
+- Оркестратор при этом пишется на Bun + TypeScript.
+- Builder на Debian 12 amd64 собирает install-артефакт оркестратора.
+- На target не должно быть обязательного JS/TS toolchain шага.
+
+Задачи builder layer
+1. Проверка структуры репозитория.
+2. Проверка наличия обязательных файлов пакета.
+3. Подготовка HY2XS admin fork к поставке.
+4. Локальная сборка оркестратора из Bun/TypeScript.
+5. Копирование UI-артефактов в package staging.
+6. Копирование templates, systemd units, docs и examples.
+7. Генерация metadata: version, build_id, checksums.
+8. Упаковка итогового архива.
+
+Порядок реализации builder
+Этап 1.
+- Создать tools/build/build.sh.
+- Создать tools/build/lib/common.sh.
+- Создать tools/build/lib/verify.sh.
+- Создать tools/build/lib/package.sh.
+- Создать tools/build/lib/deps.sh.
+- Создать tools/build/README.ru.md.
+
+Production-дополнение.
+- Проверять Debian 12 amd64.
+- Самостоятельно доставлять apt build-зависимости.
+- Проверять и фиксировать версии Go/Bun/Node.js/pnpm.
+- Использовать локальный управляемый toolchain при несовпадении версий.
+
+Этап 2.
+- Реализовать очистку package staging directory.
+- Реализовать копирование package/ skeleton.
+- Реализовать сборку `orchestrator/` и копирование артефакта в `package/orchestrator/`.
+- Реализовать копирование ui/hy2xs-admin-fork в package/ui/hy2xs-admin.
+
+Этап 3.
+- Реализовать запись package.version и package.build_id.
+- Реализовать checksums.txt.
+- Реализовать создание dist/hy2xs-install-<version>.tar.gz.
+
+Этап 4.
+- Добавить builder smoke-проверку: архив собрался, в нём есть install.sh, оркестратор, UI, unit-файлы, templates.
+
+Что builder не делает
+- Не качает Hysteria2.
+- Не выполняет серверные действия.
+- Не меняет production state.
+- Не содержит uninstall/update логики.
+- Не включает access/bot backend в baseline package.
+
+Acceptance criteria
+- Одна команда локально создаёт переносимый install package.
+- В package нет builder scripts.
+- В package есть встроенный HY2XS admin.
+- В package есть собранный Bun/TypeScript orchestrator.
+- package можно передать на сервер без дополнительной сборки.

hy2xs_implementation_plan-no_git/04-runtime-package-layout.txt

@@ -0,0 +1,50 @@
+HY2XS: runtime package layout
+
+Цель
+Зафиксировать состав итогового install package, который должен попасть на target machine.
+
+Состав пакета
+1. install entrypoint
+- install.sh
+
+2. orchestrator artifact
+- hy2xs-orchestrator
+
+3. templates
+- Hysteria config template
+- nftables template
+- post-install.env template
+
+4. systemd units
+- hysteria-server.service
+- hy2xs-admin.service
+
+5. bundled UI
+- HY2XS admin runtime files
+- статические ассеты
+- локали
+- branding assets
+
+6. metadata
+- package.version
+- package.build_id
+- checksums.txt
+
+7. docs/examples
+- короткий README по установке
+- post-install.env.example
+
+Что не должно быть в runtime package
+- builder/
+- git history
+- upstream remote URLs H UI
+- update scripts панели
+- ссылки на оригинальный бренд/репозиторий H UI в интерфейсе и документации пакета
+- target-side dependency installation для оркестратора
+- Telegram/access backend как обязательная часть baseline package
+
+Что должен делать install.sh
+- быть единой точкой входа на target
+- вызывать собранный артефакт оркестратора
+- логировать запуск
+- завершаться с понятным кодом ошибки

hy2xs_implementation_plan-no_git/05-orchestrator-install-flow.txt

@@ -0,0 +1,87 @@
+HY2XS: orchestrator install flow
+
+Главная роль
+Install-only orchestrator ставит систему на чистый Debian 12 и больше ничего не обещает.
+
+Технологическая фиксация
+- Исходники оркестратора: Bun + TypeScript.
+- Сборка оркестратора: локально, builder layer'ом.
+- Исполнение на target: готовый install-артефакт через thin wrapper.
+
+Рекомендуемый порядок модулей
+1. preflight
+- проверить Debian 12
+- проверить root/sudo context
+- проверить, что порт свободен
+- проверить, что не существует конфликтующей старой установки
+
+2. deps
+- установить системные зависимости
+- проверить наличие systemd, nft, curl/wget, tar, openssl и прочего необходимого минимума
+
+3. filesystem
+- создать системного пользователя hysteria
+- создать каталоги:
+  /etc/hysteria
+  /var/lib/hysteria
+  /opt/hy2xs-admin
+  /var/lib/hy2xs-admin
+  /var/log/hy2xs
+  /usr/local/lib/hy2xs
+
+4. bundled UI deploy
+- разложить HY2XS admin из пакета
+- назначить владельца и права
+
+5. Hysteria install
+- скачать свежую Hysteria2 из official upstream
+- установить бинарь в согласованный путь
+- зафиксировать фактическую версию
+
+6. config generation
+- сгенерировать /etc/hysteria/config.yaml
+- сгенерировать параметры obfs
+- записать домен, порт, bandwidth policy
+
+7. systemd
+- разложить hysteria-server.service
+- разложить hy2xs-admin.service
+- daemon-reload
+- enable services
+
+8. firewall
+- применить baseline nftables
+- не терять SSH
+
+9. post-install.env
+- создать /etc/hysteria/post-install.env
+- записать package version, build id, orchestrator stack/build, Hysteria version, UI build info, порты и пути
+
+10. start and smoke
+- стартовать сервисы
+- проверить systemctl is-active
+- проверить UDP listen
+- проверить доступность UI
+
+Политика ошибок
+- Любой конфликт неизвестного старого состояния = stop with error.
+- Никакой сложной автомиграции.
+- Ошибки должны быть текстовыми и пригодными для диагностики.
+
+CLI baseline
+Допустимые флаги:
+- --non-interactive
+- --domain
+- --port
+- --ssh-port
+- --skip-firewall
+- --skip-start
+- --ui-port
+- --ui-bind-host
+
+Что не реализовывать
+- update subcommands
+- rollback subcommands
+- uninstall subcommands
+- reconcile logic
+- bot/access-delivery subcommands

hy2xs_implementation_plan-no_git/06-hysteria-runtime-layer.txt

@@ -0,0 +1,42 @@
+HY2XS: Hysteria runtime layer plan
+
+Цель
+Сделать серверный транспорт предсказуемым и полностью ванильным со стороны Hysteria2.
+
+Решения
+1. Hysteria2 не форкается.
+2. Скачивается во время установки с official upstream.
+3. Используется одна baseline-схема без port hopping.
+
+Базовый runtime policy
+- Listen: 0.0.0.0:<PORT>
+- Transport: QUIC/UDP
+- IPv4-only
+- obfs.type: salamander
+- obfs.password: генерируется при установке
+- bandwidth.up: 50 Mbps
+- bandwidth.down: 50 Mbps
+- ignoreClientBandwidth: false
+
+Что надо реализовать
+1. Шаблон server config.
+2. Генератор переменных для шаблона.
+3. Проверку валидности конфига перед запуском.
+4. Фиксацию фактической версии Hysteria в post-install.env.
+
+Нужно зафиксировать в коде
+- Единый путь к конфигу.
+- Единый путь к бинарю.
+- Единый путь к data dir.
+- Единый набор сетевых переменных.
+
+Что не смешивать
+- Не смешивать UI-состояние и transport-конфиг в одном месте.
+- Не полагаться на host TCP BBR как на главный механизм управления Hysteria.
+- Не смешивать install runtime layer и access/delivery layer.
+
+Acceptance criteria
+- Сервис стартует через systemd.
+- Конфиг читается без ошибки.
+- Тестовый совместимый клиент подключается.
+- Политика speed limit соответствует согласованной серверной и клиентской конфигурации.

hy2xs_implementation_plan-no_git/07-hy2xs-admin-fork-plan.txt

@@ -0,0 +1,60 @@
+HY2XS admin: fork implementation plan
+
+Цель
+Превратить H UI в наш поддерживаемый внутренний компонент HY2XS admin.
+
+Главные задачи
+1. Забрать исходный UI в собственный fork внутри проекта.
+2. Отвязать интерфейс от оригинального бренда, ссылок и update-потока.
+3. Подготовить UI к поставке внутри install package.
+4. Сделать UI отдельным systemd-сервисом.
+
+Обязательные изменения в форке
+A. Ребрендинг
+- Новое имя продукта: HY2XS.
+- Новое имя панели: HY2XS admin.
+- Заменить названия в заголовках, логотипах, footer, title, README панели, системных сообщениях.
+
+B. Удаление upstream-зависимостей
+- Удалить ссылки на оригинальный GitHub/Git repository.
+- Удалить кнопки, меню и тексты, предлагающие update из внешнего upstream.
+- Удалить или скрыть экран/логику самопроверки обновлений, если она встроена.
+- Удалить любой текст вида "official repo", "check updates", "new version available" относительно оригинального H UI.
+
+C. Локализация
+- Минимум: полный русский.
+- Предпочтительно: русский + английский, если это делается быстро через словари/locale files без переписывания UI-логики.
+- Китайский как основная locale больше не нужен для поставки HY2XS.
+
+D. Packaging readiness
+- У UI должен быть предсказуемый build/runtime output.
+- UI должен работать из локально поставленных файлов, без git clone и без target-side npm/yarn/pnpm build.
+
+Слои задач по форку
+Этап 1. Первичная инвентаризация
+- Найти все brand strings.
+- Найти все repo/update ссылки.
+- Найти все locales.
+- Найти все места, где UI показывает своё имя.
+
+Этап 2. Ребрендинг
+- Переименовать UI в HY2XS admin.
+- Подменить logo/title/favicon, если есть.
+- Обновить системные тексты.
+
+Этап 3. Вырезание update-flow
+- Удалить пункты меню обновлений.
+- Удалить backend/frontend обработчики update-функций.
+- Удалить внешние endpoints и тексты об обновлениях.
+
+Этап 4. Локализация
+- Вынести строки в locale-файлы, если это ещё не сделано.
+- Создать ru locale.
+- Опционально создать en locale.
+- Проверить, что UI не содержит жёстко зашитых китайских строк.
+
+Этап 5. Runtime packaging
+- Подготовить результат, который builder просто копирует в package/ui/hy2xs-admin.
+
+Техническое правило
+Source-of-truth install lifecycle остаётся у оркестратора. HY2XS admin не должен расширять scope установки и не должен превращаться в update-manager.

hy2xs_implementation_plan-no_git/08-localization-and-rebranding.txt

@@ -0,0 +1,44 @@
+HY2XS: localization and branding plan
+
+Цель
+Сделать систему цельной по названию, языку интерфейса и операторскому UX.
+
+1. Названия
+- Система: HY2XS
+- Панель: HY2XS admin
+- Service names:
+  - hysteria-server.service
+  - hy2xs-admin.service
+- Пути и package naming должны использовать hy2xs как canonical slug
+
+2. Где переименовывать
+- UI titles
+- navbar/header/footer
+- login page
+- browser tab title
+- package metadata
+- docs
+- install output
+- post-install.env package name
+- systemd description lines
+
+3. Политика языка
+Минимум для первой версии:
+- русский интерфейс панели
+- русский install output/docs для оператора
+
+Предпочтительная быстрая модель:
+- RU по умолчанию
+- EN как дополнительная locale, если её можно добавить быстро
+- никакой сложной i18n-платформы, если в исходном UI уже есть простой словарный механизм
+
+4. Что удалить
+- китайские дефолтные тексты в видимых местах
+- оригинальные названия продукта
+- упоминания оригинальной панели как управляемого внешнего продукта
+
+5. Acceptance criteria
+- В UI нет китайского языка в обычном операторском пути.
+- В UI нет оригинального названия H UI.
+- Во всех ключевых местах виден бренд HY2XS / HY2XS admin.
+- Если включён EN, переключение не ломает layout.

hy2xs_implementation_plan-no_git/09-access-layer-out-of-scope.txt

@@ -0,0 +1,29 @@
+HY2XS: access layer out of scope
+
+Цель
+Явно убрать из плана всё, что не относится к install-only baseline.
+
+Что вне scope
+- Telegram-бот.
+- Backend выдачи ключей.
+- Remote profile publishing.
+- Deep links.
+- Billing/подписки.
+- Self-service кабинет.
+- Любой обязательный пользовательский delivery layer.
+
+Что остаётся в scope
+- Установка Hysteria2.
+- Установка HY2XS admin.
+- Настройка server config.
+- Настройка systemd.
+- Настройка firewall.
+- Генерация post-install.env.
+
+Почему это важно
+Если оставить access layer внутри baseline-плана, документация начинает неверно описывать продукт как платформу выдачи доступа. По факту здесь нужен только оркестратор установки и базовой серверной конфигурации.
+
+Минимальный deliverable
+- Один install package.
+- Один install-only orchestrator.
+- Один reproducible install flow для чистого Debian 12.

hy2xs_implementation_plan-no_git/10-post-install-env-and-config-policy.txt

@@ -0,0 +1,53 @@
+HY2XS: post-install env and config policy
+
+Цель
+Оставить после установки один прозрачный reference file с фактами развёртывания.
+
+Путь
+/etc/hysteria/post-install.env
+
+Что обязательно писать
+Deploy/package:
+- PACKAGE_NAME=HY2XS
+- PACKAGE_VERSION
+- PACKAGE_BUILD_ID
+- DEPLOY_TIMESTAMP
+- DEPLOY_TARGET_OS=debian-12
+
+Orchestrator:
+- ORCH_SOURCE_STACK=bun-typescript
+- ORCH_BUILD_MODE
+- ORCH_BUILD_ID
+- ORCH_ENTRYPOINT
+
+Network/common:
+- DEPLOY_DOMAIN
+- SSH_PORT
+
+Hysteria:
+- HY2_SOURCE=official-upstream
+- HY2_VERSION
+- HY2_LISTEN_HOST
+- HY2_PORT
+- HY2_OBFS_TYPE=salamander
+- HY2_OBFS_PASSWORD
+- HY2_BANDWIDTH_UP_Mbps=50
+- HY2_BANDWIDTH_DOWN_Mbps=50
+- HY2_IGNORE_CLIENT_BANDWIDTH=false
+- HY2_CONFIG_PATH
+
+HY2XS admin:
+- HUI_ENABLED=true
+- HUI_FORK_REF
+- HUI_BUILD_ID
+- HUI_BIND_HOST
+- HUI_PORT
+- HUI_INSTALL_DIR
+- HUI_DATA_DIR
+- HUI_BRAND=HY2XS admin
+- HUI_DEFAULT_LOCALE=ru
+
+Правило использования
+- post-install.env — reference file.
+- Изменение этого файла само по себе не должно считаться применением runtime-изменений.
+- Любые ручные правки оператора должны потом осознанно переноситься в реальные рабочие конфиги и применяться документированным способом.

hy2xs_implementation_plan-no_git/11-testing-acceptance-and-smoke.txt

@@ -0,0 +1,48 @@
+HY2XS: testing, acceptance and smoke plan
+
+1. Builder checks
+- package успешно собирается локально
+- в архиве есть UI, install entrypoint, orchestrator artifact, templates, units, metadata
+- нет builder мусора в финальном package
+
+2. Target install checks
+- чистый Debian 12
+- install flow проходит без ручной сборки
+- Hysteria скачана с upstream
+- HY2XS admin разложен из bundled package
+- созданы оба systemd unit
+- создан post-install.env
+- post-install.env фиксирует Bun/TypeScript orchestrator stack
+
+3. Runtime checks
+- systemctl is-active hysteria-server = active
+- systemctl is-active hy2xs-admin = active
+- UDP порт слушается
+- SSH не потерян после firewall
+- UI доступен на заданном bind host/port
+- тестовый совместимый клиент подключается
+
+4. Branding/localization checks
+- в UI нет китайских строк на основных маршрутах
+- в UI нет ссылок на оригинальный репозиторий
+- в UI нет update-кнопок и update-текстов
+- бренд везде HY2XS / HY2XS admin
+
+5. Negative checks
+- порт уже занят
+- старое состояние найдено
+- неверный домен
+- ошибка скачивания Hysteria2
+- конфликтующие файлы UI
+- отсутствует root context
+
+6. Acceptance definition
+Система считается реализованной, когда:
+- локальный builder собирает install package;
+- target install-only flow разворачивает систему на чистом Debian 12;
+- HY2XS admin работает как встроенный форк;
+- Hysteria2 получена с official upstream;
+- оркестратор зафиксирован как Bun/TypeScript stack;
+- UI русифицирован и ребрендирован;
+- upstream update/repo logic удалена из UI;
+- install acceptance не зависит от bot/access layer.

hy2xs_implementation_plan-no_git/12-phased-roadmap.txt

@@ -0,0 +1,59 @@
+HY2XS: phased roadmap
+
+Фаза 1. Skeleton and structure
+Результат:
+- создана структура репозитория;
+- созданы каталоги builder/, orchestrator/, package/, ui/hy2xs-admin-fork/, docs/, dist/.
+
+Фаза 2. Builder baseline
+Результат:
+- build.sh собирает package staging;
+- builder локально собирает Bun/TypeScript orchestrator artifact;
+- генерируется итоговый архив;
+- builder проверяет минимальную целостность пакета.
+
+Фаза 3. Install-only orchestrator baseline
+Результат:
+- чистый Debian 12 проходит preflight;
+- раскладываются каталоги;
+- создаётся post-install.env;
+- скачивается Hysteria2;
+- создаются unit-файлы.
+
+Фаза 4. Hysteria runtime baseline
+Результат:
+- Hysteria2 стартует через systemd;
+- слушает нужный UDP-порт;
+- firewall baseline применён;
+- smoke checks проходят.
+
+Фаза 5. HY2XS admin fork baseline
+Результат:
+- UI форк находится в проекте;
+- поставляется в пакете;
+- стартует отдельным сервисом;
+- не содержит target-side build.
+
+Фаза 6. Rebranding and de-upstreaming
+Результат:
+- UI переименован в HY2XS admin;
+- удалены ссылки на оригинальный repo;
+- удалены update-кнопки и update-flow;
+- бренд HY2XS отражён в docs, install output и metadata.
+
+Фаза 7. Localization
+Результат:
+- русский интерфейс готов полностью;
+- опционально добавлен английский;
+- китайские строки не видны оператору.
+
+Фаза 8. Scope cleanup and docs alignment
+Результат:
+- Telegram/access layer убран из baseline docs;
+- в документации зафиксирован стек оркестратора Bun + TypeScript;
+- install scope отделён от user delivery scope.
+
+Фаза 9. Final acceptance
+Результат:
+- весь install flow от builder до рабочего сервера проходит воспроизводимо;
+- docs соответствуют фактической реализации.

hy2xs_implementation_plan-no_git/13-task-breakdown-checklist.txt

@@ -0,0 +1,56 @@
+HY2XS: task breakdown checklist
+
+A. Repo and structure
+[ ] Создать целевую структуру проекта.
+[ ] Разнести builder, package, orchestrator, ui и docs.
+[ ] Добавить dist/ и metadata policy.
+
+B. Builder
+[ ] Реализовать build.sh.
+[ ] Реализовать staging сборку пакета.
+[ ] Реализовать локальную сборку Bun/TypeScript orchestrator artifact.
+[ ] Реализовать checksums и build_id.
+[ ] Проверить содержимое архива.
+
+C. Orchestrator
+[ ] Реализовать preflight.
+[ ] Реализовать deps.
+[ ] Реализовать filesystem.
+[ ] Реализовать Hysteria install from upstream.
+[ ] Реализовать UI deploy from bundled package.
+[ ] Реализовать config generation.
+[ ] Реализовать systemd units deployment.
+[ ] Реализовать nftables baseline.
+[ ] Реализовать post-install.env generation.
+[ ] Реализовать smoke checks.
+
+D. Hysteria baseline
+[ ] Сделать template config.
+[ ] Сделать obfs password generation.
+[ ] Зафиксировать bandwidth defaults.
+[ ] Проверить launch через systemd.
+
+E. HY2XS admin fork
+[ ] Инвентаризировать brand strings.
+[ ] Инвентаризировать repo/update references.
+[ ] Переименовать UI в HY2XS admin.
+[ ] Удалить update UI/actions.
+[ ] Удалить ссылки на оригинальный repo.
+[ ] Подготовить packaged runtime output.
+
+F. Localization
+[ ] Вынести строки в локали, если нужно.
+[ ] Добавить ru locale.
+[ ] Опционально добавить en locale.
+[ ] Проверить отсутствие китайского в основных маршрутах.
+
+G. Scope alignment
+[ ] Убрать Telegram/access layer из baseline docs.
+[ ] Убрать bot/profile assumptions из acceptance.
+[ ] Зафиксировать Bun + TypeScript как стек оркестратора.
+[ ] Зафиксировать deliverable как install-only server environment.
+
+H. Docs and acceptance
+[ ] Обновить docs по факту реализации.
+[ ] Прогнать acceptance checklist.
+[ ] Зафиксировать финальные инварианты.

hy2xs_implementation_plan-no_git/about_build.txt

@@ -0,0 +1,8 @@
+
+### 💎 
+
+"Проблема" с типами в Bun вообще не ваша забота на этапе создания бинарника. При сборке они просто вырезаются. Ваш план:
+1.  Пишете логику оркестратора на TS, как мы обсуждали.
+2.  Перед финальной сборкой прогоняете `bunx tsc --noEmit` для проверки типов, если хотите перестраховаться.
+3.  Собираете командой `bun build ./src/main.ts --compile --outfile orchestrator`.
+4.  Запускаете на любом сервере: `./orchestrator`.