@entro314labs/release-kit 2.3.0 → 2.3.2

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
 ```
 
@@ -172,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
 
@@ -256,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.
@@ -348,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                         |
@@ -373,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.3.0",
+  "version": "2.3.2",
   "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

@@ -229,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 {
@@ -740,9 +756,18 @@ function changelogSection(text, version) {
  * @returns {string | null} the updated document, or null when there is nothing to roll
  */
 function rollUnreleased(text, version, date) {
+  // A heading for this version already exists — possibly with an empty body, which
+  // `changelogSection` reports as absent. Rolling again would duplicate the heading.
+  if (new RegExp(`^##\\s+\\[?v?${escapeRe(version)}\\]?(?![\\w.-])`, 'm').test(text)) return null
+
   const heading = /^##\s+\[?Unreleased\]?[^\n]*$/im
   const match = heading.exec(text)
   if (!match) return null
+
+  // An empty [Unreleased] has nothing to promote; rolling it produces an empty section.
+  const rest = text.slice(match.index + match[0].length)
+  const body = (/^## /m.exec(rest) ? rest.slice(0, /^## /m.exec(rest).index) : rest).trim()
+  if (!body) return null
   const released = `## [Unreleased]\n\n## [${version}] - ${date}`
   return text.slice(0, match.index) + released + text.slice(match.index + match[0].length)
 }
@@ -1289,9 +1314,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'])
@@ -1351,6 +1376,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')
+      }
+    }
   }
 }
 
@@ -1483,6 +1524,18 @@ for (const asset of config.assets) {
   else fail(`asset ${asset} does not exist`)
 }
 
+// Reusing a tag is the resume path, and a resume writes nothing. If this run would still
+// produce a commit, that commit moves HEAD past the tag and the release ends up tagged at
+// the wrong revision — which is silent until someone checks out the tag.
+if (taggedCommit && runs('tag') && (bumping || rolledChangelog)) {
+  fail(
+    `tag ${tag} already exists at HEAD, but this run would still commit ` +
+      `${[bumping && 'a version bump', rolledChangelog && 'a changelog entry'].filter(Boolean).join(' and ')}.\n` +
+      '       That commit would leave the tag behind HEAD. Release a new version, or use ' +
+      '--only with the steps that remain.',
+  )
+}
+
 if (problems.length) {
   const summary = `${problems.length} preflight check(s) failed:\n  - ${problems.join('\n  - ')}`
   if (!dryRun) abort(summary)