@entro314labs/release-kit 2.2.2 → 2.3.1

package/README.md

@@ -94,7 +94,7 @@ release-kit minor
 No global state to drift, no install step, and the version is explicit in the command.
 
 ```sh
-npx @entro314labs/release-kit@2.1.0 minor --yes
+npx @entro314labs/release-kit@2.3.0 minor --yes
 ```
 
 ### Vendored — no registry at release time
@@ -116,7 +116,7 @@ npx @entro314labs/release-kit --sync .        # writes scripts/release.mjs
 machine you do not want to install anything on.
 
 ```sh
-curl -fsSL https://raw.githubusercontent.com/entro314-labs/release-kit/v2.1.0/release.mjs \
+curl -fsSL https://raw.githubusercontent.com/entro314-labs/release-kit/v2.3.0/release.mjs \
   | node - minor --yes
 ```
 
@@ -144,6 +144,15 @@ pnpm release -- --help
 The target is optional. With no target it releases whatever version `package.json`
 already says — which is the mode to use when a version bump landed in an earlier commit.
 
+| `auto` | derived from the Conventional Commits since the last tag |
+
+`auto` follows release-please's rules: a breaking change (`!` or a `BREAKING CHANGE:`
+footer) is a major, a `feat:` is a minor, anything else is a patch. Below `1.0.0` that is
+softened — a breaking change bumps the minor rather than jumping to `1.0.0`. A commit body
+containing `Release-As: 2.0.0` pins the version outright. It always prints what it inferred
+and why before doing anything. Set `"versioning"` to `always-patch`, `always-minor` or
+`always-major` to never infer.
+
 | Target                               | From `1.2.3`                                     | From `2.0.0-beta.1` |
 | ------------------------------------ | ------------------------------------------------ | ------------------- |
 | _(none)_                             | `1.2.3`                                          | `2.0.0-beta.1`      |
@@ -163,16 +172,20 @@ Prerelease bumps need `--preid` unless the current version already carries one t
 
 ### Flags
 
-| Flag                | Effect                                                                     |
-| ------------------- | -------------------------------------------------------------------------- |
-| `--dry-run`         | Print every step, execute nothing. Preflight still runs and still reports. |
-| `--yes`, `-y`       | Skip the confirmation prompt.                                              |
-| `--preid <id>`      | Prerelease identifier: `alpha`, `beta`, `rc`, `next`, `nightly`, `canary`. |
-| `--dist-tag <name>` | Override the npm dist-tag. Always wins over the derived one.               |
-| `--only <steps>`    | Run only these steps, comma-separated.                                     |
-| `--skip <steps>`    | Run every step except these.                                               |
-| `--sync <dir>...`   | Copy this script into other projects and exit. Touches no git state.       |
-| `--help`, `-h`      | Full flag list.                                                            |
+| Flag                         | Effect                                                                     |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `--only <steps>`             | Run only these steps, comma-separated.                                     |
+| `--skip <steps>`             | Run every step except these.                                               |
+| `--commit`                   | Add the opt-in `commit` step: commit a dirty tree with a drafted message.  |
+| `--dry-run`                  | Print every step, execute nothing. Preflight still runs and still reports. |
+| `--yes`, `-y`                | Skip the confirmation prompt.                                              |
+| `--preid <id>`               | Prerelease identifier: `alpha`, `beta`, `rc`, `next`, `nightly`, `canary`. |
+| `--dist-tag <name>`          | Override the npm dist-tag. Always wins over the derived one.               |
+| `--assistant <name>`         | Drafting CLI: `auto`, `none`, `claude`, `codex`.                           |
+| `--assistant-model <name>`   | Model the assistant runs with.                                             |
+| `--assistant-effort <level>` | Reasoning effort the assistant runs with.                                  |
+| `--sync <dir>...`            | Copy this script into other projects and exit. Touches no git state.       |
+| `--help`, `-h`               | Full flag list.                                                            |
 
 ## 🧩 Steps
 
@@ -217,7 +230,11 @@ Notes resolve in this order:
    section ends at the next `##` heading or `---` rule.
 2. The `## [Unreleased]` section, if the version has no section of its own — this is the
    same content that step 2 above is about to promote.
-3. Otherwise GitHub generates them from the commits since the previous tag.
+3. The commits grouped by Conventional Commit type — Features, Bug Fixes, Performance
+   Improvements, Reverts, with breaking changes first and chores, CI and docs hidden. This
+   is deterministic and needs nothing installed, so decent notes are the default rather
+   than something that requires an assistant.
+4. Otherwise GitHub generates them from the commits since the previous tag.
 
 The same text becomes the tag annotation, the GitHub release body, and (when rolled) the
 changelog entry. It is written once and lands in three places.
@@ -243,17 +260,18 @@ falling through to `latest` would put a prerelease on the stable line where ever
 Every check runs and every failure is reported before it aborts once with the whole list,
 rather than stopping at the first problem.
 
-- The target version is greater than the current one
-- Working tree is clean
-- On the configured branch
+- The target version is greater than the current one — and for `auto`, which bump the
+  commits imply and why
+- Working tree is clean, or listed for commit when the `commit` step runs
+- On the configured branch, and not on a detached HEAD
 - The remote exists, is reachable, and the branch is not behind it
 - The tag is free — or already exists at `HEAD`, in which case it is reused
 - `gh` is installed and authenticated
-- Commit and tag signing can actually sign, when `commit.gpgsign` or `tag.gpgsign` is on
-- The publishing CLI is authenticated, and the version is not already on the registry
+- Commit and tag signing can actually sign, and the key is one GitHub will accept
+- The publishing CLI is authenticated, and the version is not already published
 - Configured release assets exist
-- A changelog section for the version exists _(a warning, not a failure — it falls back
-  to generated notes)_
+- A shallow clone is reported, since it truncates the history notes come from _(warning)_
+- A changelog section for the version exists _(warning — it falls back to generated notes)_
 
 Under `--dry-run` the failures are reported and then the remaining steps are shown anyway,
 so you can see the whole plan without fixing the blockers first.
@@ -335,12 +353,16 @@ rather than being silently ignored.
 
 | Key             | Default                  | Meaning                                                      |
 | --------------- | ------------------------ | ------------------------------------------------------------ |
+| `steps`         | all but `commit`         | Which steps run; the order is fixed                          |
 | `tagPrefix`     | `"v"`                    | Prepended to the version to form the tag                     |
 | `branch`        | `"main"`                 | The only branch a release may run from; `null` allows any    |
 | `remote`        | `"origin"`               | Git remote to push to                                        |
-| `changelog`     | `"CHANGELOG.md"`         | Changelog path; `null` disables changelog handling           |
-| `versionFiles`  | `[]`                     | Extra JSON files whose top-level `"version"` is kept in sync |
-| `publish`       | `"npm publish --tag %d"` | Publish command; `null` skips publishing                     |
+| `changelog`     | `"CHANGELOG.md"`         | Changelog path; `null` for a project without one             |
+| `versionFile`   | detected                 | Where the version lives; `null` versions by tag alone        |
+| `versionFiles`  | `[]`                     | Further files kept in sync; a path or `{ path, pattern }`    |
+| `publish`       | `"npm publish --tag %d"` | Publish command; `null` means none is configured             |
+| `versioning`    | `"conventional"`         | How `auto` infers; or `always-patch` / `-minor` / `-major`   |
+| `assistant`     | `null`                   | Drafting CLI: a name, `"auto"`, or `{ tool, model, effort }` |
 | `commitMessage` | `"chore(release): %t"`   | Release commit subject                                       |
 | `releaseTitle`  | `"%t"`                   | GitHub release title                                         |
 | `assets`        | `[]`                     | Files attached to the GitHub release                         |
@@ -360,7 +382,7 @@ Non-interactive by default: the confirmation prompt is skipped when stdin is not
   with:
     fetch-depth: 0 # release notes and the last-tag lookup need real history
 - id: release
-  run: npx @entro314labs/release-kit@2.1.0 minor --yes
+  run: npx @entro314labs/release-kit@2.3.0 minor --yes
   env:
     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 - run: echo "shipped ${{ steps.release.outputs.tag }} ${{ steps.release.outputs.release-url }}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "2.2.2",
+  "version": "2.3.1",
   "description": "Single-file, zero-dependency release mechanism for JS/TS/Node projects: version bump, changelog roll, commit, annotated tag, push, publish, GitHub release",
   "keywords": [
     "changelog",

package/release.mjs

@@ -66,6 +66,8 @@ import { createInterface } from 'node:readline/promises'
  *   commitMessage   string   release commit subject
  *   releaseTitle    string   GitHub release title
  *   assets          string[] files attached to the GitHub release
+ *   versioning      string   how `auto` derives a bump: "conventional", or
+ *                            always-patch / always-minor / always-major to never infer
  *   assistant       string|object  drafting CLI for commit messages and notes. A key of
  *                            ASSISTANTS, "auto" for the first available, or null. The
  *                            object form { tool, model, effort } also pins which model and
@@ -105,6 +107,7 @@ const DEFAULTS = {
   releaseTitle: '%t',
   assets: [],
   assistant: null,
+  versioning: 'conventional',
 }
 
 /**
@@ -226,6 +229,22 @@ function read(command, args) {
   }).trim()
 }
 
+/**
+ * Whether GitHub knows the key git signs with.
+ *
+ * Compares key material rather than fingerprints, so no extra process is spawned per key.
+ *
+ * @returns {boolean | null} null when it cannot be determined — gh missing, token without
+ *   the scope to list signing keys, or no network. An unanswerable check is not a failure.
+ */
+function signingKeyRegistered(keyPath) {
+  const local = readFileSync(keyPath, 'utf8').trim().split(/\s+/)[1]
+  if (!local) return null
+  const listed = tryRead('gh', ['api', 'user/ssh_signing_keys', '--jq', '.[].key'])
+  if (listed === null) return null
+  return listed.split('\n').some((key) => key.trim().split(/\s+/)[1] === local)
+}
+
 /** Read-only command → trimmed stdout, or null when it exits non-zero. */
 function tryRead(command, args) {
   try {
@@ -360,16 +379,122 @@ function runAssistant(prompt) {
 function commitsSinceLastTag() {
   const lastTag = tryRead('git', ['describe', '--tags', '--abbrev=0'])
   const range = lastTag ? `${lastTag}..HEAD` : 'HEAD'
-  const log = tryRead('git', ['log', '--format=%s', range]) ?? ''
-  return {
-    lastTag,
-    subjects: log
-      .split('\n')
-      .filter(
-        (s) =>
-          s && !/^chore\(release\)/i.test(s) && !/^Merge (branch|pull request|remote)/i.test(s),
-      ),
+  // %B is the whole message: bodies carry BREAKING CHANGE and Release-As footers. A record
+  // separator keeps multi-line messages parseable when splitting the log back apart.
+  const raw = tryRead('git', ['log', `--format=%B%x1e`, range]) ?? ''
+  const commits = raw
+    .split('\u001e')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [subject, ...rest] = entry.split('\n')
+      return { subject: subject.trim(), body: rest.join('\n').trim() }
+    })
+    .filter(
+      ({ subject }) =>
+        subject &&
+        !/^chore\(release\)/i.test(subject) &&
+        !/^Merge (branch|pull request|remote)/i.test(subject) &&
+        !/^wip\b/i.test(subject) &&
+        !/^(fixup|squash)!/.test(subject),
+    )
+  return { lastTag, commits, subjects: commits.map((c) => c.subject) }
+}
+
+/**
+ * Conventional Commit types and the changelog heading each lands under, following
+ * release-please's defaults. Types marked hidden are real changes but not release notes:
+ * a reader upgrading does not need to know the CI config moved.
+ */
+const CHANGELOG_SECTIONS = [
+  { type: 'feat', section: 'Features' },
+  { type: 'fix', section: 'Bug Fixes' },
+  { type: 'perf', section: 'Performance Improvements' },
+  { type: 'revert', section: 'Reverts' },
+  { type: 'docs', section: 'Documentation', hidden: true },
+  { type: 'style', section: 'Styles', hidden: true },
+  { type: 'refactor', section: 'Code Refactoring', hidden: true },
+  { type: 'test', section: 'Tests', hidden: true },
+  { type: 'build', section: 'Build System', hidden: true },
+  { type: 'ci', section: 'Continuous Integration', hidden: true },
+  { type: 'chore', section: 'Miscellaneous Chores', hidden: true },
+]
+
+/**
+ * Parse a commit into the parts a release cares about.
+ *
+ * @returns {{type: string, scope: string|null, breaking: boolean, subject: string,
+ *   releaseAs: string|null} | null} null when the subject is not Conventional Commits
+ */
+function parseCommit(subject, body = '') {
+  const match = /^([a-z]+)(?:\(([^)]+)\))?(!)?: (.+)$/i.exec(subject)
+  if (!match) return null
+  const [, type, scope, bang, text] = match
+  // A breaking change is marked either by `!` in the header or a BREAKING CHANGE footer.
+  const breaking = !!bang || /^BREAKING[ -]CHANGE:/m.test(body)
+  // `Release-As: 1.2.3` in a commit body pins the next version, so the decision can live
+  // in git history rather than on the command line.
+  const releaseAs = /^Release-As:\s*v?(\S+)/im.exec(body)?.[1] ?? null
+  return { type: type.toLowerCase(), scope: scope ?? null, breaking, subject: text, releaseAs }
+}
+
+/**
+ * The bump implied by a set of commits, following release-please's default strategy:
+ * a breaking change is major, a feature is minor, anything else is a patch.
+ *
+ * Below 1.0.0 that is usually wrong — a breaking change in a 0.x project conventionally
+ * bumps the minor, not to 1.0.0 — so `preMajor` softens both by one level.
+ *
+ * @returns {{bump: string, breaking: string[], features: string[], releaseAs: string|null}}
+ */
+function inferBump(commits, currentVersion, strategy = 'conventional') {
+  const parsed = commits.map((c) => parseCommit(c.subject, c.body)).filter(Boolean)
+  const releaseAs = parsed.find((c) => c.releaseAs)?.releaseAs ?? null
+  const breaking = parsed.filter((c) => c.breaking).map((c) => c.subject)
+  const features = parsed
+    .filter((c) => !c.breaking && /^feat(ure)?$/.test(c.type))
+    .map((c) => c.subject)
+
+  if (strategy !== 'conventional') {
+    return { bump: strategy.replace(/^always-/, ''), breaking, features, releaseAs }
   }
+
+  const preMajor = currentVersion ? parseVersion(currentVersion)?.major === 0 : false
+  let bump = 'patch'
+  if (breaking.length) bump = preMajor ? 'minor' : 'major'
+  else if (features.length) bump = 'minor'
+  return { bump, breaking, features, releaseAs }
+}
+
+/**
+ * Group commits into changelog sections, hiding the types that are not release notes.
+ * Deterministic and offline: this is what a project gets without an assistant.
+ *
+ * @returns {string | null} markdown body, or null when nothing visible changed
+ */
+function changelogFromCommits(commits) {
+  const parsed = commits.map((c) => parseCommit(c.subject, c.body)).filter(Boolean)
+  const lines = []
+
+  const breaking = parsed.filter((c) => c.breaking)
+  if (breaking.length) {
+    lines.push('### ⚠ BREAKING CHANGES', '')
+    for (const c of breaking) lines.push(`- ${c.scope ? `**${c.scope}:** ` : ''}${c.subject}`)
+    lines.push('')
+  }
+
+  for (const { type, section, hidden } of CHANGELOG_SECTIONS) {
+    if (hidden) continue
+    const inSection = parsed.filter(
+      (c) => c.type === type || (type === 'feat' && c.type === 'feature'),
+    )
+    if (!inSection.length) continue
+    lines.push(`### ${section}`, '')
+    for (const c of inSection) lines.push(`- ${c.scope ? `**${c.scope}:** ` : ''}${c.subject}`)
+    lines.push('')
+  }
+
+  return lines.length ? lines.join('\n').trim() : null
 }
 
 const CONVENTIONAL_TYPES = 'build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test'
@@ -742,7 +867,16 @@ function writeVersionInto(entry, version) {
 // ─────────────────────────────────────────────────────────────────────────────
 
 const argv = process.argv.slice(2)
-const BUMPS = new Set(['major', 'minor', 'patch', 'premajor', 'preminor', 'prepatch', 'prerelease'])
+const BUMPS = new Set([
+  'auto',
+  'major',
+  'minor',
+  'patch',
+  'premajor',
+  'preminor',
+  'prepatch',
+  'prerelease',
+])
 
 const flag = (name) => argv.includes(name)
 const option = (name) => {
@@ -987,6 +1121,9 @@ console.log(
     (dryRun ? `  ${yellow('(dry run — nothing will execute)')}` : ''),
 )
 
+/** What `auto` inferred, kept so preflight can show the reasoning. */
+let autoBump = null
+
 let version
 if (!target) {
   if (!currentVersion) {
@@ -996,6 +1133,29 @@ if (!target) {
     )
   }
   version = currentVersion
+} else if (target === 'auto') {
+  if (!currentVersion) {
+    abort('auto needs a versionFile to bump from. Pass a version explicitly instead.')
+  }
+  const { commits, lastTag } = commitsSinceLastTag()
+  if (!commits.length) {
+    abort(
+      `no releasable commits since ${lastTag ?? 'the start of the project'} — nothing to release`,
+    )
+  }
+  autoBump = inferBump(commits, currentVersion, config.versioning)
+  if (autoBump.releaseAs) {
+    if (!parseVersion(autoBump.releaseAs)) {
+      abort(`Release-As: ${autoBump.releaseAs} in a commit is not a semver version`)
+    }
+    version = autoBump.releaseAs
+  } else {
+    version = incrementVersion(
+      currentVersion,
+      autoBump.bump,
+      requestedPreid ?? preidOf(currentVersion),
+    )
+  }
 } else if (BUMPS.has(target)) {
   if (!currentVersion) {
     abort(`a ${target} bump needs a versionFile to bump from. Pass a version explicitly instead.`)
@@ -1098,6 +1258,20 @@ const fail = (message) => {
   problems.push(message)
 }
 
+if (autoBump) {
+  const reason = autoBump.releaseAs
+    ? `Release-As: ${autoBump.releaseAs} in a commit`
+    : autoBump.breaking.length
+      ? `${autoBump.breaking.length} breaking change(s)`
+      : autoBump.features.length
+        ? `${autoBump.features.length} feature(s), no breaking changes`
+        : 'no features or breaking changes'
+  ok(`auto: ${autoBump.bump} — ${reason}`)
+  for (const subject of [...autoBump.breaking, ...autoBump.features].slice(0, 5)) {
+    console.log(dim(`       ${subject}`))
+  }
+}
+
 if (bumping && compareVersions(version, currentVersion) <= 0) {
   fail(`${version} is not greater than the current version ${currentVersion}`)
 } else if (bumping) {
@@ -1131,9 +1305,9 @@ if (runs('commit') && !assistant) {
     .join(', ')
   ok(`assistant: ${assistantName}${detail ? ` (${detail})` : ''}`)
   if (assistantModel && !assistant.model)
-    warn(`${assistantName} takes no model flag — --model ignored`)
+    warn(`${assistantName} takes no model flag — --assistant-model ignored`)
   if (assistantEffort && !assistant.effort)
-    warn(`${assistantName} takes no effort flag — --effort ignored`)
+    warn(`${assistantName} takes no effort flag — --assistant-effort ignored`)
 }
 
 const branch = tryRead('git', ['rev-parse', '--abbrev-ref', 'HEAD'])
@@ -1193,6 +1367,22 @@ if (signsSomething && signingKeys.length) {
     )
   } else {
     ok(`signing commits and tags (${format})`)
+    // git signs happily with a key GitHub has never seen, which is how a repository fills
+    // up with commits that are locally valid and permanently "Unverified". Only GitHub can
+    // answer this, and only when the token carries the scope to list signing keys — so an
+    // unanswerable check stays silent rather than guessing.
+    if (format === 'ssh' && keyPath && existsSync(keyPath) && runs('release')) {
+      const registered = signingKeyRegistered(keyPath)
+      if (registered === false) {
+        warn(
+          'this signing key is not registered with GitHub, so the commits will show as ' +
+            'Unverified.\n       Add it: gh ssh-key add ' +
+            `${signingKey} --type signing`,
+        )
+      } else if (registered === true) {
+        ok('signing key is registered with GitHub')
+      }
+    }
   }
 }
 
@@ -1269,11 +1459,15 @@ let draftedNotes = null
  */
 const notesDeferred = !!(dirty && runs('commit') && assistant)
 
-/** Draft notes from the commit log, reporting what it is doing since it takes a moment. */
+/**
+ * Notes for a version, in descending order of how much they can be trusted:
+ * an assistant's prose when one is configured, otherwise the commits grouped by
+ * Conventional Commit type. Only when neither yields anything does GitHub generate them.
+ */
 function draftNotesFor(v) {
-  if (!assistant) return null
-  const { lastTag, subjects } = commitsSinceLastTag()
-  if (!subjects.length) return null
+  const { lastTag, subjects, commits } = commitsSinceLastTag()
+  if (!commits.length) return null
+  if (!assistant) return changelogFromCommits(commits)
   if (shallow) {
     warn(
       `shallow clone: only ${subjects.length} commit(s) are visible, so the notes will ` +
@@ -1281,7 +1475,7 @@ function draftNotesFor(v) {
     )
   }
   note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
-  return draftReleaseNotes(v, subjects, lastTag)
+  return draftReleaseNotes(v, subjects, lastTag) ?? changelogFromCommits(commits)
 }
 if (config.changelog && existsSync(config.changelog)) {
   const text = readFileSync(config.changelog, 'utf8')