release-suite 2.0.0 → 3.0.0

package/.github/workflows/create-and-publish.yml

@@ -0,0 +1,243 @@
+name: Create & Publish Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  id-token: write # 🔐 REQUIRED for OIDC
+  contents: write
+  pull-requests: write
+  packages: write
+
+concurrency:
+  group: release-main
+  cancel-in-progress: true
+
+jobs:
+  # ------------------------------------------------------------
+  # JOB 1 — CREATE RELEASE PR + TAG DECISION
+  # ------------------------------------------------------------
+  create:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    # Job-level outputs = contract with publish job
+    outputs:
+      should_publish: ${{ steps.compute.outputs.should_publish }}
+      version: ${{ steps.compute.outputs.version }}
+      tagPrefix: ${{ steps.compute.outputs.tagPrefix }}
+      tag: ${{ steps.tag.outputs.tag }}
+
+    # Only run when:
+    # - manual dispatch OR
+    # - PR merged into main AND it's NOT a release PR
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      (
+        github.event.pull_request.merged == true &&
+        !contains(join(github.event.pull_request.labels.*.name, ','), 'release')
+      )
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install release-suite (self)
+        run: npm install .
+
+      # --------------------------------------------------------
+      # Decide if a release should happen
+      # --------------------------------------------------------
+      - name: Compute next version
+        id: compute
+        run: |
+          set +e
+          RESULT=$(node bin/version.js compute)
+          STATUS=$?
+          VERSION=$(echo "$RESULT" | jq -r '.nextVersion // empty')
+          TAG_PREFIX=$(echo "$RESULT" | jq -r '.tagPrefix // ""')
+
+          echo "$RESULT"
+
+          if [ "$STATUS" -ne 0 ] || [ -z "$VERSION" ]; then
+            echo "should_publish=false" >> $GITHUB_OUTPUT
+          else
+            echo "should_publish=true" >> $GITHUB_OUTPUT
+            echo "version=$VERSION" >> $GITHUB_OUTPUT
+            echo "tagPrefix=$TAG_PREFIX" >> $GITHUB_OUTPUT 
+          fi
+
+      # --------------------------------------------------------
+      # Prepare release artifacts
+      # --------------------------------------------------------
+      - name: Bump package.json
+        if: steps.compute.outputs.should_publish == 'true'
+        run: npm version ${{ steps.compute.outputs.version }} --no-git-tag-version
+
+      - name: Sync package-lock.json
+        if: steps.compute.outputs.should_publish == 'true'
+        run: npm install --package-lock-only
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Generate changelog
+        if: steps.compute.outputs.should_publish == 'true'
+        run: node bin/changelog.js generate
+
+      # --------------------------------------------------------
+      # Stage files (dist is optional)
+      # --------------------------------------------------------
+      - name: Stage release files
+        if: steps.compute.outputs.should_publish == 'true'
+        run: |
+          git add package.json package-lock.json CHANGELOG.md
+          [ -d dist ] && git add dist || true
+          git status --short
+
+      # --------------------------------------------------------
+      # Create Release PR
+      # --------------------------------------------------------
+      - name: Create Release PR
+        id: pr
+        if: steps.compute.outputs.should_publish == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: release/${{ steps.compute.outputs.tagPrefix }}${{ steps.compute.outputs.version }}
+          title: ":bricks: chore(release): ${{ steps.compute.outputs.tagPrefix }}${{ steps.compute.outputs.version }} [skip ci]"
+          commit-message: ":bricks: chore(release): prepare version ${{ steps.compute.outputs.tagPrefix }}${{ steps.compute.outputs.version }} [skip ci]"
+          labels: release
+          delete-branch: true
+          assignees: ${{ github.event.pull_request.merged_by.login }}
+          body: |
+            Automated release PR.
+
+            - Version bump: ${{ steps.compute.outputs.tagPrefix }}${{ steps.compute.outputs.version }}
+            - Updated changelog
+            - Build artifacts included if present
+
+            Merging this PR will trigger publish automatically.
+
+      # --------------------------------------------------------
+      # Merge Release PR (best-effort)
+      # --------------------------------------------------------
+      - name: Merge Release PR
+        if: steps.pr.outputs.pull-request-number != ''
+        run: |
+          PR=${{ steps.pr.outputs.pull-request-number }}
+          echo "Merging PR #$PR"
+          if ! gh pr merge "$PR" --squash --admin; then
+            echo "Immediate merge failed, attempting to enable auto-merge"
+            gh pr merge "$PR" --auto --squash
+          fi
+
+      # --------------------------------------------------------
+      # Validate merge (soft)
+      # --------------------------------------------------------
+      - name: Validate release commit
+        id: validate
+        run: |
+          git fetch origin main --depth=1
+          git checkout main
+          git reset --hard origin/main
+
+          if git log -1 --pretty=%s | grep -q "^:bricks: chore(release):"; then
+            echo "ok=true" >> $GITHUB_OUTPUT
+          else
+            echo "ok=false" >> $GITHUB_OUTPUT
+          fi
+
+      # --------------------------------------------------------
+      # Create Git tag (soft)
+      # --------------------------------------------------------
+      - name: Create tag
+        id: tag
+        if: steps.validate.outputs.ok == 'true'
+        run: |
+          set +e
+          RESULT=$(node bin/tag.js create)
+          TAG=$(echo "$RESULT" | jq -r '.tag // empty')
+
+          echo "$RESULT"
+
+          if [ -n "$TAG" ]; then
+            echo "tag=$TAG" >> $GITHUB_OUTPUT
+          fi
+
+  # ------------------------------------------------------------
+  # JOB 2 — PUBLISH (only if tag exists)
+  # ------------------------------------------------------------
+  publish:
+    needs: create
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    if: needs.create.outputs.tag != ''
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Setup Node (npm OIDC)
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          always-auth: true
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install release-suite (self)
+        run: npm install .
+
+      # --------------------------------------------------------
+      # Publish to npm using Trusted Publishing (OIDC)
+      # --------------------------------------------------------
+      - name: Publish to npm (Trusted Publishing)
+        run: npm publish
+
+      # --------------------------------------------------------
+      # Generate release notes for GitHub Release
+      # --------------------------------------------------------
+      - name: Generate GitHub Release Notes
+        run: node bin/release-notes.js generate
+
+      # --------------------------------------------------------
+      # Create GitHub Release with notes and attach built assets
+      # --------------------------------------------------------
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ASSETS=()
+          if [ -d dist ]; then
+            ASSETS=(dist/**)
+          fi
+
+          gh release create "${{ needs.create.outputs.tag }}" \
+            --title "${{ needs.create.outputs.tag }}" \
+            --notes-file RELEASE_NOTES.md \
+            "${ASSETS[@]}"

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+All notable changes to this project will be documented in this file.
+The format follows the conventions of [Conventional Commits](https://www.conventionalcommits.org) and semantic versioning (SemVer).
+
+## 3.0.0
+
+### 💥 Breaking Changes
+- Introduce action-based CLI and reorganize release architecture (#21)
+
+### 📚 Documentation
+- Update README.md and ci.md with GitHub CLI usage (#20)
+
+### 🤖 CI
+- Simplify GitHub CLI usage and make authentication explicit (#19)
+- Unify release automation into a single resilient workflow (#18)
+
 ## 2.0.0
 
 ### 💥 Breaking Changes
@@ -11,52 +26,24 @@
 ## 1.0.1
 
 ### 🐛 Fixes
-
 - Harden changelog generation for squash commits (#13)
 
-### 📚 Docs
-
-- Update ci/cd examples with trigger adjustment
-
-### 🔁 CI
-
-- Adjust trigger in workflow
+### 🤖 CI
+- Harden workflow triggers and merge conditions (#12)
 
 ## 1.0.0
 
 ### 💥 Breaking Changes
-
 - Harden computeVersion contract and CLI behavior (#4)
 
 ### 🐛 Fixes
-
 - Normalize path resolution for all CLI scripts (#2)
 
-### 🔧 Chore
-
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-- 
-
-### 🔁 CI
-
+### 🤖 CI
 - Harden local script execution and dist resolution (#10)
 - Binary resolution (#3)
 
 ## 0.1.0
 
-### 🔧 Chore
-
+### 📦 Other
 - Init: project created

package/README.md

@@ -9,8 +9,8 @@ Semantic versioning tools for Git-based projects, providing automated version co
 - Automatic version bump based on commit messages
 - Conventional commit parsing (custom prefixes supported)
 - Auto-generated `CHANGELOG.md`
-- Auto-generated `RELEASE_NOTES.md` using GitHub CLI (gh)
-- Local preview mode (`CHANGELOG.preview.md`, `RELEASE_NOTES.preview.md`)
+- Auto-generated `RELEASE_NOTES.md` using GitHub API
+- Local dry-run mode (`CHANGELOG.dry-run.md`, `RELEASE_NOTES.dry-run.md`)
 - CI/CD ready for GitHub Actions
 - No commit rules enforced on the main project
 - Trusted Publishing (OIDC) — no npm tokens required
@@ -26,78 +26,94 @@ Add to your project's `package.json`:
 ```json
 {
   "scripts": {
-    "preview": "rs-preview create",
-    "preview:clean": "rs-preview remove",
-    "compute-version": "rs-compute-version",
-    "compute-version:ci": "rs-compute-version --ci --json",
-    "compute-version:json": "rs-compute-version --json",
-    "changelog": "rs-generate-changelog",
-    "release-notes": "rs-generate-release-notes"
+    "dry-run": "rs-dry-run create",
+    "dry-run:clean": "rs-dry-run remove",
+    "version:compute": "rs-version compute",
+    "changelog": "rs-changelog generate",
+    "release-notes": "rs-release-notes generate",
+    "tag:create": "rs-tag create"
   }
 }
 ```
 
-Generate preview files without touching your real changelog:
+Generate dry-run files without touching your real changelog:
 
 ```bash
-npm run preview
+npm run dry-run
 ```
 
-Remove previews:
+Remove dry-run files:
 
 ```bash
-npm run preview:clear
+npm run dry-run:clear
 ```
 
+## ⚙️ Configuration
+
+Release Suite can be configured using a `release.config.js` file.
+
+This file controls:
+
+- Git tag prefix (`v1.2.3` vs `1.2.3`)
+- Emoji usage in changelog rendering
+
+See [`docs/config.md`](docs/config.md) for full documentation.
+
+---
+
 ## 🖥️ CLI Commands
 
-| Command                     | Description                                               |
-| --------------------------- | --------------------------------------------------------- |
-| `rs-compute-version`        | Computes next semantic version based on git commits       |
-| `rs-generate-changelog`     | Generates `CHANGELOG.md`                                  |
-| `rs-generate-release-notes` | Generates `RELEASE_NOTES.md` using GitHub PRs             |
-| `rs-preview`                | Generates preview changelog & release notes               |
-| `rs-create-tag`             | Create and push a git tag based on `package.json` version |
+| Command                     | Description                                                |
+| --------------------------- | ---------------------------------------------------------- |
+| `rs-version compute`        | Computes next semantic version based on git commits        |
+| `rs-changelog generate`     | Generates a new changelog entry for the next release       |
+| `rs-changelog rebuild` ⚠️   | Fully rebuilds CHANGELOG.md from git history (Danger Zone) |
+| `rs-release-notes generate` | Generates RELEASE_NOTES.md                                 |
+| `rs-dry-run`                | Generates dry-run changelog & release notes                |
+| `rs-tag create`             | Creates and pushes a git tag                               |
 
 Each command follows a strict and predictable CLI contract (exit codes, stdout, JSON mode).
 
 > 💡 **Note about execution**
 >
+> ⚠️ `rs-changelog rebuild` is a destructive operation.
+> Always use `--dry-run` first.
+>
 > - When using these commands via `npm run`, they can be referenced directly (`rs-*`).
 > - In CI/CD environments (e.g. GitHub Actions), always invoke them using `npx`
->   (e.g. `npx rs-generate-changelog`) to ensure proper binary resolution.
+>   (e.g. `npx rs-changelog generate`) to ensure proper binary resolution.
 
 ## 🔁 Release Flow
 
-This project follows a **two-step release strategy** designed for safety,
-automation and reusability.
+This project uses an automated, PR-based release strategy
+designed for safety and traceability.
 
-### 1️⃣ Prepare Release (Create Release PR)
+See [Release Process](docs/release-process.md) for details.
+
+### 1️⃣ Create Release PR
 
 Triggered when:
 
 - A PR is merged into `main`
+- Or the workflow is manually dispatched
 
 Actions:
 
 - Computes next semantic version
-- Updates `package.json`
-- Generates `CHANGELOG.md`
+- Updates `package.json` and `CHANGELOG.md`
 - Builds the project (if applicable)
-- Opens a **Release PR** (`release/x.y.z`)
+- Opens and auto-merges a Release PR
+- Creates a Git tag
 
 ### 2️⃣ Publish Release
 
-Triggered when:
-
-- A Release PR (`release/x.y.z`) with `release` label is merged into `main`
+Triggered automatically after the Release PR merge (only if tag exists).
 
 Actions:
 
-- Creates a Git tag
 - Publishes to npm using **Trusted Publishing (OIDC)**
 - Generates GitHub Release Notes
-- Uploads build artifacts (`dist/**`)
+- Uploads build artifacts (`dist/**` if present)
 
 ---
 
@@ -105,10 +121,13 @@ Actions:
 
 ```mermaid
 flowchart TD
-    A[Feature / Fix PR] -->|Merge| B[main]
-    B -->|create-release-pr.yml| C[Create Release PR]
-    C -->|Manual Review & Merge| D[pull_request.closed]
-    D -->|publish-on-merge.yml| E[Publish Release]
+    A[Feature / Fix PR] -->|merge| B[main]
+    B -->|workflow trigger| C[Compute Version]
+    C -->|release needed| D[Create Release PR]
+    D -->|auto-merge| E[main updated]
+    E -->|create tag| F[Git Tag]
+    F -->|publish| G[npm Registry]
+    F -->|release| H[GitHub Release]
 ```
 
 ✔️ Fully automated releases  
@@ -123,12 +142,6 @@ flowchart TD
 
 This project is designed to be used in automated pipelines.
 
-Typical flow:
-
-1. Create a Release PR (compute version, changelog, build)
-2. Review and merge the Release PR into `main`
-3. Publish the release (tag, npm, GitHub Release)
-
 👉 See full examples in [`docs/ci.md`](./docs/ci.md)
 
 ## 📦 Publishing to npm (Trusted Publishing)
@@ -154,11 +167,11 @@ are **not available via npm or npx**, since they are not installed as a dependen
 In this case, run the scripts directly with Node.js:
 
 ```bash
-node bin/compute-version.js
-node bin/generate-changelog.js
-node bin/generate-release-notes.js
-node bin/preview.js create
-node bin/create-tag.js
+node bin/version.js compute
+node bin/changelog.js generate
+node bin/release-notes.js generate
+node bin/dry-run.js create
+node bin/tag.js create
 ```
 
 To test the CLI as a real consumer, you can use:

package/bin/changelog.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { generateChangelog } from "../lib/changelog/generate.js";
+import { rebuildChangelog } from "../lib/changelog/rebuild.js";
+import { parseFlags } from "../lib/utils.js";
+
+/* ===========================
+ * CLI
+ * =========================== */
+
+/**
+ * Main CLI entrypoint for changelog (generate/rebuild).
+ *
+ * Behavior:
+ *  - Calls generateChangelog({ dryRun: flags.dryRun }).
+ *  - Calls rebuildChangelog({ dryRun: flags.dryRun }).
+ *
+ * Exit codes (contract):
+ *  - 0  -> changelog generated/rebuilt
+ *  - 10 -> no release/no-tags
+ *  - 2  -> no-commits/no-valid-commits
+ *  - 11 -> already exists
+ *  - 1  -> unexpected error
+ */
+function main() {
+  const action = process.argv[2];
+  const flags = parseFlags(process.argv.slice(3), {
+    dryRun: "--dry-run",
+  });
+
+  if (!["generate", "rebuild"].includes(action)) {
+    console.error(
+      JSON.stringify(
+        {
+          "error": "invalid-usage",
+          "message": "Invalid action. Usage: npx rs-changelog [generate|rebuild]"
+        },
+        null,
+        2
+      )
+    );
+    process.exit(1);
+  }
+
+  try {
+
+    let result = null;
+    if (action === "generate") {
+      result = generateChangelog({ dryRun: flags.dryRun });
+    }
+    else if (action === "rebuild") {
+      result = rebuildChangelog({ dryRun: flags.dryRun });
+    }
+
+    console.log(JSON.stringify(result, null, 2));
+
+    if (action === "generate") {
+      if (result.generated) process.exit(0);
+      if (result.reason === "no-release") process.exit(10);
+      if (result.reason === "no-commits") process.exit(2);
+      if (result.reason === "already-exists") process.exit(11);
+    }
+    else if (action === "rebuild") {
+      if (result.rebuilt) process.exit(0);
+      if (result.reason === "no-tags") process.exit(10);
+      if (result.reason === "no-valid-commits") process.exit(2);
+    }
+
+    process.exit(1);
+  } catch (err) {
+    console.error(
+      JSON.stringify(
+        {
+          error: "unexpected-error",
+          message: err.message || String(err),
+        },
+        null,
+        2
+      )
+    );
+    process.exit(1);
+  }
+}
+
+const __filename = fileURLToPath(import.meta.url);
+if (process.argv[1] === __filename) {
+  main();
+}

package/bin/dry-run.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { dryRun } from "../lib/dry-run.js";
+
+/* ===========================
+ * CLI
+ * =========================== */
+
+function main() {
+  const action = process.argv[2];
+
+  if (!["create", "remove"].includes(action)) {
+    console.error(
+      JSON.stringify(
+        {
+          "error": "invalid-usage",
+          "message": "Invalid action. Usage: npx rs-dry-run [create|remove]"
+        },
+        null,
+        2
+      )
+    );
+    process.exit(1);
+  }
+
+  try {
+    const result = dryRun({ action });
+
+    console.log(JSON.stringify(result, null, 2));
+
+    if (action === "create" && result.generated === false) {
+      process.exit(10);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    console.error(
+      JSON.stringify(
+        {
+          error: "unexpected-error",
+          message: err.message || String(err),
+        },
+        null,
+        2
+      )
+    );
+    process.exit(1);
+  }
+}
+
+const __filename = fileURLToPath(import.meta.url);
+if (process.argv[1] === __filename) {
+  main();
+}