@cmflow/cli 3.4.0-alpha.1 → 3.4.0-alpha.5

package/README.md

@@ -1,362 +1,178 @@
-<h1 style="text-align: center" align="center">@clubmed/cli aka ClubMed Flow </h1>
-
 <div align="center">
-
+  <img src="https://ns.clubmed.com/fbs/RWD/branding2023/Logo/MicrosoftTeams-image%20(9).png" width="200" alt="Club Med" />
+  <h1>@cmflow/cli</h1>
    <hr />
 
-[![npm version](https://badge.fury.io/js/%40cmflow%cli.svg)](https://badge.fury.io/js/%40cmflow%2Fcli)
+[![npm version](https://badge.fury.io/js/%40cmflow%2Fcli.svg)](https://badge.fury.io/js/%40cmflow%2Fcli)
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
-[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
-
+[![code style: oxfmt](https://img.shields.io/badge/code_style-oxfmt-ef4444.svg?style=flat-square)](https://oxc.rs/docs/guide/usage/formatter)
 </div>
 
-<hr />
-
-```
-npm i -g @cmflow/cli
-```
-
-## CmFlow release using Semantic Release
+Club Med Flow command-line tooling for Git Flow, Semantic Release and publishing Yarn workspace packages.
 
-### Installation
+## Installation
 
-CmFlow is compatible with [semantic-release](https://github.com/semantic-release/semantic-release) 📦🚀. You can use
-CmFlow release to deploy your projects based on CmFlow convention.
+Install globally for the Git Flow commands:
 
-Add the cmflow to your project:
-
-```sh
-npm i --save-dev @cmflow/cli
+```bash
+npm install --global @cmflow/cli
+cm --help
 ```
 
-Edit your `package.json` and add the following configuration:
+Install it as a development dependency when a project uses its release plugins or package-artifact commands:
 
-```json
-{
-  "flow": {
-    "branch": {
-      "develop": "master",
-      "production": "master"
-    }
-  }
-}
+```bash
+npm install --save-dev @cmflow/cli
 ```
 
-Then create `release.config.js` with this configuration:
+## Git Flow commands
 
-```javascript
-import { defineConfig } from "@cmflow/cli";
+`cm` provides commands for starting, finishing, pushing, pulling, merging, rebasing and deploying branches, plus release and Jira helpers.
 
-export default defineConfig({
-  verifyConditions: ["@cmflow/cli/semantic/core/verify-conditions"],
-  analyzeCommits: ["@cmflow/cli/semantic/core/analyze-commits"],
-  verifyRelease: ["@cmflow/cli/semantic/core/verify-release"],
-  generateNotes: [
-    [
-      "@cmflow/cli/semantic/conditional", // add this task to trigger build npm task
-      {
-        // when: (context) => context.branch.type === "release" //  default condition to run the task
-        run: ["@semantic-release/core/release-notes-generator"]
-      }
-    ]
-  ],
-  prepare: [
-    "@cmflow/cli/semantic/core/prepare/bump-version",
-    [
-      "@cmflow/cli/semantic/core/prepare/run", // add this task to trigger build npm task
-      {
-        command: "build"
-      }
-    ],
-    [
-      "@cmflow/cli/semantic/core/prepare/run", // add this task to trigger build npm task
-      {
-        command: "test_e2e"
-      }
-    ],
-    [
-      "@cmflow/cli/semantic/core/conditional", // add this task to trigger build npm task
-      {
-        // when: (context) => context.branch.type === "release" //  default condition to run the task
-        run: ["@cmflow/cli/semantic/core/prepare/commit"]
-      }
-    ]
-  ],
-  publish: [
-    [
-      "@cmflow/cli/semantic/core/conditional",
-      {
-        // when: (context) => context.branch.type === "release" //  default condition to run the task
-        run: ["@cmflow/cli/semantic/core/sync-repository", "@semantic-release/github"] // only run if the conditional rule is true
-      }
-    ],
-    [
-      "@cmflow/cli/semantic/core/exit", // run process.exit(0) if the branch is not a release branch - legacy: maybe not necessary now all task are conditional
-      {
-        when: (context) => context.nextRelease.channel === "prerelease"
-      }
-    ]
-  ],
-  success: [
-    [
-      "@cmflow/cli/semantic/core/conditional",
-      {
-        // when: (context) => context.branch.type === "release" //  default condition to run the task
-        run: "@semantic-release/github" // only run if the conditional rule is true
-      }
-    ]
-  ],
-  fail: [
-    [
-      "@cmflow/cli/semantic/core/conditional",
-      {
-        // when: (context) => context.branch.type === "release" //  default condition to run the task
-        run: "@semantic-release/github" // only run if the conditional rule is true
-      }
-    ]
-  ],
-  npmPublish: false
-});
+```bash
+cm --help
+cm start --help
+cm finish --help
+cm deploy --help
 ```
 
-Then edit your `package.json` add the following tasks on script property:
+### Jira releases
 
-```json
-{
-  "script": {
-    "release": "cmrelease",
-    "release:dry_run": "cmrelease --dry-run"
-  }
-}
-```
-
-Now, CmFlow and semantic release are correctly installed on your project.
+`jira-releases` lists release versions for a Jira project and component, generates delivery notes, and can mark versions as released.
 
-### Condition step (publish, success, fail)
-
-CMFlow provide a `@cmflow/cli/semantic/core/conditional` task to run one task or many task only if a condition is true. The condition is a
-function that takes the semantic context as parameter and return a boolean.
-
-You can customize the condition to run the task by adding a `when` property to the configuration object.
-
-```javascript
-export default defineConfig({
-  publish: [
-    "@cmflow/cli/semantic/core/conditional",
-    {
-      when: (context) => context.branch.type === "release", //  default condition to run the task
-      run: ["@semantic-release/github", "@semantic-release/github"] // only run if the conditional rule is true
-    }
-  ]
-});
+```bash
+cm jira-releases --project-id <PROJECT_KEY> --component <COMPONENT> --tag <VERSION> [--update] [--verbose]
 ```
 
-### Sync repository plugin (@cmflow/cli/semantic/core/sync-repository)
-
-This plugin synchronizes your remote repository after publishing:
+It requires `JIRA_API`, `JIRA_EMAIL` and `JIRA_TOKEN`. Directus workflow support is optional and uses `DIRECTUS_URL`, `DIRECTUS_FLOW_ID` and `DIRECTUS_ACCESS_TOKEN`. Run without `--update` first to review the selected versions.
 
-- It pushes the current branch to the remote (with --set-upstream) if it is part of the candidate branches.
-- It then synchronizes the development branch with the production branch if they are different.
+## Monorepo package artifacts
 
-Options:
+`cm packages build` creates the npm-ready artifacts of a Yarn-workspace monorepo. It performs the following steps:
 
-- pluginOptions.branches: Allows you to explicitly define the list of branches that must be pushed to synchronize the remote. Example:
+1. Cleans the configured output directory.
+2. Runs the configured build script.
+3. Copies non-private workspace packages into `dist/<package-name>`.
+4. Writes package manifests with the release version and rewritten internal dependencies.
 
-```javascript
-export default defineConfig({
-  publish: [
-    [
-      "@cmflow/cli/semantic/core/conditional",
-      {
-        run: [["@cmflow/cli/semantic/core/sync-repository", { includes: ["main", "develop", "release"] }], "@semantic-release/github"]
-      }
-    ]
-  ]
-});
+```bash
+cm packages build
+cm packages build --version 3.4.0-alpha.3
 ```
 
-Default behavior:
-
-- If pluginOptions.branches is not provided, the plugin falls back to semantic-release's branches configuration (options.branches). Values can be strings or branch objects; in the latter case, only the branch name is used.
+The default output is `dist`. Private workspaces are never included in the artifacts or published. If `--version` is omitted, the current root `package.json` version is retained.
 
-Notes:
+`cm packages build` is invoked by the Semantic Release `prepare` step for the `cmflow` bump method. Do not add it to the release command: Semantic Release owns the artifact lifecycle.
 
-- PRODUCTION_BRANCH and DEVELOP_BRANCH are defined via the CmFlow configuration (flow.branch.production and flow.branch.develop) and are used for the synchronization between production and develop.
-
-### Build and E2E Test
-
-CmFlow release is able to run `build` and `test_e2e` task during the `prepare` step. It's useful when you want to
-deploy a docker image on docker hub with the right revision number in the `package.json`. The only requirement, is to
-have a `build` and `test_e2e` tasks in you npm scripts.
-
-Example:
+Use a dedicated script only to verify artifact generation locally or in a pre-release CI check:
 
 ```json
 {
   "scripts": {
-    "build": "docker-compose build",
-    "test_e2e": "docker-compose up -d && sleep 10 && npm run test_cucumber && docker-compose stop"
+    "artifacts:prepare": "yarn build && cm packages build"
   }
 }
 ```
 
-Then:
-
-```javascript
-export default defineConfig({
-  prepare: [
-    [
-      "@cmflow/cli/semantic/core/run",
-      {
-        command: "build"
-      }
-    ],
-    [
-      "@cmflow/cli/semantic/core/run",
-      {
-        command: "test_e2e"
-      }
-    ]
-  ]
-});
-```
-
-### Generate release.info file
+## `flow` configuration
 
-CmFlow release generate a `release.info` file in the root of your project. This file contains the branch name.
+Configure package build and publication defaults in the root `package.json`:
 
-```js
-import { defineConfig } from "@cmflow/cli";
-
-export default defineConfig({
-  prepare: [
-    "@cmflow/cli/semantic/prepare/bump-version",
-    [
-      "@cmflow/cli/semantic/prepare/release-info",
-      {
-        path: "./resources/release.info"
-      }
-    ]
-  ]
-});
+```json
+{
+  "workspaces": ["packages/*"],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "flow": {
+    "outputDir": "dist",
+    "buildCmd": "build",
+    "npmAccess": "public",
+    "npmDistTag": "next",
+    "npmFallbackDistTag": "latest",
+    "registries": [],
+    "skipNpmPublish": false,
+    "trustedPublishing": true
+  }
+}
 ```
 
-### Deploy on Docker Hub
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `outputDir` | `dist` | Destination directory for generated package artifacts. |
+| `buildCmd` | `build` | Root package script run by `cm packages build`. |
+| `npmAccess` | `public` | npm access passed to `npm publish`. |
+| `npmDistTag` | `publishConfig.tag` | Dist-tag written in generated package manifests. |
+| `npmFallbackDistTag` | `latest` | Tag used when npm rejects an implicit `latest` tag. |
+| `registries` | `[]` | Additional registries to publish to. |
+| `skipNpmPublish` | `false` | Builds release artifacts but skips npm publication. |
+| `trustedPublishing` | `false` | Enables npm trusted publishing; no npmjs token is written to `.npmrc`. |
 
-Add the following configuration to your `release.config.js`:
+A workspace package may set its own `flow.registries` array to replace the root registries for that package.
 
-```js
-import { defineConfig } from "@cmflow/cli";
+## Semantic Release
 
-export default defineConfig({
-  publish: ["@cmflow/cli/semantic/docker/publish"]
-});
+Use `cmrelease` to run Semantic Release:
+
+```json
+{
+  "scripts": {
+    "release": "cmrelease",
+    "release:dry_run": "cmrelease --dry-run"
+  }
+}
 ```
 
-### Publish & Clean docker tags
+For a workspace release, the publish sequence must push the release branch and tag before npm publication:
 
 ```js
 import { defineConfig } from "@cmflow/cli";
 
 export default defineConfig({
-  success: ["@cmflow/cli/semantic/docker/success"]
+  prepare: [
+    "@cmflow/cli/semantic/core/prepare/bump-version",
+    "@cmflow/cli/semantic/core/prepare/commit"
+  ],
+  publish: [
+    "@cmflow/cli/semantic/core/push-release",
+    "@cmflow/cli/semantic/core/publish-packages",
+    "@cmflow/cli/semantic/core/sync-repository"
+  ],
+  npmPublish: false
 });
 ```
 
-### Configure CI
-
-CmFlow release can be used with Travis CI, Circle CI and GitLab. You have to create these environments variables to
-allow git release note deployment, commit push and docker image deployment.
-
-| Variable              | Description                                                                                                                     |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| PROJECT_NAME          | The project to publish artifact on docker                                                                                       |
-| SCM_TOKEN             | A SCM Token (GH_TOKEN or GITLAB_TOKEN)                                                                                          |
-| GH_TOKEN (deprecated) | A GitHub token [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line). |
-| GIT_USER_EMAIL        | User mail to sign the commit produced by CmFlow release                                                                         |
-| GIT_USER_NAME         | User name to sign the commit produced by CmFlow release                                                                         |
-| DOCKER_HUB_ID         | The docker hub id                                                                                                               |
-| DOCKER_HUB_PWD        | The docker password account                                                                                                     |
-
-## Jira Releases Command
-
-The `jira-releases` command lists and (optionally) updates Jira versions related to an application version, then generates a share-ready delivery note.
-
-### Goal
-
-- For a given Jira project and component, retrieve all versions whose number is less than or equal to a target tag/version.
-- Display the issues associated with those versions and produce a delivery note.
-- Optionally mark the versions as "released" (with today's date) and move the corresponding issues to the "Livré en production" state.
-- Optionally trigger a CMS (Directus) workflow if configuration is provided.
-
-### Prerequisites
+`push-release` pushes the branch and release tag first. `publish-packages` publishes only non-private generated artifacts. It supports npmjs, GitHub Packages and additional registries; `trustedPublishing` uses npm’s OIDC-based trusted publishing flow. During a dry run, packages are packed but never published.
 
-- Access to the Jira API via environment variables:
-  - `JIRA_API` (e.g., https://your-instance.atlassian.net)
-  - `JIRA_EMAIL`
-  - `JIRA_TOKEN` (API token)
-  - Optional: `HTTPS_PROXY` if you need a proxy
-- Optional (to trigger a Directus workflow):
-  - `DIRECTUS_URL`
-  - `DIRECTUS_FLOW_ID`
-  - `DIRECTUS_ACCESS_TOKEN`
+For CircleCI, export the OIDC token in each job that runs a real release:
 
-If all three Directus variables are present, `CmFlow` considers `CAN_TRIGGER_WORKFLOW=true` and will attempt to run the workflow after updating releases.
-
-### Usage
-
-```sh
-cm jira-releases --project-id <PROJECT_KEY> --component <COMPONENT> --tag <VERSION> [--update] [--verbose]
+```yaml
+- run:
+    name: Cm Release
+    command: |
+      export NPM_ID_TOKEN=$(circleci run oidc get --claims '{"aud":"npm:registry.npmjs.org"}')
+      yarn release
 ```
 
-Aliases and options (from `bin/cm-jira-releases.js`):
-
-- `-c, --component <component>`: Jira component filter (e.g., `API`).
-- `-c, --project-id <projectId>`: Jira project key (e.g., `CMAB`).
-- `-t, --tag <tag>`: target version to analyze (e.g., `0.3241.3`, `v0.3241.3`, or `version-0.3241.3`). `v` and `version-` prefixes are automatically ignored.
-- `-u, --update`: updates Jira (marks the version(s) as released with today's date and moves the issues).
-- `-v, --verbose`: verbose logs.
-
-Note: Jira versions are expected to follow `<COMPONENT>-<version>` or similar. For example, if `--component API` and a Jira version is named `API-0.3241.3`, the `0.3241.3` part will be compared to `--tag` using semver.
-
-### Detailed behavior
+Each npm package must also be configured with a CircleCI trusted publisher and allow the `npm publish` action. The Organization ID, Project ID, Pipeline definition ID and VCS origin configured on npm must match the CircleCI project exactly. [npm’s CircleCI trusted publishing guide](https://docs.npmjs.com/trusted-publishers/) details the required values.
 
-1. Fetch all Jira versions for the project (`projectId`).
-2. Keep those whose version (after stripping `component-`, `version-`, and `v` prefixes) is semver <= the provided `--tag`.
-3. Print the delivery note to stdout (example below).
-4. If `--update` is provided:
-   - Mark the relevant version(s) as `released=true` with `releaseDate=YYYY-MM-DD` (today's date).
-5. If the Directus config is complete, trigger the workflow by passing the list of `version` values for the processed releases.
+## Atlas
 
-> Important: moving issue isn't supported from the cmflow. You have to create a jira automation script to move the issue on your board.
+API-to-backend catalogue tooling is published separately as [`@cmflow/atlas`](../atlas). Its project configuration is `atlas.config.ts`; it does not belong in this repository or in this CLI package.
 
-### Example
+## Development
 
-From this repo, a sample script is provided in `package.json`:
+From the monorepo root:
 
-```sh
-yarn jira:releases
+```bash
+yarn workspace @cmflow/cli build
+yarn workspace @cmflow/cli test
+yarn check
 ```
 
-which runs, with `.env` loaded:
-
-```sh
-node --env-file=.env bin/cm.js jira-releases \
-  --project-id CMAB \
-  --component API \
-  --tag 0.3241.3 \
-  --verbose
-```
-
-Raw CLI example:
-
-```
-cm jira-releases --project-id CMAB --component API --tag v0.3241.3 --update
-```
+## License
 
-### Best practices
+The MIT License (MIT)
+Copyright (c) 2016 - Today ClubMed
 
-- Use a valid semver `--tag` (the `v`/`version-` prefixes are accepted).
-- Ensure your Jira versions follow a consistent schema that includes the component (`<COMPONENT>-<version>`) to allow matching.
-- First run without `--update` to preview the note and verify selected versions and issues.
-- Provide `HTTPS_PROXY` if your environment requires it to reach Jira/Directus.
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.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 OR COPYRIGHT HOLDERS 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.