Technical Design: Управление конфигурацией HSM
1. Принципы
HSM придерживается философии Separation of Concerns (разделение ответственности) и 12-Factor App.
- HSM не модифицирует файлы, находящиеся в зоне ответственности менеджеров пакетов (например,
pyproject.toml). - Настройки самого HSM отделены от настроек управляемых им проектов.
- Инструмент стремится к полной кроссплатформенности.
2. Итоговая стратегия хранения настроек
| Тип настроек | Источник / Место | Назначение |
|---|---|---|
| Разработка HSM (Local Dev) | .env в корне репозитория HSM | Внутренние флаги отладки (HSM_DEBUG_TESTS), лимиты истории (HSM_KEEP_RUNS). |
| CI/CD (GitHub Actions) | Environment Variables | Переменные окружения пайплайна для автоматизации тестов. |
| Глобальные (User Tool) | ~/.config/hsm/config.yaml | Глобальные предпочтения пользователя (например, выбор рантайма по умолчанию). |
| Проектные (Project) | hsm.yaml | Манифест конкретного проекта, определяющий его стек и зависимости. |
3. Переменные окружения (Environment Variables)
HSM использует переменные окружения для настройки поведения ядра и инструментов тестирования.
| Переменная | Описание | Значение по умолчанию |
|---|---|---|
HSM_REGISTRY_PATH | Путь к глобальному реестру компонентов. | ./hsm-registry |
HSM_DEBUG_TESTS | Включает режим отладки тестов (сохранение артефактов). | 0 (выключено) |
HSM_KEEP_RUNS | Количество последних запусков тестов, хранимых в debug_tests/. | 10 |
LOG_LEVEL | Уровень логирования (DEBUG, INFO, WARNING, ERROR). | INFO |
UV_NO_WORKSPACE | Используется для обеспечения изоляции VES (внутренняя). | 1 |
4. Иерархия приоритетов (Hierarchy)
При определении значения настройки HSM проверяет источники в следующем порядке (от высшего к низшему):
- Explicit Flags: Аргументы командной строки (например,
hsm sync --frozen). - Environment Variables: Переменные окружения (включая подгруженные из
.envпри разработке). - Project Manifest: Файл
hsm.yamlв корне управляемого проекта. - User Config: Глобальный файл
~/.config/hsm/config.yaml. - Defaults: Значения по умолчанию, зашитые в код HSM.
5. Кроссплатформенность
Для работы с путями конфигурации используется библиотека pathlib, что гарантирует корректную работу на Linux, macOS и Windows.
- Глобальный конфиг на Windows:
%APPDATA%\hsm\config.yaml. - Глобальный конфиг на Linux/macOS:
~/.config/hsm/config.yaml.
5. Инфраструктура тестирования
В режиме отладки (HSM_DEBUG_TESTS=1) HSM использует систему версионированных песочниц в директории debug_tests/.
- Каждый запуск создает папку
run_N/. - Файл
LATEST.txtсодержит номер последнего запуска. - Количество хранимых запусков регулируется переменной
HSM_KEEP_RUNS.