@mirta/cli 0.3.0

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,176 @@
+# @mirta/cli
+
+[![en](https://img.shields.io/badge/lang-en-olivedrab.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-dimgray.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 Downloads](https://img.shields.io/npm/dm/@mirta/cli?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/cli)
+
+Utility for efficient release management and automated package publishing in NPM, supports work in monorepositories.
+
+### Key Features
+
+- Convenient system for updating project versions;
+- Easy integration with existing CI/CD processes;
+- Access to all necessary operations through intuitive commands;
+- Support for customizing workflows specific to your infrastructure.
+
+## Installation and Initial Setup
+
+Add `@mirta/cli` as a development dependency to your project using the following command:
+
+```sh
+pnpm add -wD @mirta/cli
+```
+You can configure additional parameters by adding a configuration file named `mirta.config.json` at the root of your main project. For example:
+
+```json
+{
+  "scope": "myscope",
+  "scopeAsPackagePrefix": false
+}
+```
+### Main Configuration Options
+
+- `scope` sets the correspondence to an account or organization name in the NPM registry.
+  ```
+- `scopeAsPackagePrefix` enables transformation of module paths by prefixing the specified `scope` before the package name. Default is `false`.
+
+Example of `scopeAsPackagePrefix` for the package `@myscope/globals`:
+
+- `false` - location `packages/globals`
+- `true` - location `packages/myscope-globals`
+
+Activating this option helps prevent collisions with third-party NPM packages without a `scope`.
+
+If you are satisfied with the default behavior of the tool, creating a separate configuration file is not required. Simply specify the scope in the main `package.json` file like so:
+
+```json
+{
+  "name": "@myscope/myproject"
+}
+```
+
+### Special Mirta Framework Options
+
+- `templates` contains a set of paths to templates used by the project generation wizard. Performs recursive search for `package.json` files within the listed locations.
+
+Example Mirta configuration:
+
+```json
+{
+  "scopeAsPackagePrefix": true,
+  "templates": [
+    "packages/create-mirta/public/templates"
+  ]
+}
+```
+## Release Management
+
+Performing the release procedure interactively:
+
+```sh
+pnpm mirta release
+```
+The command will prompt you to select an appropriate version. If the project is managed by Git, it will prepare a list of changes in the `CHANGELOG.md` file, check the CI status, and create a commit.
+
+During operation with Git, the needed repository is automatically recognized, but two checks are performed:
+
+1. Local changes have been synchronized with the remote storage beforehand;
+2. The CI process named `Build` for the last commit has completed successfully.
+
+To generate a change log file, add the [conventional-changelog-cli](https://www.npmjs.com/package/conventional-changelog-cli) package as a dev dependency in the root `package.json`. Additionally, include a `changelog` script in the `scripts` section:
+
+```json
+{
+  "scripts": {
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
+  }
+}
+```
+The changelog entries are based on commits made within the version range. There are requirements for commit headers:
+
+1. Line length should not exceed 50 characters;
+2. Use prefixes such as `fix:`, `feat:`, `docs:`, `chore:`, etc.
+
+For the full list of requirements, refer to the framework's [Commit Convention](https://github.com/wb-mirta/core/blob/latest/.github/commit-convention.md).
+
+### Semantic Versioning
+
+A semantic version follows the format `major.minor.patch` (for example, `1.2.3`), where each segment represents different levels of changes:
+
+- `major` increases when incompatible changes are introduced;
+- `minor` increases when new functionality is added while maintaining backward compatibility;
+- `patch` increases when bug fixes are applied, preserving backward compatibility.
+
+Releasing with a specific version:
+
+```sh
+pnpm mirta release 1.2.3
+```
+Release specifying the incremented part:
+
+```sh
+pnpm mirta release patch
+# 0.0.1
+```
+```sh
+pnpm mirta release minor
+# 0.1.0
+```
+```sh
+pnpm mirta release major
+# 1.0.0
+```
+Pre-release version specifying the type:
+
+```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
+```
+Incrementing an already existing pre-release version is done via
+
+```sh
+pnpm mirta release prerelease --preid alpha
+# 0.0.1-alpha.1
+```
+## Automatic Publishing
+
+Publish ready-made packages to the NPM repository:
+
+```sh
+pnpm mirta publish
+```
+
+This operation will initiate the build and publication process for the prepared packages.
+
+If the process is triggered from a CI environment on GitHub, then every file inside the published package will be automatically enriched with [provenance information](https://docs.npmjs.com/generating-provenance-statements) - hash values and metadata that confirm its integrity and authenticity.
+
+The primary goal of this feature is to enhance trust and security for published packages. When a package is published using this option, users can verify whether the content of the downloaded package matches the original source provided by the author.
+
+## Auxiliary options
+
+### `release` options
+
+`--dry` runs the command in simulation mode ("dry run"), showing changes that would be made without actually applying them. Useful for previewing changes before application.
+
+`--preid <custom-pre-release-id>` sets a custom prefix for the pre-release version, which is appended to the package version number (e.g., beta.1). This option allows creating pre-release versions such as alpha, beta, RC, etc., before the official stable release.
+
+`--skipPrompts` skips interactive user queries. The command runs automatically using default values or predefined settings.
+
+`--skipGit` ignores actions related to the Git version control system, such as committing changes, creating commit tags, or pushing updates to a remote repository. Might be useful if you wish to manage Git operations manually later.
+
+### `publish` options
+
+`--dry` runs the command in simulation mode ("dry run"), showing changes that would be made without actually applying them. Useful for previewing changes before application.
+
+`--skipBuild` excludes running the build process after updating package versions. Skips executing tasks defined in the build pipeline, allowing you to decide whether recompilation is necessary after changing version numbers.
+
+`--skipGit` ignores actions related to the Git version control system, such as committing changes, creating commit tags, or pushing updates to a remote repository. Might be useful if you wish to manage Git operations manually later.

package/README.ru.md

@@ -0,0 +1,175 @@
+# @mirta/cli
+
+[![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 Downloads](https://img.shields.io/npm/dm/@mirta/cli?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/cli)
+
+Утилита для эффективного управления выпуском релизов и автоматизированной публикации пакетов в NPM, поддерживает работу в монорепозиториях.
+
+### Ключевые возможности
+
+- Удобная система обновления версий проектов;
+- Простая интеграция с существующими процессами CI/CD;
+- Доступ ко всем необходимым операциям через интуитивные команды;
+- Поддержка кастомизации рабочего потока под специфику вашей инфраструктуры.
+
+## Установка и начальная настройка
+
+Подключите `@mirta/cli` в ваш проект как dev-зависимость следующей командой:
+
+```sh
+pnpm add -wD @mirta/cli
+```
+Можно настроить дополнительные параметры, добавив файл конфигурации `mirta.config.json` в корень главного проекта. Например:
+
+```json
+{
+  "scope": "myscope",
+  "scopeAsPackagePrefix": false
+}
+```
+### Основные опции конфигурации
+
+- `scope` задаёт соответствие названию аккаунта или организации в реестре NPM
+
+- `scopeAsPackagePrefix` включает преобразование путей к модулям, добавляя указанный `scope` перед названием пакета. По умолчанию - `false`.
+
+Пример `scopeAsPackagePrefix` для пакета `@myscope/globals`:
+- `true` - расположение `packages/myscope-globals`,
+- `false` - расположение `packages/globals`.
+
+Активация данной опции позволяет предотвратить коллизии со сторонними NPM-пакетами без `scope`.
+
+Если вам подходит стандартное поведение инструмента, создание отдельного файла конфигурации не требуется. Достаточно указать scope в основном файле `package.json` следующим образом:
+
+```json
+{
+  "name": "@myscope/myproject"
+}
+```
+
+### Специальные опции фреймворка Мирта
+
+- `templates` содержит набор путей к шаблонам мастера генерации проектов. Выполняет рекурсивный поиск файлов `package.json` в перечисленных расположениях.
+
+Пример конфигурации Мирты:
+
+```json
+{
+  "scopeAsPackagePrefix": true,
+  "templates": [
+    "packages/create-mirta/public/templates"
+  ]
+}
+```
+
+## Управление релизами
+
+Выполнение процедуры выпуска релиза в интерактивном режиме:
+
+```sh
+pnpm mirta release
+```
+Команда предложит выбрать подходящую версию, а если проект управляется Git, то подготовит список изменений в файле `CHANGELOG.md`, проверит CI-статус и создаст коммит.
+
+Во время работы с Git нужный репозиторий распознаётся автоматически, однако выполняются две проверки:
+1. Локальные изменения заранее синхронизированы с удалённым хранилищем;
+2. Процесс CI под названием `Build` для последнего коммита успешно завершён.
+
+Для генерации файла со списком изменений в dev-зависимости корневого `package.json` нужно добавить пакет [conventional-changelog-cli](https://www.npmjs.com/package/conventional-changelog-cli), а в секции `scripts` должна присутствовать команда `changelog`:
+```json
+{
+  "scripts": {
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
+  }
+}
+```
+
+Список изменений в автоматически генерируемом Changelog основывается на выполненных в пределах версии коммитах. При этом есть требования к заголовкам:
+
+1. Общая длина строки не должна превышать 50 символов;
+2. Использовать префиксы вида `fix:`, `feat:`, `docs:`, `chore:` и т.п.
+
+Полный список требований смотреть в соглашении [Commit Convention](https://github.com/wb-mirta/core/blob/latest/.github/commit-convention.md) фреймворка.
+
+### Семантическое версионирование
+
+Семантическая версия имеет вид `major.minor.patch` (например, `1.2.3`), где каждый сегмент обозначает разные уровни изменений:
+
+- `major` увеличивается, когда вносятся несовместимые изменения;
+- `minor` увеличивается, когда добавляется новая функциональность, сохраняющая обратную совместимость;
+- `patch` увеличивается при исправлениях багов, сохраняя обратную совместимость.
+
+Релиз с указанием конкретной версии:
+
+```sh
+pnpm mirta release 1.2.3
+```
+Релиз с указанием инкрементируемой части:
+
+```sh
+pnpm mirta release patch
+# 0.0.1
+```
+```sh
+pnpm mirta release minor
+# 0.1.0
+```
+```sh
+pnpm mirta release major
+# 1.0.0
+```
+Релиз предварительной версии с указанием типа:
+
+```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
+```
+
+## Автоматическая публикация
+
+Публикуйте готовые пакеты в репозиторий NPM:
+
+```sh
+pnpm mirta publish
+```
+Операция запустит процедуру сборки и публикации готовых пакетов.
+
+Если процесс запущен через CI на GitHub, то к публикуемому пакету автоматически добавляется [информация о происхождении](https://docs.npmjs.com/generating-provenance-statements) каждого файла внутри пакета - хэш и метаданные, подтверждающие целостность и подлинность.
+
+Основная цель опции заключается в повышении уровня доверия и безопасности публикуемых пакетов. Если пакет опубликован с использованием этой опции, пользователи смогут проверить, соответствует ли содержимое загруженного пакета оригинальному источнику, указанному автором.
+
+## Вспомогательные опции
+
+### Опции `release`
+
+`--dry` запускает команду в режиме симуляции ("dry run"), показывая изменения, которые будут произведены, но фактически ничего не меняя. Полезно для предварительного просмотра изменений перед применением.
+
+`--preid <custom-pre-release-id>` устанавливает кастомный префикс для предварительной версии, который добавляется к номеру версии пакета (например, beta.1). Эта опция позволяет создавать предварительные версии типа альфа, бета, RC и др. перед официальным стабильным выпуском.
+
+`--skipPrompts` пропускает интерактивные запросы пользователя. Команда выполняется автоматически, используя значения по умолчанию или заданные настройки.
+
+`--skipGit` игнорирует действия, связанные с системой контроля версий Git, такие как фиксация изменений, создание меток коммитов или отправка изменений на удалённый репозиторий. Может пригодиться, если вы хотите самостоятельно управлять операциями с Git позже.
+
+### Опции `publish`
+
+`--dry` запускает команду в режиме симуляции ("dry run"), показывая изменения, которые будут произведены, но фактически ничего не меняя. Полезно для предварительного просмотра изменений перед применением.
+
+`--skipBuild` исключает запуск процесса сборки после обновления версий пакетов. Пропускает выполнение заданий, указанных в конвейере сборки, позволяя вам самим решать, необходима ли повторная компиляция после изменения номеров версий.
+
+`--skipGit` игнорирует действия, связанные с системой контроля версий Git, такие как фиксация изменений, создание меток коммитов или отправка изменений на удалённый репозиторий. Может пригодиться, если вы хотите самостоятельно управлять операциями с Git позже.

package/bin/mirta.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.mjs'

package/dist/github.mjs

@@ -0,0 +1,135 @@
+import p from 'prompts';
+import { r as runCommandAsync } from './shell.mjs';
+
+class PromptCanceledError extends Error {
+    constructor() {
+        super();
+        // Убедимся, что экземпляр имеет правильный прототип
+        Object.setPrototypeOf(this, PromptCanceledError.prototype);
+        this.name = 'PromptCanceledError';
+        Error.captureStackTrace(this, PromptCanceledError);
+    }
+}
+/**
+ * @param {import('prompts').PromptObject<string> | Array<import('prompts').PromptObject<string>>} questions
+ * @param {import('prompts').Options} options
+ */
+async function prompts(questions, options) {
+    const po = {
+        onCancel: () => {
+            throw new PromptCanceledError();
+        },
+    };
+    return await p(questions, po);
+}
+
+const baseUrl = 'https://api.github.com/repos';
+/** Класс ошибки уровня Git. */
+class GitError extends Error {
+    constructor(message) {
+        super(message);
+        // Убедимся, что экземпляр имеет правильный прототип
+        Object.setPrototypeOf(this, GitError.prototype);
+        this.name = 'GitError';
+        this.message = message;
+        Error.captureStackTrace(this, GitError);
+    }
+}
+/** Класс ошибки уровня взаимодействия GitHub. */
+class GithubError extends Error {
+    constructor(message) {
+        super(message);
+        // Убедимся, что экземпляр имеет правильный прототип
+        Object.setPrototypeOf(this, GithubError.prototype);
+        this.name = 'GithubError';
+        this.message = message;
+        Error.captureStackTrace(this, GithubError);
+    }
+}
+/** Класс ошибки уровня GitHub Workflow. */
+class WorkflowStatusError extends Error {
+    constructor(message) {
+        super(message);
+        // Убедимся, что экземпляр имеет правильный прототип
+        Object.setPrototypeOf(this, WorkflowStatusError.prototype);
+        this.name = 'WorkflowStatusError';
+        this.message = message;
+        Error.captureStackTrace(this, WorkflowStatusError);
+    }
+}
+/** Определяет, находится ли текущее решение в рабочем дереве Git. */
+async function checkIsInWorkTreeAsync() {
+    try {
+        const { stdout } = await runCommandAsync('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'pipe' });
+        return stdout === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+const getConnectionType = (url) => {
+    if (url.startsWith('git@'))
+        return 'ssh';
+    if (url.startsWith('https://'))
+        return 'https';
+};
+/** Возвращает имя репозитория и тип подключения. */
+async function getRepositoryDetails() {
+    const { stdout, stderr } = await runCommandAsync('git', ['config', 'remote.origin.url'], { stdio: 'pipe' });
+    if (stderr)
+        throw new GitError(stderr);
+    // Match the URLs like:
+    // git@github.com:wb-mirta/core.git
+    // https://github.com/wb-mirta/core.git
+    //
+    const regex = /^(?:git@|https:\/\/)(?:[^/:]+)[/:]?(.*?).git$/i;
+    const match = regex
+        .exec(stdout);
+    if (!match?.[1])
+        throw new GitError(`Unable to detect remote origin url`);
+    return {
+        name: match[1],
+        connectionType: getConnectionType(stdout),
+    };
+}
+/** Возвращает SHA текущего HEAD. */
+async function getShaAsync() {
+    return (await runCommandAsync('git', ['rev-parse', 'HEAD'])).stdout;
+}
+/** Возвращает имя текущей ветки. */
+async function getBranchAsync() {
+    return (await runCommandAsync('git', ['rev-parse', '--abbrev-ref', 'HEAD'])).stdout;
+}
+/** Проверяет, синхронизирован ли текущий HEAD с удаленным. */
+async function ensureIsSyncedWithRemoteAsync(repository) {
+    let isSynced = false;
+    try {
+        const branch = await getBranchAsync();
+        const remote = await fetch(`${baseUrl}/${repository}/commits/${branch}?per_page=1`);
+        const data = await remote.json();
+        isSynced = data.sha === await getShaAsync();
+    }
+    catch {
+        throw new GithubError('Failed to check whether local HEAD is up-to-date with remote');
+    }
+    if (!isSynced)
+        throw new GithubError('Local HEAD is not up-to-date with remote');
+}
+/** Проверяет успешность CI-построения последнего коммита. */
+async function ensureWorkflowResultAsync(repository, name) {
+    let isBuildPassed = false;
+    try {
+        const sha = await getShaAsync();
+        const result = await fetch(`${baseUrl}/${repository}/actions/runs?head_sha=${sha}&status=completed&exclude_pull_requests=true`);
+        const data = await result.json();
+        isBuildPassed = data.workflow_runs.some(({ name: workflowName, conclusion }) => workflowName.toLowerCase() === name.toLowerCase()
+            && conclusion === 'success');
+    }
+    catch {
+        throw new GithubError('Unable to get CI status for the current commit');
+    }
+    if (!isBuildPassed)
+        throw new WorkflowStatusError('CI build of the latest commit has not passed yet');
+}
+
+export { GitError as G, PromptCanceledError as P, WorkflowStatusError as W, GithubError as a, ensureWorkflowResultAsync as b, checkIsInWorkTreeAsync as c, ensureIsSyncedWithRemoteAsync as e, getRepositoryDetails as g, prompts as p };

package/dist/index.mjs

@@ -0,0 +1,46 @@
+import { g as getLocalized, S as ShellError, u as useLogger } from './shell.mjs';
+import { G as GitError, a as GithubError, W as WorkflowStatusError, P as PromptCanceledError } from './github.mjs';
+import 'node:child_process';
+import 'node:url';
+import 'node:fs';
+import 'node:path';
+import 'lodash.merge';
+import 'chalk';
+import 'prompts';
+
+const messages = await getLocalized();
+const logger = useLogger(messages);
+async function run() {
+    const command = process.argv[2];
+    if (command === 'release') {
+        await import('./release.mjs');
+    }
+    else if (command === 'publish') {
+        await import('./publish.mjs');
+    }
+}
+function prettify(message, name) {
+    if (name && message.startsWith(name))
+        return message.slice(name.length);
+    return message;
+}
+run().catch((e) => {
+    if (e instanceof GitError || e instanceof GithubError || e instanceof WorkflowStatusError || e instanceof ShellError) {
+        logger.error(prettify(e.message, e.name));
+    }
+    else if (e instanceof PromptCanceledError) {
+        logger.cancel(messages.errors.operationCanceled);
+    }
+    else if (e instanceof Error && 'code' in e) {
+        // if (e.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION')
+        // if (e.code === 'ENOENT')
+        logger.error(prettify(e.message, e.name));
+    }
+    else if (e instanceof Error) {
+        logger.error(prettify(e.message, e.name));
+    }
+    else if (typeof e === 'string') {
+        logger.error(e);
+    }
+    process.exit();
+});

package/dist/locales/en-US.json

@@ -0,0 +1,21 @@
+{
+  "validation": {
+    "required": "Must be provided"
+  },
+  "status": {
+    "info": "Info",
+    "note": "Note",
+    "success": "Success",
+    "warn": "Warn",
+    "error": "Error",
+    "canceled": "Canceled"
+  },
+  "accent": {
+    "recommended": "(recommended)",
+    "ifConfigured": "(if configured)"
+  },
+  "errors": {
+    "operationCanceled": "Operation canceled",
+    "rootIsNotRelative": "Location is out of working directory"
+  }
+}

package/dist/locales/ru-RU.json

@@ -0,0 +1,21 @@
+{
+  "validation": {
+    "required": "Требуется указать значение"
+  },
+  "status": {
+    "info": "Инфо",
+    "note": "Примечание",
+    "success": "Успешно",
+    "warn": "Внимание",
+    "error": "Ошибка",
+    "canceled": "Отменено"
+  },
+  "accent": {
+    "recommended": "(рекомендуется)",
+    "ifConfigured": "(если настроен)"
+  },
+  "errors": {
+    "operationCanceled": "Операция прервана",
+    "rootIsNotRelative": "Расположение находится вне рабочей директории"
+  }
+}