spectrum-cli 2.1.2 → 3.0.1

package/CHANGELOG.md

@@ -5,39 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
-### 💥 Breaking change
-
-_Список обратно несовместимых изменений._
-
-### 🆕 Added
-
-_Список новой функциональности._
-
-### 🛠 Changed
-
-_Список изменившейся функциональности._
-
-### 📜 Deprecated
-
-_Список устаревшей функциональности._
-
-### 🗑 Removed
-
-_Список удаленной функциональности._
+## 🚀 [3.0.1] - 2026-08-31
 
 ### 🪲 Fixed
 
-_Список исправлений багов._
+- Исправлено создание переносимых путей changelog fragments в Windows.
 
-### 🔐 Security
+## 🚀 [3.0.0] - 2026-08-31
 
-_Список правок для обеспечения безопасности._
+### 💥 Breaking change
 
-### 📦 Support
+- Команда `spectrum changelog append` создает независимый fragment в `.changelog/` вместо изменения общего `CHANGELOG.md`; для проверки добавлена команда `spectrum changelog check`, а `spectrum release start` собирает и удаляет fragments автоматически.
+- Источник правды о версии — git-теги `vX.Y.Z`: CLI больше не читает и не изменяет `package.json`, lock-файлы, не создает и не проверяет `release/*`-ветки; команда `spectrum version up` удалена.
+- `spectrum release start` вычисляет target от максимального стабильного тега, достижимого из stable-ветки, схлопывает fragments в `CHANGELOG.md` одним коммитом в dev и атомарно пушит release commit напрямую в dev и main/master без MR.
+- `spectrum release start` блокирует новый релиз, пока `CHANGELOG.md` содержит одну или несколько версий новее последнего стабильного тега, не позволяя повторному запуску понизить версию.
+- `spectrum release deploy` и `spectrum release close` читают версию релиза из верхнего заголовка `## 🚀 [X.Y.Z]` файла `CHANGELOG.md`.
+- Changelog task ID принимается только из веток `<type>/<YOUTRACK-ID>` или `<type>/<YOUTRACK-ID>-<slug>`.
+
+### 🆕 Added
 
-_Список правок для обеспечения технической поддержки._
+- Команда `spectrum chart create` требует запись о версии в `CHANGELOG.md` чарта и запрещает версию не больше последней опубликованной (обход через `--force`).
+- Флаг `--wait` команды `spectrum chart create` дожидается публикации версии чарта в Helm-registry GitLab.
+- Команда `spectrum chart deploy` проверяет наличие версии чарта в Helm-registry перед обновлением helmrelease-файлов (требуется `GITLAB_PRIVATE_TOKEN`).
+- Флаг `--instances` команды `spectrum chart deploy` ограничивает деплой выбранными инстансами; в сообщение коммита добавлены версия чарта и список инстансов.
 
 ## 🚀 [2.1.2] - 2026-08-17
 

package/README.md

@@ -36,23 +36,22 @@ spectrum --help
 # Показать текущую версию CLI
 spectrum -v | --version
 
-# 📦 Управление версиями
-spectrum version up major    # Поднять major версию (1.0.0 → 2.0.0)
-spectrum version up minor    # Поднять minor версию (1.0.0 → 1.1.0)
-spectrum version up patch    # Поднять patch версию (1.0.0 → 1.0.1)
-
 # 🚀 Управление релизами
-spectrum release start       # Полный цикл релиза
-spectrum release close       # Закрыть релиз и смержить в dev
-spectrum release deploy      # Деплой релиза (создать тег)
+spectrum release start               # Схлопнуть fragments и атомарно отправить release commit в dev и main/master
+spectrum release deploy              # Создать стабильный тег vX.Y.Z из заголовка CHANGELOG
+spectrum release close               # Свести stable main/master в dev
 
 # 📈 Теги chart
-spectrum chart create 1.2.3  # Создать и запушить chart-$name-$version
+spectrum chart create 1.2.3  # Создать и запушить chart-$name-$version (требует запись в CHANGELOG.md чарта)
+spectrum chart create 1.2.3 --wait   # После пуша тега дождаться публикации версии в Helm-registry
+spectrum chart create 1.2.2 --force  # Разрешить версию не больше последней опубликованной
 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 "Сообщение"  # Добавить запись в CHANGELOG.md
+spectrum changelog append "Сообщение"  # Создать fragment в .changelog/
+spectrum changelog check               # Проверить CHANGELOG.md и все fragments
 
 # 🔑 GitLab токены
 spectrum token rotate  # Пролить GITLAB_PRIVATE_TOKEN в CI variables
@@ -64,9 +63,6 @@ spectrum token rotate  # Пролить GITLAB_PRIVATE_TOKEN в CI variables
 # Справка по релизам
 spectrum release --help
 
-# Справка по версиям
-spectrum version up --help
-
 # Справка по changelog
 spectrum changelog --help
 
@@ -96,11 +92,13 @@ spectrum token --help
 ```
 spectrum-cli/
 ├── index.js           # 🚀 Главный CLI интерфейс
+├── .changelog/        # 🧩 Независимые записи для следующего релиза
 ├── src/               # 📁 Исходный код
 │   ├── utils.js       # 🛠️ Утилиты и логирование
 │   ├── git.js         # 📝 Git операции
-│   ├── version.js     # 📦 Управление версиями SemVer
-│   ├── changelog.js   # 📋 Работа с CHANGELOG.md
+│   ├── version.js     # 📦 SemVer-хелперы (парсинг, сравнение, бамп)
+│   ├── changelog-config.js # 🧩 Типы и правила changelog fragments
+│   ├── changelog.js   # 📋 Создание и сборка changelog fragments
 │   ├── chart.js       # 📈 Создание и push chart тегов
 │   ├── token.js       # 🔑 Ротация GitLab PAT и CI variables
 │   ├── development.js # ⚡ Dev команды (внутренние)
@@ -115,13 +113,11 @@ spectrum-cli/
 
 | Команда                     | Описание                            |
 | --------------------------- | ----------------------------------- |
-| `spectrum release start`    | Запустить полный цикл релиза        |
-| `spectrum release deploy`   | Деплой релиза                       |
+| `spectrum release start`    | Схлопнуть и опубликовать fragments  |
+| `spectrum release deploy`   | Создать стабильный тег vX.Y.Z       |
 | `spectrum release close`    | Закрыть релиз                       |
-| `spectrum version up major` | Увеличить major версию              |
-| `spectrum version up minor` | Увеличить minor версию              |
-| `spectrum version up patch` | Увеличить patch версию              |
-| `spectrum changelog append` | Добавить запись в changelog         |
+| `spectrum changelog append` | Создать changelog fragment          |
+| `spectrum changelog check`  | Проверить changelog и fragments     |
 | `spectrum chart create`     | Создать и запушить chart тег        |
 | `spectrum chart deploy`     | Обновить chart версию в helmrelease |
 | `spectrum chart verify`     | Проверить ingress paths chart       |
@@ -129,13 +125,11 @@ spectrum-cli/
 
 ### 🛡️ Preflight-проверки по командам
 
-- `spectrum release start`: `git-repo` (внутри git-репозитория), `clean-working-tree` (нет незакоммиченных изменений), `main-and-dev-branches` (есть `origin/main` и `origin/develop`), `package-version` (версия в `package.json` существует и валидный semver), `changelog-exists` (есть `CHANGELOG.md`), `changelog-prettier-check` (`prettier --check CHANGELOG.md`).
-- `spectrum release close`: `git-repo`, `clean-working-tree`, `main-and-dev-branches`.
-- `spectrum release deploy`: `git-repo`, `clean-working-tree`, `on-main-branch` (текущая ветка `main`), `package-version`, `tag-missing` (тега `v<version>` нет локально и на `origin`).
-- `spectrum version up major`: `package-json-exists` (есть `package.json`), `package-version`, `clean-working-tree`.
-- `spectrum version up minor`: `package-json-exists`, `package-version`, `clean-working-tree`.
-- `spectrum version up patch`: `package-json-exists`, `package-version`, `clean-working-tree`.
-- `spectrum changelog append <message>`: `changelog-exists`, `prettier-available` (доступен `prettier` или `npx --yes prettier`), `changelog-prettier-check`.
+- `spectrum release start`: чистая и актуальная dev-ветка, стабильный тег, достижимый из `origin/main` или `origin/master`, отсутствие в `CHANGELOG.md` незакрытых версий новее этого тега, валидные fragments и отсутствие целевых hotfix-веток и тега. Версия вычисляется только из тегов и fragments — `package.json` не читается.
+- `spectrum release deploy`: чистая и актуальная main/master, стабильная версия `X.Y.Z` из верхнего заголовка `CHANGELOG.md`, отсутствие локального и remote-тега `vX.Y.Z`. Команда не создает RC-теги.
+- `spectrum release close`: чистая и актуальная main/master, версия из верхнего заголовка `CHANGELOG.md` и remote-тег `vX.Y.Z`, указывающий на текущий 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 create <version>`: `git-repo`, `clean-working-tree`, `on-main-branch`, `valid-semver` (переданный `<version>` — semver), `single-chart` (ровно один `charts/<chart-name>/Chart.yaml`), `tag-missing` (тега `chart-<name>-<version>` нет локально и на `origin`).
 - `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`.
@@ -145,28 +139,47 @@ spectrum-cli/
 
 ### `spectrum release start`
 
-1. Переключается на dev ветку
-2. Создает release/X.Y.Z ветку
-3. Обновляет заголовок в CHANGELOG.md
-4. Удаляет пустые секции из changelog
-5. Добавляет новый блок Unreleased
-6. Коммитит изменения
-7. Пушит release ветку
-8. Выводит прямую ссылку на создание Merge Request
+Выполняется на `dev`:
+
+1. Проверяет `CHANGELOG.md`, отсутствие релизов новее последнего стабильного тега и все файлы `.changelog/<name>.<type>.md`. Новый релиз нельзя начать, пока предыдущий не получил stable-тег.
+2. После `git fetch origin --prune --tags` находит максимальный стабильный тег `vX.Y.Z`, достижимый из stable-ветки, и применяет к нему максимальное повышение: `breaking` → major, `added` → minor, остальные типы → patch.
+3. Собирает новый релизный блок `## 🚀 [X.Y.Z]` в `CHANGELOG.md` из fragments в стабильном порядке разделов.
+4. Удаляет использованные fragments.
+5. Повторно проверяет формат `CHANGELOG.md`.
+6. Коммитит схлопнутый changelog одним коммитом в `dev` и атомарно пушит этот commit напрямую в `origin/dev` и `origin/main` или `origin/master`, без Merge Request.
+
+Команда не изменяет `package.json`, lock-файлы и не создает `release/*`-веток. Прямой push в stable-ветку должен быть разрешен правилами защиты репозитория; non-fast-forward обновление не выполняется.
 
 ### `spectrum release close`
 
-1. Переключается на main ветку
-2. Обновляет main ветку
-3. Переключается на dev ветку
-4. Мержит main в dev
-5. Пушит dev ветку
+1. Читает версию из верхнего заголовка `CHANGELOG.md` и проверяет, что стабильный `vX.Y.Z` уже указывает на текущий commit main/master.
+2. Обновляет main/master и dev.
+3. Мержит main/master в dev.
+4. Пушит синхронизированный `dev`.
 
 ### `spectrum release deploy`
 
-1. Переключается на main ветку
-2. Создает тег с текущей версией
-3. Пушит тег в remote
+1. Проверяет актуальную main/master и читает версию `X.Y.Z` из верхнего заголовка `CHANGELOG.md`.
+2. Создает единственный release-тег `vX.Y.Z`.
+3. Пушит тег в `origin`. RC-теги CLI не создает.
+
+### Цикл версий и CI
+
+Источник правды о версии — git-тег `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-тег `v1.1.0` | git-тег | проверенный RC продвигается в `1.1.0` |
+| merge stable в dev (`release close`) | тег `v1.1.0` + бамп fragments | `X.Y.Z-alpha.SHORTSHA` |
+
+Номер RC хранится в registry и переиспользуется при retry того же commit SHA.
+Git содержит только стабильные теги `vX.Y.Z`. Stable pipeline проверяет OCI
+revision обязательных образов и копирует точные RC digest без пересборки. Эту
+CI-часть реализует подключенный release component, а не Spectrum CLI.
 
 ### `spectrum chart create <version>`
 
@@ -226,37 +239,58 @@ projects: []
 
 ### `spectrum changelog append "Сообщение"`
 
-Умная команда для добавления записей в CHANGELOG.md с автоматическим определением контекста:
+Команда создает независимый файл `.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** с подсказками по настройке
 - 🎯 **Умное определение раздела** по типу ветки
-- 🎨 **Контекстный вывод** с цветовым выделением
-- 🧹 **Автоматическая очистка** дефолтного текста
-- ✅ **Проверка Prettier** перед изменениями `CHANGELOG.md` (команда остановится при ошибке)
+- 🧩 **Дополнение существующего fragment** той же задачи без дублирования строк
+- 🔀 **Автоматическая сборка** общего changelog во время `spectrum release start`
 
 **📋 Поддерживаемые типы веток:**
-- `feature/` → выбор между Added, Changed, Deprecated, Removed
+- `feature/`, `feat/` → выбор между Breaking change, Added, Changed, Deprecated, Removed
 - `bugfix/`, `fix/` → автоматически Fixed
 - `support/` → выбор между Support, Security
 - другие → показ всех разделов
 
+**📋 Типы fragment и SemVer:**
+
+| Суффикс | Раздел | Повышение версии |
+| --- | --- | --- |
+| `breaking` | Breaking change | major |
+| `added` | Added | minor |
+| `changed`, `deprecated`, `removed` | Соответствующий раздел | patch |
+| `fixed`, `security`, `support` | Соответствующий раздел | patch |
+
 **📌 Пример использования:**
+
 ```bash
 # На ветке feature/ABC-123-new-component
 spectrum changelog append "Добавлен новый компонент кнопки"
 
-# Результат в CHANGELOG.md:
+# Результат:
+# .changelog/ABC-123-feature-new-component.added.md
 # - ABC-123 Добавлен новый компонент кнопки. [Ваше Имя](ваш@email.com)
 ```
 
-### 🔍 Линтинг CHANGELOG с Prettier
+Fragment должен содержать только непустые Markdown-строки, начинающиеся с `- `. Один fragment может содержать несколько записей одного типа. Fragment коммитится вместе с изменением и удаляется только автоматикой релиза.
+
+### `spectrum changelog check`
+
+Команда предназначена для локальной и CI-проверки перед merge:
 
-- Перед любыми изменениями changelog выполняется проверка наличия `prettier` и команда `prettier --check CHANGELOG.md`.
-- Если `prettier` недоступен или проверка не пройдена, выполнение прекращается с ошибкой.
-- Запуск через `npx` поддерживается автоматически: используется `npx --yes prettier` при наличии.
+- проверяет формат `CHANGELOG.md` через Prettier;
+- требует хотя бы один fragment в `.changelog/`;
+- проверяет имя `<name>.<type>.md`, поддерживаемый тип и формат каждой строки;
+- не изменяет файлы.
 
 > Совет: Приведите файл к нужному формату командой:
 >

package/index.js

@@ -3,7 +3,6 @@ const { Command } = require("commander");
 const program = new Command();
 
 const git = require("./src/git");
-const version = require("./src/version");
 const release = require("./src/release");
 const changelog = require("./src/changelog");
 const chart = require("./src/chart");
@@ -34,53 +33,34 @@ const releaseCmd = program
 
 releaseCmd
   .command("start")
-  .description("Запустить полный процесс релиза")
+  .description("Схлопнуть changelog fragments в dev и создать MR в main/master")
   .action(() => runAction(release.releaseStart));
 
 releaseCmd
   .command("close")
-  .description("Закрыть релиз и влить в dev")
+  .description("Свести стабильный релиз из main/master в dev")
   .action(() => runAction(release.releaseClose));
 
 releaseCmd
   .command("deploy")
-  .description("Деплой релиза (создать и отправить тег)")
+  .description("Создать и отправить только стабильный тег vX.Y.Z")
   .action(() => runAction(git.gitCreateTagAndPush));
 
-// Команды обновления версии
-const versionCmd = program
-  .command("version")
-  .description("Обновить версию по semantic versioning");
-
-const upCmd = versionCmd
-  .command("up")
-  .description("Обновить версию по semantic versioning");
-
-upCmd
-  .command("major")
-  .description("Повысить major версию (x.0.0)")
-  .action(() => runAction(() => version.setVersion("major")));
-
-upCmd
-  .command("minor")
-  .description("Повысить minor версию (x.y.0)")
-  .action(() => runAction(() => version.setVersion("minor")));
-
-upCmd
-  .command("patch")
-  .description("Повысить patch версию (x.y.z)")
-  .action(() => runAction(() => version.setVersion("patch")));
-
 // Команды changelog
 const changelogCmd = program
   .command("changelog")
-  .description("Команды управления changelog");
+  .description("Команды управления changelog fragments");
 
 changelogCmd
   .command("append <message>")
-  .description("Добавить запись в changelog с номером задачи из ветки")
+  .description("Создать changelog fragment с номером задачи из ветки")
   .action((message) => runAction(() => changelog.changelogAppend(message)));
 
+changelogCmd
+  .command("check")
+  .description("Проверить CHANGELOG.md и changelog fragments")
+  .action(() => runAction(changelog.changelogCheck));
+
 // Команды chart
 const chartCmd = program
   .command("chart")
@@ -89,7 +69,9 @@ const chartCmd = program
 chartCmd
   .command("create <version>")
   .description("Создать и отправить chart-тег (chart-<name>-<version>)")
-  .action((version) => runAction(() => chart.chartCreateTag(version)));
+  .option("--force", "Разрешить версию не больше последней опубликованной")
+  .option("--wait", "Дождаться публикации версии чарта в Helm-registry")
+  .action((version, options) => runAction(() => chart.chartCreateTag(version, options)));
 
 chartCmd
   .command("verify <source_path>")
@@ -99,7 +81,8 @@ chartCmd
 chartCmd
   .command("deploy")
   .description("Задеплоить последнюю версию chart в файлы helmrelease")
-  .action(() => runAction(chart.chartDeploy));
+  .option("--instances <names>", "Список инстансов через запятую (по умолчанию все)")
+  .action((options) => runAction(() => chart.chartDeploy(options)));
 
 const tokenCmd = program
   .command("token")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-cli",
-  "version": "2.1.2",
+  "version": "3.0.1",
   "description": "🚀 Modern CLI for development workflow automation - release management, versioning, and changelog generation",
   "main": "index.js",
   "bin": {

package/src/changelog-config.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+const CHANGELOG_FILE = 'CHANGELOG.md';
+const CHANGELOG_DIR = '.changelog';
+
+const FRAGMENT_TYPES = Object.freeze({
+    breaking: Object.freeze({ section: '### 💥 Breaking change', bump: 'major' }),
+    added: Object.freeze({ section: '### 🆕 Added', bump: 'minor' }),
+    changed: Object.freeze({ section: '### 🛠 Changed', bump: 'patch' }),
+    deprecated: Object.freeze({ section: '### 📜 Deprecated', bump: 'patch' }),
+    removed: Object.freeze({ section: '### 🗑 Removed', bump: 'patch' }),
+    fixed: Object.freeze({ section: '### 🪲 Fixed', bump: 'patch' }),
+    security: Object.freeze({ section: '### 🔐 Security', bump: 'patch' }),
+    support: Object.freeze({ section: '### 📦 Support', bump: 'patch' })
+});
+
+const SECTION_TO_TYPE = Object.freeze(
+    Object.fromEntries(Object.entries(FRAGMENT_TYPES).map(([type, config]) => [config.section, type]))
+);
+
+const FRAGMENT_TYPE_PATTERN = Object.keys(FRAGMENT_TYPES).join('|');
+const FRAGMENT_FILE_PATTERN = new RegExp(`^(.+)\\.(${FRAGMENT_TYPE_PATTERN})\\.md$`);
+
+function getFragmentType(filePath) {
+    const normalizedPath = String(filePath || '').replace(/\\/g, '/');
+    const fileName = normalizedPath.split('/').pop();
+    const match = fileName.match(FRAGMENT_FILE_PATTERN);
+    return match ? match[2] : null;
+}
+
+module.exports = {
+    CHANGELOG_FILE,
+    CHANGELOG_DIR,
+    FRAGMENT_TYPES,
+    SECTION_TO_TYPE,
+    FRAGMENT_FILE_PATTERN,
+    getFragmentType
+};