dotmd-cli 0.41.0 → 0.42.0

package/bin/dotmd.mjs

@@ -51,11 +51,11 @@ Lifecycle:
   pickup <file> [--takeover]        Pick up a plan (set in-session + print body)
   release [<file>] [--to <s>]       Release in-session lease (alias: unpickup)
   runlist <hub> [next]              Show or walk an ordered group of plans (see \`dotmd help runlist\`)
-  finish <file> [done|active]       Finish a plan (set done or active)
-  status <file> <status>            Transition document status
+  status <file> <status>            Transition document status (deprecated; prefer \`set\`)
   set <status> [<file>]             Unified transition: archive/release/transition in one verb
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
+  ship [patch|minor|major]          Regen + commit + bump in one step (default: patch)
   bulk-tag [files...]               Tag pre-existing untagged .md files
   touch <file>                      Bump updated date
   touch --git                       Bulk-sync dates from git history
@@ -139,10 +139,10 @@ plan statuses (each maps to a distinct unstuck-action)
 
 Canonical transitions:
   active → in-session              \`dotmd pickup <file>\`
-  in-session → active              \`dotmd release <file>\`
-  in-session → partial             \`dotmd status <file> partial\` (+ release)
-  in-session → awaiting            \`dotmd status <file> awaiting\` (+ release)
-  any → archived                   \`dotmd archive <file>\`
+  in-session → active              \`dotmd set active\` (auto-releases lease)
+  in-session → partial             \`dotmd set partial\` (auto-releases lease)
+  in-session → awaiting            \`dotmd set awaiting\` (auto-releases lease)
+  any → archived                   \`dotmd set archived <file>\` (or \`dotmd archive\`)
 
 ────────────────────────────────────────────────────────────────────
 doc statuses
@@ -296,16 +296,30 @@ status. With no file, releases every lease owned by the current session.
 Identical behavior to \`dotmd unpickup\`; both names route to the same
 implementation. See \`dotmd unpickup --help\` for full option list.`,
 
-  finish: `dotmd finish <file> [done|active] — finish working on a plan
-
-Sets the plan status to done (default) or back to active.
-Only works on plans currently in-session.
+  ship: `dotmd ship [patch|minor|major] — regen + commit + bump in one step
+
+Bundles the multi-step release dance into a single command:
+  1. Regenerate \`.claude/commands/*.md\` with the TARGET version stamp
+     (the post-bump version, so the slash-command files match the new
+     release and no dirty tree lingers after).
+  2. Auto-stage every dirty file matching the release allowlist
+     (src/, test/, bin/, docs/, .claude/commands/, package*.json,
+     dotmd.config*.mjs, README.md, CLAUDE.md, .gitignore). Anything
+     outside the allowlist is left dirty — secrets, sibling-session
+     WIP, etc. never get bundled in.
+  3. Commit with an auto-generated message including the held plan
+     title (if any).
+  4. Run \`npm version <bump>\` to bump package.json, tag, push, run
+     the publish workflow, and reinstall locally.
 
 Options:
-  --json                 Output as JSON
-  --dry-run, -n          Preview without writing
+  --dry-run, -n          Show what would happen without staging or bumping.
+
+Defaults to patch. Pass \`minor\` or \`major\` to bump those instead.
 
-If no file is given, prompts with a list of in-session plans.`,
+Network failures mid-bump (e.g. \`git push\` fails) leave the local
+commit + tag intact. Inspect with \`git log -1\` and rerun
+\`git push origin main --tags\` to recover.`,
 
   set: `dotmd set <status> [<file>] — unified status-transition verb
 
@@ -1160,9 +1174,9 @@ async function main() {
   if (command === 'unpickup' || command === 'release') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
   if (command === 'runlist') { const { runRunlist } = await import('../src/runlist.mjs'); await runRunlist(restArgs, config, { dryRun }); return; }
   if (command === 'handoff') { die('`dotmd handoff` was removed in 0.31.0. Use `dotmd prompts new <name>` to create a saved prompt instead. The .dotmd/handoffs/ sidecar mechanism no longer exists; see CHANGELOG.'); }
-  if (command === 'finish') { const { runFinish } = await import('../src/lifecycle.mjs'); await runFinish(restArgs, config, { dryRun }); return; }
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'set') { const { runSet } = await import('../src/lifecycle.mjs'); await runSet(restArgs, config, { dryRun }); return; }
+  if (command === 'ship') { const { runShip } = await import('../src/ship.mjs'); await runShip(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { const { runArchive } = await import('../src/lifecycle.mjs'); runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'archive') { const { runBulkArchive } = await import('../src/lifecycle.mjs'); runBulkArchive(restArgs.slice(1), config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'tag') { const { runBulkTag } = await import('../src/bulk-tag.mjs'); runBulkTag(restArgs.slice(1), config, { dryRun }); return; }

package/dotmd.config.example.mjs

@@ -268,7 +268,6 @@ export const presets = {
 // export function onRename({ oldPath, newPath, referencesUpdated }) {}
 // export function onLint({ path, fixes }) {}
 // export function onPickup({ path, oldStatus, newStatus }) {}
-// export function onFinish({ path, oldStatus, newStatus }) {}
 
 // AI hooks — override summarization (replaces local MLX model).
 // export function summarizeDoc(body, meta) { return 'Custom summary'; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/claude-commands.mjs

@@ -5,13 +5,13 @@ import { green, dim, yellow } from './color.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
-const VERSION_MARKER = `<!-- dotmd-generated: ${pkg.version} -->`;
 // Marker is no longer pinned to line 1 — it now lives below the YAML
 // frontmatter that Claude Code surfaces as the slash command's description.
 // The regex is intentionally non-anchored so getInstalledVersion finds it
 // wherever it sits, and the marker string is specific enough that a false
 // positive elsewhere in a user-edited file is not a realistic concern.
 const VERSION_REGEX = /<!-- dotmd-generated: ([\d.]+) -->/;
+function markerFor(version) { return `<!-- dotmd-generated: ${version} -->`; }
 
 // Trigger sentences surfaced by Claude Code's available-skills system reminder.
 // Front-load the "when to reach for it" cue so Claude can route to the right
@@ -55,11 +55,11 @@ function frontmatterFor(name, config) {
   return ['---', `description: ${description}`, '---'];
 }
 
-function generatePlansCommand(config) {
-  const lines = [...frontmatterFor('plans', config), VERSION_MARKER, ''];
+function generatePlansCommand(config, version) {
+  const lines = [...frontmatterFor('plans', config), markerFor(version), ''];
   lines.push('Run `dotmd context` to get the current plans briefing, then use it to orient yourself.');
   lines.push('');
-  lines.push(`Plans are managed by **dotmd** (v${pkg.version}). Config at \`dotmd.config.mjs\`. Always use \`dotmd\` directly.`);
+  lines.push(`Plans are managed by **dotmd** (v${version}). Config at \`dotmd.config.mjs\`. Always use \`dotmd\` directly.`);
   lines.push('');
   lines.push('Plan-specific commands:');
   lines.push('- `dotmd context` — briefing with active/paused/ready plans, age tags, next steps');
@@ -94,8 +94,8 @@ function generatePlansCommand(config) {
   return lines.join('\n');
 }
 
-function generateBatonCommand(config) {
-  const lines = [...frontmatterFor('baton', config), VERSION_MARKER, ''];
+function generateBatonCommand(config, version) {
+  const lines = [...frontmatterFor('baton', config), markerFor(version), ''];
   lines.push('Wrap this session. Minimum required (two commands):');
   lines.push('');
   lines.push('1. **Save the resume prompt.** `dotmd new prompt resume-<plan-slug>` with a 10-20 line body via heredoc: the next concrete decision plus any gotchas. NOT a recap of the plan body. The saved prompt IS the handoff — never print it into chat for copy-paste.');
@@ -114,12 +114,12 @@ function generateBatonCommand(config) {
   return lines.join('\n');
 }
 
-function generateDocsCommand(config) {
+function generateDocsCommand(config, version) {
   const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
   const rootCount = roots.length;
 
-  const lines = [...frontmatterFor('docs', config), VERSION_MARKER, ''];
-  lines.push(`All documentation in this repo is managed by **dotmd** (v${pkg.version}). Docs across ${rootCount} root${rootCount > 1 ? 's' : ''}: ${roots.join(', ')}. Config at \`dotmd.config.mjs\`.`);
+  const lines = [...frontmatterFor('docs', config), markerFor(version), ''];
+  lines.push(`All documentation in this repo is managed by **dotmd** (v${version}). Docs across ${rootCount} root${rootCount > 1 ? 's' : ''}: ${roots.join(', ')}. Config at \`dotmd.config.mjs\`.`);
   lines.push('');
 
   // Document types from config
@@ -177,7 +177,7 @@ function getInstalledVersion(filePath) {
 }
 
 export function scaffoldClaudeCommands(cwd, config, opts = {}) {
-  const { dryRun = false } = opts;
+  const { dryRun = false, version = pkg.version } = opts;
   const claudeDir = path.join(cwd, '.claude');
   if (!existsSync(claudeDir)) return [];
 
@@ -185,16 +185,16 @@ export function scaffoldClaudeCommands(cwd, config, opts = {}) {
   const results = [];
 
   const files = [
-    { name: 'plans.md', generate: () => generatePlansCommand(config) },
-    { name: 'docs.md', generate: () => generateDocsCommand(config) },
-    { name: 'baton.md', generate: () => generateBatonCommand(config) },
+    { name: 'plans.md', generate: () => generatePlansCommand(config, version) },
+    { name: 'docs.md', generate: () => generateDocsCommand(config, version) },
+    { name: 'baton.md', generate: () => generateBatonCommand(config, version) },
   ];
 
   for (const { name, generate } of files) {
     const filePath = path.join(commandsDir, name);
     const installedVersion = getInstalledVersion(filePath);
 
-    if (installedVersion === pkg.version) {
+    if (installedVersion === version) {
       results.push({ name, action: 'current' });
     } else if (installedVersion) {
       // Outdated — regenerate
@@ -202,7 +202,7 @@ export function scaffoldClaudeCommands(cwd, config, opts = {}) {
         mkdirSync(commandsDir, { recursive: true });
         writeFileSync(filePath, generate(), 'utf8');
       }
-      results.push({ name, action: 'updated', from: installedVersion, to: pkg.version });
+      results.push({ name, action: 'updated', from: installedVersion, to: version });
     } else if (!existsSync(filePath)) {
       // New — create
       if (!dryRun) {
@@ -231,7 +231,8 @@ export function refreshStaleSlashCommands(config) {
   return results.filter(r => r.action === 'updated');
 }
 
-export function checkClaudeCommands(cwd) {
+export function checkClaudeCommands(cwd, opts = {}) {
+  const { version = pkg.version } = opts;
   const commandsDir = path.join(cwd, '.claude', 'commands');
   if (!existsSync(commandsDir)) return [];
 
@@ -239,11 +240,11 @@ export function checkClaudeCommands(cwd) {
   for (const name of ['plans.md', 'docs.md', 'baton.md']) {
     const filePath = path.join(commandsDir, name);
     const installedVersion = getInstalledVersion(filePath);
-    if (installedVersion && installedVersion !== pkg.version) {
+    if (installedVersion && installedVersion !== version) {
       warnings.push({
         path: `.claude/commands/${name}`,
         level: 'warning',
-        message: `Claude command outdated (v${installedVersion} → v${pkg.version}). Run \`dotmd doctor\` to update.`,
+        message: `Claude command outdated (v${installedVersion} → v${version}). Run \`dotmd doctor\` to update.`,
       });
     }
   }

package/src/commands.mjs

@@ -4,8 +4,9 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'set', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'status', 'set', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
+  'ship',
 ];

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
 

package/src/lifecycle.mjs

@@ -112,6 +112,10 @@ export async function runStatus(argv, config, opts = {}) {
   const input = argv[0];
   let newStatus = argv[1];
 
+  if (!opts.suppressDeprecation) {
+    process.stderr.write(dim('`dotmd status <file> <status>` is deprecated; prefer `dotmd set <status> [<file>]` (note: <status> first, <file> optional when a lease is held). Removed in a future major.\n'));
+  }
+
   if (!input) { die('Usage: dotmd status <file> <new-status>'); }
 
   const filePath = resolveDocPath(input, config);
@@ -519,66 +523,6 @@ export async function runUnpickup(argv, config, opts = {}) {
   }
 }
 
-export async function runFinish(argv, config, opts = {}) {
-  const { dryRun } = opts;
-  const json = argv.includes('--json');
-  const positional = argv.filter(a => !a.startsWith('-'));
-  let input = positional[0];
-  const targetStatus = positional[1] ?? 'done';
-
-  if (!['done', 'active'].includes(targetStatus)) die(`Invalid finish status: ${targetStatus}. Use 'done' or 'active'.`);
-
-  // Interactive: pick from in-session plans
-  if (!input) {
-    if (!isInteractive()) die('Usage: dotmd finish <file> [done|active]');
-    const index = buildIndex(config);
-    const inSession = index.docs.filter(d => d.status === 'in-session');
-    if (inSession.length === 0) die('No plans currently in-session.');
-    if (inSession.length === 1) {
-      input = inSession[0].path;
-      process.stderr.write(`${dim(`Auto-selected: ${input}`)}\n`);
-    } else {
-      const choice = await promptChoice('Finish which plan:', inSession.map(d => `${d.title} — ${d.path}`));
-      if (!choice) die('No plan selected.');
-      const idx = inSession.findIndex((_, i) => choice === `${inSession[i].title} — ${inSession[i].path}`);
-      if (idx === -1) die('No plan selected.');
-      input = inSession[idx].path;
-    }
-  }
-
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) die(`File not found: ${input}`);
-
-  const raw = readFileSync(filePath, 'utf8');
-  const { frontmatter: fmRaw } = extractFrontmatter(raw);
-  const parsedFm = parseSimpleFrontmatter(fmRaw);
-  const oldStatus = asString(parsedFm.status);
-  const repoPath = toRepoPath(filePath, config.repoRoot);
-
-  if (oldStatus !== 'in-session') die(`Plan is not in-session (current: ${oldStatus}).\n  ${repoPath}`);
-
-  const today = nowIso();
-
-  if (dryRun) {
-    process.stderr.write(`${dim('[dry-run]')} Would update: status: in-session → ${targetStatus}, updated: ${today}\n`);
-  } else {
-    updateFrontmatter(filePath, { status: targetStatus, updated: today });
-    regenIndex(config);
-  }
-
-  if (json) {
-    process.stdout.write(JSON.stringify({ path: repoPath, oldStatus, newStatus: targetStatus }, null, 2) + '\n');
-  } else {
-    process.stdout.write(`${green('✓ Finished')}: ${repoPath} (in-session → ${targetStatus})\n`);
-  }
-
-  if (!dryRun) {
-    try { releaseLease(config, repoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${repoPath}: ${err.message}`); }
-  }
-
-  try { config.hooks.onFinish?.({ path: repoPath, oldStatus, newStatus: targetStatus }); } catch (err) { warn(`Hook 'onFinish' threw: ${err.message}`); }
-}
-
 export function runArchive(argv, config, opts = {}) {
   const { dryRun, out = process.stdout } = opts;
   const noIndex = argv.includes('--no-index') || opts.noIndex;
@@ -747,7 +691,7 @@ export async function runSet(argv, config, opts = {}) {
   const statusArgs = [filePath, newStatus];
   if (noIndex) statusArgs.push('--no-index');
   if (showFiles) statusArgs.push('--show-files');
-  await runStatus(statusArgs, config, { dryRun });
+  await runStatus(statusArgs, config, { dryRun, suppressDeprecation: true });
 
   if (oldStatus === 'in-session' && newStatus !== 'in-session' && !dryRun) {
     const repoPath = toRepoPath(filePath, config.repoRoot);

package/src/ship.mjs

@@ -0,0 +1,149 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { die, warn, toRepoPath } from './util.mjs';
+import { green, dim, yellow } from './color.mjs';
+import { scaffoldClaudeCommands } from './claude-commands.mjs';
+import { readLeases, currentSessionId } from './lease.mjs';
+
+// Files dotmd ship will auto-stage when they're dirty. Anything outside this
+// allowlist stays in the working tree — user has to `git add` it explicitly,
+// so secrets / .env / sibling-session WIP never get bundled into a release.
+const ALLOWLIST_PATTERNS = [
+  /^src\//,
+  /^test\//,
+  /^bin\//,
+  /^docs\//,
+  /^\.claude\/commands\//,
+  /^dotmd\.config\.example\.mjs$/,
+  /^dotmd\.config\.mjs$/,
+  /^package(?:-lock)?\.json$/,
+  /^README\.md$/,
+  /^CLAUDE\.md$/,
+  /^\.gitignore$/,
+];
+
+export function bumpVersion(current, bump) {
+  const parts = current.split('.').map(Number);
+  if (parts.length !== 3 || parts.some(Number.isNaN)) {
+    die(`Cannot parse current version: ${current}`);
+  }
+  const [maj, min, pat] = parts;
+  if (bump === 'major') return `${maj + 1}.0.0`;
+  if (bump === 'minor') return `${maj}.${min + 1}.0`;
+  if (bump === 'patch') return `${maj}.${min}.${pat + 1}`;
+  die(`Invalid bump: ${bump}. Use patch | minor | major.`);
+}
+
+export function isAllowed(repoPath) {
+  return ALLOWLIST_PATTERNS.some(re => re.test(repoPath));
+}
+
+function listDirtyFiles(repoRoot) {
+  // -u expands untracked directories into individual file entries; without it,
+  // a fresh `docs/` shows up as a single `?? docs/` line and the allowlist
+  // check sees no per-file paths to whitelist.
+  const result = spawnSync('git', ['status', '--porcelain', '-u'], { cwd: repoRoot, encoding: 'utf8' });
+  if (result.status !== 0) die(`git status failed: ${result.stderr}`);
+  return result.stdout
+    .split('\n')
+    .filter(Boolean)
+    .map(line => ({
+      status: line.slice(0, 2),
+      path: line.slice(3),
+    }));
+}
+
+function findHeldPlanTitle(config) {
+  const leases = readLeases(config);
+  const sid = currentSessionId();
+  const owned = Object.entries(leases).filter(([_, l]) => l.session === sid);
+  if (owned.length !== 1) return null;
+  return path.basename(owned[0][0], '.md');
+}
+
+export async function runShip(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const positional = argv.filter(a => !a.startsWith('-'));
+  const bump = positional[0] ?? 'patch';
+  if (!['patch', 'minor', 'major'].includes(bump)) {
+    die(`Invalid bump: ${bump}. Usage: dotmd ship [patch|minor|major]`);
+  }
+
+  const pkgPath = path.join(config.repoRoot, 'package.json');
+  if (!existsSync(pkgPath)) die(`No package.json at ${toRepoPath(pkgPath, config.repoRoot)}`);
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  const current = pkg.version;
+  const target = bumpVersion(current, bump);
+
+  process.stdout.write(`${green('→')} Shipping ${current} → ${target} (${bump})\n`);
+
+  // 1. Regen slash commands at the *target* version so the resulting commit
+  //    matches the post-bump state and no dirty tree lingers after release.
+  const regenResults = scaffoldClaudeCommands(config.repoRoot, config, { version: target, dryRun });
+  const refreshed = regenResults.filter(r => r.action === 'updated' || r.action === 'created');
+  if (refreshed.length > 0) {
+    const verb = dryRun ? 'Would regenerate' : 'Regenerated';
+    process.stdout.write(`${green('→')} ${verb} slash commands @ ${target}: ${refreshed.map(r => r.name).join(', ')}\n`);
+  }
+
+  // 2. Identify dirty tracked files. Anything matching the allowlist gets
+  //    staged; everything else is left dirty so the user can handle it.
+  const dirty = listDirtyFiles(config.repoRoot);
+  const untracked = dirty.filter(d => d.status === '??');
+  const tracked = dirty.filter(d => d.status !== '??');
+
+  const toStage = tracked.filter(d => isAllowed(d.path)).map(d => d.path);
+  const skipped = tracked.filter(d => !isAllowed(d.path)).map(d => d.path);
+
+  // Untracked files matching the allowlist (e.g. a fresh new plan) are also
+  // safe to add — that's the common case of "scaffolded a plan, now shipping."
+  const newAllowed = untracked.filter(d => isAllowed(d.path)).map(d => d.path);
+  const newSkipped = untracked.filter(d => !isAllowed(d.path)).map(d => d.path);
+
+  const allToStage = [...toStage, ...newAllowed];
+  const allSkipped = [...skipped, ...newSkipped];
+
+  if (allSkipped.length > 0) {
+    process.stderr.write(`${dim(`Not staging (outside allowlist): ${allSkipped.join(', ')}`)}\n`);
+  }
+
+  if (dryRun) {
+    process.stdout.write(`${dim('[dry-run]')} Would stage ${allToStage.length} file(s):\n`);
+    for (const p of allToStage) process.stdout.write(`  ${p}\n`);
+    process.stdout.write(`${dim('[dry-run]')} Would commit and run \`npm version ${bump}\`\n`);
+    return;
+  }
+
+  if (allToStage.length > 0) {
+    const add = spawnSync('git', ['add', '--', ...allToStage], { cwd: config.repoRoot, encoding: 'utf8' });
+    if (add.status !== 0) die(`git add failed: ${add.stderr}`);
+
+    const planTitle = findHeldPlanTitle(config);
+    const subject = planTitle
+      ? `chore: release ${target} (${planTitle})`
+      : `chore: release ${target}`;
+    const body = `Auto-staged by \`dotmd ship\`:\n${allToStage.map(p => `- ${p}`).join('\n')}`;
+    const commitMsg = `${subject}\n\n${body}`;
+    const commit = spawnSync('git', ['commit', '-m', commitMsg], { cwd: config.repoRoot, encoding: 'utf8' });
+    if (commit.status !== 0) die(`git commit failed: ${commit.stderr || commit.stdout}`);
+    process.stdout.write(`${green('→')} Committed: ${subject}\n`);
+  } else {
+    process.stdout.write(`${dim('→ Nothing to commit before bump.')}\n`);
+  }
+
+  // 3. npm version <bump> — handles package.json bump, tag, push, GH release,
+  //    npm publish, and local reinstall via the existing pre/postversion
+  //    scripts. We stream its output so the user sees CI progress live.
+  process.stdout.write(`${green('→')} Running \`npm version ${bump}\`…\n`);
+  const npmResult = spawnSync('npm', ['version', bump], {
+    cwd: config.repoRoot,
+    stdio: 'inherit',
+  });
+  if (npmResult.status !== 0) {
+    warn('`npm version` failed. The bump commit + tag may already exist locally. Inspect with `git log -1` and `git tag --sort=-creatordate | head` before retrying.');
+    process.exit(npmResult.status ?? 1);
+  }
+
+  process.stdout.write(`${green('✓')} Shipped ${target}\n`);
+}