@cmflow/cli 2.2.5 → 2.3.0

package/README.md

@@ -191,7 +191,7 @@ Notes:
 
 ### Build and E2E Test
 
-CmFlow release are able to run `build` and `test_e2e` task during the prepare step. It's useful when you want to
+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.
 
@@ -287,3 +287,103 @@ allow git release note deployment, commit push and docker image deployment.
 | 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
+- 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`
+
+If all 3 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]
+```
+
+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
+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. For each selected version, fetch related issues and prepare a delivery note by type:
+   - `Story` → `feat`
+   - `Sous-tâche` → `tech`
+   - `Tâche` → `chore`
+   - `Bug` → `fix`
+4. Print the delivery note to stdout (example below).
+5. If `--update` is provided:
+   - Mark the relevant version(s) as `released=true` with `releaseDate=YYYY-MM-DD` (today's date).
+   - Move each related issue to the Jira state `id=18`, `name="Livré en production"` (transition errors are logged but won't stop the whole process).
+6. If the Directus config is complete, trigger the workflow by passing the list of `version` values for the processed releases.
+
+### Example
+
+From this repo, a sample script is provided in `package.json`:
+
+```sh
+yarn jira_releases
+```
+
+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
+```
+
+### Example of generated note
+The console output includes a share-ready message (note: the tool prints the message in French by default):
+
+```text
+Hello,
+We will deploy to production version <TAG> of the <COMPONENT>
+Here is what this delivery includes:
+
+- v<version>:
+ - feat(CMAB-123): Story title
+ - fix(CMAB-456): XYZ fix
+
+The API team
+```
+
+The exact structure may vary depending on how many versions are included and which issues are associated.
+
+### Best practices
+- 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmflow/cli",
-  "version": "2.2.5",
+  "version": "2.3.0",
   "description": "An awesome Git Flow",
   "author": "camfou",
   "license": "MIT",

package/src/commands/jira-releases.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import figures from "figures";
 import moment from "moment";
 
+import { triggerDirectusFlow } from "../common/back/directus/directus-flow.js";
 import { jiraGetReleasesAndIssues } from "../common/back/jira/jira-get-releases-and-issues.js";
 import { jiraIssueMoveTo } from "../common/back/jira/jira-issue-move-to.js";
 import { updateJiraRelease } from "../common/back/jira/jira-releases.js";
@@ -69,6 +70,18 @@ export class JiraReleases {
             );
           }
         }
+      },
+      {
+        title: `Trigger CMS API Workflow`,
+        skip: () => !getConfig().CAN_TRIGGER_WORKFLOW,
+        task: () => {
+          return triggerDirectusFlow(
+            context.projectId,
+            context.releases.map(({ version }) => {
+              return version;
+            })
+          );
+        }
       }
     ];
   }

package/src/common/back/directus/directus-flow.js

@@ -0,0 +1,36 @@
+import { getConfig } from "../../get-config.js";
+import { httpRequest } from "../http/http-request.js";
+
+/**
+ * Trigger a Directus Flow
+ *
+ * @param {string} projectId - The project identifier to send to the flow
+ * @param {string[]} versions - The versions list to send to the flow
+ * @param {object} [opts] - Additional request options (e.g., rejectUnauthorized)
+ * @returns {Promise<unknown>} The parsed JSON response
+ */
+export async function triggerDirectusFlow(projectId, versions, opts = {}) {
+  const { DIRECTUS_URL, DIRECTUS_FLOW_ID, DIRECTUS_ACCESS_TOKEN } = getConfig();
+
+  const endpoint = `${DIRECTUS_URL}/flows/trigger/${DIRECTUS_FLOW_ID}`;
+
+  const options = {
+    method: "post",
+    callee: "DIRECTUS",
+    headers: {
+      Authorization: `Bearer ${DIRECTUS_ACCESS_TOKEN}`,
+      "Content-Type": "application/json"
+    },
+    body: {
+      projectId,
+      versions
+    },
+    ...opts
+  };
+
+  if (options.body && options.headers?.["Content-Type"] === "application/json") {
+    options.body = JSON.stringify(options.body);
+  }
+
+  return httpRequest(endpoint, options);
+}

package/src/common/back/directus/directus-flow.test.js

@@ -0,0 +1,62 @@
+// Use vi.hoisted to create mock references that are available to mock factories
+const httpRequestMock = vi.hoisted(() => vi.fn());
+
+// Mock get-config to provide DIRECTUS_* env values
+vi.mock("../../get-config.js", () => ({
+  getConfig: () => ({
+    DIRECTUS_URL: "https://directus.example.com",
+    DIRECTUS_FLOW_ID: "flow-123",
+    DIRECTUS_ACCESS_TOKEN: "token-abc"
+  })
+}));
+
+// Spy/mock for httpRequest
+vi.mock("../http/http-request.js", () => ({
+  httpRequest: httpRequestMock
+}));
+
+// Now import the SUT after mocks are in place
+import { triggerDirectusFlow } from "./directus-flow.js";
+
+describe("triggerDirectusFlow", () => {
+  beforeEach(() => {
+    httpRequestMock.mockReset();
+  });
+
+  it("should call httpRequest with the expected endpoint, headers and body", async () => {
+    httpRequestMock.mockResolvedValue({ ok: true, data: { status: "queued" } });
+
+    const projectId = "CMAB";
+    const versions = ["2.3.0", "2.2.0"];
+    const opts = { rejectUnauthorized: true };
+
+    const result = await triggerDirectusFlow(projectId, versions, opts);
+
+    expect(result).toEqual({ ok: true, data: { status: "queued" } });
+
+    expect(httpRequestMock).toHaveBeenCalledTimes(1);
+
+    const expectedEndpoint = "https://directus.example.com/flows/trigger/flow-123";
+    const expectedBody = JSON.stringify({ projectId, versions });
+
+    expect(httpRequestMock).toHaveBeenCalledWith(
+      expectedEndpoint,
+      expect.objectContaining({
+        method: "post",
+        callee: "DIRECTUS",
+        rejectUnauthorized: true,
+        headers: expect.objectContaining({
+          Authorization: "Bearer token-abc",
+          "Content-Type": "application/json"
+        }),
+        body: expectedBody
+      })
+    );
+  });
+
+  it("should propagate errors from httpRequest", async () => {
+    httpRequestMock.mockRejectedValue(new Error("network error"));
+
+    await expect(triggerDirectusFlow("CMAB", ["1.0.0"])).rejects.toThrow("network error");
+  });
+});

package/src/common/get-config.js

@@ -90,6 +90,9 @@ export function getConfig() {
     JIRA_API,
     JIRA_EMAIL,
     JIRA_TOKEN,
+    DIRECTUS_URL,
+    DIRECTUS_FLOW_ID,
+    DIRECTUS_ACCESS_TOKEN,
     HTTPS_PROXY
   } = process.env;
 
@@ -140,6 +143,10 @@ export function getConfig() {
     JIRA_EMAIL,
     JIRA_TOKEN,
     HTTPS_PROXY,
+    DIRECTUS_URL,
+    DIRECTUS_FLOW_ID,
+    DIRECTUS_ACCESS_TOKEN,
+    CAN_TRIGGER_WORKFLOW: DIRECTUS_ACCESS_TOKEN && DIRECTUS_FLOW_ID && DIRECTUS_URL,
     WORKSPACES: pkg.workspaces || [],
     ...getCI()
   };