@vodmal/vdx-cli 0.19.0 → 0.20.1

package/README.md

@@ -42,7 +42,7 @@ vdx audit [project-path] [--format=ansi|markdown|json] [--rubric <path>] [--stac
 vdx init  [project-path] [--baseline github.com/org/repo@vX.Y] [--stack <id>] [--dry-run] [--force]   # default: cwd
 
 # Publish a library (Node MVP; PHP/Python coming in Y.3)
-vdx publish <patch|minor|major> [--dry-run] [--force]
+vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
 
 # Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin)
 vdx doctor [--format=ansi|markdown|json]
@@ -72,7 +72,7 @@ vdx init --stack node
 vdx test            # → mise run test (which calls `vitest run` or whatever was detected)
 
 # 3. Ship a new minor release of a Node lib
-vdx publish minor   # bump → npm publish (OTP prompt) → git commit + tag (no push)
+vdx publish minor   # npm login if expired → bump package.json + lock → npm publish (OTP) → commit + tag → push → wait for the registry
 
 # 4. Start the agent here, continuing its last conversation (--new: a new one;
 #    another machine's conversation is continued on that machine);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/src/ai.ts

@@ -957,6 +957,8 @@ export interface ConversationChoice {
   remote?: { host: string; id: string; reachable: boolean };
   /** Continue it here only after a yes: another machine's that cannot be asked, or one running here already. */
   askHere?: { id: string; why: string };
+  /** The person ended the question (Ctrl-D): start nothing. */
+  abort?: boolean;
   /** For the person: what was found and what is taken. */
   lines: string[];
 }
@@ -1047,7 +1049,8 @@ export function chooseConversation(plan: LaunchPlan, deps: AiDeps, canAsk: boole
     deps.log('  n) a new conversation');
     for (let tries = 0; tries < 2; tries++) {
       const answer = deps.ask(`Which one to continue? [1]: `);
-      if (answer === null) break;
+      // Ctrl-D at the question is a cancel, not "no terminal": start nothing.
+      if (answer === null) return { args: [], abort: true, lines: ['no answer — nothing started'] };
       const a = answer.trim();
       if (/^n(ew)?$/i.test(a)) return { args: [], lines: ['a new conversation'] };
       const c = a === '' ? found[0] : /^\d+$/.test(a) ? found[Number(a) - 1] : undefined;
@@ -1244,6 +1247,7 @@ export function runAi(opts: AiOptions, deps: AiDeps): number {
     return EXIT_OK;
   }
   for (const l of choice?.lines ?? []) log(l);
+  if (choice?.abort) return EXIT_LAUNCH_FAILED;
 
   let askHere = choice?.askHere;
   if (choice?.remote) {

package/src/index.ts

@@ -23,8 +23,10 @@ import { runDoctor, looksLikeProject, readCliVersion } from './doctor.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
 import {
   planPublish,
+  preflightFixable,
   renderPublishPlan,
   executePublish,
+  defaultPublishDeps,
   type BumpKind,
   type PublishOptions,
 } from './publish.ts';
@@ -38,7 +40,7 @@ const USAGE = `Usage:
   vdx <up|down|build|test|check|fix>     run lifecycle verb (via mise run <verb>)
   vdx audit   [project_path]  [--rubric <path>] [--stack <stack>] [--format=ansi|markdown|json] [--json]   (default: cwd)
   vdx init    [project_path]  [--stack <id>] [--baseline <ref>] [--dry-run] [--force]                     (default: cwd)
-  vdx publish <patch|minor|major> [--dry-run] [--force]
+  vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
   vdx doctor  [--format=ansi|markdown|json] [--json]
   vdx ai[@host] [project_path] [--new | --conversation <id>] [--restart] [--detach] [--dry-run]   (default: cwd; @host: over ssh, in tmux there)
   vdx <command> --help                   what the command does; an unknown option is refused (exit 2)
@@ -119,12 +121,18 @@ mise.toml is overwritten only with --force.
     positionals: 1,
   },
   publish: {
-    usage: 'vdx publish <patch|minor|major> [--dry-run] [--force]',
-    help: `Releases the library in the current directory: pre-flight checks, version bump,
-npm publish (npm asks for an OTP), git commit and tag. Does not push.
---dry-run runs the pre-flight and prints the plan; --force goes on past a failed pre-flight.
+    usage: 'vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]',
+    help: `Releases the library in the current directory, start to finish:
+  pre-flight checks — at a terminal an expired npm login is renewed (\`npm login\`)
+  and the checks run again;
+  the version bump in package.json and package-lock.json;
+  npm publish (npm asks for an OTP);
+  git commit and tag, then \`git push --follow-tags\` to the branch's upstream;
+  a wait until the registry shows the new version (up to 3 min).
+--dry-run runs the pre-flight and prints the plan; --force goes on past a failed
+pre-flight; --no-push leaves the commit and the tag local.
 `,
-    bools: ['dry-run', 'force'],
+    bools: ['dry-run', 'force', 'no-push'],
     positionals: 1,
   },
   doctor: {
@@ -320,7 +328,7 @@ function cmdPublish(opts: ParsedArgs): void {
   const bumpArg = opts.positionals[0];
   if (!bumpArg || !['patch', 'minor', 'major'].includes(bumpArg)) {
     process.stderr.write(
-      'Usage: vdx publish <patch|minor|major> [--dry-run] [--force]\n',
+      'Usage: vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]\n',
     );
     process.exit(1);
   }
@@ -340,15 +348,18 @@ function cmdPublish(opts: ParsedArgs): void {
     bump,
     dryRun: Boolean(opts.flags['dry-run']),
     force: Boolean(opts.flags.force),
+    push: !opts.flags['no-push'],
   };
 
-  let plan;
-  try {
-    plan = planPublish(planOpts, auditResult, ctx);
-  } catch (e: any) {
-    process.stderr.write(`error: ${e?.message ?? String(e)}\n`);
-    process.exit(2);
-  }
+  const replan = () => {
+    try {
+      return planPublish(planOpts, auditResult, ctx);
+    } catch (e: any) {
+      process.stderr.write(`error: ${e?.message ?? String(e)}\n`);
+      process.exit(2);
+    }
+  };
+  let plan = replan();
 
   process.stdout.write(renderPublishPlan(plan));
 
@@ -357,13 +368,30 @@ function cmdPublish(opts: ParsedArgs): void {
     return;
   }
 
+  // A failure a command fixes (an expired npm login): run it here, then check again.
+  const deps = defaultPublishDeps();
+  const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+  if (!plan.preflightPassed && !planOpts.force && interactive && preflightFixable(plan)) {
+    for (const c of plan.preflight.filter((c) => !c.ok && c.fix)) {
+      process.stderr.write(`\n→ ${c.name}: ${c.fix!.cmd} ${c.fix!.args.join(' ')}\n`);
+      try {
+        deps.run(c.fix!.cmd, c.fix!.args, projectRoot);
+      } catch {
+        process.stderr.write(`error: \`${c.fix!.cmd} ${c.fix!.args.join(' ')}\` failed\n`);
+        process.exit(2);
+      }
+    }
+    plan = replan();
+    process.stdout.write('\n' + renderPublishPlan(plan));
+  }
+
   if (!plan.preflightPassed && !planOpts.force) {
     process.stderr.write('\nerror: pre-flight failed (use --force to bypass)\n');
     process.exit(2);
   }
 
   try {
-    executePublish(plan);
+    executePublish(plan, deps);
   } catch (e: any) {
     process.stderr.write(`\nerror: ${e?.message ?? String(e)}\n`);
     process.exit(3);

package/src/publish.ts

@@ -11,12 +11,28 @@ export interface PublishOptions {
   bump: BumpKind;
   dryRun: boolean;
   force: boolean;
+  /** `git push --follow-tags` after the tag; `--no-push` turns it off. */
+  push?: boolean;
 }
 
 export interface PreflightCheck {
   name: string;
   ok: boolean;
   message: string;
+  /** A failed check a command at the terminal can fix — `npm login` for an expired session. */
+  fix?: { cmd: string; args: string[] };
+}
+
+/** Where the release goes after the tag. */
+export interface PushPlan {
+  /** Asked for (not `--no-push`). */
+  enabled: boolean;
+  /** `origin/main`; null — the branch has none, nothing to push to. */
+  upstream: string | null;
+  /** Local commits not on the upstream yet — they go with the release. */
+  ahead: number;
+  /** Upstream commits not here: the push would be refused. */
+  behind: number;
 }
 
 export interface PublishPlan {
@@ -27,6 +43,9 @@ export interface PublishPlan {
   newVersion: string;
   bump: BumpKind;
   packageJsonPath: string;
+  /** package-lock.json beside package.json, when there is one: its version goes into the same commit. */
+  lockPath?: string | null;
+  push?: PushPlan;
   preflight: PreflightCheck[];
   preflightPassed: boolean;
   delegatedToMise: boolean;
@@ -82,6 +101,33 @@ function isGitWorkingTreeClean(projectRoot: string): { ok: boolean; detail: stri
 /** Runs npm with these args and returns stdout; throws with `stderr` on a non-zero exit. */
 export type NpmRunner = (args: string[]) => string;
 
+/** Runs git with these args in `cwd` and returns stdout; throws on a non-zero exit. */
+export type GitRunner = (args: string[], cwd: string) => string;
+
+const runGit: GitRunner = (args, cwd) =>
+  execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+/**
+ * The branch's upstream and how far apart they are — from what git knows
+ * since the last fetch; nothing is fetched.
+ */
+export function planPush(projectRoot: string, enabled: boolean, git: GitRunner = runGit): PushPlan {
+  let upstream: string | null = null;
+  try {
+    upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], projectRoot).trim() || null;
+  } catch {
+    return { enabled, upstream: null, ahead: 0, behind: 0 };
+  }
+  const count = (range: string) => {
+    try {
+      return parseInt(git(['rev-list', '--count', range], projectRoot).trim(), 10) || 0;
+    } catch {
+      return 0;
+    }
+  };
+  return { enabled, upstream, ahead: count('@{u}..HEAD'), behind: count('HEAD..@{u}') };
+}
+
 // A caller's `npm run -s` passes `npm_config_loglevel=silent` down, and npm then
 // fails with an empty stderr — no E401 or E404 left to tell the cases apart.
 const runNpm: NpmRunner = (args) =>
@@ -128,11 +174,13 @@ export function publishRegistry(
  */
 export function checkNpmAuth(registry: string | null, npm: NpmRunner): PreflightCheck {
   const where = registry ?? 'npm';
-  const login = registry ? `npm login --registry ${registry}` : 'npm login';
+  const loginArgs = registry ? ['login', '--registry', registry] : ['login'];
+  const login = `npm ${loginArgs.join(' ')}`;
+  const fix = { cmd: 'npm', args: loginArgs };
   try {
     const who = npm(registry ? ['whoami', '--registry', registry] : ['whoami']).trim();
     if (who) return { name: 'npm-auth', ok: true, message: `OK (logged in to ${where} as ${who})` };
-    return { name: 'npm-auth', ok: false, message: `npm whoami answered nothing for ${where}. Run: ${login}` };
+    return { name: 'npm-auth', ok: false, message: `npm whoami answered nothing for ${where}. Run: ${login}`, fix };
   } catch (e: any) {
     const stderr = String(e?.stderr ?? e?.message ?? '');
     if (/E401|ENEEDAUTH/.test(stderr)) {
@@ -140,6 +188,7 @@ export function checkNpmAuth(registry: string | null, npm: NpmRunner): Preflight
         name: 'npm-auth',
         ok: false,
         message: `not logged in to ${where} (the npm session may have expired). Run: ${login}`,
+        fix,
       };
     }
     return {
@@ -174,6 +223,7 @@ export function planPublish(
   audit: AuditResult,
   ctx: Ctx,
   npm: NpmRunner = runNpm,
+  git: GitRunner = runGit,
 ): PublishPlan {
   if (checkMiseOverride(opts.projectRoot)) {
     return {
@@ -288,6 +338,26 @@ export function planPublish(
     });
   }
 
+  const push = planPush(opts.projectRoot, opts.push ?? true, git);
+  if (push.enabled && push.upstream && push.behind > 0) {
+    preflight.push({
+      name: 'push-target',
+      ok: false,
+      message:
+        `${push.upstream} has ${push.behind} commit(s) this branch lacks — the push after npm publish ` +
+        `would be refused. Pull first (or --no-push)`,
+    });
+  } else if (push.enabled) {
+    preflight.push({
+      name: 'push-target',
+      ok: true,
+      message: push.upstream
+        ? `OK (${push.upstream}${push.ahead ? `, ${push.ahead} local commit(s) go with the release` : ''})`
+        : 'no upstream for this branch — the release commit and tag stay local',
+    });
+  }
+
+  const lockPath = path.join(path.dirname(pkgJsonPath), 'package-lock.json');
   const preflightPassed = preflight.every((c) => c.ok);
 
   return {
@@ -298,82 +368,187 @@ export function planPublish(
     newVersion,
     bump: opts.bump,
     packageJsonPath: pkgJsonPath,
+    lockPath: fs.existsSync(lockPath) ? lockPath : null,
+    push,
     preflight,
     preflightPassed,
     delegatedToMise: false,
   };
 }
 
+/** Every failed check has a command that fixes it — run at a terminal, then plan again. */
+export function preflightFixable(plan: PublishPlan): boolean {
+  const failed = plan.preflight.filter((c) => !c.ok);
+  return failed.length > 0 && failed.every((c) => c.fix);
+}
+
+/** Runs a command on this terminal (stdio inherited); throws on a non-zero exit. */
+export type CommandRunner = (cmd: string, args: string[], cwd: string) => void;
+
+export interface PublishDeps {
+  run: CommandRunner;
+  npm: NpmRunner;
+  log: (line: string) => void;
+  sleep: (ms: number) => void;
+  /** How long to wait for the registry to show the new version. */
+  registryWaitMs: number;
+  /** Rewrites one status line in place (a terminal); without it the wait logs a line now and then. */
+  progress?: (text: string) => void;
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function defaultPublishDeps(): PublishDeps {
+  return {
+    run: (cmd, args, cwd) => {
+      execFileSync(cmd, args, { cwd, stdio: 'inherit' });
+    },
+    npm: runNpm,
+    log: (line) => process.stderr.write(line + '\n'),
+    sleep: sleepSync,
+    registryWaitMs: 180_000,
+    progress: process.stderr.isTTY ? (text) => process.stderr.write(`\r${text}\x1b[K`) : undefined,
+  };
+}
+
+/** Set `version` in package-lock.json — the root and its own entry under `packages`. */
+export function bumpLockText(text: string, version: string): string {
+  const lock = JSON.parse(text);
+  lock.version = version;
+  if (lock.packages?.['']) lock.packages[''].version = version;
+  return JSON.stringify(lock, null, 2) + '\n';
+}
+
+/**
+ * npm answers `202 Accepted` and the version shows up a minute or two later;
+ * until then `npm view` and `npx` still see the previous one. Waiting here
+ * turns "is it out?" into an answer. A version that does not show up in time
+ * is not a failure: npm took it.
+ */
+export function waitForRegistry(name: string, version: string, deps: PublishDeps): boolean {
+  const started = Date.now();
+  const deadline = started + deps.registryWaitMs;
+  const limit = Math.round(deps.registryWaitMs / 1000);
+  const seconds = () => Math.round((Date.now() - started) / 1000);
+  deps.log(
+    `→ waiting for the registry to show ${name}@${version} — npm has taken it; ` +
+      `the registry usually shows it within ~2 min (giving it ${limit} s)`,
+  );
+  const shown = () => {
+    try {
+      return deps.npm(['view', `${name}@${version}`, 'version', '--prefer-online']).trim() === version;
+    } catch {
+      return false; // E404 until it is processed
+    }
+  };
+  // Ask npm every 10 s; between the asks, count the seconds on one line.
+  let lastLogged = 0;
+  for (let found = shown(); ; found = shown()) {
+    if (found) {
+      deps.progress?.('');
+      deps.log(`✓ ${name}@${version} is on the registry (${seconds()} s after publish)`);
+      return true;
+    }
+    if (Date.now() >= deadline) break;
+    for (let i = 0; i < 10 && Date.now() < deadline; i++) {
+      if (deps.progress) deps.progress(`  … ${seconds()} s of ${limit} s`);
+      else if (seconds() - lastLogged >= 30) {
+        lastLogged = seconds();
+        deps.log(`  … ${lastLogged} s`);
+      }
+      deps.sleep(1_000);
+    }
+  }
+  deps.progress?.('');
+  deps.log(
+    `! ${name}@${version} not visible on the registry after ${Math.round(deps.registryWaitMs / 60_000)} min — ` +
+      `npm accepted it; check later: npm view ${name}@${version} version`,
+  );
+  return false;
+}
+
 /**
  * Execute the publish pipeline. Order is transactional:
- *   1. bump package.json in-place (reversible by file restore).
+ *   1. bump package.json and package-lock.json in place (reversible by file restore).
  *   2. `npm publish` (irreversible — first because npm errors are easier
  *      to recover from than a published-but-uncommitted state).
  *   3. git add + commit + tag (reversible by reset/tag delete, but only
  *      a problem if step 2 succeeded — uncommitted bump after success
  *      is recoverable manually).
- *   4. NOT pushed — that's the user's call.
+ *   4. `git push --follow-tags` to the branch's upstream, unless `--no-push`
+ *      or there is none. The pre-flight refused a branch behind its upstream.
+ *   5. Wait until the registry shows the version.
  *
- * On npm publish failure → restore original package.json contents.
+ * On npm publish failure → restore the original files.
  * Git failures after a successful npm publish leave the user in a
- * partially-released state; they fix it manually (commit/tag what's
+ * partially-released state; they fix it manually (commit/tag/push what's
  * needed) — we don't try to unpublish.
  */
-export function executePublish(plan: PublishPlan): void {
+export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPublishDeps()): void {
   if (plan.delegatedToMise) {
-    process.stderr.write('→ delegating to `mise run publish`...\n');
-    execFileSync('mise', ['run', 'publish'], {
-      cwd: plan.projectRoot,
-      stdio: 'inherit',
-    });
+    deps.log('→ delegating to `mise run publish`...');
+    deps.run('mise', ['run', 'publish'], plan.projectRoot);
     return;
   }
 
-  // 1. Bump package.json in-place (keep original text for revert)
-  const originalText = fs.readFileSync(plan.packageJsonPath, 'utf8');
-  const pkg = JSON.parse(originalText);
-  pkg.version = plan.newVersion;
-  fs.writeFileSync(
-    plan.packageJsonPath,
-    JSON.stringify(pkg, null, 2) + '\n',
-    'utf8',
-  );
-  process.stderr.write(
-    `✓ bumped ${path.relative(plan.projectRoot, plan.packageJsonPath)}: ${plan.currentVersion} → ${plan.newVersion}\n`,
+  // 1. Bump package.json (and the lock) in place, keeping the original text for revert.
+  const originals = new Map<string, string>();
+  const rewrite = (file: string, next: (text: string) => string) => {
+    const text = fs.readFileSync(file, 'utf8');
+    originals.set(file, text);
+    fs.writeFileSync(file, next(text), 'utf8');
+  };
+  rewrite(plan.packageJsonPath, (text) => {
+    const pkg = JSON.parse(text);
+    pkg.version = plan.newVersion;
+    return JSON.stringify(pkg, null, 2) + '\n';
+  });
+  if (plan.lockPath) rewrite(plan.lockPath, (text) => bumpLockText(text, plan.newVersion));
+  const bumped = [...originals.keys()];
+  deps.log(
+    `✓ bumped ${bumped.map((f) => path.relative(plan.projectRoot, f)).join(' and ')}: ${plan.currentVersion} → ${plan.newVersion}`,
   );
 
   // 2. npm publish (interactive — OTP prompt may appear)
-  process.stderr.write(`→ running \`npm publish\` (OTP prompt may appear)...\n`);
-  const pkgDir = path.dirname(plan.packageJsonPath);
+  deps.log('→ running `npm publish` (OTP prompt may appear)...');
   try {
-    execFileSync('npm', ['publish'], { cwd: pkgDir, stdio: 'inherit' });
+    deps.run('npm', ['publish'], path.dirname(plan.packageJsonPath));
   } catch (e: any) {
-    fs.writeFileSync(plan.packageJsonPath, originalText, 'utf8');
-    process.stderr.write(
-      `✗ npm publish failed (exit ${e?.status ?? '?'}); reverted package.json\n`,
-    );
+    for (const [file, text] of originals) fs.writeFileSync(file, text, 'utf8');
+    deps.log(`✗ npm publish failed (exit ${e?.status ?? '?'}); reverted ${bumped.map((f) => path.basename(f)).join(' and ')}`);
     throw new Error('npm publish failed');
   }
-  process.stderr.write(`✓ published ${plan.packageName}@${plan.newVersion}\n`);
+  deps.log(`✓ published ${plan.packageName}@${plan.newVersion}`);
 
   // 3. git add + commit + tag (at project root)
-  execFileSync('git', ['add', plan.packageJsonPath], {
-    cwd: plan.projectRoot,
-    stdio: 'inherit',
-  });
-  execFileSync('git', ['commit', '-m', `release: v${plan.newVersion}`], {
-    cwd: plan.projectRoot,
-    stdio: 'inherit',
-  });
-  execFileSync(
-    'git',
-    ['tag', '-a', `v${plan.newVersion}`, '-m', `v${plan.newVersion}`],
-    { cwd: plan.projectRoot, stdio: 'inherit' },
-  );
-  process.stderr.write(`✓ committed + tagged v${plan.newVersion}\n`);
-  process.stderr.write(
-    `\n! NOT pushed — your call: \`git push --follow-tags\`\n`,
-  );
+  deps.run('git', ['add', '--', ...bumped], plan.projectRoot);
+  deps.run('git', ['commit', '-m', `release: v${plan.newVersion}`, '--', ...bumped], plan.projectRoot);
+  deps.run('git', ['tag', '-a', `v${plan.newVersion}`, '-m', `v${plan.newVersion}`], plan.projectRoot);
+  deps.log(`✓ committed + tagged v${plan.newVersion}`);
+
+  // 4. push
+  const push = plan.push;
+  if (push?.enabled && push.upstream) {
+    deps.log(`→ git push --follow-tags (${push.upstream})...`);
+    try {
+      deps.run('git', ['push', '--follow-tags'], plan.projectRoot);
+    } catch {
+      deps.log(`✗ git push failed — ${plan.packageName}@${plan.newVersion} is published and tagged here; push it: git push --follow-tags`);
+      throw new Error('git push failed');
+    }
+    deps.log(`✓ pushed to ${push.upstream} with tag v${plan.newVersion}`);
+  } else {
+    deps.log(
+      push?.enabled === false
+        ? '! not pushed (--no-push): git push --follow-tags'
+        : '! not pushed — the branch has no upstream: git push --follow-tags -u <remote> <branch>',
+    );
+  }
+
+  // 5. registry
+  waitForRegistry(plan.packageName, plan.newVersion, deps);
 }
 
 export function renderPublishPlan(plan: PublishPlan): string {
@@ -409,14 +584,28 @@ export function renderPublishPlan(plan: PublishPlan): string {
     lines.push(`| ${c.name} | ${c.ok ? 'OK' : 'FAIL'} | ${c.message} |`);
   }
   lines.push('');
-  if (plan.preflightPassed) {
+  const fixable = !plan.preflightPassed && preflightFixable(plan);
+  if (plan.preflightPassed || fixable) {
+    const files = plan.lockPath ? 'package.json and package-lock.json' : 'package.json';
+    const push = plan.push;
     lines.push('## Pipeline (would execute on `vdx publish`)');
     lines.push('');
-    lines.push(`1. Set \`version\` in package.json → \`${plan.newVersion}\``);
+    if (fixable) {
+      const fixes = plan.preflight.filter((c) => !c.ok && c.fix).map((c) => `\`${c.fix!.cmd} ${c.fix!.args.join(' ')}\``);
+      lines.push(`0. ${fixes.join(', ')} — at a terminal, then the pre-flight again`);
+    }
+    lines.push(`1. Set \`version\` in ${files} → \`${plan.newVersion}\``);
     lines.push(`2. \`npm publish\` (cwd = directory containing package.json)`);
-    lines.push(`3. \`git add package.json && git commit -m "release: v${plan.newVersion}"\``);
+    lines.push(`3. \`git commit -m "release: v${plan.newVersion}"\` (${files})`);
     lines.push(`4. \`git tag -a v${plan.newVersion} -m "v${plan.newVersion}"\``);
-    lines.push(`5. (NOT pushed — your call: \`git push --follow-tags\`)`);
+    lines.push(
+      !push?.enabled
+        ? '5. Not pushed (`--no-push`): `git push --follow-tags` is yours'
+        : push.upstream
+          ? `5. \`git push --follow-tags\` → ${push.upstream}${push.ahead ? ` (with ${push.ahead} local commit(s) not pushed yet)` : ''}`
+          : '5. Not pushed: the branch has no upstream',
+    );
+    lines.push(`6. Wait until the registry shows ${plan.newVersion} (up to 3 min)`);
   } else {
     lines.push('> Pre-flight failed. Use `--force` to bypass at your own risk.');
   }