release-suite 0.1.0 → 1.0.0

package/bin/generate-release-notes.js

@@ -1,123 +1,135 @@
-#!/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"
-);
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const run = (cmd, cwd = process.cwd()) => execSync(cmd, { encoding: "utf8", cwd }).trim();
+
+function ensureGhCLI() {
+  try {
+    run("gh --version");
+  } catch {
+    throw new Error("GitHub CLI (gh) is required but not installed.");
+  }
+}
+
+function getDefaultBranch(cwd = process.cwd()) {
+  try {
+    const out = run("git remote show origin", cwd);
+    const m = out.match(/HEAD branch: (\S+)/);
+    return (m && m[1]) || "main";
+  } 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;
+}
+
+export function generateReleaseNotes({ isPreview = process.env.PREVIEW_MODE === "true", cwd = process.cwd() } = {}) {
+  if (!isPreview) {
+    try {
+      ensureGhCLI();
+    } catch (err) {
+      console.error(`❌ ${err.message}`);
+      console.error("❌ GitHub CLI (gh) is required but not installed.");
+      console.error("   Install: https://cli.github.com/");
+      process.exit(2);
+    }
+  } else {
+    console.log("ℹ Preview mode: GH CLI not required.");
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+  const version = pkg.version;
+  const repoURL = normalizeRepoURL(pkg.repository?.url);
+
+  let lastTag = "";
+  try {
+    lastTag = run("git describe --tags --abbrev=0", cwd);
+  } catch {
+    console.log("⚠ No previous tags found — first release?");
+    lastTag = "";
+  }
+
+  console.log("Last tag:", lastTag || "(none)");
+
+  const baseBranch = getDefaultBranch(cwd);
+
+  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, cwd));
+    } 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'`,
+          cwd
+        )
+          .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`;
+  }
+
+  const target = path.join(cwd, isPreview ? "RELEASE_NOTES.preview.md" : "RELEASE_NOTES.md");
+  fs.writeFileSync(target, notes, "utf8");
+
+  console.log(isPreview ? "✔ Generated RELEASE_NOTES.preview.md" : "✔ Generated RELEASE_NOTES.md");
+}
+
+function main() {
+  const isPreview = process.env.PREVIEW_MODE === "true";
+  generateReleaseNotes({ isPreview });
+}
+
+const __filename = fileURLToPath(import.meta.url);
+if (process.argv[1] === __filename) main();

package/bin/preview.js

@@ -1,47 +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);
-}
+#!/usr/bin/env node
+import fs from "node:fs";
+import { computeVersion } from "./compute-version.js";
+import { generateChangelog } from "./generate-changelog.js";
+import { generateReleaseNotes } from "./generate-release-notes.js";
+
+process.env.PREVIEW_MODE = "true";
+
+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 = computeVersion({ isPreview: true });
+
+  if (versionOutput) {
+    console.log("🔖 Computed version:");
+    console.log(versionOutput);
+  }
+
+  generateChangelog({ isPreview: true });
+  generateReleaseNotes({ isPreview: true });
+
+  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/docs/api.md

@@ -0,0 +1,28 @@
+# API Documentation
+
+Each `bin/*.js` script now also exposes a programmatic API so you can call
+the core logic directly from Node without spawning child processes. This
+is useful for integration tests, tooling, or when you need to orchestrate
+the actions from another script.
+
+Examples:
+
+```js
+import { computeVersion } from "release-suite/bin/compute-version.js";
+import { generateChangelog } from "release-suite/bin/generate-changelog.js";
+import { generateReleaseNotes } from "release-suite/bin/generate-release-notes.js";
+
+const result = computeVersion({ cwd: process.cwd() });
+await generateChangelog({ isPreview: true, cwd: process.cwd() });
+await generateReleaseNotes({ isPreview: true, cwd: process.cwd() });
+```
+
+Notes:
+
+- `cwd` controls the directory where git/package.json operations run (pass your consumer project's root).
+- `isPreview: true` writes preview files (`CHANGELOG.preview.md`, `RELEASE_NOTES.preview.md`) and relaxes some external requirements (e.g., `gh`).
+
+## computeVersion()
+
+> ℹ️ `computeVersion()` follows a strict, immutable contract.  
+> See [`compute-version.md`](compute-version.md).

package/docs/ci.md

@@ -0,0 +1,210 @@
+# CI/CD Examples
+
+## `create-release-pr.yml`
+
+```yml
+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
+    # - The PR does NOT have the "release" label
+    if: >
+      github.event.pull_request.merged == true &&
+      !contains(join(github.event.pull_request.labels.*.name, ','), 'release')
+    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: compute
+        run: |
+          set +e
+          RESULT=$(npx rs-compute-version --ci --json)
+          STATUS=$?
+          VERSION=$(echo "$RESULT" | jq -r '.nextVersion // empty')
+
+          echo "$RESULT"
+          echo "status=$STATUS" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Bump package.json
+        if: steps.compute.outputs.status == '0' && steps.compute.outputs.version != ''
+        run: npm version ${{ steps.compute.outputs.version }} --no-git-tag-version
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Generate changelog
+        if: steps.compute.outputs.status == '0' && steps.compute.outputs.version != ''
+        run: npx rs-generate-changelog
+
+      - name: Detect dist directory
+        id: dist
+        run: |
+          if [ -d dist ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Automatically create branches, commits, and PRs with peter-evans
+      - name: Create Release PR
+        if: steps.compute.outputs.status == '0' && steps.compute.outputs.version != ''
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: ":bricks: chore(release): prepare version ${{ steps.compute.outputs.version }} [skip ci]"
+          branch: release/${{ steps.compute.outputs.version }}
+          title: ":bricks: chore(release): ${{ steps.compute.outputs.version }}"
+          body: |
+            This PR contains the release artifacts:
+
+            - Updated `package.json` and `package-lock.json` with version ${{ steps.compute.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
+            ${{ steps.dist.outputs.exists == 'true' && 'dist/**' || '' }}
+
+```
+
+## `publish-on-merge.yml`
+
+```yml
+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
+    # - The PR has the "release" label
+    # - The PR title starts with ":bricks: chore(release):"
+    # - The PR was created by a bot
+    if: >
+      github.event.pull_request.merged == true &&
+      startsWith(github.event.pull_request.title, ':bricks: chore(release):') &&
+      contains(join(github.event.pull_request.labels.*.name, ','), 'release') &&
+      github.event.pull_request.user.type == 'Bot'
+    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: Create Git Tag
+        id: tag
+        run: |
+          set +e
+          RESULT=$(npx create-tag)
+          STATUS=$?
+          TAG=$(echo "$RESULT" | jq -r '.tag // empty')
+
+          echo "$RESULT"
+          echo "status=$STATUS" >> $GITHUB_OUTPUT
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+
+      # Publish to npm using Trusted Publishing (OIDC)
+      - name: Publish to npm (Trusted Publishing)
+        if: steps.tag.outputs.status == '0' && steps.tag.outputs.tag != ''
+        run: npm publish
+
+      # Generate release notes for GitHub Release
+      - name: Generate GitHub Release Notes
+        if: steps.tag.outputs.status == '0' && steps.tag.outputs.tag != ''
+        run: npx rs-generate-release-notes
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Create GitHub Release with notes and attach built assets
+      - name: Create GitHub Release + Tag
+        if: steps.tag.outputs.status == '0' && steps.tag.outputs.tag != ''
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+
+          ASSETS=()
+          if [ -d dist ]; then
+            ASSETS=(dist/**)
+          fi
+
+          gh release create "$VERSION" \
+            --title "$VERSION" \
+            --notes-file RELEASE_NOTES.md \
+            "${ASSETS[@]}"
+
+```