@mirta/cli 0.3.5 → 0.4.1

package/README.ru.md

@@ -2,82 +2,136 @@
 
 [![en](https://img.shields.io/badge/lang-en-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-cli/README.md)
 [![ru](https://img.shields.io/badge/lang-ru-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-cli/README.ru.md)
-[![NPM Version](https://img.shields.io/npm/v/@mirta/globals?style=flat-square)](https://npmjs.com/package/@mirta/cli)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/cli?style=flat-square)](https://npmjs.com/package/@mirta/cli)
 [![NPM Downloads](https://img.shields.io/npm/dm/@mirta/cli?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/cli)
 
-Утилита для эффективного управления выпуском релизов и автоматизированной публикации пакетов в NPM, поддерживает работу в монорепозиториях.
+> Универсальный CLI-инструмент для версионирования, публикации и деплоя в монорепозиториях с синхронным семантическим версионированием.
 
-### Ключевые возможности
+`@mirta/cli` — оркестратор процессов, который:
+- Синхронно обновляет версии в пакетах монорепозитория,
+- Запускает генерацию `CHANGELOG` (если настроен),
+- Публикует пакеты в NPM с поддержкой `--provenance` в CI,
+- Синхронизирует артефакты с контроллерами Wiren Board через `rsync`.
 
-- Удобная система обновления версий проектов;
-- Простая интеграция с существующими процессами CI/CD;
-- Доступ ко всем необходимым операциям через интуитивные команды;
-- Поддержка кастомизации рабочего потока под специфику вашей инфраструктуры.
+Работает в любых монорепозиториях, использующих `pnpm` и синхронное семантическое версионирование.
 
-## Установка и начальная настройка
+**Не предназначен для выполнения в среде Duktape на контроллерах Wiren Board.**
 
-Подключите `@mirta/cli` в ваш проект как dev-зависимость следующей командой:
+## 📦 Установка
 
 ```sh
 pnpm add -wD @mirta/cli
 ```
-Можно настроить дополнительные параметры, добавив файл конфигурации `mirta.config.json` в корень главного проекта. Например:
 
-```json
-{
-  "scope": "myscope",
-  "scopeAsPackagePrefix": false
-}
-```
-### Основные опции конфигурации
+✅ Этот пакет разработан для фреймворка Mirta, но работает в любых `pnpm`-монорепозиториях с синхронным версионированием.
 
-- `scope` задаёт соответствие названию аккаунта или организации в реестре NPM
+## 🚀 Быстрый старт
 
-- `scopeAsPackagePrefix` включает преобразование путей к модулям, добавляя указанный `scope` перед названием пакета. По умолчанию - `false`.
+**Запустите релиз**:
 
-Пример `scopeAsPackagePrefix` для пакета `@myscope/globals`:
-- `true` - расположение `packages/myscope-globals`,
-- `false` - расположение `packages/globals`.
+```sh
+pnpm mirta release
+```
+Выберите тип обновления → версии обновятся.
 
-Активация данной опции позволяет предотвратить коллизии со сторонними NPM-пакетами без `scope`.
+**Опубликуйте (в CI или локально)**:
 
-Если вам подходит стандартное поведение инструмента, создание отдельного файла конфигурации не требуется. Достаточно указать scope в основном файле `package.json` следующим образом:
+```sh
+pnpm mirta publish
+```
+Все публичные пакеты отправятся в NPM.
 
-```json
-{
-  "name": "@myscope/myproject"
-}
+**Разверните на контроллере**:
+
+```sh
+pnpm mirta deploy
 ```
+Синхронизирует файлы по профилю (по умолчанию — `default`).
 
-### Специальные опции фреймворка Мирта
+## 🧰 Команды
 
-- `templates` содержит набор путей к шаблонам мастера генерации проектов. Выполняет рекурсивный поиск файлов `package.json` в перечисленных расположениях.
+### `mirta [options]`
 
-Пример конфигурации Мирты:
+Эти глобальные опции работают для всех команд:
 
-```json
-{
-  "scopeAsPackagePrefix": true,
-  "templates": [
-    "packages/create-mirta/public/templates"
-  ]
-}
-```
+- `--help` (`-h`) — отображает справку по доступным командам и параметрам.
+- `--version` (`-v`) — выводит версию `@mirta/cli`.
+- `--locale <loc>` — задаёт язык интерфейса (`en`, `ru`).
 
-## Управление релизами
+### `pnpm mirta release`
 
-Выполнение процедуры выпуска релиза в интерактивном режиме:
+Подготавливает релиз: определяет текущую версию, предлагает выбрать тип обновления (`patch`, `minor`, `major`, `pre*`) и применяет его ко всем пакетам с полем `version`.
 
-```sh
-pnpm mirta release
-```
-Команда предложит выбрать подходящую версию, а если проект управляется Git, то подготовит список изменений в файле `CHANGELOG.md`, проверит CI-статус и создаст коммит.
+<details>
+<summary>Технические подробности</summary>
+
+Процесс разделён на этапы:
+
+#### Этап 1: Проверка git-состояния (если проект под git)
+- Синхронизация с `origin`.
+- Успешность CI (по workflow `build`).
 
-Во время работы с Git нужный репозиторий распознаётся автоматически, однако выполняются две проверки:
-1. Локальные изменения заранее синхронизированы с удалённым хранилищем;
-2. Процесс CI под названием `Build` для последнего коммита успешно завершён.
+#### Этап 2: Обновление зависимостей
+- Для путей из `mirta.config.json#project.templates`, рекурсивно обнаруживает `package.json`.
+- Зависимости монорепозитория (`dependencies`, `devDependencies`) обновляются до актуальной версии.
+
+#### Этап 3: Генерация CHANGELOG
+- Запускает `pnpm run changelog`, если такой скрипт существует.
+
+#### Этап 4: Фиксация изменений
+- При доступе к GitHub по `ssh` создаёт коммит и тег:
+   ```sh
+   git commit -m "release: vX.X.X"
+   git tag vX.X.X
+   ```
+- При доступе по `https` изменения остаются в рабочей директории для ручной фиксации.
+
+</details>
+
+#### Поддерживаемые опции
+
+`--dry-run` (`--dry`) — симуляция без применения изменений.
+
+`--preid` `<id>` — кастомный префикс преверсии (`alpha.0`, `beta.1`).
+
+`--skip-prompts` — пропускает интерактивные запросы.
+
+`--skip-git` — не создаёт коммит и тег.
+
+#### Частые вопросы
+
+<details>
+<summary>Почему версионирование синхронное?</summary>
+
+Все пакеты получают одинаковую версию при релизе. Это обеспечивает:
+- Гарантированную совместимость (`@mirta/cli@0.4.0` работает с `@mirta/package@0.4.0`),
+- Атомарность релиза,
+- Упрощение управления зависимостями.
+
+💡 При использовании `workspace:*` все ссылки заменяются на конкретную версию при релизе.
+
+</details>
+
+<details>
+<summary>Что такое «семантическая» версия?</summary>
+
+Формат `major.minor.patch`:
+- `major` — breaking changes,
+- `minor` — новые возможности без нарушения,
+- `patch` — исправления ошибок.
+
+Версии до `1.0.0` (например, `0.4.0`) считаются экспериментальными:<br/>
+любое обновление может включать breaking changes.
+
+Подробнее на сайте [semver.org](https://semver.org/lang/ru/)
+
+</details>
+
+<details>
+<summary>Как настроить генерацию CHANGELOG.md?</summary>
+
+Добавьте в dev-зависимости корневого `package.json` пакет `conventional-changelog-cli` и определите скрипт:
 
-Для генерации файла со списком изменений в dev-зависимости корневого `package.json` нужно добавить пакет [conventional-changelog-cli](https://www.npmjs.com/package/conventional-changelog-cli), а в секции `scripts` должна присутствовать команда `changelog`:
 ```json
 {
   "scripts": {
@@ -86,27 +140,31 @@ pnpm mirta release
 }
 ```
 
-Список изменений в автоматически генерируемом Changelog основывается на выполненных в пределах версии коммитах. При этом есть требования к заголовкам:
-
-1. Общая длина строки не должна превышать 50 символов;
-2. Использовать префиксы вида `fix:`, `feat:`, `docs:`, `chore:` и т.п.
+Список изменений формируется на основе коммитов. Требования к заголовкам:
+- Длина ≤ 50 символов,
+- Префиксы: `fix:`, `feat:`, `docs:`, `chore:` и др.
 
-Полный список требований смотреть в соглашении [Commit Convention](https://github.com/wb-mirta/core/blob/latest/.github/commit-convention.md) фреймворка.
+Подробнее: [Commit Convention](https://github.com/wb-mirta/core/blob/latest/.github/commit-convention.md)
 
-### Семантическое версионирование
+</details>
 
-Семантическая версия имеет вид `major.minor.patch` (например, `1.2.3`), где каждый сегмент обозначает разные уровни изменений:
+#### Расширенное управление
 
-- `major` увеличивается, когда вносятся несовместимые изменения;
-- `minor` увеличивается, когда добавляется новая функциональность, сохраняющая обратную совместимость;
-- `patch` увеличивается при исправлениях багов, сохраняя обратную совместимость.
+<details>
+<summary>Явное указание версии</summary>
 
-Релиз с указанием конкретной версии:
+Установит ровно ту версию, которая передана в качестве аргумента:
 
 ```sh
 pnpm mirta release 1.2.3
 ```
-Релиз с указанием инкрементируемой части:
+⚠️ **Не перезаписывайте опубликованные версии — NPM это запрещает.**
+
+</details>
+
+
+<details>
+<summary>Инкремент: patch, minor, major</summary>
 
 ```sh
 pnpm mirta release patch
@@ -120,56 +178,222 @@ pnpm mirta release minor
 pnpm mirta release major
 # 1.0.0
 ```
-Релиз предварительной версии с указанием типа:
+
+</details>
+
+<details>
+<summary>Преверсии: alpha, beta, rc</summary>
 
 ```sh
 pnpm mirta release prepatch --preid alpha
 # 0.0.1-alpha.0
 ```
+
 ```sh
 pnpm mirta release preminor --preid alpha
 # 0.1.0-alpha.0
 ```
+
 ```sh
 pnpm mirta release premajor --preid alpha
 # 1.0.0-alpha.0
 ```
-Инкремент уже существующей предварительной версии осуществляется через
+
+#### Инкремент преверсии
 
 ```sh
 pnpm mirta release prerelease --preid alpha
 # 0.0.1-alpha.1
 ```
 
-## Автоматическая публикация
+</details>
+
+---
+
+### `pnpm mirta publish`
+
+Публикует пакеты в NPM, пропуская `private: true`.
+
+<details>
+<summary>Технические подробности</summary>
+
+⚠️ Обычно запускается в CI после `git push` тега `vX.X.X`.
+
+Тег публикации определяется автоматически:
+- `alpha` → `--tag` `alpha`
+- `beta` → `--tag` `beta`
+- `rc` → `--tag` `rc`
+
+В CI добавляется `--provenance` для подтверждения происхождения.
+
+</details>
+
+#### Поддерживаемые опции
+
+- `--dry-run` (`--dry`) — симуляция.
+- `--skip-build` — пропускает `pnpm run build`.
+- `--skip-git` — отключает git-проверки (аналог `--no-git-checks` в `pnpm publish`).
+
+---
+
+### `pnpm mirta deploy`
+
+Синхронизирует файлы с контроллерами Wiren Board через `rsync` по SSH.
+
+<details>
+<summary>Технические подробности</summary>
+
+- Транспорт: `rsync -rtzgO` (рекурсивно, сжатие, сохранение времени и группы, без времени на папках).
+- Поддержка WSL2: на Windows команды выполняются внутри WSL.
+- Аутентификация:
+  - Через изолированный `ssh-agent`.
+  - Поддержка PKCS#11 (Rutoken) и SSH-ключей.
+  - `ttl` — время жизни ключа.
+- Режим `--dry-run`: показывает изменения без применения.
+- Симлинки не передаются.
+
+</details>
+
+#### Поддерживаемые опции
+
+- `--config`, `-c <path>` — путь к `mirta.config.json`.
+- `--profile`, `-p <name>` — профиль деплоя (по умолчанию: `default`).
+- `--to <conn>` — переопределение подключения.
+- `--dry-run` — симуляция синхронизации.
+
+Параметр `--to` принимает:
+- Название подключения из файла конфигурации `mirta.config.json`, 
+- Строку подключения, если она начинается с префикса `ssh://`.
+
+#### Переменные окружения и секреты
+
+Для безопасного хранения учётных данных используйте файл `.env.local` (игнорируется git):
+
+```sh
+# .env.local
+
+SSH_KEY=~/.ssh/id_ed25519
+
+# Доступно в конфигурации:
+WB_CONN_OPTIONS=`key=${SSH_KEY};ttl=1h30m`
+WB_CONN_WORK=`ssh://user@mycompany.local;${WB_CONN_OPTIONS}`
+```
+Поддерживаемые префиксы:
+- `WB_` — переменные, специфичные для CLI
+- `MIRTA_` — переменные для использования в любом контексте Mirta
+- `NODE_ENV` — стандартное значение окружения
+
+#### Формат строки подключения
+
+```sh
+ssh://[user@]host[:port][;param1=value1;param2=value2...]
+```
+Поддерживаемые параметры:
+
+| Параметр | Описание | Пример |
+|----------|---------|---------|
+| `pkcs11` | Путь к библиотеке PKCS#11 (Rutoken) | `pkcs11=/usr/lib/librtpkcs11ecp.so` |
+| `key` | Путь к SSH-ключу (ED25519, RSA) | `key=~/.ssh/id_ed25519` |
+| `ttl` | Время жизни ключа в ssh-agent | `ttl=1h` |
+| `wsl` | Дистрибутив WSL2 для Windows | `wsl=Debian` |
 
-Публикуйте готовые пакеты в репозиторий NPM:
+> Примечание: `pkcs11` имеет приоритет над `key`, если указаны одновременно.
+
+Примеры:
 
 ```sh
-pnpm mirta publish
+# SSH-ключ ED25519
+ssh://deploy@192.168.42.1;key=~/.ssh/id_ed25519;ttl=30m
+
+# PKCS#11 токен (Rutoken) с WSL2 на Windows
+ssh://deploy@192.168.42.1;pkcs11=/usr/lib/librtpkcs11ecp.so;wsl=Ubuntu-22.04
+
+# С переменными окружения
+ssh://deploy@${WB_HOST};key=${MIRTA_SSH_KEY}
 ```
-Операция запустит процедуру сборки и публикации готовых пакетов.
 
-Если процесс запущен через CI на GitHub, то к публикуемому пакету автоматически добавляется [информация о происхождении](https://docs.npmjs.com/generating-provenance-statements) каждого файла внутри пакета - хэш и метаданные, подтверждающие целостность и подлинность.
+<details>
+<summary>Нюансы PKCS#11</summary>
+
+Если `ssh-agent` выбрасывает ошибку `agent refused operation`:
+
+- Путь к модулю PKCS#11 должен быть реальным — симлинки отклоняются
+- Превышено число попыток ввода PIN-кода, токен заблокирован
 
-Основная цель опции заключается в повышении уровня доверия и безопасности публикуемых пакетов. Если пакет опубликован с использованием этой опции, пользователи смогут проверить, соответствует ли содержимое загруженного пакета оригинальному источнику, указанному автором.
+</details>
+
+#### Пример и описание структуры `mirta.config.json`
+
+```jsonc
+{
+  // Строки подключений к контроллерам
+  "connections": {
+    // Без подробностей в публичном репозитории
+    "work": "${WB_CONN_WORK}",
+    // Частичное сокрытие подробностей
+    "home": "ssh://user@192.168.42.1;${WB_CONN_OPTIONS};wsl=Ubuntu",
+  },
+  "deploy": {
+    // Наборы правил синхронизации
+    "mappings": {
+      "wb-rules-es5": [
+        {
+          // Локальная папка (относительно корня проекта)
+          "from": "dist/es5/wb-rules-rules",
+          // Целевая папка на контроллере
+          "to": "/mnt/data/etc/wb-rules-rules",
+          // Группа пользователей с доступом на контроллере (опционально)
+          "toGroup": "developers",
+          // Удалять файлы в целевой папке, если их нет в исходной
+          "cleanup": true,
+          // Список файлов и папок, которые нельзя удалять при cleanup: true
+          "protect": ["alarms.conf"]
+        },
+        // {
+        //   Следующее правило синхронизации...
+        // }
+      ]
+    },
+    // Заранее настроенные сценарии деплоя
+    "profiles": {
+      "default": {
+        // Массив имён наборов правил секции deploy.mappings
+        "mappings": ["wb-rules-es5"],
+        // Имя или строка подключения
+        "connection": "work",
+        // Группа пользователей с доступом на контроллере (опционально)
+        "toGroup": "developers"
+      }
+    }
+  }
+}
+```
 
-## Вспомогательные опции
+## ✅ Тестирование
 
-### Опции `release`
+Инструмент протестирован вручную и в CI:
+- Интерактивный и автоматический релиз.
+- Обработка ошибок (откат версий при сбое).
+- Проверка git-состояния и CI.
+- Поддержка `--dry-run`.
 
-`--dry` запускает команду в режиме симуляции ("dry run"), показывая изменения, которые будут произведены, но фактически ничего не меняя. Полезно для предварительного просмотра изменений перед применением.
+Дополнительные испытания:
 
-`--preid <custom-pre-release-id>` устанавливает кастомный префикс для предварительной версии, который добавляется к номеру версии пакета (например, beta.1). Эта опция позволяет создавать предварительные версии типа альфа, бета, RC и др. перед официальным стабильным выпуском.
+- Деплой с `Rutoken`, деплой с ключом `ED25519` в WSL2 под Windows и отдельно в Linux Debian (Trixie).
 
-`--skipPrompts` пропускает интерактивные запросы пользователя. Команда выполняется автоматически, используя значения по умолчанию или заданные настройки.
+## ⚠️ Ограничения
 
-`--skipGit` игнорирует действия, связанные с системой контроля версий Git, такие как фиксация изменений, создание меток коммитов или отправка изменений на удалённый репозиторий. Может пригодиться, если вы хотите самостоятельно управлять операциями с Git позже.
+**Работает только в Node.js** (не в Duktape).<br/>
+Автоматическое создание коммита и тега — только при `ssh`-подключении к GitHub.<br/>
+WSL2 требуется для деплоя под Windows.
 
-### Опции `publish`
+## 🛠 Конфигурация Mirta
 
-`--dry` запускает команду в режиме симуляции ("dry run"), показывая изменения, которые будут произведены, но фактически ничего не меняя. Полезно для предварительного просмотра изменений перед применением.
+Файл `mirta.config.json` настраивает поведение `@mirta/cli`.
 
-`--skipBuild` исключает запуск процесса сборки после обновления версий пакетов. Пропускает выполнение заданий, указанных в конвейере сборки, позволяя вам самим решать, необходима ли повторная компиляция после изменения номеров версий.
+Поддерживаемые поля:
 
-`--skipGit` игнорирует действия, связанные с системой контроля версий Git, такие как фиксация изменений, создание меток коммитов или отправка изменений на удалённый репозиторий. Может пригодиться, если вы хотите самостоятельно управлять операциями с Git позже.
+- `project.templates` — пути к шаблонам (например, для `create-mirta`).
+- `connections` — именованные подключения.
+- `deploy.mappings` — правила синхронизации.
+- `deploy.profiles` — профили деплоя.

package/dist/constants.mjs

@@ -0,0 +1,9 @@
+/**
+ * Имя текущего пакета.
+ *
+ * @since 0.4.0
+ *
+ **/
+const THIS_PACKAGE_NAME = '@mirta/cli';
+
+export { THIS_PACKAGE_NAME as T };