@mirta/cli 0.3.4 → 0.4.0

package/README.md

@@ -2,82 +2,125 @@
 
 [![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 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)
 
-Utility for efficient release management and automated package publishing in NPM, supports work in monorepositories.
+> Universal CLI tool for versioning, publishing, and deployment in monorepos with synchronized semantic versioning.
 
-### Key Features
+`@mirta/cli` is a process orchestrator that:
+- Synchronously updates versions across monorepo packages,
+- Runs `CHANGELOG` generation (if configured),
+- Publishes packages to NPM with `--provenance` support in CI,
+- Synchronizes artifacts with Wiren Board controllers via `rsync`.
 
-- 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.
+Works in any monorepo using `pnpm` and synchronized semantic versioning.
 
-## Installation and Initial Setup
+To recognize the monorepo structure, `@mirta/cli` relies on the packages `@mirta/workspace` and `@mirta/package`, which read the configuration from the workspaces field in the root `package.json`.
 
-Add `@mirta/cli` as a development dependency to your project using the following command:
+**Not intended for execution in Duktape environment on Wiren Board controllers.**
+
+## 📦 Installation
 
 ```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
-}
+✅ This package is designed for the Mirta framework but works in any `pnpm` monorepo with synchronized versioning.
+
+## 🚀 Quick Start
+
+**Run a release**:
+
+```sh
+pnpm mirta release
 ```
-### Main Configuration Options
+Select the update type → versions will be updated.
 
-- `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`.
+**Publish (in CI or locally)**:
 
-Example of `scopeAsPackagePrefix` for the package `@myscope/globals`:
+```sh
+pnpm mirta publish
+```
+All public packages will be published to NPM.
 
-- `false` - location `packages/globals`
-- `true` - location `packages/myscope-globals`
+## 🧰 Commands
 
-Activating this option helps prevent collisions with third-party NPM packages without a `scope`.
+### `mirta [options]`
 
-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:
+These global options are available for all commands:
+- `--help` (`-h`) — displays help on available commands and options.
+- `--version` (`-v`) — prints `@mirta/cli` version.
+- `--locale <loc>` — sets the interface language (`en`, `ru`).
 
-```json
-{
-  "name": "@myscope/myproject"
-}
-```
+### `pnpm mirta release`
 
-### Special Mirta Framework Options
+Prepares a release: detects the current version, prompts to select an update type (`patch`, `minor`, `major`, `pre*`), and applies it to all packages with the `version` field.
 
-- `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.
+<details>
+<summary>Technical Details</summary>
 
-Example Mirta configuration:
+The process is divided into stages:
 
-```json
-{
-  "scopeAsPackagePrefix": true,
-  "templates": [
-    "packages/create-mirta/public/templates"
-  ]
-}
-```
-## Release Management
+#### Stage 1: Git state check (if project is under git)
+- Ensures synchronization with `origin`.
+- Verifies CI success (via `build` workflow).
 
-Performing the release procedure interactively:
+#### Stage 2: Dependency update
+- Recursively discovers `package.json` in paths specified in `mirta.config.json#project.templates`.
+- Updates monorepo dependencies (`dependencies`, `devDependencies`) to the current version.
 
-```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.
+#### Stage 3: CHANGELOG generation
+- Runs `pnpm run changelog` if the script exists.
 
-During operation with Git, the needed repository is automatically recognized, but two checks are performed:
+#### Stage 4: Commit and tag
+- If GitHub access is via `ssh`, creates a commit and tag:
+  ```sh
+  git commit -m "release: vX.X.X"
+  git tag vX.X.X
+  ```
+- If access is via `https`, changes remain in the working directory for manual commit.
 
-1. Local changes have been synchronized with the remote storage beforehand;
-2. The CI process named `Build` for the last commit has completed successfully.
+</details>
 
-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:
+#### Supported Options
+
+- `--dry-run` (`--dry`) — simulation mode, shows changes without applying them.
+- `--preid` `<id>` — custom prerelease identifier (`alpha.0`, `beta.1`).
+- `--skip-prompts` — skips interactive prompts, uses defaults.
+- `--skip-git` — skips commit and tag creation.
+
+#### Frequently Asked Questions
+
+<details>
+<summary>Why synchronized versioning?</summary>
+
+All packages receive the same version on release. This ensures:
+- Guaranteed compatibility (`@mirta/cli@0.4.0` works with `@mirta/package@0.4.0`),
+- Atomic releases,
+- Simplified dependency management.
+
+💡 When using `workspace:*`, all references are replaced with the concrete version during release.
+
+</details>
+
+<details>
+<summary>What is "semantic" versioning?</summary>
+
+Format: `major.minor.patch`:
+- `major` — breaking changes,
+- `minor` — new features without breaking compatibility,
+- `patch` — bug fixes.
+
+Versions below `1.0.0` (e.g., `0.4.0`) are experimental: any update may include breaking changes.
+
+More: [semver.org](https://semver.org/)
+
+</details>
+
+<details>
+<summary>How to set up CHANGELOG.md generation?</summary>
+
+Add `conventional-changelog-cli` to devDependencies in the root `package.json` and define the script:
 
 ```json
 {
@@ -86,90 +129,264 @@ To generate a change log file, add the [conventional-changelog-cli](https://www.
   }
 }
 ```
-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.
+The changelog is generated from commit messages. Requirements:
+- Subject line ≤ 50 characters,
+- Use prefixes: `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).
+See: [Commit Convention](https://github.com/wb-mirta/core/blob/latest/.github/commit-convention.md)
 
-### Semantic Versioning
+</details>
 
-A semantic version follows the format `major.minor.patch` (for example, `1.2.3`), where each segment represents different levels of changes:
+#### Advanced Usage
 
-- `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.
+<details>
+<summary>Explicit version</summary>
 
-Releasing with a specific version:
+Sets the exact version passed as an argument:
 
 ```sh
 pnpm mirta release 1.2.3
 ```
-Release specifying the incremented part:
+⚠️ **Never overwrite published versions — NPM will reject them.**
+
+</details>
+
+<details>
+<summary>Increment: patch, minor, major</summary>
 
 ```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:
+</details>
+
+<details>
+<summary>Pre-releases: 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
 ```
-Incrementing an already existing pre-release version is done via
+
+#### Incrementing pre-release version
 
 ```sh
 pnpm mirta release prerelease --preid alpha
 # 0.0.1-alpha.1
 ```
-## Automatic Publishing
+</details>
+
+---
+
+### `pnpm mirta publish`
+
+Publishes packages to NPM, skipping those with `private: true`.
+
+<details>
+<summary>Technical Details</summary>
+
+⚠️ Typically runs in CI after `git push` of the `vX.X.X` tag.
+
+The publish tag is determined automatically:
+- `alpha` → `--tag alpha`
+- `beta` → `--tag beta`
+- `rc` → `--tag rc`
+
+In CI, `--provenance` is added to attest package origin.
+
+</details>
+
+#### Supported Options
+
+- `--dry-run` (`--dry`) — simulation mode.
+- `--skip-build` — skips running `pnpm run build`.
+- `--skip-git` — disables git checks (equivalent to `--no-git-checks` in `pnpm publish`).
+
+---
+
+### `pnpm mirta deploy`
+
+Synchronizes files with Wiren Board controllers via `rsync` over SSH.
+
+<details>
+<summary>Technical Details</summary>
+
+- Transport: `rsync -rtzgO` (recursive, compressed, preserves timestamps and group, omits directory timestamps — safe for overlayfs).
+- WSL2 support: on Windows, commands run inside WSL.
+- Authentication:
+  - Uses an isolated `ssh-agent`.
+  - Supports PKCS#11 (Rutoken) and SSH keys.
+  - `ttl` — key lifetime (e.g., `1h`).
+- `--dry-run` mode: shows changes without applying.
+- Symbolic links are not transferred — should be created on the controller manually.
+
+</details>
+
+#### Supported Options
+
+- `--config`, `-c <path>` — path to `mirta.config.json`.
+- `--profile`, `-p <name>` — deployment profile (default: `default`).
+- `--to <conn>` — override connection string.
+- `--dry-run` — simulate synchronization.
+Parameter `--to` accepts:
+- Connection name from `mirta.config.json`,
+- Connection string starting with `ssh://`.
+
+#### Environment variables and secrets
+
+For secure credential storage, use `.env.local` (git-ignored):
+
+```sh
+# .env.local
+
+SSH_KEY=~/.ssh/id_ed25519
+
+# Available in config:
+WB_CONN_OPTIONS=`key=${SSH_KEY};ttl=1h30m`
+WB_CONN_WORK=`ssh://user@mycompany.local;${WB_CONN_OPTIONS}`
+```
+
+Supported prefixes:
+- `WB_` — CLI-specific variables
+- `MIRTA_` — general Mirta context
+- `NODE_ENV` — standard environment value
 
-Publish ready-made packages to the NPM repository:
+#### Connection string format
 
 ```sh
-pnpm mirta publish
+ssh://[user@]host[:port][;param1=value1;param2=value2...]
+```
+
+Supported parameters:
+
+| Parameter | Description | Example |
+|---------|-------------|---------|
+| `pkcs11` | Path to PKCS#11 library (Rutoken) | `pkcs11=/usr/lib/librtpkcs11ecp.so` |
+| `key` | Path to SSH key (ED25519, RSA) | `key=~/.ssh/id_ed25519` |
+| `ttl` | Key lifetime in ssh-agent | `ttl=1h` |
+| `wsl` | WSL2 distribution for Windows | `wsl=Debian` |
+
+> Note: `pkcs11` takes precedence over `key` if both are specified.
+
+Examples:
+
+```sh
+# ED25519 SSH key
+ssh://deploy@192.168.42.1;key=~/.ssh/id_ed25519;ttl=30m
+```
+
+```sh
+# PKCS#11 token (Rutoken) with WSL2 on Windows
+ssh://deploy@192.168.42.1;pkcs11=/usr/lib/librtpkcs11ecp.so;wsl=Ubuntu-22.04
+```
+
+```sh
+# With environment variables
+ssh://deploy@${WB_HOST};key=${MIRTA_SSH_KEY}
 ```
 
-This operation will initiate the build and publication process for the prepared packages.
+<details>
+<summary>PKCS#11 nuances</summary>
+
+If `ssh-agent` throws `agent refused operation`:
 
-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.
+- PKCS#11 module path must be real — symlinks are rejected
+- PIN code attempt limit exceeded, token is locked
 
-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.
+</details>
 
-## Auxiliary options
+#### Example and structure of `mirta.config.json`
+
+```jsonc
+{
+  // Connection strings to controllers
+  "connections": {
+    // Omitted details in public repository
+    "work": "${WB_CONN_WORK}",
+    // Partial detail hiding
+    "home": "ssh://user@192.168.42.1;${WB_CONN_OPTIONS};wsl=Ubuntu"
+  },
+  "deploy": {
+    // File sync rule sets
+    "mappings": {
+      "wb-rules-es5": [
+        {
+          // Local folder (relative to project root)
+          "from": "dist/es5/wb-rules-rules",
+          // Target folder on controller
+          "to": "/mnt/data/etc/wb-rules-rules",
+          // User group with access on controller (optional)
+          "toGroup": "developers",
+          // Delete files in target if missing in source
+          "cleanup": true,
+          // List of files/dirs to protect from deletion when cleanup: true
+          "protect": ["alarms.conf"]
+        },
+        // {
+        //   Next sync rule...
+        // }
+      ]
+    },
+    // Predefined deployment profiles
+    "profiles": {
+      "default": {
+        // Array of rule set names from deploy.mappings
+        "mappings": ["wb-rules-es5"],
+        // Connection name or string
+        "connection": "work",
+        // User group with access on controller (optional)
+        "toGroup": "developers"
+      }
+    }
+  }
+}
+```
 
-### `release` options
+## ✅ Testing
 
-`--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.
+The tool has been tested manually and in CI:
+- Interactive and automated releases.
+- Error handling (version rollback on failure).
+- Git state and CI checks.
+- Support for `--dry-run`.
 
-`--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.
+Additional tests:
+- Deployment using `Rutoken`, deployment with `ED25519` key in WSL2 on Windows and standalone Linux Debian (Trixie).
 
-`--skipPrompts` skips interactive user queries. The command runs automatically using default values or predefined settings.
+## ⚠️ Limitations
 
-`--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.
+**Runs only in Node.js** (not in Duktape).<br/>
+Automatic commit and tag creation works only with `ssh` access to GitHub.<br/>
+WSL2 is required for deployment from Windows.
 
-### `publish` options
+## 🛠 Mirta Configuration
 
-`--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.
+The `mirta.config.json` file configures `@mirta/cli` behavior.
 
-`--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.
+Supported fields:
 
-`--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.
+- `project.templates` — paths to templates (e.g., for `create-mirta`).
+- `connections` — named connections.
+- `deploy.mappings` — file sync rules.
+- `deploy.profiles` — deployment profiles.