@eclipse-docks/cli 0.7.114 → 0.7.122

package/README.md

@@ -9,18 +9,26 @@ npx @eclipse-docks/cli release                       # bump patch, prompt for re
 npx @eclipse-docks/cli release minor                 # bump minor
 npx @eclipse-docks/cli release major -m "notes"      # bump major with inline release notes
 npx @eclipse-docks/cli release v1.2.3                # explicit version
-npx @eclipse-docks/cli release --dry-run             # print what would be committed
-npx @eclipse-docks/cli release --no-push             # commit locally without pushing
+npx @eclipse-docks/cli release --since v1.2.0        # notes from commits since that tag
+npx @eclipse-docks/cli release --dry-run             # print what would be tagged
+npx @eclipse-docks/cli release --no-push             # create the tag locally without pushing
 ```
 
 ## `release`
 
-Creates an empty commit whose subject is the next version (`vX.Y.Z`) and pushes it.
-Pair this with a CI workflow that tags/releases on that commit subject (see
-[`.github/workflows/app-release.yml`](../../.github/workflows/app-release.yml) for a
-reusable one) — the commit body becomes the release notes.
+Creates an annotated tag whose name is the version (`vX.Y.Z`) and pushes it.
+When pushing (the default), any unpushed commits on the current branch are pushed
+to `origin` first. The tag message body becomes the GitHub Release notes.
+
+Wire release in CI with [`.github/workflows/app-release.yml`](../../.github/workflows/app-release.yml):
+downstream apps usually trigger it on `v*` tag push; this monorepo waits for a green
+**CI** run on `main` first (see [`.github/workflows/release.yml`](../../.github/workflows/release.yml)).
+
+The last version is the most recent `vX.Y.Z` tag reachable from `HEAD` (via
+`git describe`), not the highest semver tag in the repository. That drives the
+default bump and changelog range.
 
 If no release notes are given via `-m`, an end-user-facing summary is generated from the
-commits since the last version, grouped under **Features**, **Fixes**, **Docs**, and
-**Chore/Refactor**, and offered as the default (press Enter on an empty first line to
-accept it).
+commits since that tag (or since `--since vX.Y.Z` when set), grouped under **Features**,
+**Fixes**, **Docs**, and **Chore/Refactor**, and offered as the default (press Enter on
+an empty first line to accept it).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eclipse-docks/cli",
-  "version": "0.7.114",
+  "version": "0.7.122",
   "description": "Developer CLI for Eclipse Docks apps (release automation and more)",
   "type": "module",
   "bin": {

package/src/commands/release.js

@@ -1,6 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 
+/** CLI arg / release tag name: exact `vX.Y.Z`. */
 const VERSION_RE = /^v\d+\.\d+\.\d+$/;
 
 function git(args, cwd) {
@@ -16,8 +17,12 @@ function gitOrNull(args, cwd) {
   return result.status === 0 ? result.stdout.trim() : null;
 }
 
+function usage() {
+  return 'Usage: docks release [major|minor|patch|vX.Y.Z] [-m "release notes"] [--since vX.Y.Z] [--dry-run] [--no-push]';
+}
+
 function parseArgs(argv) {
-  const opts = { bump: 'patch', version: '', notes: '', dryRun: false, push: true };
+  const opts = { bump: 'patch', version: '', since: '', notes: '', dryRun: false, push: true };
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -25,6 +30,12 @@ function parseArgs(argv) {
       opts.bump = arg;
     } else if (VERSION_RE.test(arg)) {
       opts.version = arg;
+    } else if (arg === '--since') {
+      const value = argv[++i] ?? '';
+      if (!VERSION_RE.test(value)) {
+        throw new Error(`--since requires a version like v1.2.3\n${usage()}`);
+      }
+      opts.since = value;
     } else if (arg === '-m' || arg === '--message') {
       opts.notes = argv[++i] ?? '';
     } else if (arg === '-n' || arg === '--dry-run') {
@@ -34,9 +45,7 @@ function parseArgs(argv) {
     } else if (arg === '--no-push') {
       opts.push = false;
     } else {
-      throw new Error(
-        `Unknown argument: ${arg}\nUsage: docks release [major|minor|patch|vX.Y.Z] [-m "release notes"] [--dry-run] [--no-push]`,
-      );
+      throw new Error(`Unknown argument: ${arg}\n${usage()}`);
     }
   }
 
@@ -44,12 +53,57 @@ function parseArgs(argv) {
 }
 
 function findLastVersion(cwd) {
-  const log = gitOrNull(['log', '--pretty=%s'], cwd);
-  if (!log) return null;
-  for (const subject of log.split('\n')) {
-    if (VERSION_RE.test(subject)) return subject;
+  const tag = gitOrNull(['describe', '--tags', '--abbrev=0', '--match', 'v*', 'HEAD'], cwd);
+  if (!tag) return null;
+  const trimmed = tag.trim();
+  return VERSION_RE.test(trimmed) ? trimmed : null;
+}
+
+function findVersionCommit(cwd, version) {
+  return gitOrNull(['rev-parse', '--verify', `${version}^{commit}`], cwd);
+}
+
+function currentBranch(cwd) {
+  const branch = gitOrNull(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+  if (!branch || branch === 'HEAD') return null;
+  return branch;
+}
+
+function upstreamStatus(cwd) {
+  const upstream = gitOrNull(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], cwd);
+  if (!upstream) return null;
+  const counts = git(['rev-list', '--left-right', '--count', `${upstream}...HEAD`], cwd);
+  const [behind, ahead] = counts.split('\t').map(Number);
+  return { upstream, behind, ahead };
+}
+
+function pushBranchIfNeeded(cwd, { dryRun = false } = {}) {
+  const branch = currentBranch(cwd);
+  if (!branch) {
+    throw new Error('Detached HEAD — checkout a branch before releasing.');
+  }
+
+  const status = upstreamStatus(cwd);
+  if (!status) {
+    throw new Error(`Branch ${branch} has no upstream. Push it first:\n  git push -u origin ${branch}`);
+  }
+
+  if (status.behind > 0) {
+    throw new Error(
+      `Branch ${branch} is ${status.behind} commit(s) behind ${status.upstream}. Pull before releasing.`,
+    );
+  }
+
+  if (status.ahead === 0) return branch;
+
+  if (dryRun) {
+    console.log(`[dry run] would push ${status.ahead} commit(s) to origin ${branch}`);
+    return branch;
   }
-  return null;
+
+  console.log(`Pushing ${status.ahead} commit(s) to origin ${branch}...`);
+  git(['push', 'origin', branch], cwd);
+  return branch;
 }
 
 function bumpVersion(last, bump) {
@@ -64,16 +118,18 @@ function bumpVersion(last, bump) {
   }
 }
 
-function generateSummary(cwd, last) {
-  // find the commit whose subject *is* the last version, not a tag (tags may not exist locally)
-  const lastCommit = last ? gitOrNull(['log', '-E', '--pretty=%H', '-1', `--grep=^${last}$`], cwd) : null;
-  const range = lastCommit ? `${lastCommit}..HEAD` : 'HEAD';
+function generateSummary(cwd, since) {
+  const sinceCommit = since ? findVersionCommit(cwd, since) : null;
+  if (since && !sinceCommit) {
+    throw new Error(`No tag found for --since ${since}.`);
+  }
+  const range = sinceCommit ? `${sinceCommit}..HEAD` : 'HEAD';
 
   const log = gitOrNull(['log', range, '--no-merges', '--pretty=%s'], cwd) ?? '';
   const buckets = { features: [], fixes: [], docs: [], chores: [] };
 
   for (const subject of log.split('\n')) {
-    if (!subject || VERSION_RE.test(subject)) continue;
+    if (!subject || VERSION_RE.test(subject.trim())) continue;
 
     const stripped = subject.includes(': ') ? subject.slice(subject.indexOf(': ') + 2) : subject;
     const text = stripped.charAt(0).toUpperCase() + stripped.slice(1);
@@ -126,7 +182,7 @@ export async function release(argv, cwd = process.cwd()) {
   let version = opts.version;
   if (!version) {
     version = bumpVersion(last ?? 'v0.0.0', opts.bump);
-    console.log(`Last version commit: ${last ?? 'v0.0.0'}`);
+    console.log(`Last release tag: ${last ?? 'v0.0.0'}`);
   }
 
   if (gitOrNull(['rev-parse', version], cwd)) {
@@ -135,28 +191,39 @@ export async function release(argv, cwd = process.cwd()) {
 
   let notes = opts.notes;
   if (!notes) {
-    const summary = generateSummary(cwd, last);
+    const since = opts.since || last;
+    if (since) console.log(`Summarizing commits since ${since}`);
+    const summary = generateSummary(cwd, since);
     notes = await promptNotes(version, summary);
   }
 
   if (opts.dryRun) {
-    console.log(`\n[dry run] would create empty commit:\n  ${version}\n`);
+    if (opts.push) pushBranchIfNeeded(cwd, { dryRun: true });
+    console.log(`\n[dry run] would create annotated tag ${version} at HEAD`);
     console.log(notes.replace(/^/gm, '  '));
     if (opts.push) {
-      const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
-      console.log(`[dry run] would push to origin ${branch}`);
+      console.log(`[dry run] would push tag to origin ${version}`);
     }
     return;
   }
 
-  git(['commit', '--allow-empty', '-m', version, '-m', notes], cwd);
+  if (opts.push) {
+    pushBranchIfNeeded(cwd);
+  }
+
+  const tagArgs = ['tag', '-a', version, '-m', version];
+  if (notes.trim()) {
+    tagArgs.push('-m', notes.trimEnd());
+  }
+  git(tagArgs, cwd);
 
-  const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
   if (opts.push) {
-    git(['push', 'origin', branch], cwd);
-    console.log(`\nPushed ${version} to origin/${branch}; the release workflow will take over.`);
+    git(['push', 'origin', version], cwd);
+    console.log(`\nPushed tag ${version}; the release workflow will take over.`);
   } else {
-    console.log(`\nCreated release commit for ${version}. Push it to trigger the release:`);
-    console.log(`  git push origin ${branch}`);
+    console.log(`\nCreated annotated tag ${version}. Push your branch and tag to trigger the release:`);
+    const branch = currentBranch(cwd);
+    if (branch) console.log(`  git push origin ${branch}`);
+    console.log(`  git push origin ${version}`);
   }
 }