Перейти к основному содержимому

Technical Design: HSM CLI & Manifest Management Architecture

Статус: Accepted Дата: 2026-02-03

1. Обзор​

Этот документ описывает архитектуру CLI для Hyper Stack Manager (hsm), ориентированную на декларативное управление конфигурацией и четкое разделение между операциями с глобальным реестром и локальным состоянием проекта.

2. Принципы​

  1. Declarative Intent (hsm.yaml):
    • Файл hsm.yaml является единственным источником правды (Single Source of Truth) для желаемого состояния проекта.
    • Команды CLI — это прежде всего инструменты для редактирования этого манифеста.
  2. Atomic Reconciliation (Sync):
    • Изменения применяются транзакционно через команду hsm sync.
    • Если адаптер (например, uv) сообщает об ошибке, артефакты проекта (pyproject.toml) остаются неизменными.
  3. Round-Trip Editing:
    • Использование ruamel.yaml гарантирует сохранение комментариев и форматирования пользователя в hsm.yaml при редактировании через CLI.

3. Структура CLI​

CLI разделен на функциональные модули в пакете hsm/src/hyper_stack_manager/cli/ для обеспечения чистоты кода и удобства расширения:

  • root.py: Команды верхнего уровня (init, sync, check, list, mode).
  • registry.py: Управление глобальным реестром (hsm registry ...).
  • project.py: Управление текущим проектом (hsm package, hsm group, hsm container).
  • utils.py: Общие утилиты, автодополнение и настройка логирования.

3.1. Управление проектом (Top Level)​

Команды, управляющие локальным состоянием и жизненным циклом проекта.

  • hsm init: Инициализация нового проекта и создание hsm.yaml.
  • hsm sync: Материализация манифеста в специфичные для окружения артефакты.
  • hsm check: Валидация манифеста относительно реестра без применения изменений.
  • hsm list: Отображение текущего стека проекта (активные группы, пакеты и режимы).

3.2. Редактирование манифеста (hsm package/group/container)​

Команды для модификации файла hsm.yaml.

  • hsm package add <name>: Добавление отдельного пакета.
  • hsm package init <name>: Инициализация нового локального пакета.
  • hsm group add <name> --option <opt>: Добавление группы с выбором опции.
  • hsm mode <dev|prod>: Глобальное переключение режима проекта.
  • hsm package mode <name> <dev|prod>: Переключение режима пакета.
  • hsm container mode <name> <dev|prod>: Переключение режима контейнера.

3.3. Глобальный реестр (hsm registry)​

Команды для взаимодействия с глобальной базой компонентов.

  • hsm registry search <query>: Поиск компонентов по всем категориям.
  • hsm registry show <name>: Просмотр детальных метаданных компонента.
  • hsm registry list: Отображение дерева всех доступных компонентов в реестре.

4. Структура Реестра (Registry Layout)​

Реестр разделен на специализированные директории для обработки различных типов компонентов:

  • packages/: Манифесты Python-пакетов.
  • containers/: Манифесты Docker-контейнеров.
  • package_groups/: Группы выбора для Python-пакетов.
  • container_groups/: Группы выбора для Docker-сервисов.

5. Стратегия реализации​

  1. Manifest Engine: Реализован на базе ruamel.yaml для надежной работы с YAML.
  2. Adapter Pattern: Отделяет логику HSM от специфики инструментов, таких как uv или docker compose.
  3. Rich UI: Использование библиотеки rich для наглядной визуализации в терминале.