spectrum-cli 3.2.0 → 4.0.0

package/CHANGELOG.md

@@ -5,13 +5,35 @@ 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).
 
+This is the changelog of the `spectrum-cli` npm package. Its version comes from
+`package.json`; the release commands use Git tags and `CHANGELOG.md` in the
+**target project** and do not update that project's `package.json`.
+
+## 🚀 [4.0.0] - 2026-10-01
+
+### 💥 Breaking change
+
+- `spectrum chart create <version>` заменена на `spectrum chart start`: версия берётся из верхнего заголовка `charts/<chart-name>/CHANGELOG.md` и больше не передаётся аргументом.
+- `chart start` по умолчанию ждёт публикации чарта в Helm-registry. Прежний `--wait` заменён на `-n, --no-wait` для запуска без ожидания.
+- Исходные модули перемещены из файлов `src/*.js` в каталоги с `index.js`; прямые импорты файлов со старыми путями требуют обновления.
+
+### 🆕 Added
+
+- Все команды с действием поддерживают `-d, --dry` для запуска только предпроверок и `-s, --silence` для скрытия сообщений об успешно пройденных проверках. Для всех флагов доступны короткие формы.
+- Перед созданием chart-тега проверяется, что версия из changelog ещё не существует среди локальных и удалённых Git-тегов и в Helm-registry.
+
+### 🛠 Changed
+
+- Предпроверки сообщают, что именно проверено, выполняются все доступные проверки и завершают команду с ошибкой, если хотя бы одна не прошла; имя запущенной команды из сообщений убрано.
+- Код CLI и тесты распределены по тематическим модулям; документация по установке, релизам и безопасности приведена в соответствие с текущим кодом.
+
 ## 🚀 [3.2.0] - 2026-10-01
 
 ### 🆕 Added
 
 - Добавлена команда `spectrum changelog write`: выравнивает заголовки релизов и хотфиксов и форматирует `CHANGELOG.md` через Prettier.
 - Добавлена команда `spectrum upgrade` для глобального обновления CLI через npm.
-- Перед выполнением команд CLI проверяет наличие новой версии в npm с таймаутом 200 мс и выводит версии и команду обновления; ошибка проверки не прерывает команду.
+- Перед выполнением команд с действием CLI проверяет наличие новой версии в npm с таймаутом 200 мс и выводит версии и команду обновления; ошибка проверки не прерывает команду. `--help` и `--version` проверку не запускают.
 
 ### 🪲 Fixed
 

package/README.md

@@ -40,7 +40,7 @@ npm install
 # Показать справку
 spectrum --help
 # Показать текущую версию CLI
-spectrum -v | --version
+spectrum -v  # или spectrum --version
 
 # 🚀 Управление релизами
 spectrum release start               # Схлопнуть fragments и атомарно отправить release commit в dev и main/master
@@ -53,9 +53,9 @@ spectrum hotfix deploy               # После merge MR: stable-тег на
 spectrum hotfix close                # После stable pipeline: main/master → dev
 
 # 📈 Теги chart
-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 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 исходников
@@ -69,6 +69,31 @@ spectrum changelog write               # Выравнять заголовки C
 spectrum token rotate  # Пролить GITLAB_PRIVATE_TOKEN в 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 |
+
 ### Справка по командам:
 
 ```bash
@@ -103,24 +128,29 @@ spectrum token --help
 
 ```
 spectrum-cli/
-├── index.js           # 🚀 Главный CLI интерфейс
-├── .changelog/        # 🧩 Независимые записи для следующего релиза
-├── src/               # 📁 Исходный код
-│   ├── utils.js       # 🛠️ Утилиты и логирование
-│   ├── git.js         # 📝 Git операции
-│   ├── 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 команды (внутренние)
-│   └── release.js     # 🚀 Release процесс
-├── package.json       # 📦 Конфигурация проекта
-├── install.sh         # 🔧 Автоматический установщик
-├── INSTALL.md         # 📋 Инструкции по установке
-└── README.md          # 📖 Документация
+├── 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` файлов нет.
+
 ### Команды
 
 | Команда                     | Описание                            |
@@ -130,7 +160,7 @@ spectrum-cli/
 | `spectrum release close`    | Закрыть релиз                       |
 | `spectrum changelog append` | Создать changelog fragment          |
 | `spectrum changelog check`  | Проверить changelog и fragments     |
-| `spectrum chart create`     | Создать и запушить chart тег        |
+| `spectrum chart start`      | Создать и запушить chart тег        |
 | `spectrum chart deploy`     | Обновить chart версию в helmrelease |
 | `spectrum chart verify`     | Проверить ingress paths chart       |
 | `spectrum token rotate`     | Пролить GITLAB_PRIVATE_TOKEN в CI   |
@@ -142,7 +172,7 @@ spectrum-cli/
 - `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 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 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 нужен `GITLAB_PRIVATE_TOKEN`; ошибка доступа блокирует команду. `-f, --force` обходит только проверку повышения версии относительно последнего remote-тега. После push команда по умолчанию ждёт версию в registry; `-n, --no-wait` отключает ожидание.
 - `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 и `GITLAB_PRIVATE_TOKEN` только в памяти), `check-access` (все группы и проекты доступны owner PAT).
@@ -266,14 +296,14 @@ pipeline и фактического выката выполняется отд
 revision обязательных образов и копирует точные RC digest без пересборки. Эту
 CI-часть реализует подключенный release component, а не Spectrum CLI.
 
-### `spectrum chart create <version>`
+### `spectrum chart start`
 
 1. Ищет `Chart.yaml` в `charts/<chart-name>/Chart.yaml` и читает поле `name`
 2. Проверяет, что текущая ветка — `main`
-3. Проверяет semver для переданной версии
+3. Читает версию из верхнего заголовка `charts/<chart-name>/CHANGELOG.md` и проверяет SemVer
 4. Собирает тег `chart-<name>-<version>`
-5. Проверяет, что такого тега еще нет
-6. Создает тег и пушит его в `origin`
+5. Проверяет, что такого тега еще нет локально и на `origin`, а версия отсутствует в Helm-registry
+6. Создает тег и пушит его в `origin`, затем ждёт появления версии в registry; `-n, --no-wait` отключает ожидание
 
 ### `spectrum chart deploy`
 

package/index.js

@@ -1,177 +1,9 @@
 #!/usr/bin/env node
-const { Command } = require("commander");
-const program = new Command();
-
-const git = require("./src/git");
-const release = require("./src/release");
-const hotfix = require("./src/hotfix");
-const changelog = require("./src/changelog");
-const chart = require("./src/chart");
-const token = require("./src/token");
-const { checkForUpdates, upgrade } = require("./src/update-check");
-const { version: pkgVersion } = require("./package.json");
-
-async function runAction(action, ...args) {
-  try {
-    await checkForUpdates();
-  } catch {
-    // A failed update check must not affect the command.
-  }
-  try {
-    const result = await action(...args);
-    if (!result) {
-      process.exit(1);
-    }
-  } catch (error) {
-    console.error(`❌ Ошибка: ${error.message}`);
-    process.exit(1);
-  }
-}
-
-program
-  .name("spectrum")
-  .description("🚀 Spectrum CLI для процесса разработки")
-  .version(pkgVersion, "-v, --version");
-
-program
-  .command("upgrade")
-  .description("Обновить Spectrum CLI через npm install -g spectrum-cli")
-  .action(() => runAction(upgrade));
-
-// Команды релиза
-const releaseCmd = program
-  .command("release")
-  .description("Команды управления релизом");
-
-releaseCmd
-  .command("start")
-  .description("Схлопнуть fragments и атомарно отправить release commit в dev и main/master")
-  .action(() => runAction(release.releaseStart));
-
-releaseCmd
-  .command("close")
-  .description("Свести стабильный релиз из main/master в dev")
-  .action(() => runAction(release.releaseClose));
-
-releaseCmd
-  .command("deploy")
-  .description("Создать и отправить только стабильный тег release/X.Y.Z")
-  .action(() => runAction(git.gitCreateTagAndPush));
-
-const hotfixCmd = program.command("hotfix").description("Изолированный цикл срочного patch-релиза");
-
-hotfixCmd.command("start")
-  .description("Подготовить 🩹 CHANGELOG на hotfix/* или main/master, без commit, push и merge")
-  .action(() => runAction(hotfix.hotfixStart));
-hotfixCmd.command("deploy")
-  .description("После merge хотфикса отправить stable-тег с main/master")
-  .action(() => runAction(hotfix.hotfixDeploy));
-hotfixCmd.command("close")
-  .description("После stable pipeline свести production в dev")
-  .action(() => runAction(hotfix.hotfixClose));
-
-// Команды changelog
-const changelogCmd = program
-  .command("changelog")
-  .description("Команды управления changelog fragments");
-
-changelogCmd
-  .command("append <message>")
-  .description("Создать changelog fragment с номером задачи из ветки")
-  .action((message) => runAction(() => changelog.changelogAppend(message)));
-
-changelogCmd
-  .command("check")
-  .description("Проверить CHANGELOG.md и changelog fragments")
-  .action(() => runAction(changelog.changelogCheck));
-
-changelogCmd
-  .command("write")
-  .description("Привести заголовки CHANGELOG.md к формату релиза и запустить Prettier")
-  .action(() => runAction(changelog.changelogWrite));
-
-// Команды chart
-const chartCmd = program
-  .command("chart")
-  .description("Команды управления тегами chart");
-
-chartCmd
-  .command("create <version>")
-  .description("Создать и отправить chart-тег (chart-<name>-<version>)")
-  .option("--force", "Разрешить версию не больше последней опубликованной")
-  .option("--wait", "Дождаться публикации версии чарта в Helm-registry")
-  .action((version, options) => runAction(() => chart.chartCreateTag(version, options)));
-
-chartCmd
-  .command("verify <source_path>")
-  .description("Проверить пути ingress chart относительно исходников Next.js")
-  .action((sourcePath) => runAction(() => chart.chartVerify(sourcePath)));
-
-chartCmd
-  .command("deploy")
-  .description("Задеплоить последнюю версию chart в файлы helmrelease")
-  .option("--instances <names>", "Список инстансов через запятую (по умолчанию все)")
-  .action((options) => runAction(() => chart.chartDeploy(options)));
-
-const tokenCmd = program
-  .command("token")
-  .description("Команды управления GitLab токенами");
-
-tokenCmd
-  .command("rotate")
-  .description("Пролить GITLAB_PRIVATE_TOKEN в CI variables через owner PAT")
-  .action(() => runAction(token.tokenRotate));
-
-// Переопределяем help, чтобы показать кастомный формат с алиасами
-program.configureHelp({
-  formatHelp: (cmd, helper) => {
-    const cmdUsage = helper.commandUsage(cmd);
-    const cmdDescription = helper.commandDescription(cmd);
-    const options = helper.visibleOptions(cmd);
-    const commands = helper.visibleCommands(cmd);
-
-    let output = "";
-
-    // Использование
-    if (cmdUsage) {
-      output += `Использование: ${cmdUsage}\n\n`;
-    }
-
-    // Описание
-    if (cmdDescription) {
-      output += `${cmdDescription}\n\n`;
-    }
-
-    // Команды с алиасами
-    if (commands.length > 0) {
-      output += "Команды:\n";
-      commands.forEach((cmd) => {
-        const nameAndArgs = cmd.name() + cmd.usage().replace(/^[^\s]+\s*/, " ");
-        const aliases = cmd.aliases();
-        const description = cmd.description();
-
-        let cmdLine = `  ${nameAndArgs}`;
-        if (aliases.length > 0) {
-          cmdLine = cmdLine.padEnd(25) + `[${aliases.join(", ")}]`;
-        }
-        cmdLine = cmdLine.padEnd(40) + description;
-        output += cmdLine + "\n";
-      });
-      output += "\n";
-    }
-
-    // Опции
-    if (options.length > 0) {
-      output += "Опции:\n";
-      options.forEach((option) => {
-        const flags = helper.optionTerm(option);
-        const description = helper.optionDescription(option);
-        output += `  ${flags.padEnd(25)} ${description}\n`;
-      });
-    }
-
-    return output;
-  },
-});
+const { Command } = require('commander');
+const { registerCommands } = require('./src/cli/commands');
+const { configureHelp } = require('./src/cli/help');
 
+const program = new Command();
+registerCommands(program);
+configureHelp(program);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-cli",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "description": "🚀 Modern CLI for development workflow automation - release management, versioning, and changelog generation",
   "main": "index.js",
   "bin": {
@@ -71,9 +71,9 @@
     "testEnvironment": "node",
     "collectCoverageFrom": [
       "index.js",
-      "src/command-executor.js",
-      "src/development.js",
-      "src/utils.js"
+      "src/cli/command-executor.js",
+      "src/cli/development.js",
+      "src/common/utils.js"
     ],
     "testMatch": [
       "**/__tests__/**/*.js",

package/src/changelog/commands.js

@@ -0,0 +1,44 @@
+const { runCommand } = require('../cli/command-executor');
+const { requireGitRepo, requireFileExists, requirePrettierAvailable, requireChangelogFormatted, requireChangelogFragments } = require('../preflight');
+const { CHANGELOG_FILE } = require('./config');
+const { prepareChangelogEntry, appendPreparedChangelogEntry } = require('./fragments');
+const { writeCurrentChangelog } = require('./format');
+function changelogAppend(message) {
+    return runCommand({
+        name: 'changelog append',
+        checks: [
+            { name: 'git-repo', run: requireGitRepo },
+            { name: 'changelog-exists', run: () => requireFileExists(CHANGELOG_FILE) },
+            { name: 'prepare-fragment', dependsOn: ['git-repo', 'changelog-exists'], run: () => prepareChangelogEntry(message) }
+        ],
+        steps: [
+            { name: 'write-fragment', run: appendPreparedChangelogEntry }
+        ]
+    });
+}
+
+function changelogCheck() {
+    return runCommand({
+        name: 'changelog check',
+        checks: [
+            { name: 'git-repo', run: requireGitRepo },
+            { name: 'changelog-exists', run: () => requireFileExists(CHANGELOG_FILE) },
+            { name: 'changelog-prettier-check', run: requireChangelogFormatted },
+            { name: 'changelog-fragments', run: requireChangelogFragments }
+        ]
+    });
+}
+
+function changelogWrite() {
+    return runCommand({
+        name: 'changelog write',
+        checks: [
+            { name: 'git-repo', run: requireGitRepo },
+            { name: 'changelog-exists', run: () => requireFileExists(CHANGELOG_FILE) },
+            { name: 'prettier-available', run: requirePrettierAvailable }
+        ],
+        steps: [{ name: 'write-changelog', run: writeCurrentChangelog }]
+    });
+}
+
+module.exports = { changelogAppend, changelogCheck, changelogWrite };

package/src/changelog/format.js

@@ -0,0 +1,51 @@
+const fs = require('fs');
+const { logError, execCommand } = require('../common/utils');
+const { CHANGELOG_FILE } = require('./config');
+function normalizeChangelogHeadings(text) {
+    const version = '(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)';
+    const date = '(\\d{4}-\\d{2}-\\d{2}|\\d{4}\\.\\d{2}\\.\\d{2}|\\d{2}\\.\\d{2}\\.\\d{4})';
+    const releaseHeading = new RegExp(`^##[ \\t]*(?:(🚀|🩹)[ \\t]*)?\\[${version}\\](?:[ \\t]+-[ \\t]+${date})?[ \\t]*\\r?$`);
+    return text.replace(/^##(?!#)[^\n]*$/gm, (heading) => {
+        const match = releaseHeading.exec(heading);
+        if (!match) throw new Error(`Некорректный заголовок ${CHANGELOG_FILE}: ${heading.trimEnd()}`);
+        const marker = match[1] ? `${match[1]} ` : '';
+        const releaseVersion = `${match[2]}.${match[3]}.${match[4]}`;
+        const releaseDate = match[5] ? ` - ${match[5]}` : '';
+        return `## ${marker}[${releaseVersion}]${releaseDate}${heading.endsWith('\r') ? '\r' : ''}`;
+    });
+}
+
+function writeCurrentChangelog(context) {
+    let original;
+    let mayHaveChanged = false;
+    try {
+        original = fs.readFileSync(CHANGELOG_FILE, 'utf8');
+        const normalized = normalizeChangelogHeadings(original);
+        if (normalized !== original) {
+            mayHaveChanged = true;
+            fs.writeFileSync(CHANGELOG_FILE, normalized);
+        }
+        mayHaveChanged = true;
+        if (!execCommand(`${context.prettierRunner} --write ${CHANGELOG_FILE}`) ||
+            !execCommand(`${context.prettierRunner} --check ${CHANGELOG_FILE}`)) {
+            throw new Error('Prettier не смог отформатировать CHANGELOG.md.');
+        }
+        const formatted = fs.readFileSync(CHANGELOG_FILE, 'utf8');
+        if (normalizeChangelogHeadings(formatted) !== formatted) {
+            throw new Error('После Prettier заголовки CHANGELOG.md не соответствуют формату релизов.');
+        }
+        return true;
+    } catch (error) {
+        if (mayHaveChanged && original !== undefined) {
+            try {
+                fs.writeFileSync(CHANGELOG_FILE, original);
+            } catch (restoreError) {
+                logError('❌', 'Не удалось восстановить %s: %s', CHANGELOG_FILE, restoreError.message);
+            }
+        }
+        logError('❌', 'Не удалось отформатировать %s: %s', CHANGELOG_FILE, error.message);
+        return false;
+    }
+}
+
+module.exports = { normalizeChangelogHeadings, writeCurrentChangelog };