🚀 Spectrum CLI

Современный CLI для workflow разработки - переписанный с shell-скриптов на Node.js

📦 Установка

🌟 NPM (рекомендуется)

# Установить глобально
npm install -g spectrum-cli

# Использовать
spectrum --help

Перед выполнением каждой команды CLI проверяет опубликованную версию spectrum-cli в npm Registry. Если доступна новая версия, показывает текущую и новую версии и команду spectrum upgrade. Она запускает npm install -g spectrum-cli. Проверка ограничена 200 мс; недоступность Registry не влияет на выполнение команды и не выводит ошибку.

🔧 Из исходников

# Клонировать и установить
git clone https://github.com/dnwsilver/spectrum-cli.git
cd spectrum-cli
npm install
./index.js --help

📋 Подробные инструкции: INSTALL.md

🚀 Использование

Основные команды:

# Показать справку
spectrum --help
# Показать текущую версию CLI
spectrum -v  # или spectrum --version

# 🚀 Управление релизами
spectrum release start [--stable]    # Схлопнуть fragments и атомарно отправить release commit в dev и main/master
spectrum release deploy              # Создать стабильный тег release/X.Y.Z из заголовка CHANGELOG
spectrum release close               # Свести stable main/master в dev

# Срочный patch без переноса незавершённого dev в production
spectrum hotfix start                # Локальная подготовка 🩹 CHANGELOG на hotfix/* или main/master
spectrum hotfix deploy               # После merge MR: stable-тег на актуальном main/master
spectrum hotfix close                # После stable pipeline: main/master → dev

# 📈 Теги chart
spectrum chart start         # Создать тег по CHANGELOG.md чарта и дождаться публикации в Helm-registry
spectrum chart start -n      # Не ждать публикации после отправки тега
spectrum chart start --force # Разрешить версию не выше последнего remote-тега, если ее еще нет в registry и Git
spectrum chart deploy  # Обновить helmrelease.yaml до последнего chart-тега и запушить
spectrum chart deploy --instances sd,cbch  # Обновить только выбранные инстансы instances/<name>
spectrum chart verify ~/repo  # Сравнить ingress paths AS IS vs TO BE для Next.js исходников

# 📝 Управление changelog
spectrum changelog append "Сообщение"  # Создать fragment в .changelog/
spectrum changelog check               # Проверить CHANGELOG.md и все fragments
spectrum changelog write               # Выравнять заголовки CHANGELOG.md и запустить Prettier

# 🔑 GitLab токены
spectrum token rotate  # Пролить SC_BOT_PAT в CI variables

Все команды с действием показывают, какая предпроверка успешно пройдена; при ошибке выводят её имя и причину. Независимые предпроверки продолжают выполняться после ошибки; зависимые проверки без нужных данных помечаются как невыполненные. Шаги команды запускаются, только если все проверки прошли. -s, --silence скрывает сообщения об успешно пройденных предпроверках. Ошибки проверок и итоговое сообщение команды остаются видны; флаг можно совмещать с -d, --dry. -d, --dry выполняет все предпроверки, показывает их результаты и не запускает шаги записи, создания тегов, публикации или деплоя. Предпроверки могут обращаться к origin, registry и GitLab; token rotate -d запрашивает токены и проверяет доступ к целям, но не изменяет CI variables. Если конфиг токенов отсутствует, --dry завершится ошибкой и не создаст его. Для upgrade -d предпроверок нет: команда сообщает об успехе, не запуская npm.

| Короткий флаг | Полный флаг | Где действует | | --- | --- | --- | | -d | --dry | Все команды с действием: только предпроверки | | -s | --silence | Все команды с действием: скрыть успешные предпроверки | | -f | --force | chart start: разрешить версию не больше последнего тега на origin; проверки Git-тега и Helm-registry обязательны | | -n | --no-wait | chart start: не ждать появления версии в Helm-registry после push; по умолчанию команда ждёт | | -i <names> | --instances <names> | chart deploy: выбрать инстансы через запятую | | -h | --help | Справка CLI и команд | | -v | --version | Версия CLI |

Справка по командам:

# Справка по релизам
spectrum release --help

# Справка по changelog
spectrum changelog --help

# Справка по chart
spectrum chart --help

# Справка по токенам
spectrum token --help

✨ Особенности

• 🎯 Минималистичный интерфейс - только необходимые команды
• 🎨 Цветной вывод с эмодзи для лучшего UX
• 🔄 Автоматическое определение пакетного менеджера (npm/yarn/bun)
• 📊 Детальная обратная связь по каждой операции
• 🛡️ Обработка ошибок и fallback'ы
• 🚀 Полная совместимость с Git workflow

🔧 Требования

• Node.js >= 20
• Git

🏗️ Архитектура

spectrum-cli/
├── index.js             # Точка входа CLI
├── .changelog/          # Записи для следующего релиза
├── src/
│   ├── cli/             # Команды, справка и запуск действий
│   ├── common/          # Общие утилиты и версии
│   ├── git/             # Git операции
│   ├── preflight/       # Независимые предпроверки по областям
│   ├── changelog/       # Fragments, конфиг и релизные разделы
│   ├── chart/           # Метаданные, теги, registry, verify и deploy
│   ├── release/         # Версии и этапы обычного релиза
│   ├── hotfix/          # Проверки и этапы hotfix
│   ├── token/           # Конфиг, GitLab API и ротация
│   ├── integrations/    # Общие функции внешних сервисов
├── __tests__/           # Модульные и интеграционные тесты
├── package.json
├── install.sh
├── INSTALL.md
└── README.md

Входы модулей находятся в index.js соответствующих каталогов. Например, require('./src/chart') загружает src/chart/index.js; в корне src файлов нет.

Команды

| Команда | Описание | | --------------------------- | ----------------------------------- | | spectrum release start | Схлопнуть и опубликовать fragments | | spectrum release deploy | Создать стабильный тег release/X.Y.Z | | spectrum release close | Закрыть релиз | | spectrum changelog append | Создать changelog fragment | | spectrum changelog check | Проверить changelog и fragments | | spectrum chart start | Создать и запушить chart тег | | spectrum chart deploy | Обновить chart версию в helmrelease | | spectrum chart verify | Проверить ingress paths chart | | spectrum token rotate | Пролить SC_BOT_PAT в CI |

🛡️ Preflight-проверки по командам

• spectrum release start: чистая и актуальная dev-ветка, dev содержит origin/main или origin/master, стабильный тег, достижимый из production-ветки, согласованная опубликованная история CHANGELOG.md и не более одного открытого релиза. При первом запуске нужны валидные fragments и свободная версия; повторный дополняет открытый раздел без повышения версии. package.json не читается.
• spectrum release deploy: чистая и актуальная main/master, стабильная версия X.Y.Z из верхнего заголовка CHANGELOG.md, отсутствие этой версии среди локальных и remote-тегов всех трёх форм. Команда не создает RC-теги.
• spectrum release close: чистая и актуальная main/master, версия из верхнего заголовка CHANGELOG.md и remote stable-тег поддерживаемой формы, указывающий на текущий commit.
• spectrum changelog append <message>: git-repo, changelog-exists, валидные ID задачи, git identity и тип fragment. Команда не изменяет общий CHANGELOG.md.
• spectrum changelog check: git-repo, changelog-exists, changelog-prettier-check, наличие и формат всех changelog fragments.
• spectrum chart start: git-repo, clean-working-tree, on-main-branch, single-chart (ровно один charts/<chart-name>/Chart.yaml), валидный верхний SemVer-заголовок в charts/<chart-name>/CHANGELOG.md, отсутствие тега chart-<name>-<version> локально и на origin, отсутствие этой версии чарта в Helm-registry. Для запроса registry нужен SC_DEVELOPER_PAT (PAT со scope api и доступом к проекту; роль Owner не требуется); ошибка доступа блокирует команду. Право отправки chart-тега определяется отдельно правилами protected tags. -f, --force обходит только проверку повышения версии относительно последнего remote-тега. После push команда по умолчанию ждёт версию в registry; -n, --no-wait отключает ожидание.

Для обратной совместимости chart-команды принимают SC_OWNER_PAT, если SC_DEVELOPER_PAT не задана или пуста. SC_OWNER_PAT deprecated: поддержка будет удалена в следующей версии. При её использовании CLI один раз за процесс выводит предупреждение с просьбой перейти на SC_DEVELOPER_PAT. Если заданы обе переменные, используется SC_DEVELOPER_PAT без предупреждения.

• spectrum chart deploy: git-repo, clean-working-tree, on-main-branch (текущая ветка main), remote-origin (настроен origin), remote-reachable (доступен origin), single-chart, helmrelease-files (найдены helmrelease.yaml).
• spectrum chart verify <source_path>: git-repo, single-values-yaml (ровно один charts/**/values.yaml), values-ingress-sections (есть ingress.paths.api/pages/assets), source-path-directory, next-project, build-command-support.
• spectrum token rotate: load-config (есть валидный ~/.config/spectrum-cli/config.yaml), ask-tokens (owner PAT и SC_BOT_PAT только в памяти), check-access (все группы и проекты доступны owner PAT).

🔄 Workflow релиза

spectrum release start

Выполняется на dev:

1. Проверяет чистую актуальную dev-ветку, включающую origin/main или origin/master, changelog и fragments.
2. После git fetch origin --prune --tags находит максимальный stable-тег среди release/X.Y.Z, hotfix/X.Y.Z и vX.Y.Z, достижимый из production-ветки.
3. Если открытого релиза нет, вычисляет версию по fragments. До 1.0.0: breaking, removed и added → minor, остальные → patch. Начиная с 1.0.0: breaking и removed → major, added → minor, остальные → patch. Если раздел уже открыт в main/master, сохраняет его версию и дату, объединяет прежние записи с новыми по разделам без дублей. Тип новых fragments не повышает уже выбранную версию.
4. Форматирует и проверяет CHANGELOG.md, затем удаляет использованные fragments.
5. Коммитит изменения и атомарно пушит dev в origin/dev и origin/main или origin/master, без Merge Request. Если новых записей нет, пустой коммит не создаётся; можно повторить отправку после её сбоя.

Первый стабильный выпуск создаётся явно: spectrum release start --stable вычисляет ровно 1.0.0 от опубликованного 0.x. Другой открытый релиз блокирует переход; повтор подготовки открытого 1.0.0 допустим. Флаг запрещён после перехода на 1.x. Он выполняет обычный workflow release start, включая commit и push; --dry запускает только предпроверки. Обычный запуск от 0.3.7 с breaking/removed даёт 0.4.0, с исправлением — 0.3.8; исходные типы записей сохраняются. Alpha CI должен применять ту же политику к своей базовой версии.

Сброс прежней высокой нумерации на 0.x не выполняется этой командой: это отдельная миграция с архивом changelog и ссылок тегов, согласованием dev/master и исключением старых тегов из расчёта версии. Нельзя запускать release start, пока опубликованная история в dev и production различается.

Например, повторный release start дополняет открытый 1.4.0; после публикации release/1.4.0 новые fragments уже формируют следующий релиз. Изменение опубликованной истории и конфликтующие открытые версии блокируют команду.

Команда не изменяет package.json, lock-файлы и не создает release/*-веток. Прямой push в stable-ветку должен быть разрешен правилами защиты репозитория; non-fast-forward обновление не выполняется.

spectrum release close

1. Читает версию из верхнего заголовка CHANGELOG.md и проверяет, что remote stable-теги этой версии указывают на текущий commit main/master.
2. Обновляет main/master и dev.
3. Мержит main/master в dev.
4. Пушит синхронизированный dev.

spectrum release deploy

1. Проверяет актуальную main/master и читает версию X.Y.Z из верхнего заголовка CHANGELOG.md.
2. Создает единственный release-тег release/X.Y.Z.
3. Пушит тег в origin. RC-теги CLI не создает.

Формат стабильных тегов

Новые обычные релизы получают release/X.Y.Z, хотфиксы — hotfix/X.Y.Z. Старый vX.Y.Z эквивалентен release/X.Y.Z: он участвует в поиске последней версии и проверке занятости номера. Старые теги не нужно переименовывать. Нумерация общая: после release/1.2.3 и hotfix/1.2.4 следующий patch — 1.2.5. Выпустить занятый номер под другим префиксом нельзя. В changelog и версиях образов остаётся X.Y.Z, без release/ и hotfix/. Это имена тегов, не веток.

Все hotfix-команды сначала проверяют ветку: разрешены только hotfix/*, main или master. dev, develop, feature/* и detached HEAD отклоняются до fetch. Для start подходят hotfix/<TASK>[-slug] и production-ветка main/master, содержащая актуальный origin. Локальные исправления и commits допустимы. deploy и close требуют чистый production commit, совпадающий с origin.

Изолированный цикл хотфикса

Создайте hotfix/<TASK> или hotfix/<TASK>-<slug> от актуального origin/main или origin/master, либо работайте прямо в актуальной production-ветке main/master. Включайте только срочное исправление и его patch fragments (fixed, security, support либо другой совместимый patch-тип). added, breaking и removed требуют обычного релиза. Все команды запускаются из корня репозитория; для start нужен Prettier, как для обычной сборки changelog.

1. spectrum hotfix start обновляет сведения об origin и выбирает опубликованный stable-тег, достижимый из production. Цель — этот stable плюс один patch. Как и release start, команда читает все файлы текущей .changelog/ независимо от того, когда они попали в Git. Проверяет их общими правилами changelog и допускает только patch-типы; файлы added, breaking и removed требуют обычного релиза. Формат CHANGELOG.md проверяется только в текущей ветке. История может отличаться от stable-тега: её исправления не блокируют хотфикс. Снимок production используется для сохранения записей уже подготовленного хотфикса, без строгой проверки старых заголовков. Команда формирует верхний раздел ## 🩹 [X.Y.Z] - YYYY-MM-DD и удаляет только собранные fragments. Она не делает commit, staging, push, merge или tag, не меняет файлы версий и сохраняет посторонние локальные изменения.
2. Повторный start дополняет тот же неопубликованный раздел, сохраняя дату и существующие записи без дублей. Дата необязательна: раздел без даты останется без даты. Старые заголовки с 🚀, 🩹, без значка и с датами через точки читаются без переписывания опубликованной истории. Без новых fragments подготовленный раздел остаётся без изменений. Например, от v6.35.0 первый и повторные запуски готовят 6.35.1; только после публикации hotfix/6.35.1 следующий хотфикс получит 6.35.2.
3. Проверьте diff, закоммитьте и отправьте исправление по правилам проекта. В MR из hotfix в production уже должны быть верхний patch-раздел и удаления использованных fragments. Merge выполняется отдельно после ревью. Если другой хотфикс уже в production, сначала перенесите его изменения в свою ветку и повторите подготовку: пока stable-тега нет, раздел и версия общие.
4. После доставки подготовленного исправления в production через MR или разрешённый проектом push и проверки RC выполните spectrum hotfix deploy на чистом main/master, точно совпадающем с origin. Команда проверяет следующий patch, отсутствие несобранных hotfix fragments, создаёт hotfix/X.Y.Z на проверенном SHA и отправляет только этот тег. Повтор после ошибки push допускает существующий локальный тег лишь на том же SHA; опубликованный тег не перемещается. Ветки не сливаются.
5. После успешного stable pipeline выполните spectrum hotfix close на том же чистом production commit с тегом hotfix/X.Y.Z. Команда обновит dev/develop только fast-forward, смержит production в integration и отправит integration. Незавершённая работа и fragments в dev сохраняются. Локальные неопубликованные commits блокируют автоматическую отправку; конфликт остаётся для ручного разрешения, без push. При неуспешном push готового merge проверьте локальный diff и согласуйте ветку вручную — повторный close не отправляет локальные commits без проверки.

CLI не проверяет статус CI и не управляет кластером: проверка RC, успешного stable pipeline и фактического выката выполняется отдельно в системе доставки. Обычный release start не используется в этом цикле: он отправляет integration в production. changelog check проверяет исходные fragments до сборки; после сборки сам hotfix start проверяет подготовленный раздел. CI проекта должен принимать собранные заметки в MR, не требуя повторного fragment для уже включённой записи.

Цикл версий и CI

Источник версии — Git-теги release/X.Y.Z, hotfix/X.Y.Z и legacy vX.Y.Z. Файлы версий (package.json, Makefile) не читаются ни CLI, ни CI:

| Событие | Источник версии | Артефакт | | --- | --- | --- | | stable-тег v1.0.0 | git-тег | 1.0.0 | | коммиты в dev | тег v1.0.0 + бамп из .changelog/ | 1.1.0-alpha.SHORTSHA | | release start на dev | fragments схлопнуты в ## 🚀 [1.1.0] | release commit в dev и main/master | | merge в main/master | заголовок CHANGELOG 1.1.0 | 1.1.0-rc.1, затем rc.2, ... | | stable-тег release/1.1.0 | git-тег | проверенный RC продвигается в 1.1.0 | | merge stable в dev (release close) | тег release/1.1.0 + бамп fragments | X.Y.Z-alpha.SHORTSHA |

Номер RC хранится в registry и переиспользуется при retry того же commit SHA. Новые stable-теги — release/X.Y.Z и hotfix/X.Y.Z; старые vX.Y.Z сохраняются. Stable pipeline проверяет OCI revision обязательных образов и копирует точные RC digest без пересборки. Эту CI-часть реализует подключенный release component, а не Spectrum CLI.

spectrum chart start

1. Ищет Chart.yaml в charts/<chart-name>/Chart.yaml и читает поле name
2. Проверяет, что текущая ветка — main
3. Читает версию из верхнего заголовка charts/<chart-name>/CHANGELOG.md и проверяет SemVer
4. Собирает тег chart-<name>-<version>
5. Проверяет, что такого тега еще нет локально и на origin, а версия отсутствует в Helm-registry
6. Создает тег и пушит его в origin, затем ждёт появления версии в registry; -n, --no-wait отключает ожидание

spectrum chart deploy

1. Находит последний тег чарта на remote origin в формате chart-<app>-<version>
2. Ищет все helmrelease.yaml в репозитории
3. Обновляет spec.chart.spec.version до найденной версии и печатает список файлов (зеленым обновленные, серым без изменений)
4. Если обновлений нет, завершает выполнение сообщением, что все уже на последней версии
5. Запрашивает подтверждение публикации через Enter
6. Делает git add обновленных файлов, создает коммит 🚀 Deploy service. и пушит изменения

spectrum chart verify <source_path>

1. Находит charts/**/values.yaml и читает ingress.paths.api/pages/assets как AS IS
2. Собирает TO BE для Next.js из .next артефактов, при необходимости запускает build, затем делает fallback на файловую структуру роутов
3. Для assets использует фиксированный набор regex-путей
4. Печатает diff только по изменениям: лишние пути (-) и недостающие (+) с цветовой подсветкой
5. Завершает команду с ошибкой, если есть расхождения

spectrum token rotate

Пролив уже созданного PAT SC_BOT_PAT в CI/CD variables групп и проектов. Команда токен не выпускает.

Конфиг: ~/.config/spectrum-cli/config.yaml

Если файла нет, команда создаст его:

bot: bot
token_ttl_months: 12
groups: []
projects: []

• bot и token_ttl_months читаются только из конфига.
• Скрытым вводом запрашиваются два токена. Оба живут только в памяти.
• Owner PAT: ходит в API, проверяет доступ, читает/удаляет/создает CI variables. Для групп нужен Owner, для проектов — Maintainer+.
• SC_BOT_PAT: только значение, которое пишется в CI variable.
• Для каждой группы и проекта CI variable SC_BOT_PAT удаляется (если есть) и создается заново как masked and hidden.
• Description переменной: PAT от бота <bot>, владелец Колосов. Истекает YYYY-MM-DD. Дата = сегодня + token_ttl_months.

1. Загружает или создает конфиг
2. Запрашивает owner PAT
3. Запрашивает SC_BOT_PAT
4. Проверяет доступ ко всем группам и проектам owner PAT
5. Обновляет CI variables во всех целях

📝 Работа с Changelog

spectrum changelog append "Сообщение"

Команда создает независимый файл .changelog/<task>-<branch>.<type>.md. Разработчики больше не редактируют общий блок Unreleased, поэтому параллельные ветки не конфликтуют в CHANGELOG.md.

Рабочая ветка должна полностью соответствовать <type>/<YOUTRACK-ID> или <type>/<YOUTRACK-ID>-<slug>, например feature/AR-123 или bugfix/ABBVJSOP-1-timeout. YouTrack ID начинается сразу после первого / и соответствует [A-Z]+-[0-9]+; отсутствующий ID больше не запрашивается интерактивно и не придумывается.

✨ Основные возможности:

• 🔍 Автоматическое извлечение номера задачи из названия ветки
• 🧭 Строгая проверка GitFlow-префикса и YouTrack ID в имени ветки
• 👤 Проверка Git config с подсказками по настройке
• 🎯 Умное определение раздела по типу ветки
• 🧩 Дополнение существующего fragment той же задачи без дублирования строк
• 🔀 Автоматическая сборка общего changelog во время spectrum release start

📋 Поддерживаемые типы веток:

• feature/, feat/ → выбор между Breaking change, Added, Changed, Deprecated, Removed
• bugfix/, fix/ → автоматически Fixed
• support/ → выбор между Support, Security
• другие → показ всех разделов

📋 Типы fragment и SemVer:

| Суффикс | Раздел | До 1.0.0 | С 1.0.0 | | --- | --- | --- | --- | | breaking | Breaking change | minor | major | | removed | Removed | minor | major | | added | Added | minor | minor | | changed, deprecated | Соответствующий раздел | patch | patch | | fixed, security, support | Соответствующий раздел | patch | patch |

📌 Пример использования:

# На ветке feature/ABC-123-new-component
spectrum changelog append "Добавлен новый компонент кнопки"

# Результат:
# .changelog/ABC-123-feature-new-component.added.md
# - ABC-123 Добавлен новый компонент кнопки. [Ваше Имя](ваш@email.com)

Fragment должен содержать только непустые Markdown-строки, начинающиеся с - . Один fragment может содержать несколько записей одного типа. Fragment коммитится вместе с изменением и удаляется только автоматикой релиза.

spectrum changelog check

Команда предназначена для локальной и CI-проверки перед merge:

• проверяет формат CHANGELOG.md через Prettier;
• требует хотя бы один fragment в .changelog/;
• проверяет имя <name>.<type>.md, поддерживаемый тип и формат каждой строки;
• не изменяет файлы.

Совет: Приведите файл к нужному формату командой:

spectrum changelog write

spectrum changelog write

Команда приводит все релизные заголовки CHANGELOG.md к виду ## 🚀 [X.Y.Z], ## 🩹 [X.Y.Z] или ## [X.Y.Z] с необязательной датой, затем запускает Prettier. Старые даты через точки и текст записей сохраняются. Неверный заголовок, включая Unreleased, останавливает команду без удаления записей. При ошибке Prettier исходный CHANGELOG.md восстанавливается. Файлы .changelog/ команда не меняет; commit и push не выполняет.

🎯 Философия

• Простота - минимум команд, максимум функциональности
• Безопасность - все операции с обработкой ошибок
• Скорость - быстрые операции без лишних зависимостей
• Читаемость - понятные логи и сообщения

📚 Дополнительная документация

• 📋 Установка - подробные инструкции по установке
• 🚀 Релизы - инструкции по выпуску новых версий

🤝 Участие в разработке

# Форк репозитория
git clone https://github.com/dnwSilver/spectrum-cli.git
cd spectrum-cli

# Установка dev зависимостей
npm install

# Тестирование
./index.js --help

📄 Лицензия

MIT License - см. LICENSE

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