import * as fs from 'node:fs'; import * as path from 'node:path'; import { execFileSync } from 'node:child_process'; import type { AuditResult } from './audit.ts'; import { stackForDir, type Ctx } from './facts.ts'; import { defaultGateDeps, GATE_PREFIX, planGate, pushThroughGate, type GatePlan, type GateTarget } from './gate.ts'; import { machineIo } from './hosting.ts'; import { at, dict, errorMessage, stderrOf, str } from './narrow.ts'; export type BumpKind = 'patch' | 'minor' | 'major'; export interface PublishOptions { projectRoot: string; 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[] }; /** A failed check the person at the terminal may waive: the question, Enter answering no. */ waive?: 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; /** The upstream requires checks: the release commit goes through them (`vdx push`). */ gate?: GateTarget; } export interface PublishPlan { projectRoot: string; stack: string; packageName: string; currentVersion: string; 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; } export function bumpSemver(current: string, kind: BumpKind): string { const m = current.match(/^(\d+)\.(\d+)\.(\d+)/); if (!m) throw new Error(`Cannot parse semver "${current}"`); let major = parseInt(m[1]!, 10); let minor = parseInt(m[2]!, 10); let patch = parseInt(m[3]!, 10); if (kind === 'major') { major += 1; minor = 0; patch = 0; } else if (kind === 'minor') { minor += 1; patch = 0; } else { patch += 1; } return `${major}.${minor}.${patch}`; } export function compareSemver(a: string, b: string): number { const norm = (s: string) => s .replace(/^v/, '') .split(/[.\-+]/) .map((p) => parseInt(p, 10) || 0); const pa = norm(a); const pb = norm(b); for (let i = 0; i < Math.max(pa.length, pb.length); i++) { const av = pa[i] ?? 0; const bv = pb[i] ?? 0; if (av !== bv) return av < bv ? -1 : 1; } return 0; } function isGitWorkingTreeClean(projectRoot: string): { ok: boolean; detail: string } { try { const out = execFileSync('git', ['status', '--porcelain'], { cwd: projectRoot, encoding: 'utf8', }); if (out.trim() === '') return { ok: true, detail: 'OK' }; const lines = out.trim().split('\n'); const sample = lines.slice(0, 3).join(', '); return { ok: false, detail: `${lines.length} uncommitted file(s) — ${sample}` }; } catch { return { ok: false, detail: 'not a git repo (or git not available)' }; } } /** 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; 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}') }; } /** * How far apart the branch and the remote really are. The upstream ref is what this station last * heard, and a push made on the other one reaches it by Syncthing, minutes after the commit * (intercom-session-mode Sidetrack #10). Null: the remote does not answer, or names a commit not here. */ function remoteDistance( projectRoot: string, target: GateTarget, git: GitRunner, ): { ahead: number; behind: number } | null { try { const out = git(['ls-remote', target.remote, `refs/heads/${target.branch}`], projectRoot); const sha = /^[0-9a-f]{40}\b/.exec(out)?.[0]; if (!sha) return null; const count = (range: string) => parseInt(git(['rev-list', '--count', range], projectRoot).trim(), 10); return { ahead: count(`${sha}..HEAD`), behind: count(`HEAD..${sha}`) }; } catch { return null; } } // 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) => execFileSync('npm', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, npm_config_loglevel: 'error' }, }); function fetchPublishedVersion(packageName: string, npm: NpmRunner): string | null { try { const out = npm(['view', packageName, 'version']); return out.trim() || null; } catch (e) { const stderr = stderrOf(e); if (stderr.includes('E404') || stderr.includes('404 Not Found')) return null; throw new Error(`npm view failed: ${stderr.split('\n')[0] ?? stderr}`, { cause: e }); } } /** * The registry `npm publish` sends this package to, when it is not npm's * default: `publishConfig.registry`, else the scope's registry from npm config. */ export function publishRegistry(pkg: unknown, npm: NpmRunner): string | null { const registry = str(at(pkg, 'publishConfig', 'registry')); if (registry) return registry; const scope = str(at(pkg, 'name'))?.match(/^(@[^/]+)\//)?.[1]; if (!scope) return null; try { const value = npm(['config', 'get', `${scope}:registry`]).trim(); return value && value !== 'undefined' ? value : null; } catch { return null; } } /** * Logged in where the package goes? Without it `npm publish` fails only after * the bump and the pack, and with E404 on a scoped package, not E401 — an * expired npm session reads as a missing package. */ export function checkNpmAuth(registry: string | null, npm: NpmRunner): PreflightCheck { const where = registry ?? 'npm'; 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}`, fix }; } catch (e) { const stderr = stderrOf(e); if (/E401|ENEEDAUTH/.test(stderr)) { return { name: 'npm-auth', ok: false, message: `not logged in to ${where} (the npm session may have expired). Run: ${login}`, fix, }; } // A 5xx is the registry's trouble, not the login: 0.35.0 met E503 during an npm // incident on 2026-10-22, and the line read as a failed login. const outage = /\bE(5\d\d)\b/.exec(stderr); if (outage) { const npmjs = !registry || registry.includes('registry.npmjs.org'); return { name: 'npm-auth', ok: false, message: `${where} is not answering (E${outage[1]}) — trouble on its side, not the login${npmjs ? '; status: https://status.npmjs.org' : ''}. Run vdx publish again once it answers`, }; } return { name: 'npm-auth', ok: false, message: `npm whoami failed for ${where}: ${stderr.split('\n').find((l) => l.trim()) ?? stderr}`, }; } } function checkMiseOverride(projectRoot: string): boolean { const miseToml = path.join(projectRoot, 'mise.toml'); if (!fs.existsSync(miseToml)) return false; try { const text = fs.readFileSync(miseToml, 'utf8'); // Lightweight check — a [tasks.publish] section header is unambiguous // enough for the delegation gate; no need for full TOML parsing here. return /^\[tasks\.publish\b/m.test(text); } catch { return false; } } function resolvePackageJsonPath(projectRoot: string, audit: AuditResult): string { const subpkg = audit.primary_subpackage; const root = subpkg ? path.join(projectRoot, subpkg) : projectRoot; return path.join(root, 'package.json'); } export function planPublish( opts: PublishOptions, audit: AuditResult, ctx: Ctx, npm: NpmRunner = runNpm, git: GitRunner = runGit, gate: (projectRoot: string) => GatePlan = (root) => planGate(machineIo(root)), ): PublishPlan { if (checkMiseOverride(opts.projectRoot)) { return { projectRoot: opts.projectRoot, stack: ctx.stack, packageName: '(delegated)', currentVersion: '', newVersion: '', bump: opts.bump, packageJsonPath: '', preflight: [ { name: 'mise-override', ok: true, message: '[tasks.publish] present in mise.toml — delegating to mise', }, ], preflightPassed: true, delegatedToMise: true, }; } // Resolve effective stack: prefer subpackage stack if primary_subpackage is set // (meta-projects publishing a nested lib, e.g. vdx itself with primary_subpackage=cli). const subpkg = audit.primary_subpackage; const effectiveStack = subpkg ? stackForDir(path.join(opts.projectRoot, subpkg)) : ctx.stack; if (effectiveStack !== 'node') { throw new Error( `vdx publish: only "node" stack is supported in the MVP (Шаг X). ` + `Effective stack: "${effectiveStack}" (root: "${ctx.stack}"${ subpkg ? `, subpackage: "${subpkg}"` : '' }). PHP/Python come in Шаг X.2.`, ); } const pkgJsonPath = resolvePackageJsonPath(opts.projectRoot, audit); if (!fs.existsSync(pkgJsonPath)) { throw new Error(`vdx publish: package.json not found at ${pkgJsonPath}`); } const pkg: unknown = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8')); const packageName = str(at(pkg, 'name')) ?? '(unnamed)'; const currentVersion = str(at(pkg, 'version')) ?? '0.0.0'; const newVersion = bumpSemver(currentVersion, opts.bump); const preflight: PreflightCheck[] = []; const tree = isGitWorkingTreeClean(opts.projectRoot); preflight.push({ name: 'working-tree-clean', ok: tree.ok, message: tree.detail, }); const raAxis = audit.per_axis.find((a) => a.axis_id === 'release-artifact'); const isExcluded = raAxis?.drift_kind === 'excluded'; preflight.push({ name: 'lib-intent (applies_when)', ok: !!raAxis && !isExcluded, message: !raAxis ? 'release-artifact axis missing from rubric' : isExcluded ? 'release-artifact axis excluded — this looks like an app, not a library. ' + 'Use [tasks.publish] in mise.toml if you really need vdx publish here.' : 'OK (axis applies → lib-intent)', }); const raLevel = raAxis?.achieved ?? 'L0'; const raLevelInt = parseInt(raLevel.slice(1), 10) || 0; preflight.push({ name: 'release-artifact >= L3', ok: raLevelInt >= 3, message: raLevelInt >= 3 ? `OK (release-artifact ${raLevel})` : `release-artifact at ${raLevel}, need >= L3. Add files[], main/exports, license in package.json.`, }); preflight.push(checkNpmAuth(publishRegistry(pkg, npm), npm)); preflight.push( checkChangesSinceRelease(opts.projectRoot, path.dirname(pkgJsonPath), currentVersion, newVersion, git), ); let published: string | null = null; let registryError: string | null = null; try { published = fetchPublishedVersion(packageName, npm); } catch (e) { registryError = errorMessage(e); } if (registryError) { preflight.push({ name: 'registry-collision', ok: false, message: `could not query npm registry: ${registryError}`, }); } else if (published === null) { preflight.push({ name: 'registry-collision', ok: true, message: `first publish (no prior version on registry)`, }); } else { const cmp = compareSemver(newVersion, published); preflight.push({ name: 'registry-collision', ok: cmp > 0, message: cmp > 0 ? `OK (registry @ ${published}, new ${newVersion})` : `registry @ ${published} ≥ new ${newVersion}; pick a higher bump`, }); } const push = planPush(opts.projectRoot, opts.push ?? true, git); if (push.enabled && push.upstream) { const g = gate(opts.projectRoot); if (g.kind === 'gate') { push.gate = g.target; if (push.ahead > 0) Object.assign(push, remoteDistance(opts.projectRoot, g.target, 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.gate && push.ahead > 0) { // npm publish comes before the push (DL #9 of docs/tasks/hosting-extension): what // CI has not seen would reach npm first. preflight.push({ name: 'push-target', ok: false, message: `${push.ahead} local commit(s) are not on ${push.upstream}, which requires ${push.gate.checks.join(', ')}: ` + `npm would get them before CI checks them. Push them first: vdx push`, }); } else if (push.enabled) { preflight.push({ name: 'push-target', ok: true, message: push.gate ? `OK (${push.upstream}, through ${push.gate.checks.join(', ')})` : 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 { projectRoot: opts.projectRoot, stack: ctx.stack, packageName, currentVersion, newVersion, bump: opts.bump, packageJsonPath: pkgJsonPath, lockPath: fs.existsSync(lockPath) ? lockPath : null, push, preflight, preflightPassed, delegatedToMise: false, }; } /** * Anything to release? 0.30.0 went out on 2026-10-18 with nothing since v0.29.0 but * its release commit (hosting-extension Sidetrack #6). Nothing in the package's * directory since the tag of the current version — the same package under a new * number; a terminal asks, Enter answering no. */ export function checkChangesSinceRelease( projectRoot: string, packageDir: string, current: string, next: string, git: GitRunner, ): PreflightCheck { const name = 'changes-since-release'; const tag = `v${current}`; try { git(['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], projectRoot); } catch { return { name, ok: true, message: `OK (no tag ${tag} to compare with)` }; } const where = path.relative(projectRoot, packageDir) || '.'; const shown = where === '.' ? `${path.basename(packageDir)}/` : `${where}/`; let count: number; try { count = parseInt(git(['rev-list', '--count', `${tag}..HEAD`, '--', where], projectRoot).trim(), 10) || 0; } catch { return { name, ok: true, message: `OK (git could not compare with ${tag})` }; } if (count > 0) return { name, ok: true, message: `OK (${count} commit(s) in ${shown} since ${tag})` }; return { name, ok: false, message: `nothing in ${shown} has changed since ${tag}: ${next} would be the package ${current} is`, waive: `Release ${next} anyway, the same package under a new number? [y/N] `, }; } /** * Every failed check is resolved at a terminal: a command that fixes it (run, then * plan again) or a question the person may answer yes to. */ export function preflightFixable(plan: PublishPlan): boolean { const failed = plan.preflight.filter((c) => !c.ok); return failed.length > 0 && failed.every((c) => c.fix || c.waive); } /** Runs a command on this terminal (stdio inherited); throws on a non-zero exit. */ 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; /** HEAD through the upstream's checks, with the tag (`vdx push`); throws when the upstream did not take it. */ gatePush: (target: GateTarget, projectRoot: 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: 10 * 60_000, progress: process.stderr.isTTY ? (text) => process.stderr.write(`\r${text}\x1b[K`) : undefined, gatePush: (target, projectRoot) => pushThroughGate(target, defaultGateDeps(projectRoot)), }; } /** Set `version` in package-lock.json — the root and its own entry under `packages`. */ export function bumpLockText(text: string, version: string): string { const lock = dict(JSON.parse(text)) ?? {}; lock['version'] = version; const self = dict(at(lock, 'packages', '')); if (self) self['version'] = version; return JSON.stringify(lock, null, 2) + '\n'; } /** * npm answers `202 Accepted` and the version shows up minutes later — 0.30.0 * about 6 min after publish, 0.31.2 past 5 (hosting-extension Sidetrack #9); until * then `npm view` and `npx` still see the previous one. Waiting here turns "is it * out?" into an answer. The time counts from `npm publish` (`since`): the push * through CI before the wait is part of it. 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, since = Date.now()): boolean { const started = since; 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 has taken up to 6 min to show a version (giving it ${limit} s from publish; ` + `Ctrl-C stops only this wait)`, ); 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 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. `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. * An upstream that requires checks takes the commit through them (`vdx push`). * 5. Wait until the registry shows the version. * * On npm publish failure or interruption (Ctrl-C at its prompt) → 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/push what's * needed) — we don't try to unpublish. */ export function executePublish(plan: PublishPlan, deps: PublishDeps = defaultPublishDeps()): void { if (plan.delegatedToMise) { deps.log('→ delegating to `mise run publish`...'); deps.run('mise', ['run', 'publish'], plan.projectRoot); return; } // 1. Bump package.json (and the lock) in place, keeping the original text for revert. const originals = new Map(); 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 = dict(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 — npm asks for an OTP or a confirmation in the browser). // Ctrl-C at that prompt reaches npm and vdx alike: vdx holds out while npm runs, so the // interrupted npm comes back as an error and the bump is put back — not left for the next run. deps.log('→ running `npm publish` (npm may ask for an OTP or a confirmation in the browser)...'); const holdOut = () => {}; const signals: NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGHUP']; for (const s of signals) process.on(s, holdOut); try { deps.run('npm', ['publish'], path.dirname(plan.packageJsonPath)); } catch (e) { for (const [file, text] of originals) fs.writeFileSync(file, text, 'utf8'); const signal = str(at(e, 'signal')); const status = at(e, 'status'); const what = signal ? `interrupted (${signal})` : `failed (exit ${typeof status === 'number' ? status : '?'})`; deps.log(`✗ npm publish ${what}; reverted ${bumped.map((f) => path.basename(f)).join(' and ')}`); throw new Error(`npm publish ${signal ? 'interrupted' : 'failed'}`, { cause: e }); } finally { for (const s of signals) process.off(s, holdOut); } const publishedAt = Date.now(); deps.log(`✓ published ${plan.packageName}@${plan.newVersion}`); // 3. git add + commit + tag (at project root) 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.gate) { try { deps.gatePush(push.gate, plan.projectRoot); } catch (e) { deps.log( `✗ ${errorMessage(e)} — ${plan.packageName}@${plan.newVersion} is published and tagged here; ` + `once the checks pass: vdx push`, ); throw new Error(`${push.upstream} did not take the release commit`, { cause: e }); } deps.log(`✓ pushed to ${push.upstream} with tag v${plan.newVersion}, through ${push.gate.checks.join(', ')}`); } else 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 ', ); } // 5. registry waitForRegistry(plan.packageName, plan.newVersion, deps, publishedAt); } export function renderPublishPlan(plan: PublishPlan): string { const lines: string[] = []; lines.push('# vdx publish plan'); lines.push(''); if (plan.delegatedToMise) { lines.push('- **Mode**: delegated to `[tasks.publish]` from mise.toml'); lines.push(''); lines.push('## Pre-flight checks'); lines.push(''); lines.push('| Check | Status | Message |'); lines.push('|-------|:------:|---------|'); for (const c of plan.preflight) { lines.push(`| ${c.name} | ${c.ok ? 'OK' : 'FAIL'} | ${c.message} |`); } lines.push(''); lines.push('> vdx will exec `mise run publish` — no vdx-native pipeline involved.'); return lines.join('\n') + '\n'; } lines.push(`- **Package**: ${plan.packageName}`); lines.push(`- **Stack**: ${plan.stack}`); lines.push(`- **Bump**: ${plan.bump}`); lines.push(`- **Version**: ${plan.currentVersion} → ${plan.newVersion}`); lines.push(`- **package.json**: ${plan.packageJsonPath}`); lines.push(''); lines.push('## Pre-flight checks'); lines.push(''); lines.push('| Check | Status | Message |'); lines.push('|-------|:------:|---------|'); for (const c of plan.preflight) { lines.push(`| ${c.name} | ${c.ok ? 'OK' : 'FAIL'} | ${c.message} |`); } lines.push(''); 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(''); if (fixable) { const fixes = plan.preflight .filter((c) => !c.ok && c.fix) .map((c) => `\`${c.fix!.cmd} ${c.fix!.args.join(' ')}\``); if (fixes.length > 0) lines.push(`0. ${fixes.join(', ')} — at a terminal, then the pre-flight again`); for (const c of plan.preflight.filter((c) => !c.ok && c.waive)) { lines.push(`0. At a terminal: ${c.waive!.trim()} — Enter releases nothing`); } } lines.push(`1. Set \`version\` in ${files} → \`${plan.newVersion}\``); lines.push(`2. \`npm publish\` (cwd = directory containing package.json)`); 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( !push?.enabled ? '5. Not pushed (`--no-push`): `git push --follow-tags` is yours' : push.gate ? `5. Through CI (\`vdx push\`): \`${GATE_PREFIX}${push.gate.branch}\`, then ${push.upstream} with the tag once ${push.gate.checks.join(', ')} pass` : 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 10 min from publish)`); } else { lines.push('> Pre-flight failed. Use `--force` to bypass at your own risk.'); } return lines.join('\n') + '\n'; }