@entro314labs/release-kit 1.0.3 → 2.1.0

package/README.md

@@ -54,7 +54,9 @@ Released v2.5.0
 | ----------------------------------------------------------------------- | --------------------------------------- |
 | [📦 Install](#-install)                                                 | package, `npx`, or vendored file        |
 | [⚡ Usage](#-usage)                                                     | targets, bumps, flags                   |
-| [🔁 What a release does](#-what-a-release-does)                         | the seven steps, notes, dist-tags       |
+| [🧩 Steps](#-steps)                                                     | the seven steps and how to select them  |
+| [🤖 Assistant](#-assistant-optional)                                    | optional AI drafting                    |
+| [🌍 Any language](#-any-language)                                       | Rust, Python, tag-only, anything        |
 | [✅ Preflight](#-preflight)                                             | what is checked before anything mutates |
 | [♻️ Recovering from a failed run](#️-recovering-from-a-failed-run)       | why re-running is safe                  |
 | [⚙️ Configuration](#️-configuration)                                     | `release.config.json`, publishing, auth |
@@ -136,35 +138,50 @@ 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`. |
-| `--tag <dist-tag>` | Override the npm dist-tag. Always wins over the derived one.               |
-| `--skip-publish`   | Do not publish to the registry.                                            |
-| `--skip-release`   | Do not create the GitHub release.                                          |
-| `--sync <dir>...`  | Copy this script into other projects and exit. Touches no git state.       |
-| `--help`, `-h`     | Full flag list.                                                            |
-
-## 🔁 What a release does
-
-Steps that do not apply are skipped silently — a project with no changelog, or with
-`publish` disabled, simply has fewer steps.
-
-1. **Write the version** into `package.json` and any configured `versionFiles`. The value
-   is replaced in place, so key order, indentation, and trailing newline all survive. A
-   `package-lock.json` is resynced, because it embeds the root version twice.
-2. **Roll the changelog**: `## [Unreleased]` becomes `## [x.y.z] - YYYY-MM-DD`, with a
-   fresh empty `## [Unreleased]` reopened above it for the next cycle — the
-   [Keep a Changelog](https://keepachangelog.com/) convention.
-3. **Commit** the files that actually changed.
-4. **Tag**, annotated, with the release notes as the annotation — so a CI workflow can
-   read the notes straight off the tag instead of re-deriving them.
-5. **Push** with `git push --follow-tags`, which sends the commit and the tag in one
-   call. Pushing them separately is how a tag ends up on the remote without its commit.
-6. **Publish** to the registry.
-7. **Create the GitHub release**, marked `--latest` or `--prerelease`.
+| 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.                                                            |
+
+## 🧩 Steps
+
+A release is seven named steps. They always run in this order — `steps` selects which of
+them execute, it never reorders them.
+
+| Step        | Default | What it does                                                                                    |
+| ----------- | ------- | ----------------------------------------------------------------------------------------------- |
+| `commit`    | off     | Commit a dirty working tree with a drafted message ([assistant](#-assistant-optional) required) |
+| `version`   | on      | Write the version into `package.json` and `versionFiles`                                        |
+| `changelog` | on      | Roll `[Unreleased]` into the version, or add drafted notes                                      |
+| `tag`       | on      | Annotated git tag carrying the release notes                                                    |
+| `push`      | on      | Push the branch and tag together (`--follow-tags`)                                              |
+| `publish`   | on      | Run the configured `publish` command                                                            |
+| `release`   | on      | Create the GitHub release                                                                       |
+
+`version` and `changelog` write files; those writes are persisted by a release commit made
+automatically when either step runs.
+
+```sh
+release-kit minor --skip publish            # everything but publish
+release-kit --only tag,push,release         # a version already committed elsewhere
+release-kit minor --commit                  # add the opt-in commit step
+```
+
+Or fix it per project, and just run `release-kit minor`:
+
+```json
+{ "steps": ["commit", "version", "changelog", "tag", "push", "release"] }
+```
+
+`steps` decides **what** runs. Every other key describes **how** a step behaves — `publish`
+is the command, `changelog` is the file. A step whose configuration is `null` runs as a
+no-op and says so, rather than silently meaning "skip".
 
 ### Release notes
 
@@ -194,7 +211,7 @@ version, never guessed:
 
 The refusal is deliberate: an unrecognised prerelease identifier has no safe channel, and
 falling through to `latest` would put a prerelease on the stable line where every
-`npm install` picks it up. Pass `--tag <dist-tag>` to choose a channel explicitly.
+`npm install` picks it up. Pass `--dist-tag <name>` to choose a channel explicitly.
 
 ## ✅ Preflight
 
@@ -233,6 +250,54 @@ it stopped. There is no cleanup step, no `--resume`, and nothing to remember.
 The one case that is not recoverable by re-running is a tag that exists at a _different_
 commit than `HEAD`. That is a genuine conflict, and it aborts rather than guessing.
 
+## 🌍 Any language
+
+Only one step is Node-specific: `publish`. Committing, changelog rolling, tagging, pushing
+and GitHub releases are the same everywhere, so `versionFile` points at wherever a project
+keeps its version and the rest works unchanged.
+
+| Project                        | Config                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------- |
+| Node (npm)                     | nothing — `package.json` and `npm publish` are the defaults                     |
+| Node (pnpm / bun)              | `{"publish": "pnpm publish --tag %d"}` or `{"publish": "bun publish --tag %d"}` |
+| Rust                           | `{"versionFile": "Cargo.toml", "publish": "cargo publish"}`                     |
+| Python                         | `{"versionFile": "pyproject.toml", "publish": "uv publish"}`                    |
+| Go                             | `{"versionFile": null, "publish": "go list -m %n@%t"}` — the tag is the release |
+| Anything with a `VERSION` file | `{"versionFile": "VERSION", "publish": null}`                                   |
+| Versioned only by tag          | `{"versionFile": null}`, then `release-kit 1.2.3`                               |
+
+The publish step also gets a preflight when the command is one it recognises:
+
+| Publish command | Authentication                        | Already published?                  |
+| --------------- | ------------------------------------- | ----------------------------------- |
+| `npm` / `pnpm`  | `whoami`                              | `view <name>@<version>`             |
+| `bun`           | `bun pm whoami`                       | `bun pm view <name>@<version>`      |
+| `uv`            | `UV_PUBLISH_TOKEN` in the environment | none — `uv` skips duplicates itself |
+| `go`            | none needed                           | `go list -m <module>@<tag>`         |
+
+Anything else runs as written with no preflight. The project name comes from the manifest —
+`name` in `package.json`, `Cargo.toml` or `pyproject.toml`, `module` in `go.mod` — falling
+back to the repository directory.
+
+The format is inferred from the file name: `.json` reads the `"version"` field, `.toml`
+reads the first `version = "x.y.z"` line, and any other file is treated as containing just
+the version. Only the version itself is rewritten, so comments and formatting survive — and
+because the TOML match is anchored to the start of a line, a dependency's
+`serde = { version = "1.0" }` is left alone.
+
+For anything else, give a pattern with one capture group around the version. `versionFiles`
+takes the same entries, so several files stay in sync across formats:
+
+```json
+{
+  "versionFile": { "path": "version.go", "pattern": "^const Version = \"(.+)\"" },
+  "versionFiles": [{ "path": "Chart.yaml", "pattern": "^version: (.+)$" }]
+}
+```
+
+The project name comes from the manifest when there is one (`name` in `package.json`,
+`Cargo.toml` or `pyproject.toml`), and falls back to the repository directory.
+
 ## ⚙️ Configuration
 
 `release.config.json`, beside `package.json`. Every key is optional; unknown keys abort
@@ -313,6 +378,56 @@ A project releasing off a non-default branch with a different tag scheme:
 }
 ```
 
+## 🤖 Assistant (optional)
+
+An assistant is an AI CLI already installed on your machine. When one is configured,
+release-kit can write the Conventional Commits message for a dirty working tree and draft
+release notes from the commit log. It is **off by default**, and every failure — not
+installed, not authenticated, timed out, unusable answer — falls back to the behaviour you
+already have. A release is never blocked because a text generator was unavailable.
+
+```sh
+pnpm release minor --commit --assistant claude --assistant-model sonnet --assistant-effort low
+```
+
+| Tool     | Invocation   | Model               | Effort                           |
+| -------- | ------------ | ------------------- | -------------------------------- |
+| `claude` | `claude -p`  | `--assistant-model` | `--assistant-effort` (low … max) |
+| `codex`  | `codex exec` | `-m`                | `-c model_reasoning_effort=`     |
+
+Configure it once instead:
+
+```json
+{
+  "assistant": { "tool": "claude", "model": "sonnet", "effort": "low" }
+}
+```
+
+`"assistant": "auto"` picks the first tool found on PATH; `"claude"` is shorthand for
+`{ "tool": "claude" }`. Naming a tool that is not installed is an error rather than a silent
+downgrade, so a configured pipeline fails loudly; `"auto"` degrades quietly by design.
+
+### What it does
+
+- **`--commit`** stages the working tree, drafts a Conventional Commits message for the
+  staged diff, and commits — instead of refusing to release. The subject is validated
+  against the Conventional Commits grammar; an answer that does not parse is rejected rather
+  than committed. Attribution lines (`Co-Authored-By`, `Generated with`) are stripped, so
+  the tool never signs your commits.
+- **Release notes** are drafted from the commits since the last tag when `CHANGELOG.md` has
+  no section for the version. They are written into the changelog, used as the tag
+  annotation, and posted as the GitHub release body — the same "written once, lands in three
+  places" path a hand-written section takes.
+
+With `--commit`, notes are drafted _after_ that commit lands, so they describe the change it
+just made. Merge, release, `WIP` and `fixup!`/`squash!` commits are excluded from the prompt.
+
+### Adding another tool
+
+One row in `ASSISTANTS` in `release.mjs`: the command, the args that make it read a prompt on
+stdin, and how it spells model and effort. Tools whose stdout carries session scaffolding
+declare `outputFile` and the answer is read from there instead.
+
 ## 🔄 Keeping vendored copies in sync
 
 Installed as a dependency, updates come from your package manager and there is nothing to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entro314labs/release-kit",
-  "version": "1.0.3",
+  "version": "2.1.0",
   "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",
@@ -49,6 +49,6 @@
     "oxlint": "^1.78.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   }
 }

package/release.mjs

@@ -32,7 +32,8 @@
  */
 
 import { execFileSync, execSync } from 'node:child_process'
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { basename, join, relative, resolve, sep } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
@@ -50,22 +51,53 @@ import { createInterface } from 'node:readline/promises'
  *   branch          string   the only branch a release may run from; null to allow any
  *   remote          string   git remote to push to
  *   changelog       string   changelog path; null to disable changelog handling
- *   versionFiles    string[] extra JSON files whose top-level "version" is kept in sync
+ *   versionFile     string|object|null  where the project's version lives; null when the
+ *                            repository versions by git tag alone
+ *   versionFiles    array    further files whose version is kept in sync; each is a path
+ *                            or { path, pattern }
  *   publish         string   publish command; null to skip publishing entirely
  *   commitMessage   string   release commit subject
  *   releaseTitle    string   GitHub release title
  *   assets          string[] files attached to the GitHub release
+ *   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
+ *                            reasoning effort that CLI is invoked with.
  */
+/**
+ * The release pipeline, in the only order that is safe to run it. `steps` selects which of
+ * these execute; it never reorders them — publishing before tagging, or pushing before
+ * committing, is a mistake the tool should not let you express.
+ *
+ *   commit     commit a dirty working tree (opt-in; touches work that predates the release)
+ *   version    write the version into package.json and versionFiles
+ *   changelog  roll [Unreleased] into the version, or add drafted notes
+ *   tag        annotated git tag carrying the release notes
+ *   push       push the branch and the tag together
+ *   publish    run the configured publish command
+ *   release    create the GitHub release
+ *
+ * `version` and `changelog` write files; those writes are persisted by a release commit
+ * made automatically when either step runs.
+ */
+const STEPS = ['commit', 'version', 'changelog', 'tag', 'push', 'publish', 'release']
+
+/** Everything but `commit`, which is opt-in because it commits work you did not stage. */
+const DEFAULT_STEPS = STEPS.filter((name) => name !== 'commit')
+
 const DEFAULTS = {
+  steps: DEFAULT_STEPS,
   tagPrefix: 'v',
   branch: 'main',
   remote: 'origin',
   changelog: 'CHANGELOG.md',
+  versionFile: 'package.json',
   versionFiles: [],
   publish: 'npm publish --tag %d',
   commitMessage: 'chore(release): %t',
   releaseTitle: '%t',
   assets: [],
+  assistant: null,
 }
 
 /**
@@ -94,13 +126,23 @@ Target (optional; defaults to the version already in package.json):
   prepatch preminor premajor prerelease
                        prerelease bump; needs --preid unless it can be inferred
 
+Steps, in the fixed order they run. All but "commit" run by default:
+  ${STEPS.join('  ')}
+
 Flags:
+  --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 working tree with a
+                       drafted Conventional Commits message instead of refusing to release
   --preid <id>         prerelease identifier (alpha, beta, rc, next, nightly, canary)
-  --tag <dist-tag>     override the npm dist-tag (default: derived from the version)
+  --dist-tag <name>    override the npm dist-tag (default: derived from the version)
   --dry-run            print every step and execute nothing
   --yes, -y            skip the confirmation prompt
-  --skip-publish       do not publish to the registry
-  --skip-release       do not create the GitHub release
+  --assistant <name>   drafting CLI to use: auto, none, claude, codex
+  --assistant-model <name>
+                       model the assistant runs with (e.g. sonnet, opus)
+  --assistant-effort <level>
+                       reasoning effort the assistant runs with (low … max)
   --sync <dir>...      copy this script into other projects' scripts/ and exit
   --help, -h           show this
 
@@ -192,6 +234,203 @@ function tryRead(command, args) {
  */
 const succeeds = (command, args) => tryRead(command, args) !== null
 
+// ─────────────────────────────────────────────────────────────────────────────
+// ASSISTANTS — optional CLIs that draft prose (commit messages, release notes)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Drafting tools, tried in this order when `assistant` is "auto". Each is a CLI that
+ * reads a prompt on stdin and writes plain text to stdout. Supporting another harness is
+ * one row here; nothing else in the file names a specific tool.
+ */
+const ASSISTANTS = {
+  claude: {
+    command: 'claude',
+    args: ['-p'],
+    probe: ['--version'],
+    model: (m) => ['--model', m],
+    effort: (e) => ['--effort', e],
+  },
+  codex: {
+    command: 'codex',
+    args: ['exec', '--skip-git-repo-check', '--sandbox', 'read-only'],
+    probe: ['--version'],
+    model: (m) => ['-m', m],
+    effort: (e) => ['-c', `model_reasoning_effort="${e}"`],
+    // `codex exec` streams session scaffolding (MCP notices, hook logs) to stdout, so the
+    // answer is only clean when written to a file with --output-last-message.
+    outputFile: (path) => ['--output-last-message', path],
+  },
+}
+
+/** How long a draft may take before the release gives up and falls back. */
+const DRAFT_TIMEOUT_MS = 180_000
+
+/**
+ * Lines a drafting tool may append that must never reach a commit message or release
+ * notes: attribution for the tool itself, and the markdown fences models wrap output in.
+ */
+function cleanDraft(text) {
+  return text
+    .replace(/^\s*```[a-z]*\s*\n?/i, '')
+    .replace(/\n?```\s*$/, '')
+    .split('\n')
+    .filter(
+      (line) =>
+        !/^\s*co-authored-by:/i.test(line) &&
+        !/^\s*(🤖\s*)?generated with/i.test(line) &&
+        !/^\s*signed-off-by:\s*claude/i.test(line),
+    )
+    .join('\n')
+    .trim()
+}
+
+/**
+ * Release notes carry two artefacts a commit message does not: stray code fences around
+ * part of the output, and a trailing paragraph explaining the model's reasoning. Keep the
+ * document only up to its last heading or list item; prose after that is commentary.
+ */
+function cleanNotes(text) {
+  const lines = cleanDraft(text)
+    .split('\n')
+    .filter((line) => !/^\s*```/.test(line))
+  let end = lines.length
+  while (end > 0) {
+    const line = lines[end - 1]
+    if (!line.trim()) {
+      end -= 1
+      continue
+    }
+    // A heading, a bullet, or an indented continuation of a bullet: the document proper.
+    if (/^\s*[-*+] /.test(line) || /^#{1,6} /.test(line) || /^\s+\S/.test(line)) break
+    end -= 1
+  }
+  return lines.slice(0, end).join('\n').trim() || null
+}
+
+/**
+ * Run the selected assistant against a prompt.
+ *
+ * Every failure mode — not installed, not authenticated, timed out, empty answer — returns
+ * null rather than throwing. Drafting is a convenience; a release must never be blocked
+ * because a text generator was unavailable.
+ *
+ * @returns {string | null} the cleaned draft, or null when unavailable
+ */
+function runAssistant(prompt) {
+  if (!assistant) return null
+
+  const args = [...assistant.args]
+  if (assistantModel && assistant.model) args.push(...assistant.model(assistantModel))
+  if (assistantEffort && assistant.effort) args.push(...assistant.effort(assistantEffort))
+
+  // Tools whose stdout carries session scaffolding hand back the answer through a file.
+  const answerFile = assistant.outputFile
+    ? join(mkdtempSync(join(tmpdir(), 'release-kit-')), 'answer.md')
+    : null
+  if (answerFile) args.push(...assistant.outputFile(answerFile))
+
+  try {
+    const stdout = execFileSync(assistant.command, args, {
+      input: prompt,
+      encoding: 'utf8',
+      timeout: DRAFT_TIMEOUT_MS,
+      stdio: ['pipe', 'pipe', 'ignore'],
+      maxBuffer: 10 * 1024 * 1024,
+    })
+    const answer = answerFile
+      ? existsSync(answerFile)
+        ? readFileSync(answerFile, 'utf8')
+        : ''
+      : stdout
+    return cleanDraft(answer) || null
+  } catch {
+    return null
+  }
+}
+
+/** Commit subjects since the last tag, with release and merge commits filtered out. */
+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),
+      ),
+  }
+}
+
+const CONVENTIONAL_TYPES = 'build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test'
+const CONVENTIONAL_RE = new RegExp(`^(${CONVENTIONAL_TYPES})(\\([^)]+\\))?!?: .+`)
+
+/**
+ * Draft a Conventional Commits message for the staged changes.
+ *
+ * @returns {string | null} a message whose subject is valid Conventional Commits, or null
+ */
+function draftCommitMessage() {
+  const stat = tryRead('git', ['diff', '--cached', '--stat'])
+  // Cap the diff: a large one wastes the context window and rarely improves the subject.
+  const diff = tryRead('git', ['diff', '--cached', '--unified=1'])?.slice(0, 12_000)
+  if (!stat) return null
+
+  const prompt = [
+    'Write a Conventional Commits message for these staged changes.',
+    '',
+    'Rules:',
+    `- Subject: "<type>(<optional scope>): <description>" where type is one of ${CONVENTIONAL_TYPES.split('|').join(', ')}.`,
+    '- Subject in the imperative mood, no trailing period, under 72 characters.',
+    '- Add a body only if the change needs explanation; separate it with a blank line.',
+    '- Output the raw commit message and nothing else: no markdown fences, no preamble.',
+    '- Do NOT add Co-Authored-By, Signed-off-by, or any attribution or tool credit.',
+    '',
+    'Files changed:',
+    stat,
+    '',
+    'Diff:',
+    diff ?? '(unavailable)',
+  ].join('\n')
+
+  const message = runAssistant(prompt)
+  if (!message) return null
+  const [subject] = message.split('\n')
+  return CONVENTIONAL_RE.test(subject) ? message : null
+}
+
+/**
+ * Draft release notes from the commits since the last tag, in the changelog's own style.
+ *
+ * @returns {string | null} markdown body (no version heading), or null
+ */
+function draftReleaseNotes(version, subjects, lastTag) {
+  if (!subjects.length) return null
+
+  const prompt = [
+    `Write release notes for version ${version}.`,
+    '',
+    'Rules:',
+    '- Group the changes under Keep a Changelog headings (`### Added`, `### Changed`,',
+    '  `### Fixed`, `### Removed`), including only the headings that apply.',
+    '- One bullet per user-visible change. Merge related commits into a single bullet.',
+    '- Omit internal chores: CI, linting, formatting, dependency bumps, version bumps.',
+    '- Write for someone upgrading: say what changed for them, not which files moved.',
+    '- Plain, factual language. No hype, no emoji, no concluding summary.',
+    '- Output only the markdown body: no version heading, no code fences, no attribution.',
+    '- Do NOT explain your reasoning or add any commentary before or after the notes.',
+    '',
+    `Commit subjects since ${lastTag ?? 'the start of the project'}:`,
+    ...subjects.map((s) => `- ${s}`),
+  ].join('\n')
+
+  const drafted = runAssistant(prompt)
+  return drafted ? cleanNotes(drafted) : null
+}
+
 /** One-line rendering of an argv, so a multi-line arg (release notes) stays readable. */
 const formatCommand = (command, args) =>
   [
@@ -392,6 +631,17 @@ function rollUnreleased(text, version, date) {
   return text.slice(0, match.index) + released + text.slice(match.index + match[0].length)
 }
 
+/**
+ * Insert a section for a version above the newest existing one, so drafted notes are kept
+ * in the changelog rather than only reaching the tag and the GitHub release.
+ */
+function insertChangelogSection(text, version, date, body) {
+  const entry = `## [${version}] - ${date}\n\n${body}\n`
+  const firstSection = /^## /m.exec(text)
+  if (!firstSection) return `${text.trimEnd()}\n\n${entry}`
+  return `${text.slice(0, firstSection.index)}${entry}\n${text.slice(firstSection.index)}`
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // JSON FILES
 // ─────────────────────────────────────────────────────────────────────────────
@@ -399,18 +649,84 @@ function rollUnreleased(text, version, date) {
 const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'))
 
 /**
- * Write a top-level "version" into a JSON file without reformatting the rest of it: the
- * value is replaced in place, so key order, indentation and trailing newline all survive.
+ * Where a project keeps its version. The format is inferred from the file name, so the
+ * common cases need nothing but a path:
+ *
+ *   *.json          the JSON `"version": "x.y.z"` field
+ *   *.toml          the first `version = "x.y.z"` line — the `[package]` / `[project]`
+ *                   table comes first in Cargo.toml and pyproject.toml
+ *   anything else   the whole file is the version (a plain VERSION file)
+ *
+ * An explicit `pattern` overrides inference for formats not listed. Whatever the source,
+ * it must capture the version in exactly one group, which is what gets replaced on write.
+ */
+const VERSION_PATTERNS = {
+  json: /^\s*"version"\s*:\s*"([^"]*)"/m,
+  toml: /^version\s*=\s*"([^"]*)"/m,
+}
+
+/** The project name in the same files, used for display and the registry lookup. */
+const NAME_PATTERNS = {
+  json: /^\s*"name"\s*:\s*"([^"]*)"/m,
+  toml: /^name\s*=\s*"([^"]*)"/m,
+}
+
+/** @returns {string | null} the project name recorded beside the version */
+function readNameFrom(entry) {
+  const source = versionSource(entry)
+  const kind = source.path.endsWith('.json')
+    ? 'json'
+    : source.path.endsWith('.toml')
+      ? 'toml'
+      : null
+  if (!kind || !existsSync(source.path)) return null
+  return NAME_PATTERNS[kind].exec(readFileSync(source.path, 'utf8'))?.[1] ?? null
+}
+
+/** Normalise a versionFile / versionFiles entry to { path, pattern }. */
+const versionSource = (entry) => (typeof entry === 'string' ? { path: entry } : entry)
+
+/** The regex for a source, or null when the whole file is the version. */
+function patternFor({ path, pattern }) {
+  if (pattern) return new RegExp(pattern, 'm')
+  if (path.endsWith('.json')) return VERSION_PATTERNS.json
+  if (path.endsWith('.toml')) return VERSION_PATTERNS.toml
+  return null
+}
+
+/** @returns {string | null} the version recorded in a source file */
+function readVersionFrom(entry) {
+  const source = versionSource(entry)
+  const text = readFileSync(source.path, 'utf8')
+  const pattern = patternFor(source)
+  if (!pattern) return text.trim() || null
+  const match = pattern.exec(text)
+  return match ? match[1] : null
+}
+
+/**
+ * Replace the version in a source file, touching nothing else: only the captured range is
+ * rewritten, so formatting, key order and comments all survive.
  *
  * @returns {boolean} whether the file needed changing
  */
-function writeVersionInto(path, version) {
-  const text = readFileSync(path, 'utf8')
-  const field = /^(\s*"version"\s*:\s*)"[^"]*"/m
-  if (!field.test(text)) throw new Error(`${path} has no top-level "version" field`)
-  const updated = text.replace(field, `$1"${version}"`)
+function writeVersionInto(entry, version) {
+  const source = versionSource(entry)
+  const text = readFileSync(source.path, 'utf8')
+  const pattern = patternFor(source)
+
+  let updated
+  if (pattern) {
+    const match = pattern.exec(text)
+    if (!match) throw new Error(`${source.path} has no version matching ${pattern}`)
+    const start = match.index + match[0].indexOf(match[1])
+    updated = text.slice(0, start) + version + text.slice(start + match[1].length)
+  } else {
+    updated = `${version}\n`
+  }
+
   if (updated === text) return false
-  if (!dryRun) writeFileSync(path, updated)
+  if (!dryRun) writeFileSync(source.path, updated)
   return true
 }
 
@@ -429,10 +745,14 @@ const option = (name) => {
 
 const dryRun = flag('--dry-run')
 const assumeYes = flag('--yes') || flag('-y')
-const skipPublish = flag('--skip-publish')
-const skipRelease = flag('--skip-release')
-const explicitDistTag = option('--tag')
+const onlySteps = option('--only')
+const skippedSteps = option('--skip')
+const explicitDistTag = option('--dist-tag')
 const requestedPreid = option('--preid')
+const autoCommit = flag('--commit')
+const requestedAssistant = option('--assistant')
+const requestedModel = option('--assistant-model')
+const requestedEffort = option('--assistant-effort')
 
 if (flag('--help') || flag('-h')) {
   console.log(USAGE)
@@ -472,7 +792,31 @@ if (flag('--sync')) {
   process.exit(0)
 }
 
-const target = argv.find((a) => !a.startsWith('-') && a !== explicitDistTag && a !== requestedPreid)
+/**
+ * Options that consume the argument after them. Without this list a positional target is
+ * found by guessing, and `--only tag,push` gets read as the version to release.
+ */
+const VALUE_OPTIONS = new Set([
+  '--only',
+  '--skip',
+  '--preid',
+  '--dist-tag',
+  '--assistant',
+  '--assistant-model',
+  '--assistant-effort',
+])
+
+/** The version or bump target: the first argument that is neither a flag nor a flag's value. */
+const target = (() => {
+  for (let i = 0; i < argv.length; i += 1) {
+    if (VALUE_OPTIONS.has(argv[i])) {
+      i += 1
+      continue
+    }
+    if (!argv[i].startsWith('-')) return argv[i]
+  }
+  return undefined
+})()
 
 // ─────────────────────────────────────────────────────────────────────────────
 // SETUP
@@ -497,11 +841,6 @@ if (existsSync(localManifest) && localManifest !== rootManifest) {
 }
 process.chdir(root)
 
-if (!existsSync('package.json')) abort(`no package.json at ${root}`)
-const pkg = readJson('package.json')
-if (!pkg.version) abort('package.json has no "version" field')
-if (!parseVersion(pkg.version)) abort(`package.json version "${pkg.version}" is not semver`)
-
 const config = {
   ...DEFAULTS,
   ...(existsSync('release.config.json') ? readJson('release.config.json') : {}),
@@ -509,25 +848,125 @@ const config = {
 const unknownKeys = Object.keys(config).filter((key) => !(key in DEFAULTS))
 if (unknownKeys.length) abort(`release.config.json has unknown keys: ${unknownKeys.join(', ')}`)
 
+/**
+ * Which steps run: config provides the baseline, --only replaces it, --skip subtracts, and
+ * --commit adds the opt-in step. Unknown names are an error rather than a silent no-op.
+ */
+const parseStepList = (value) =>
+  value
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean)
+
+/**
+ * The project's current version and name. Both normally come from package.json, but the
+ * only Node-specific thing about a release is publishing: `versionFile` points at whatever
+ * file this project keeps its version in, and `null` means the repository versions by git
+ * tag alone and the version has to be passed explicitly.
+ */
+const manifest = existsSync('package.json') ? readJson('package.json') : null
+const versionFile = config.versionFile ? versionSource(config.versionFile) : null
+
+if (versionFile && !existsSync(versionFile.path)) {
+  abort(`versionFile ${versionFile.path} does not exist`)
+}
+
+const currentVersion = versionFile ? readVersionFrom(versionFile) : null
+if (versionFile && !currentVersion) {
+  abort(`could not read a version from ${versionFile.path}`)
+}
+if (currentVersion && !parseVersion(currentVersion)) {
+  abort(`${versionFile.path} version "${currentVersion}" is not semver`)
+}
+
+/** Used for display, the registry lookup, and the %n token. */
+const goModule = existsSync('go.mod')
+  ? (/^module\s+(\S+)/m.exec(readFileSync('go.mod', 'utf8'))?.[1] ?? null)
+  : null
+const projectName =
+  manifest?.name ?? (versionFile ? readNameFrom(versionFile) : null) ?? goModule ?? basename(root)
+
+// Validate every name that was asked for, not just the ones that survive: a typo in
+// --skip would otherwise delete nothing and silently run the step you meant to drop.
+const requestedStepNames = [
+  ...(onlySteps ? parseStepList(onlySteps) : []),
+  ...(skippedSteps ? parseStepList(skippedSteps) : []),
+  ...(Array.isArray(config.steps) ? config.steps : []),
+]
+const unknownSteps = [...new Set(requestedStepNames)].filter((name) => !STEPS.includes(name))
+if (unknownSteps.length) {
+  abort(`unknown step(s): ${unknownSteps.join(', ')}\n  Known steps: ${STEPS.join(', ')}`)
+}
+
+const steps = new Set(onlySteps ? parseStepList(onlySteps) : (config.steps ?? DEFAULT_STEPS))
+if (skippedSteps) for (const name of parseStepList(skippedSteps)) steps.delete(name)
+if (autoCommit) steps.add('commit')
+const runs = (name) => steps.has(name)
+
+/**
+ * The drafting tool, resolved from --assistant then config. "auto" picks the first one
+ * present on PATH; a named tool must be known and installed, otherwise it is an error
+ * rather than a silent downgrade to no drafting.
+ */
+const assistantConfig =
+  config.assistant && typeof config.assistant === 'object' ? config.assistant : {}
+const assistantChoice =
+  requestedAssistant ??
+  (typeof config.assistant === 'string' ? config.assistant : assistantConfig.tool) ??
+  'none'
+const assistantModel = requestedModel ?? assistantConfig.model ?? null
+const assistantEffort = requestedEffort ?? assistantConfig.effort ?? null
+let assistantName = null
+if (assistantChoice !== 'none' && assistantChoice !== null) {
+  const candidates =
+    assistantChoice === 'auto'
+      ? Object.keys(ASSISTANTS)
+      : [assistantChoice].filter((name) => {
+          if (name in ASSISTANTS) return true
+          abort(
+            `unknown assistant "${name}" (known: ${Object.keys(ASSISTANTS).join(', ')}, auto, none)`,
+          )
+          return false
+        })
+  assistantName =
+    candidates.find((name) => succeeds(ASSISTANTS[name].command, ASSISTANTS[name].probe)) ?? null
+  if (!assistantName && assistantChoice !== 'auto') {
+    abort(
+      `assistant "${assistantChoice}" is configured but \`${ASSISTANTS[assistantChoice].command}\` is not on PATH`,
+    )
+  }
+}
+const assistant = assistantName ? ASSISTANTS[assistantName] : null
+
 // ─────────────────────────────────────────────────────────────────────────────
 // RESOLVE THE TARGET VERSION
 // ─────────────────────────────────────────────────────────────────────────────
 
 console.log(
-  bold(`${pkg.name} release`) + (dryRun ? `  ${yellow('(dry run — nothing will execute)')}` : ''),
+  bold(`${projectName} release`) +
+    (dryRun ? `  ${yellow('(dry run — nothing will execute)')}` : ''),
 )
 
 let version
 if (!target) {
-  ;({ version } = pkg)
+  if (!currentVersion) {
+    abort(
+      'this repository has no versionFile, so there is no version to default to.\n' +
+        '  Pass one explicitly: release-kit 1.2.3',
+    )
+  }
+  version = currentVersion
 } else if (BUMPS.has(target)) {
-  const preid = requestedPreid ?? preidOf(pkg.version)
+  if (!currentVersion) {
+    abort(`a ${target} bump needs a versionFile to bump from. Pass a version explicitly instead.`)
+  }
+  const preid = requestedPreid ?? preidOf(currentVersion)
   if (target.startsWith('pre') && !preid) {
     abort(
       `a ${target} bump from a stable version needs --preid <${[...KNOWN_CHANNELS].sort().join('|')}>`,
     )
   }
-  version = incrementVersion(pkg.version, target, preid)
+  version = incrementVersion(currentVersion, target, preid)
 } else if (parseVersion(target)) {
   version = target
 } else {
@@ -536,7 +975,7 @@ if (!target) {
 
 const tag = `${config.tagPrefix}${version}`
 const isPrerelease = parseVersion(version).pre.length > 0
-const bumping = version !== pkg.version
+const bumping = !!versionFile && version !== currentVersion && runs('version')
 
 let distTag
 try {
@@ -549,7 +988,7 @@ const expandWith = (template, transform) =>
   template
     .replaceAll('%v', transform(version))
     .replaceAll('%t', transform(tag))
-    .replaceAll('%n', transform(pkg.name))
+    .replaceAll('%n', transform(projectName))
     .replaceAll('%d', transform(distTag))
 
 /** Expand tokens for a message or title, which never reaches a shell. */
@@ -563,17 +1002,32 @@ const expand = (template) => expandWith(template, (value) => value)
 const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`
 const expandShell = (template) => expandWith(template, shellQuote)
 
-const publishCommand = config.publish && !skipPublish ? expandShell(config.publish) : null
+const publishCommand = runs('publish') && config.publish ? expandShell(config.publish) : null
 
 /**
- * npm and pnpm answer `whoami` and `view` identically and share `~/.npmrc`, so whichever
- * one publishes can also run the registry preflight. Checking with the wrong one mislabels
- * the result. A publish command driving anything else (vsce, a shell pipeline) is left
- * alone — it cannot be introspected, and guessing would invent failures.
+ * Registries whose preflight can be run, keyed by the first word of the publish command.
+ * Each declares how that CLI answers "who am I" and "does this version already exist";
+ * either may be null when the tool has no such notion. A publish command outside this
+ * table (vsce, a shell pipeline) is run as written with no preflight — it cannot be
+ * introspected, and guessing would invent failures.
  */
-const REGISTRY_CLIS = new Set(['npm', 'pnpm'])
+const REGISTRIES = {
+  npm: { whoami: ['whoami'], published: (name, v) => ['view', `${name}@${v}`, 'version'] },
+  pnpm: { whoami: ['whoami'], published: (name, v) => ['view', `${name}@${v}`, 'version'] },
+  bun: {
+    whoami: ['pm', 'whoami'],
+    published: (name, v) => ['pm', 'view', `${name}@${v}`, 'version'],
+  },
+  // uv authenticates with a token from the environment rather than a logged-in session,
+  // and skips duplicate uploads itself via --check-url, so there is no version lookup.
+  uv: { env: ['UV_PUBLISH_TOKEN', 'UV_PUBLISH_PASSWORD'], login: 'set UV_PUBLISH_TOKEN' },
+  // For Go the tag is the release; `go list` warms the module proxy and doubles as the
+  // check for whether this version is already resolvable.
+  go: { published: (name, v) => ['list', '-m', `${name}@${v}`] },
+}
+
 const publishCli = publishCommand?.trim().split(/\s+/)[0]
-const registryCli = REGISTRY_CLIS.has(publishCli) ? publishCli : null
+const registry = publishCli ? REGISTRIES[publishCli] : null
 
 /**
  * CI publishing over OIDC ("trusted publishing") carries no token at all: `whoami` fails
@@ -587,7 +1041,10 @@ const isTrustedPublishing =
     !!process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN) ||
   !!process.env.NPM_ID_TOKEN
 
-console.log(`  ${dim(`${pkg.version} → ${version}   tag ${tag}   dist-tag ${distTag}`)}`)
+console.log(
+  `  ${dim(`${currentVersion ?? '(no version file)'} → ${version}   tag ${tag}   dist-tag ${distTag}`)}`,
+)
+console.log(`  ${dim(`steps: ${STEPS.filter(runs).join(' → ')}`)}`)
 
 // ─────────────────────────────────────────────────────────────────────────────
 // PREFLIGHT — every check runs, then it aborts once with all of the failures
@@ -601,18 +1058,43 @@ const fail = (message) => {
   problems.push(message)
 }
 
-if (bumping && compareVersions(version, pkg.version) <= 0) {
-  fail(`${version} is not greater than the current version ${pkg.version}`)
+if (bumping && compareVersions(version, currentVersion) <= 0) {
+  fail(`${version} is not greater than the current version ${currentVersion}`)
 } else if (bumping) {
-  ok(`version ${pkg.version} → ${version}`)
+  ok(`version ${currentVersion} → ${version}`)
+} else if (versionFile) {
+  ok(`releasing the version already in ${versionFile.path} (${version})`)
 } else {
-  ok(`releasing the version already in package.json (${version})`)
+  ok(`releasing ${version} (no version file; the tag is the version)`)
 }
 
 const dirty = tryRead('git', ['status', '--porcelain'])
 if (dirty === null) fail('could not read git status')
-else if (dirty) fail(`working tree is not clean:\n${indent(formatStatus(dirty))}`)
-else ok('working tree clean')
+else if (dirty && runs('commit')) {
+  ok(`working tree has ${dirty.split('\n').length} change(s) — will be committed first`)
+  console.log(dim(indent(formatStatus(dirty))))
+} else if (dirty) {
+  fail(`working tree is not clean:\n${indent(formatStatus(dirty))}`)
+} else ok('working tree clean')
+
+if (runs('commit') && !assistant) {
+  fail(
+    'the commit step needs a drafting assistant to write the message. Configure one with ' +
+      '`--assistant auto`, or set "assistant" in release.config.json.',
+  )
+} else if (assistant) {
+  const detail = [
+    assistantModel && `model ${assistantModel}`,
+    assistantEffort && `effort ${assistantEffort}`,
+  ]
+    .filter(Boolean)
+    .join(', ')
+  ok(`assistant: ${assistantName}${detail ? ` (${detail})` : ''}`)
+  if (assistantModel && !assistant.model)
+    warn(`${assistantName} takes no model flag — --model ignored`)
+  if (assistantEffort && !assistant.effort)
+    warn(`${assistantName} takes no effort flag — --effort ignored`)
+}
 
 const branch = tryRead('git', ['rev-parse', '--abbrev-ref', 'HEAD'])
 if (!branch) fail('could not read the current branch')
@@ -642,7 +1124,9 @@ if (!succeeds('git', ['remote', 'get-url', config.remote])) {
 
 const head = tryRead('git', ['rev-parse', 'HEAD'])
 const taggedCommit = tryRead('git', ['rev-list', '-n', '1', tag])
-if (taggedCommit && bumping) {
+if (!runs('tag')) {
+  note('tag step not selected')
+} else if (taggedCommit && bumping) {
   fail(`tag ${tag} already exists — release a different version`)
 } else if (taggedCommit && taggedCommit !== head) {
   fail(`tag ${tag} already exists at ${taggedCommit.slice(0, 8)}, not at HEAD`)
@@ -653,8 +1137,8 @@ if (taggedCommit && bumping) {
 }
 
 let releaseExists = false
-if (skipRelease) {
-  note('GitHub release skipped (--skip-release)')
+if (!runs('release')) {
+  note('release step not selected')
 } else if (!succeeds('gh', ['--version'])) {
   fail('the GitHub CLI (`gh`) is not installed — https://cli.github.com')
 } else if (!succeeds('gh', ['auth', 'status'])) {
@@ -667,34 +1151,58 @@ if (skipRelease) {
 
 let alreadyPublished = false
 if (!publishCommand) {
-  note(skipPublish ? 'publish skipped (--skip-publish)' : 'publish disabled in config')
-} else if (pkg.private) {
+  note(runs('publish') ? 'no publish command configured' : 'publish step not selected')
+} else if (manifest?.private) {
   fail('package.json is private but a publish command is configured')
-} else if (!registryCli) {
+} else if (!registry) {
   ok(`publish: ${publishCommand}`)
 } else {
   if (isTrustedPublishing) {
     ok('trusted publishing (OIDC) — no token needed')
-  } else {
-    const user = tryRead(registryCli, ['whoami'])
+  } else if (registry.env) {
+    // Token-in-the-environment auth: there is no session to interrogate, only credentials.
+    const found = registry.env.find((name) => process.env[name])
+    if (found) ok(`${publishCli} credentials found (${found})`)
+    else fail(`${publishCli} has no publish credentials — ${registry.login}`)
+  } else if (registry.whoami) {
+    const user = tryRead(publishCli, registry.whoami)
     if (user === null) {
       // npm replaced long-lived tokens with two-hour sessions in December 2025, so the
       // usual cause is an expired session rather than a missing login.
       fail(
-        `${registryCli} is not authenticated — run \`${registryCli} login\`. ` +
+        `${publishCli} is not authenticated — run \`${publishCli} login\`. ` +
           'npm logins are two-hour sessions, so an earlier one may have expired.',
       )
-    } else ok(`${registryCli} authenticated (${user || 'unknown user'})`)
+    } else ok(`${publishCli} authenticated (${user || 'unknown user'})`)
   }
-  alreadyPublished = succeeds(registryCli, ['view', `${pkg.name}@${version}`, 'version'])
-  if (alreadyPublished) {
-    note(`${pkg.name}@${version} is already on the registry — will skip publishing`)
+
+  if (registry.published) {
+    alreadyPublished = succeeds(publishCli, registry.published(projectName, version))
+    if (alreadyPublished) {
+      note(`${projectName}@${version} is already published — will skip the publish step`)
+    }
   }
 }
 
-// Notes: the changelog section for this version, else GitHub generates them from commits.
+// Notes: the changelog section for this version, else a draft, else GitHub generates them.
 let notes = null
 let rolledChangelog = null
+let draftedNotes = null
+
+/**
+ * True when --commit still has to create a commit. Notes drafted before that commit would
+ * describe an incomplete release, so drafting waits until the working tree is committed.
+ */
+const notesDeferred = !!(dirty && runs('commit') && assistant)
+
+/** Draft notes from the commit log, reporting what it is doing since it takes a moment. */
+function draftNotesFor(v) {
+  if (!assistant) return null
+  const { lastTag, subjects } = commitsSinceLastTag()
+  if (!subjects.length) return null
+  note(`drafting notes from ${subjects.length} commit(s) with ${assistantName}...`)
+  return draftReleaseNotes(v, subjects, lastTag)
+}
 if (config.changelog && existsSync(config.changelog)) {
   const text = readFileSync(config.changelog, 'utf8')
   notes = changelogSection(text, version)
@@ -706,13 +1214,26 @@ if (config.changelog && existsSync(config.changelog)) {
       notes = changelogSection(rolledChangelog, version)
       ok(`${config.changelog}: [Unreleased] will become [${version}]`)
     } else {
-      warn(
-        `${config.changelog} has no ${version} or [Unreleased] section — GitHub will generate the notes`,
-      )
+      draftedNotes = notesDeferred ? null : draftNotesFor(version)
+      if (notesDeferred) {
+        ok(`${config.changelog}: a ${version} section will be drafted after the commit`)
+      } else if (draftedNotes) {
+        notes = draftedNotes
+        ok(`${config.changelog}: a ${version} section will be drafted by ${assistantName}`)
+      } else {
+        warn(
+          `${config.changelog} has no ${version} or [Unreleased] section — GitHub will generate the notes`,
+        )
+      }
     }
   }
-} else if (config.changelog) {
-  note(`no ${config.changelog} — GitHub will generate the notes`)
+} else {
+  // No changelog file at all: there is nothing to roll, but notes can still be drafted for
+  // the tag annotation and the GitHub release.
+  notes = notesDeferred ? null : draftNotesFor(version)
+  if (notesDeferred) ok('release notes will be drafted after the commit')
+  else if (notes) ok(`release notes drafted by ${assistantName}`)
+  else if (config.changelog) note(`no ${config.changelog} — GitHub will generate the notes`)
 }
 
 for (const asset of config.assets) {
@@ -737,7 +1258,7 @@ if (!assumeYes && !dryRun && process.stdin.isTTY) {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   let answer = ''
   try {
-    answer = await rl.question(`\nRelease ${bold(tag)} of ${pkg.name}? [y/N] `)
+    answer = await rl.question(`\nRelease ${bold(tag)} of ${projectName}? [y/N] `)
   } catch {
     // Ctrl+C or Ctrl+D at the prompt rejects the question. That is a decline, not a
     // crash — without this it exits on an unhandled AbortError and a stack trace.
@@ -753,13 +1274,36 @@ if (!assumeYes && !dryRun && process.stdin.isTTY) {
 
 const staged = []
 
+if (dirty && runs('commit')) {
+  step('Commit the working tree')
+  mutate('git', ['add', '--all'])
+  // Draft after staging: the message describes what is staged, not what happens to be
+  // in the tree. Under --dry-run nothing was staged, so there is nothing to describe.
+  const message = dryRun ? null : draftCommitMessage()
+  if (!message && !dryRun) {
+    abort(
+      `${assistantName} could not draft a Conventional Commits message for the staged changes.\n\n` +
+        '  Commit them yourself and re-run, or run without --commit.',
+    )
+  }
+  console.log(indent(message ?? '<drafted at run time>'))
+  mutate('git', ['commit', '-m', message ?? 'chore: working tree'])
+
+  // Now that the commit exists it is part of the release, so the notes can describe it.
+  if (notesDeferred && !dryRun) {
+    draftedNotes = draftNotesFor(version)
+    if (draftedNotes) notes = draftedNotes
+  }
+}
+
 if (bumping) {
   step(`Write version ${version}`)
-  for (const file of ['package.json', ...config.versionFiles]) {
-    if (!existsSync(file)) abort(`versionFiles entry ${file} does not exist`)
-    if (writeVersionInto(file, version)) {
-      staged.push(file)
-      console.log(`  ${dryRun ? yellow('would write') : dim('wrote')} ${file}`)
+  for (const entry of [versionFile, ...config.versionFiles]) {
+    const source = versionSource(entry)
+    if (!existsSync(source.path)) abort(`versionFiles entry ${source.path} does not exist`)
+    if (writeVersionInto(source, version)) {
+      staged.push(source.path)
+      console.log(`  ${dryRun ? yellow('would write') : dim('wrote')} ${source.path}`)
     }
   }
   // A package-lock.json embeds the root version twice, so it goes stale on a bump.
@@ -769,11 +1313,26 @@ if (bumping) {
   }
 }
 
-if (rolledChangelog) {
+if (rolledChangelog && runs('changelog')) {
   step(`Roll ${config.changelog} to ${version}`)
   if (dryRun) console.log(`  ${yellow('would write')} ${config.changelog}`)
   else writeFileSync(config.changelog, rolledChangelog)
   staged.push(config.changelog)
+} else if (runs('changelog') && draftedNotes && config.changelog && existsSync(config.changelog)) {
+  step(`Add the drafted ${version} section to ${config.changelog}`)
+  if (dryRun) console.log(`  ${yellow('would write')} ${config.changelog}`)
+  else {
+    writeFileSync(
+      config.changelog,
+      insertChangelogSection(
+        readFileSync(config.changelog, 'utf8'),
+        version,
+        new Date().toISOString().slice(0, 10),
+        draftedNotes,
+      ),
+    )
+  }
+  staged.push(config.changelog)
 }
 
 if (staged.length) {
@@ -782,7 +1341,7 @@ if (staged.length) {
   mutate('git', ['commit', '-m', expand(config.commitMessage)])
 }
 
-if (!taggedCommit) {
+if (runs('tag') && !taggedCommit) {
   step(`Annotated tag ${tag}`)
   // The notes become the tag annotation too, so a CI release workflow can read them
   // straight off the tag instead of re-deriving them. --cleanup=verbatim is required:
@@ -794,21 +1353,23 @@ if (!taggedCommit) {
     tag,
     '--cleanup=verbatim',
     '-m',
-    `${notes ?? `${pkg.name} ${tag}`}\n`,
+    `${notes ?? `${projectName} ${tag}`}\n`,
   ])
 }
 
-step(`Push branch and tag to ${config.remote}`)
-// --follow-tags sends the commit and the tag in one call; pushing them separately is how
-// a tag ends up on the remote without its commit, or a release without its tag.
-mutate('git', ['push', '--follow-tags', config.remote, branch ?? 'HEAD'])
+if (runs('push')) {
+  step(`Push branch and tag to ${config.remote}`)
+  // --follow-tags sends the commit and the tag in one call; pushing them separately is how
+  // a tag ends up on the remote without its commit, or a release without its tag.
+  mutate('git', ['push', '--follow-tags', config.remote, branch ?? 'HEAD'])
+}
 
 if (publishCommand && !alreadyPublished) {
   step(`Publish to the registry (dist-tag ${distTag})`)
   mutateShell(publishCommand)
 }
 
-if (!skipRelease && !releaseExists) {
+if (runs('release') && !releaseExists) {
   step(`GitHub release ${tag}`)
   const args = [
     'release',