release-suite 0.1.0

package/.github/workflows/create-release-pr.yml

@@ -0,0 +1,94 @@
+name: Create Release PR
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: release-pr-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release-pr:
+    # Only runs when:
+    # - The PR has been merged
+    # - And the branch is NOT release/v/*
+    if: >
+      github.event.pull_request.merged == true &&
+      !startsWith(github.event.pull_request.head.ref, 'release/v/')
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      # Avoids loops: ignores commits created by bots
+      - name: Skip if last commit is from bot
+        run: |
+          last_author="$(git log -1 --pretty=format:'%an')"
+          echo "Last author: $last_author"
+          if [[ "$last_author" == *"github-actions"* ]]; then
+            echo "Commit created by bot. Canceling workflow."
+            exit 0
+          fi
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install release-suite locally (self usage)
+        run: npm install . 
+
+      # Compute next version to release
+      - name: Compute next version
+        id: semver
+        run: |
+          VERSION=$(rs-compute-version || echo "")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Stop if no release needed
+        if: steps.semver.outputs.version == ''
+        run: exit 0
+
+      - name: Bump package.json
+        run: npm version ${{ steps.semver.outputs.version }} --no-git-tag-version
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Generate changelog
+        run: rs-generate-changelog
+
+      # Automatically create branches, commits, and PRs with peter-evans
+      - name: Create Release PR
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: ":bricks: chore(release): prepare version ${{ steps.semver.outputs.version }} [skip ci]"
+          branch: release/v/${{ steps.semver.outputs.version }}
+          title: ":bricks: chore(release): ${{ steps.semver.outputs.version }}"
+          body: |
+            This PR contains the release artifacts:
+
+            - Updated `package.json` and `package-lock.json` with version ${{ steps.semver.outputs.version }}
+            - Updated `CHANGELOG.md` with latest changes
+            - Generated `/dist` directory with build files (if applicable)
+
+            Upon approving & merging, the publish will run automatically.
+          labels: |
+            release
+          add-paths: |
+            package.json
+            CHANGELOG.md
+            dist/**

package/.github/workflows/publish-on-merge.yml

@@ -0,0 +1,73 @@
+name: Publish Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+
+permissions:
+  contents: write
+  id-token: write # 🔐 REQUIRED for OIDC
+  packages: write
+  pull-requests: write
+
+concurrency:
+  group: publish-release
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    # Only runs when:
+    # - The PR has been merged
+    # - And the branch is release/v/*
+    if: >
+      github.event.pull_request.merged == true &&
+      startsWith(github.event.pull_request.head.ref, 'release/v/')
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install release-suite locally (self usage)
+        run: npm install .
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Create Git Tag
+        run: rs-create-tag
+
+      # 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: rs-generate-release-notes
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Create GitHub Release with notes and attach built assets
+      - name: Create GitHub Release + Tag
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+
+          gh release create "$VERSION" \
+            --title "$VERSION" \
+            --notes-file RELEASE_NOTES.md \
+            ./dist/* || true

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 100,
+  "trailingComma": "none"
+}

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+## 0.1.0
+
+### 🔧 Chore
+
+- Init: project created

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jonas Souza
+
+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.

package/README.md

@@ -0,0 +1,183 @@
+# 🎉 Release Suite
+
+Semantic versioning tools for Git-based projects, providing automated version computation, changelog generation and release notes creation.
+
+## 🚀 Features
+
+- 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`)
+- CI/CD ready for GitHub Actions
+- No commit rules enforced on the main project
+- Trusted Publishing (OIDC) — no npm tokens required
+
+## ⚙️ Installation
+
+```bash
+npm install release-suite --save-dev
+```
+
+## 🖥️ 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 |
+
+## 🧠 Usage
+
+Add to your project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "version:compute": "rs-compute-version",
+    "changelog": "rs-generate-changelog",
+    "release:notes": "rs-generate-release-notes",
+    "preview": "rs-preview create",
+    "preview:clear": "rs-preview remove",
+    "create-tag": "rs-create-tag",
+    "create-tag:compute": "rs-create-tag --compute",
+    "create-tag:dry": "rs-create-tag --dry-run"
+  }
+}
+```
+
+## 🤖 CI/CD Usage (GitHub Actions)
+
+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)
+
+Example workflows:
+- create-release-pr.yml
+- publish-on-merge.yml
+
+## 🔁 Release Flow
+
+This project follows a **two-step release strategy** designed for safety,
+automation and reusability.
+
+### 1️⃣ Prepare Release (Create Release PR)
+
+Triggered when:
+
+- A PR is merged into `main`
+
+Actions:
+
+- Computes next semantic version
+- Updates `package.json`
+- Generates `CHANGELOG.md`
+- Builds the project (if applicable)
+- Opens a **Release PR** (`release/v/x.y.z`)
+
+### 2️⃣ Publish Release
+
+Triggered when:
+
+- A Release PR (`release/v/*`) is merged into `main`
+
+Actions:
+
+- Creates a Git tag
+- Publishes to npm using **Trusted Publishing (OIDC)**
+- Generates GitHub Release Notes
+- Uploads build artifacts (`dist/**`)
+
+---
+
+### 📊 Flow Diagram
+
+```mermaid
+flowchart TD
+    A[Feature / Fix PR] -->|Merge| B[main]
+    B -->|create-release-pr.yml| C[Create Release PR]
+    C -->|release/v/x.y.z| D[Review & Merge]
+    D -->|publish-on-merge.yml| E[Publish Release]
+    E --> F[npm Publish]
+    E --> G[GitHub Release]
+```
+
+✔️ Fully automated releases  
+✔️ No npm tokens or secrets required (OIDC)  
+✔️ No release loops  
+✔️ Safe for concurrent merges  
+✔️ Reusable in any project 
+
+## 📦 Publishing to npm (Trusted Publishing)
+
+This project uses **npm [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) with GitHub Actions (OIDC)**.
+
+- No npm tokens or secrets are required
+- Publishing is handled entirely by GitHub Actions
+- Triggered automatically when a Release PR is merged into `main`
+
+## 🔍 Preview Mode
+
+Generate preview files without touching your real changelog:
+
+```bash
+npm run preview
+```
+
+Remove previews:
+
+```bash
+npm run preview:clear
+```
+
+## 🛠 Development (Maintainers)
+
+When working inside the `release-suite` repository itself, the CLI binaries
+are **not available via npm or npx**, since they are not installed as a dependency.
+
+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
+```
+
+To test the CLI as a real consumer, you can use:
+
+```bash
+npm link
+# or
+npm install ../release-suite
+```
+
+## 📄 License
+
+This project is licensed under the [MIT License](./LICENSE).
+
+---
+
+## ✨ Author
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://jonasmzsouza.github.io/">
+         <img style="border-radius: 50%;" src="https://avatars.githubusercontent.com/u/61324433?v=4" width="100px;" alt=""/>
+         <br />
+         <sub><b>Jonas Souza</b></sub>
+      </a>
+    </td>
+  </tr>
+</table>
+ 
+💼 [LinkedIn](https://linkedin.com/in/jonasmzsouza)
+💻 [GitHub](https://github.com/jonasmzsouza)

package/bin/compute-version.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+
+function run(cmd) {
+  return execSync(cmd, { encoding: "utf8" }).trim();
+}
+
+const isPreview = process.env.PREVIEW_MODE === "true";
+
+function getPackageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function getLastTag() {
+  try {
+    const tag = run("git describe --tags --abbrev=0");
+    return tag.replace(/^v/, "");
+  } catch {
+    const pkgVersion = getPackageVersion();
+    if (isPreview) {
+      console.log(
+        `⚠ No previous tag found. Using package.json version (${pkgVersion}) as base.`
+      );
+    }
+    return pkgVersion;
+  }
+}
+
+function getCommitsSince(version) {
+  try {
+    // If version came from package.json (no tag), include all commits
+    const hasTag = (() => {
+      try {
+        run("git describe --tags --abbrev=0");
+        return true;
+      } catch {
+        return false;
+      }
+    })();
+
+    const range = hasTag ? `${version}..HEAD` : "HEAD";
+
+    return run(
+      `git log ${range} --pretty=format:%H%x1f%s%x1f%b`
+    )
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function parseCommitLine(line) {
+  const [hash, subject = "", body = ""] = line.split("\x1f");
+  return { hash, subject, body };
+}
+
+function detectType(subject, body) {
+  const re =
+    /^(:\S+: )?(feat|fix|refactor|docs|chore|style|test|build|perf|ci|raw|cleanup|remove)(\(.+\))?(!)?:/i;
+
+  const m = subject.match(re);
+  const isBreaking =
+    /BREAKING CHANGE/i.test(body) || (m && m[4] === "!");
+
+  if (isBreaking) return "major";
+  if (m) {
+    const t = m[2].toLowerCase();
+    if (t === "feat") return "minor";
+    if (t === "fix") return "patch";
+  }
+  return "none";
+}
+
+function bumpVersion(type, version) {
+  const [major, minor, patch] = version
+    .split(".")
+    .map(n => parseInt(n, 10) || 0);
+
+  if (type === "major") return `${major + 1}.0.0`;
+  if (type === "minor") return `${major}.${minor + 1}.0`;
+  return `${major}.${minor}.${patch + 1}`;
+}
+
+function main() {
+  const baseVersion = getLastTag();
+  const commits = getCommitsSince(baseVersion).map(parseCommitLine);
+
+  if (!commits.length) process.exit(0);
+
+  let bump = null;
+
+  for (const c of commits) {
+    const t = detectType(c.subject, c.body);
+    if (t === "major") {
+      bump = "major";
+      break;
+    }
+    if (t === "minor" && bump !== "major") bump = "minor";
+    if (t === "patch" && !bump) bump = "patch";
+  }
+
+  if (!bump) {
+    if (isPreview) {
+      console.log("Mode: PREVIEW");
+      console.log("Base version:", baseVersion);
+      console.log("Commits analyzed:", commits.length);
+      console.log("No version bump detected.");
+    }
+    process.exit(0);
+  }
+
+  const nextVersion = bumpVersion(bump, baseVersion);
+
+  if (isPreview) {
+    console.log("Mode: PREVIEW");
+    console.log("Base version:", baseVersion);
+    console.log("Commits analyzed:", commits.length);
+    console.log("Highest bump detected:", bump);
+    console.log("Next version:", nextVersion);
+  } else {
+    console.log(nextVersion);
+  }
+}
+
+main();

package/bin/create-tag.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+
+function run(cmd, silent = false) {
+  return execSync(cmd, {
+    stdio: silent ? "pipe" : "inherit",
+    encoding: "utf8",
+  }).trim();
+}
+
+const args = process.argv.slice(2);
+const DRY_RUN = args.includes("--dry-run");
+const USE_COMPUTED = args.includes("--compute");
+
+let version;
+
+if (USE_COMPUTED) {
+  console.log("🔢 Computing version dynamically...");
+  try {
+    version = run("node bin/compute-version.js", true);
+  } catch {
+    console.error("❌ Failed to compute version.");
+    process.exit(1);
+  }
+
+  if (!version) {
+    console.log("ℹ No version bump detected. Skipping tag creation.");
+    process.exit(0);
+  }
+} else {
+  console.log("📦 Using version from package.json...");
+  try {
+    const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+    version = pkg.version;
+  } catch {
+    console.error("❌ Failed to read package.json version.");
+    process.exit(1);
+  }
+}
+
+const tag = version;
+
+console.log(`🔖 Release version: ${tag}`);
+
+// check if tag exists
+try {
+  run(`git rev-parse ${tag}`, true);
+  console.error(`❌ Tag ${tag} already exists.`);
+  process.exit(1);
+} catch {
+  // OK
+}
+
+if (DRY_RUN) {
+  console.log("🧪 Dry-run mode enabled.");
+  console.log(`Would create and push tag: ${tag}`);
+  console.log(`VERSION=${tag}`);
+  process.exit(0);
+}
+
+run(`git tag ${tag}`);
+run(`git push origin ${tag}`);
+
+console.log(`✔ Tag ${tag} created and pushed`);

package/bin/generate-changelog.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+
+function run(cmd) {
+  return execSync(cmd, { encoding: "utf8" }).trim();
+}
+
+function getAllTags() {
+  try {
+    return run("git tag --sort=-creatordate")
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function getCommitsBetween(from, to) {
+  const range = from ? `${from}..${to}` : to;
+  try {
+    return run(`git log ${range} --pretty=format:%H%x1f%s%x1f%b`)
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function parseCommit(line) {
+  const [hash, subject = "", body = ""] = line.split("\x1f");
+  return { hash, subject: subject.trim(), body: body.trim() };
+}
+
+function cleanSubject(subject) {
+  let s = subject.replace(/^(:\S+: )?/, "");
+  s = s.replace(
+    /^(feat|fix|refactor|docs|chore|style|test|build|perf|ci|raw|cleanup|remove)(\(.+\))?(!)?:\s*/i,
+    ""
+  );
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+function categorize(commits) {
+  const buckets = {
+    breaking: [],
+    feat: [],
+    fix: [],
+    refactor: [],
+    chore: [],
+    docs: [],
+    style: [],
+    test: [],
+    build: [],
+    perf: [],
+    ci: [],
+    raw: [],
+    cleanup: [],
+    remove: [],
+  };
+
+  const reType =
+    /^(:\S+: )?(feat|fix|refactor|docs|chore|style|test|build|perf|ci|raw|cleanup|remove)(\(.+\))?(!)?:/i;
+
+  for (const c of commits) {
+    const { subject, body } = c;
+
+    if (/BREAKING CHANGE/i.test(body) || /!:/i.test(subject)) {
+      buckets.breaking.push({ desc: cleanSubject(subject), hash: c.hash });
+      continue;
+    }
+
+    const match = subject.match(reType);
+    const desc = cleanSubject(subject);
+
+    if (!match) {
+      buckets.chore.push({ desc: desc || subject, hash: c.hash });
+      continue;
+    }
+
+    const type = match[2].toLowerCase();
+    (buckets[type] || buckets.chore).push({ desc, hash: c.hash });
+  }
+
+  return buckets;
+}
+
+function buildSection(version, buckets) {
+  const out = [];
+  out.push(`## ${version}\n`);
+
+  const sections = [
+    ["breaking", "### 💥 Breaking Changes"],
+    ["feat", "### ✨ Features"],
+    ["fix", "### 🐛 Fixes"],
+    ["refactor", "### ⚙️ Refactor"],
+    ["chore", "### 🔧 Chore"],
+    ["docs", "### 📚 Docs"],
+    ["style", "### 🎨 Style"],
+    ["test", "### 🧪 Tests"],
+    ["build", "### 🛠 Build"],
+    ["perf", "### ⚡ Performance"],
+    ["ci", "### 🔁 CI"],
+    ["raw", "### 🗃 Raw"],
+    ["cleanup", "### 🧹 Cleanup"],
+    ["remove", "### 🗑 Remove"],
+  ];
+
+  let hasContent = false;
+
+  for (const [key, title] of sections) {
+    if (buckets[key].length) {
+      hasContent = true;
+      out.push(`${title}\n`);
+      for (const c of buckets[key]) out.push(`- ${c.desc}`);
+      out.push("");
+    }
+  }
+
+  if (!hasContent) out.push("_No changes._\n");
+
+  return out.join("\n");
+}
+
+function changelogHasVersion(file, version) {
+  if (!fs.existsSync(file)) return false;
+  const content = fs.readFileSync(file, "utf8");
+  const safe = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^##\\s+${safe}\\b`, "m").test(content);
+}
+
+function main() {
+  const isPreview = process.env.PREVIEW_MODE === "true";
+  const CHANGELOG_FILE = isPreview
+    ? "CHANGELOG.preview.md"
+    : "CHANGELOG.md";
+
+  const tags = getAllTags();
+  const sections = [];
+
+  if (tags.length === 0) {
+    const pkgVersion = (() => {
+      try {
+        const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+        return pkg.version || "0.1.0";
+      } catch {
+        return "0.1.0";
+      }
+    })();
+
+    if (!changelogHasVersion(CHANGELOG_FILE, pkgVersion)) {
+      const commits = getCommitsBetween(null, "HEAD").map(parseCommit);
+      const buckets = categorize(commits);
+      sections.push(buildSection(pkgVersion, buckets));
+    }
+  } else {
+    for (let i = 0; i < tags.length; i++) {
+      const tag = tags[i];
+      const previous = tags[i + 1] || null;
+
+      if (changelogHasVersion(CHANGELOG_FILE, tag)) continue;
+
+      const commits = getCommitsBetween(previous, tag).map(parseCommit);
+      const buckets = categorize(commits);
+      sections.push(buildSection(tag, buckets));
+    }
+  }
+
+  if (!sections.length) {
+    console.log("ℹ No new versions to add.");
+    return;
+  }
+
+  if (isPreview) {
+    fs.writeFileSync(CHANGELOG_FILE, sections.join("\n"), "utf8");
+  } else {
+    const existing = fs.existsSync(CHANGELOG_FILE)
+      ? "\n" + fs.readFileSync(CHANGELOG_FILE, "utf8")
+      : "";
+    fs.writeFileSync(
+      CHANGELOG_FILE,
+      sections.join("\n") + existing,
+      "utf8"
+    );
+  }
+
+  console.log(
+    isPreview ? "CHANGELOG preview generated." : "CHANGELOG updated."
+  );
+}
+
+main();

package/bin/generate-release-notes.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+
+const run = (cmd) => execSync(cmd, { encoding: "utf8" }).trim();
+
+const isPreview = process.env.PREVIEW_MODE === "true";
+const RELEASE_NOTES_FILE = isPreview
+  ? "RELEASE_NOTES.preview.md"
+  : "RELEASE_NOTES.md";
+
+function ensureGhCLI() {
+  try {
+    run("gh --version");
+  } catch {
+    console.error("❌ GitHub CLI (gh) is required but not installed.");
+    console.error("   Install: https://cli.github.com/");
+    process.exit(2);
+  }
+}
+
+function getDefaultBranch() {
+  try {
+    return run("git remote show origin | sed -n 's/.*HEAD branch: //p'");
+  } catch {
+    return "main";
+  }
+}
+
+function normalizeRepoURL(url) {
+  if (!url) return null;
+  url = url.replace(/\.git$/, "");
+  if (url.startsWith("git@")) {
+    const m = url.match(/^git@(.*?):(.*)$/);
+    if (m) return `https://${m[1]}/${m[2]}`;
+  }
+  return url;
+}
+
+if (!isPreview) {
+  ensureGhCLI();
+} else {
+  console.log("ℹ Preview mode: GH CLI not required.");
+}
+
+const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
+const version = pkg.version;
+const repoURL = normalizeRepoURL(pkg.repository?.url);
+
+let lastTag = "";
+try {
+  lastTag = run("git describe --tags --abbrev=0");
+} catch {
+  console.log("⚠ No previous tags found — first release?");
+  lastTag = "";
+}
+
+console.log("Last tag:", lastTag || "(none)");
+
+const baseBranch = getDefaultBranch();
+
+let prList = [];
+
+if (!isPreview) {
+  let prQuery =
+    `gh pr list --state merged --base ${baseBranch} ` +
+    `--json number,title,author,url`;
+
+  if (lastTag) prQuery += ` --search "merged:>${lastTag}"`;
+
+  try {
+    prList = JSON.parse(run(prQuery));
+  } catch {
+    prList = [];
+  }
+}
+
+let notes = `# What's Changed\n\n`;
+
+if (!prList.length) {
+  notes += "_No changes since last release._\n\n";
+}
+
+for (const pr of prList) {
+  notes += `- ${pr.title} by @${pr.author.login} in ${pr.url}\n`;
+
+  let messages = [];
+  if (!isPreview) {
+    try {
+      messages = run(
+        `gh pr view ${pr.number} --json commits --jq '.commits[].messageHeadline'`
+      )
+        .split("\n")
+        .filter(Boolean);
+    } catch (err) {
+      console.error(`⚠ Could not fetch commits for PR #${pr.number}: ${err && err.message ? err.message : err}`);
+    }
+  }
+
+  for (const msg of messages) {
+    notes += `  - ${msg}\n`;
+  }
+
+  notes += "\n";
+}
+
+const compareLink = repoURL
+  ? lastTag
+    ? `${repoURL}/compare/${lastTag}...${version}`
+    : repoURL
+  : "";
+
+if (compareLink) {
+  notes += `**Full Changelog**: ${compareLink}\n`;
+}
+
+fs.writeFileSync(RELEASE_NOTES_FILE, notes, "utf8");
+
+console.log(
+  isPreview
+    ? "✔ Generated RELEASE_NOTES.preview.md"
+    : "✔ Generated RELEASE_NOTES.md"
+);

package/bin/preview.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+
+process.env.PREVIEW_MODE = "true";
+
+const run = (cmd) => execSync(cmd, { encoding: "utf8" }).trim();
+
+const filesMap = {
+  changelog: "CHANGELOG.preview.md",
+  notes: "RELEASE_NOTES.preview.md",
+};
+
+const action = process.argv[2];
+
+if (!["create", "remove"].includes(action)) {
+  console.log("Usage: preview.js [create|remove]");
+  process.exit(1);
+}
+
+if (action === "create") {
+  console.log("🔧 Generating preview files...");
+
+  const versionOutput = run("node bin/compute-version.js");
+
+  if (versionOutput) {
+    console.log("🔖 Computed version:");
+    console.log(versionOutput);
+  }
+
+  run("node bin/generate-changelog.js");
+  run("node bin/generate-release-notes.js");
+
+  console.log("✅ Preview ready:");
+  console.log(" -", filesMap.changelog);
+  console.log(" -", filesMap.notes);
+  process.exit(0);
+}
+
+if (action === "remove") {
+  console.log("🧹 Removing preview files...");
+  for (const f of Object.values(filesMap)) {
+    if (fs.existsSync(f)) fs.unlinkSync(f);
+  }
+  console.log("✔ Preview cleared.");
+  process.exit(0);
+}

package/eslint.config.js

@@ -0,0 +1,47 @@
+// eslint.config.js
+import js from "@eslint/js";
+import prettierConfig from "eslint-config-prettier";
+import pluginImport from "eslint-plugin-import";
+import globals from "globals";
+
+export default [
+  js.configs.recommended,
+  {
+    files: ["bin/**/*.js"],
+    plugins: {
+      import: pluginImport,
+    },
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      "no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+      "no-console": "off",
+      "prefer-const": "warn",
+      eqeqeq: ["error", "always"],
+      curly: ["error", "all"],
+      "import/order": [
+        "warn",
+        {
+          groups: [
+            "builtin",
+            "external",
+            "internal",
+            "parent",
+            "sibling",
+            "index",
+          ],
+          alphabetize: { order: "asc", caseInsensitive: true },
+        },
+      ],
+    },
+  },
+  prettierConfig,
+  {
+    ignores: ["dist/**/*.js"],
+  },
+];

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "release-suite",
+  "version": "0.1.0",
+  "description": "Semantic versioning tools for Git-based projects, providing automated version computation, changelog generation and release notes creation.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "rs-compute-version": "bin/compute-version.js",
+    "rs-generate-changelog": "bin/generate-changelog.js",
+    "rs-generate-release-notes": "bin/generate-release-notes.js",
+    "rs-preview": "bin/preview.js",
+    "rs-create-tag": "bin/create-tag.js"
+  },
+  "scripts": {
+    "lint": "eslint bin/",
+    "lint:fix": "eslint bin/ --fix",
+    "version:compute": "node bin/compute-version.js",
+    "changelog": "node bin/generate-changelog.js",
+    "release:notes": "node bin/generate-release-notes.js",
+    "preview": "node bin/preview.js create",
+    "preview:clear": "node bin/preview.js remove",
+    "create-tag": "node bin/create-tag.js",
+    "create-tag:compute": "node bin/create-tag.js --compute",
+    "create-tag:dry": "node bin/create-tag.js --dry-run",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jonasmzsouza/release-suite"
+  },
+  "keywords": [
+    "release",
+    "tools",
+    "semantic",
+    "versioning",
+    "changelog",
+    "release-notes",
+    "publish",
+    "npm",
+    "nodejs"
+  ],
+  "author": {
+    "name": "Jonas Souza",
+    "email": "jonasmzsouza@gmail.com"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jonasmzsouza/release-suite/issues"
+  },  
+  "devDependencies": {
+    "esbuild": "^0.25.11",
+    "eslint": "9.38.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^16.5.0"
+  }
+}