@vodmal/vdx-cli 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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/index.ts

@@ -6,6 +6,13 @@ import { autoDetectStack, type Ctx } from './facts.ts';
 import { audit } from './audit.ts';
 import { reportMarkdown, reportJson } from './report.ts';
 import { planInit, writeInit, renderPlanSummary } from './init.ts';
+import {
+  planPublish,
+  renderPublishPlan,
+  executePublish,
+  type BumpKind,
+  type PublishOptions,
+} from './publish.ts';
 import { resolveDefaultRubric } from './defaults.ts';
 
 const DEFAULT_RUBRIC = resolveDefaultRubric();
@@ -13,8 +20,9 @@ const DEFAULT_RUBRIC = resolveDefaultRubric();
 function usage(): never {
   process.stderr.write(
     `Usage:
-  vdx audit <project_path> [--rubric <path>] [--stack <stack>] [--json]
-  vdx init  <project_path> [--stack <id>] [--baseline <ref>] [--dry-run] [--force]
+  vdx audit   <project_path> [--rubric <path>] [--stack <stack>] [--json]
+  vdx init    <project_path> [--stack <id>] [--baseline <ref>] [--dry-run] [--force]
+  vdx publish <patch|minor|major> [--dry-run] [--force]
 `,
   );
   process.exit(1);
@@ -114,7 +122,62 @@ function cmdInit(opts: ParsedArgs): void {
   }
 }
 
+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',
+    );
+    process.exit(1);
+  }
+  const bump = bumpArg as BumpKind;
+  const projectRoot = process.cwd();
+
+  const manifest = loadManifest(projectRoot);
+  const overrides = loadOverrides(projectRoot);
+  const rubric = loadRubric(DEFAULT_RUBRIC);
+  const stack = manifest?.stack || autoDetectStack(projectRoot);
+  const ctx: Ctx = { projectRoot, stack, cache: new Map() };
+  const baselineRef = manifest?.baseline ?? `file://${DEFAULT_RUBRIC}`;
+  const auditResult = audit(rubric, ctx, overrides, baselineRef, manifest);
+
+  const planOpts: PublishOptions = {
+    projectRoot,
+    bump,
+    dryRun: Boolean(opts.flags['dry-run']),
+    force: Boolean(opts.flags.force),
+  };
+
+  let plan;
+  try {
+    plan = planPublish(planOpts, auditResult, ctx);
+  } catch (e: any) {
+    process.stderr.write(`error: ${e?.message ?? String(e)}\n`);
+    process.exit(2);
+  }
+
+  process.stdout.write(renderPublishPlan(plan));
+
+  if (planOpts.dryRun) {
+    process.stderr.write('\n[dry-run] не выполнено.\n');
+    return;
+  }
+
+  if (!plan.preflightPassed && !planOpts.force) {
+    process.stderr.write('\nerror: pre-flight failed (use --force to bypass)\n');
+    process.exit(2);
+  }
+
+  try {
+    executePublish(plan);
+  } catch (e: any) {
+    process.stderr.write(`\nerror: ${e?.message ?? String(e)}\n`);
+    process.exit(3);
+  }
+}
+
 const parsed = parseArgs(process.argv);
 if (parsed.cmd === 'audit') cmdAudit(parsed);
 else if (parsed.cmd === 'init') cmdInit(parsed);
+else if (parsed.cmd === 'publish') cmdPublish(parsed);
 else usage();

package/src/init.ts

@@ -17,12 +17,62 @@ export type Verb = (typeof STANDARD_VERBS)[number];
 export const DEFAULT_BASELINE = 'github.com/VoDmAl/vdx-rubric-vodmal@v0.3.1';
 
 const VERB_ALIASES: Record<Verb, string[]> = {
-  up: ['docker:up', 'docker-up', 'docker:up:detached', 'start'],
+  up: ['docker:up', 'docker-up', 'docker:up:detached', 'start', 'dev', 'serve'],
   down: ['docker:down', 'docker-down', 'stop'],
-  build: ['docker:build', 'build:prod', 'build-prod', 'build:dev', 'build-dev', 'build:assets'],
-  test: ['phpunit', 'test:unit', 'test-unit', 'test:unit:phpunit', 'jest', 'vitest'],
-  check: ['lint', 'check:config', 'check:before:commit', 'check:code:static', 'check:code:lint'],
-  fix: ['fix:ecs', 'format', 'lint:fix'],
+  build: [
+    'docker:build',
+    'build:prod',
+    'build-prod',
+    'build:dev',
+    'build-dev',
+    'build:assets',
+    'compile',
+    'dist',
+  ],
+  test: [
+    'phpunit',
+    'pest',
+    'test:unit',
+    'test-unit',
+    'test:unit:phpunit',
+    'tests',
+    'unit',
+    'jest',
+    'vitest',
+    'mocha',
+    'ava',
+    'spec',
+    'coverage',
+  ],
+  check: [
+    'lint',
+    'check:before:commit',
+    'check:before:push',
+    'check:config',
+    'check:code:static',
+    'check:code:lint',
+    'typecheck',
+    'tsc',
+    'eslint',
+    'prettier:check',
+    'format:check',
+    'qa',
+    'phpstan',
+    'psalm',
+  ],
+  fix: [
+    'fix:ecs',
+    'fix:rector',
+    'format',
+    'lint:fix',
+    'eslint:fix',
+    'prettier',
+    'prettier:write',
+    'prettier:fix',
+    'format:write',
+    'cs-fix',
+    'cs:fix',
+  ],
 };
 
 const VERB_PREFIX_GROUPS: Record<Verb, string[]> = {
@@ -34,10 +84,32 @@ const VERB_PREFIX_GROUPS: Record<Verb, string[]> = {
   fix: ['fix:', 'fix-'],
 };
 
+// Suffix-based monorepo fallback: lets us pick up `server:test`, `api:lint`, etc.
+// when no exact/alias/prefix-group match exists.
+const VERB_SUFFIX_GROUPS: Record<Verb, string[]> = {
+  up: [':up', '-up'],
+  down: [':down', '-down'],
+  build: [':build', '-build'],
+  test: [':test', '-test'],
+  check: [':check', '-check', ':lint', ':typecheck'],
+  fix: [':fix', '-fix', ':format'],
+};
+
+export type MatchReason = 'exact' | 'alias' | 'prefix-group' | 'suffix-group' | 'not-found';
+
 export interface VerbMapping {
   verb: Verb;
   nativeTask: string | null;
   runCommand: string | null;
+  reason: MatchReason;
+  /** Other candidate tasks that also matched but weren't chosen — useful for tuning. */
+  alternatives: string[];
+}
+
+export interface VerbMatch {
+  task: string | null;
+  reason: MatchReason;
+  alternatives: string[];
 }
 
 export interface InitPlan {
@@ -106,12 +178,74 @@ function pickPrefixGroup(prefixes: string[], tasks: Set<string>, verb: Verb): st
   return candidates[0] ?? null;
 }
 
-export function mapVerb(verb: Verb, tasks: Set<string>): string | null {
-  if (tasks.has(verb)) return verb;
-  for (const alt of VERB_ALIASES[verb]) {
-    if (tasks.has(alt)) return alt;
+function collectPrefixCandidates(prefixes: string[], tasks: Set<string>, verb: Verb): string[] {
+  if (prefixes.length === 0) return [];
+  const candidates: string[] = [];
+  for (const t of tasks) {
+    if (t === verb) continue;
+    for (const pfx of prefixes) {
+      if (t.startsWith(pfx)) {
+        candidates.push(t);
+        break;
+      }
+    }
+  }
+  return candidates;
+}
+
+function collectSuffixCandidates(suffixes: string[], tasks: Set<string>, verb: Verb): string[] {
+  if (suffixes.length === 0) return [];
+  const candidates: string[] = [];
+  for (const t of tasks) {
+    if (t === verb) continue;
+    for (const sfx of suffixes) {
+      if (t.endsWith(sfx)) {
+        candidates.push(t);
+        break;
+      }
+    }
   }
-  return pickPrefixGroup(VERB_PREFIX_GROUPS[verb], tasks, verb);
+  return candidates;
+}
+
+export function selectVerbTask(verb: Verb, tasks: Set<string>): VerbMatch {
+  // 1) exact match wins; siblings (aliases / prefix-group) reported as alternatives.
+  if (tasks.has(verb)) {
+    const alts = new Set<string>();
+    for (const a of VERB_ALIASES[verb]) if (tasks.has(a)) alts.add(a);
+    for (const c of collectPrefixCandidates(VERB_PREFIX_GROUPS[verb], tasks, verb)) alts.add(c);
+    return { task: verb, reason: 'exact', alternatives: [...alts].sort() };
+  }
+
+  // 2) alias hit (curated common alternates per stack).
+  const aliasHits = VERB_ALIASES[verb].filter((a) => tasks.has(a));
+  if (aliasHits.length > 0) {
+    const [chosen, ...rest] = aliasHits;
+    return { task: chosen!, reason: 'alias', alternatives: rest.slice().sort() };
+  }
+
+  // 3) prefix-group with canonical hint (prod/release/all preferred, then shortest).
+  const prefixCandidates = collectPrefixCandidates(VERB_PREFIX_GROUPS[verb], tasks, verb);
+  if (prefixCandidates.length > 0) {
+    const chosen = pickPrefixGroup(VERB_PREFIX_GROUPS[verb], tasks, verb)!;
+    const alts = prefixCandidates.filter((c) => c !== chosen).sort();
+    return { task: chosen, reason: 'prefix-group', alternatives: alts };
+  }
+
+  // 4) suffix-group (monorepo fallback: `server:test` -> verb 'test').
+  const suffixCandidates = collectSuffixCandidates(VERB_SUFFIX_GROUPS[verb], tasks, verb);
+  if (suffixCandidates.length > 0) {
+    suffixCandidates.sort((a, b) => a.length - b.length);
+    const [chosen, ...rest] = suffixCandidates;
+    return { task: chosen!, reason: 'suffix-group', alternatives: rest.slice().sort() };
+  }
+
+  return { task: null, reason: 'not-found', alternatives: [] };
+}
+
+/** Kept for back-compat with potential external callers; prefer `selectVerbTask`. */
+export function mapVerb(verb: Verb, tasks: Set<string>): string | null {
+  return selectVerbTask(verb, tasks).task;
 }
 
 function collectTools(ctx: Ctx): Record<string, string> {
@@ -179,6 +313,10 @@ export function renderMiseToml(
 
   for (const m of mappings) {
     if (!m.runCommand) continue;
+    if (m.reason !== 'exact' || m.alternatives.length > 0) {
+      const altPart = m.alternatives.length > 0 ? `; alt: ${m.alternatives.join(', ')}` : '';
+      out.push(`# vdx: matched "${m.nativeTask}" via ${m.reason}${altPart}`);
+    }
     out.push(`[tasks.${m.verb}]`);
     out.push(`description = ${quoteToml(VERB_DESCRIPTIONS[m.verb])}`);
     out.push(`run = ${quoteToml(m.runCommand)}`);
@@ -300,15 +438,21 @@ export function planInit(
   const tasks = listAllTasks(scanCtx);
 
   const mappings: VerbMapping[] = STANDARD_VERBS.map((verb) => {
-    const native = mapVerb(verb, tasks);
+    const sel = selectVerbTask(verb, tasks);
     let runCommand: string | null = null;
-    if (native) {
+    if (sel.task) {
       runCommand =
         primarySubpackage !== null
-          ? renderRunCommandInSubpackage(native, scanStack, scanRoot, primarySubpackage)
-          : renderRunCommand(native, stack, projectRoot);
+          ? renderRunCommandInSubpackage(sel.task, scanStack, scanRoot, primarySubpackage)
+          : renderRunCommand(sel.task, stack, projectRoot);
     }
-    return { verb, nativeTask: native, runCommand };
+    return {
+      verb,
+      nativeTask: sel.task,
+      runCommand,
+      reason: sel.reason,
+      alternatives: sel.alternatives,
+    };
   });
 
   // tools читаем из root независимо: для PHP/Node корневой manifest часто
@@ -387,19 +531,33 @@ export function renderPlanSummary(plan: InitPlan): string {
   lines.push('');
   lines.push('## Verb mappings');
   lines.push('');
-  lines.push('| Verb | Native task | Generated `run` |');
-  lines.push('|------|-------------|-----------------|');
+  lines.push('| Verb | Native task | Reason | Generated `run` |');
+  lines.push('|------|-------------|--------|-----------------|');
   for (const m of plan.mappings) {
     if (m.runCommand) {
-      lines.push(`| \`${m.verb}\` | \`${m.nativeTask}\` | \`${m.runCommand}\` |`);
+      lines.push(
+        `| \`${m.verb}\` | \`${m.nativeTask}\` | ${m.reason} | \`${m.runCommand}\` |`,
+      );
     } else {
-      lines.push(`| \`${m.verb}\` | _(not found)_ | _(skipped)_ |`);
+      lines.push(`| \`${m.verb}\` | _(not found)_ | not-found | _(skipped)_ |`);
     }
   }
   lines.push('');
+  const withAlts = plan.mappings.filter((m) => m.alternatives.length > 0);
+  if (withAlts.length > 0) {
+    lines.push('### Alternatives considered');
+    lines.push('');
+    for (const m of withAlts) {
+      const alts = m.alternatives.map((a) => `\`${a}\``).join(', ');
+      lines.push(
+        `- \`${m.verb}\` chose \`${m.nativeTask}\` (${m.reason}); also matched: ${alts}`,
+      );
+    }
+    lines.push('');
+  }
   const unmatched = plan.mappings.filter((m) => !m.runCommand).map((m) => m.verb);
   if (unmatched.length > 0) {
-    lines.push(`> Not mapped: ${unmatched.join(', ')}. Add тиски в \`mise.toml\` вручную.`);
+    lines.push(`> Not mapped: ${unmatched.join(', ')}. Добавь тиски в \`mise.toml\` вручную.`);
     lines.push('');
   }
   lines.push('## Generated mise.toml');

package/src/mcp-server.ts

@@ -156,7 +156,7 @@ function recordSuccessPath(input: {
 
   doc.vdx = doc.vdx ?? {
     schema_version: '0.2',
-    baseline: 'github.com/VoDmAl/vdx-rubric-vodmal@v0.2.1',
+    baseline: 'github.com/VoDmAl/vdx-rubric-vodmal@v0.3.1',
     stack: autoDetectStack(PROJECT_ROOT),
   };
   doc.vdx.verbs = input.verbs.map((v) => v.name);

package/src/publish.ts

@@ -0,0 +1,364 @@
+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';
+
+export type BumpKind = 'patch' | 'minor' | 'major';
+
+export interface PublishOptions {
+  projectRoot: string;
+  bump: BumpKind;
+  dryRun: boolean;
+  force: boolean;
+}
+
+export interface PreflightCheck {
+  name: string;
+  ok: boolean;
+  message: string;
+}
+
+export interface PublishPlan {
+  projectRoot: string;
+  stack: string;
+  packageName: string;
+  currentVersion: string;
+  newVersion: string;
+  bump: BumpKind;
+  packageJsonPath: string;
+  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)' };
+  }
+}
+
+function fetchPublishedVersion(packageName: string): string | null {
+  try {
+    const out = execFileSync('npm', ['view', packageName, 'version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return out.trim() || null;
+  } catch (e: any) {
+    const stderr = String(e?.stderr ?? e?.message ?? '');
+    if (stderr.includes('E404') || stderr.includes('404 Not Found')) return null;
+    throw new Error(`npm view failed: ${stderr.split('\n')[0] ?? 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,
+): 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 = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+  const packageName: string = pkg.name ?? '(unnamed)';
+  const currentVersion: string = 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.`,
+  });
+
+  let published: string | null = null;
+  let registryError: string | null = null;
+  try {
+    published = fetchPublishedVersion(packageName);
+  } catch (e: any) {
+    registryError = e?.message ?? String(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 preflightPassed = preflight.every((c) => c.ok);
+
+  return {
+    projectRoot: opts.projectRoot,
+    stack: ctx.stack,
+    packageName,
+    currentVersion,
+    newVersion,
+    bump: opts.bump,
+    packageJsonPath: pkgJsonPath,
+    preflight,
+    preflightPassed,
+    delegatedToMise: false,
+  };
+}
+
+/**
+ * Execute the publish pipeline. Order is transactional:
+ *   1. bump package.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.
+ *
+ * On npm publish failure → restore original package.json contents.
+ * Git failures after a successful npm publish leave the user in a
+ * partially-released state; they fix it manually (commit/tag what's
+ * needed) — we don't try to unpublish.
+ */
+export function executePublish(plan: PublishPlan): void {
+  if (plan.delegatedToMise) {
+    process.stderr.write('→ delegating to `mise run publish`...\n');
+    execFileSync('mise', ['run', 'publish'], {
+      cwd: plan.projectRoot,
+      stdio: 'inherit',
+    });
+    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`,
+  );
+
+  // 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);
+  try {
+    execFileSync('npm', ['publish'], { cwd: pkgDir, stdio: 'inherit' });
+  } catch (e: any) {
+    fs.writeFileSync(plan.packageJsonPath, originalText, 'utf8');
+    process.stderr.write(
+      `✗ npm publish failed (exit ${e?.status ?? '?'}); reverted package.json\n`,
+    );
+    throw new Error('npm publish failed');
+  }
+  process.stderr.write(`✓ published ${plan.packageName}@${plan.newVersion}\n`);
+
+  // 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`,
+  );
+}
+
+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('');
+  if (plan.preflightPassed) {
+    lines.push('## Pipeline (would execute on `vdx publish`)');
+    lines.push('');
+    lines.push(`1. Set \`version\` in package.json → \`${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(`4. \`git tag -a v${plan.newVersion} -m "v${plan.newVersion}"\``);
+    lines.push(`5. (NOT pushed — your call: \`git push --follow-tags\`)`);
+  } else {
+    lines.push('> Pre-flight failed. Use `--force` to bypass at your own risk.');
+  }
+  return lines.join('\n') + '\n';
+}