@vzn/vx-migrate 0.0.646 → 0.0.648

package/src/adopt.ts

@@ -2,7 +2,7 @@
 // which kind of adoption (native configs, or the runner's config read live),
 // and installing vx with the repo's own package manager (solidjs/solid,
 // 2026-10-04: the configs were written with no vx installed to run them).
-// The repo's own scripts are never edited (owner, 2026-10-06).
+// The repo's own scripts are never edited (2026-10-06).
 
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
@@ -63,6 +63,32 @@ export function packageManagerOf(root: string, userAgent?: string): PackageManag
   )
 }
 
+/**
+ * pnpm's `-w` where pnpm-workspace.yaml makes `root` a workspace: pnpm
+ * refuses it in a single-package repo ("--workspace-root may only be used
+ * inside a workspace").
+ */
+function pnpmRoot(root: string): string[] {
+  return existsSync(path.join(root, 'pnpm-workspace.yaml')) ? ['-w'] : []
+}
+
+/**
+ * Yarn 2+: its lockfile carries `__metadata`, and before the first install
+ * there is none, so `packageManager` names it (`-W` was refused there).
+ */
+function berry(root: string): boolean {
+  const lock = readText(path.join(root, 'yarn.lock'))
+  if (lock !== '') return lock.includes('__metadata:')
+  try {
+    const pm = (
+      JSON.parse(readText(path.join(root, 'package.json')) || '{}') as { packageManager?: unknown }
+    ).packageManager
+    return typeof pm === 'string' && /^yarn@([2-9]|\d{2,})/.test(pm)
+  } catch {
+    return false
+  }
+}
+
 /** argv that adds `packages` as root dev dependencies. */
 export function installArgv(
   root: string,
@@ -71,11 +97,11 @@ export function installArgv(
 ): string[] {
   switch (pm) {
     case 'pnpm':
-      return ['pnpm', 'add', '-D', '-w', ...packages]
+      return ['pnpm', 'add', '-D', ...pnpmRoot(root), ...packages]
     case 'yarn':
       // Yarn 1 refuses `add` at a workspace root without `-W`; Berry has no
-      // such flag. A Berry lockfile carries `__metadata`.
-      return readText(path.join(root, 'yarn.lock')).includes('__metadata:')
+      // such flag.
+      return berry(root)
         ? ['yarn', 'add', '-D', ...packages]
         : ['yarn', 'add', '-D', '-W', ...packages]
     case 'bun':
@@ -104,7 +130,7 @@ export function ownVersion(): string | null {
  * (at `version`, given one). Either alone is not adopted: a reset
  * package.json leaves node_modules behind, and a listing is not an
  * install; on solidjs/solid vx-migrate 0.0.512 skipped @vzn/vx that
- * package.json did not list (owner, 2026-10-06).
+ * package.json did not list (2026-10-06).
  */
 export function missingPackages(
   root: string,
@@ -129,11 +155,9 @@ export function removeArgv(
 ): string[] {
   switch (pm) {
     case 'pnpm':
-      return ['pnpm', 'remove', '-w', ...packages]
+      return ['pnpm', 'remove', ...pnpmRoot(root), ...packages]
     case 'yarn':
-      return readText(path.join(root, 'yarn.lock')).includes('__metadata:')
-        ? ['yarn', 'remove', ...packages]
-        : ['yarn', 'remove', '-W', ...packages]
+      return berry(root) ? ['yarn', 'remove', ...packages] : ['yarn', 'remove', '-W', ...packages]
     case 'bun':
       return ['bun', 'remove', ...packages]
     case 'npm':
@@ -156,7 +180,7 @@ export function listedPackages(root: string, packages: readonly string[]): strin
  * The `@vzn/vx-*` plugins the root lists from the registry (a `workspace:`
  * or `file:` link is the repo's own; a platform binary comes with core).
  * Every @vzn package releases together: an install moves them with core,
- * as `vx upgrade` does (M, 2026-10-16: "always install latest and upgrade all").
+ * as `vx upgrade` does (2026-10-16: "always install latest and upgrade all").
  */
 export function listedPlugins(root: string): string[] {
   const pj = JSON.parse(readText(path.join(root, 'package.json')) || '{}') as Record<
@@ -179,7 +203,7 @@ export function listedPlugins(root: string): string[] {
  * The `@vzn/vx*` packages a workspace file imports, parsed, not matched (a
  * formatter's quotes hid a match). Each is installed with core: a file an
  * earlier init wrote imports @vzn/vx-lockfile that package.json need not
- * list, and the lock could not find it (M, 2026-10-16).
+ * list, and the lock could not find it (2026-10-16).
  */
 export function importedPackages(text: string): string[] {
   const out = new Set<string>()
@@ -279,9 +303,26 @@ async function runManager(
   if (live) process.stdout.write('\r\x1b[2K\x1b[1A')
   if (code !== 0) {
     process.stderr.write(said)
+    const missing = notServed(said)
     throw new UserError(
-      `${what} failed (${line} exited ${code}${failed}); run it, then vx-migrate again${code > 0 ? ranHint : ''}`,
+      missing === undefined
+        ? `${what} failed (${line} exited ${code}${failed}); run it, then vx lock${code > 0 ? ranHint : ''}`
+        : `${what} failed: the npm registry does not serve ${missing} yet (404), as a release can take minutes to reach it; run vx init again`,
     )
   }
   return line
 }
+
+/**
+ * The package a manager's output says the registry answered 404 for, as
+ * `name@version` (core's `vx init` reads its installs the same way): a
+ * release's platform tarball stays unserved for minutes after publish.
+ */
+export function notServed(output: string): string | undefined {
+  for (const line of output.split('\n')) {
+    if (!line.includes('404')) continue
+    const m = /https?:\/\/\S+?\/((?:@[^/\s]+\/)?[^/\s]+)\/-\/[^/\s]+?-(\d[^/\s]*?)\.tgz/.exec(line)
+    if (m !== null) return `${decodeURIComponent(m[1]!)}@${m[2]}`
+  }
+  return undefined
+}

package/src/bin.ts

@@ -10,6 +10,7 @@
 // 2026-10-16).
 
 import path from 'node:path'
+import * as core from '@vzn/vx'
 import { isUserError, UserError, VERSION } from '@vzn/vx'
 import { ownVersion } from './adopt.js'
 
@@ -26,8 +27,27 @@ try {
   const { migrateCmd } = await import('./migrate.js')
   process.exitCode = await migrateCmd(process.argv.slice(2))
 } catch (err) {
+  // Asked for JSON (`vx init --dry --format json` hands a Turbo or Nx repo
+  // here), a refusal is core's error document on stdout too
+  // (schemas/error.json): stdout was empty.
+  const args = process.argv.slice(2)
+  if (args.some((a, i) => a === '--format=json' || (a === '--format' && args[i + 1] === 'json'))) {
+    const message = err instanceof Error ? err.message : String(err)
+    const own = isUserError(err) ? (err as { code?: unknown }).code : 'VX_E_INTERNAL'
+    const code = typeof own === 'string' ? own : 'VX_E_REFUSED'
+    const docs = code.startsWith('VX_E_')
+      ? { docs: `https://vznjs.github.io/vx/cli/#${code.toLowerCase()}` }
+      : {}
+    process.stdout.write(
+      `${JSON.stringify({ ok: false, error: { code, message: `vx-migrate: ${message}`, ...docs } })}\n`,
+    )
+  }
   if (isUserError(err)) {
-    process.stderr.write(`vx-migrate: ${err.message}\n`)
+    // `ui` by namespace: a core older than it has none, and its refusal
+    // still reaches the reader.
+    const ui = (core as Partial<typeof core>).ui
+    if (ui === undefined) process.stderr.write(`vx-migrate: ${err.message}\n`)
+    else ui.say('error', `vx-migrate: ${err.message}`)
     process.exitCode = 1
   } else {
     throw err

package/src/glob-grammar.ts

@@ -27,6 +27,51 @@ export function minimatchToVx(glob: string, negated: boolean): string | null {
   return out.includes('\0') || /[?@+*!]\(/.test(out) ? null : out
 }
 
+// A group no extglob kind opens and no backslash escapes.
+const BARE_GROUP = /(?<![\\?@+*!])\(([^()]*)\)/g
+
+/**
+ * An Nx glob's bare groups in vx's grammar, or null when one has no safe
+ * form. Nx's native glob reads `(a|b)` as `{a,b}` and `(a)` as `a`, so
+ * `dist/*.(js|map)` is the two extensions there; vx and minimatch read the
+ * parentheses as literal text, and the glob matched nothing. Turbo's
+ * grammar has no such group, so this is the Nx adapter's alone.
+ */
+export function nxBareGroups(glob: string): string | null {
+  if (!glob.includes('(')) return glob
+  let unsafe = false
+  const out = glob.replace(BARE_GROUP, (_whole, body: string) => {
+    const alts = body.split('|')
+    if (alts.some((a) => /[{},]/.test(a))) unsafe = true
+    return alts.length === 1 ? alts[0]! : `{${alts.join(',')}}`
+  })
+  return unsafe ? null : out
+}
+
+/** A segment (or brace arm) holding `**` and other text: `**.ts`, `a**`. */
+const glued = (seg: string): boolean => seg.includes('**') && /[^*]/.test(seg)
+
+/** Does `glob` glue `**` to other text, which core refuses? */
+export const hasGluedGlobstar = (glob: string): boolean =>
+  glob
+    .replace(/^!/, '')
+    .split(/[/{},]/)
+    .some(glued)
+
+/**
+ * A glued `**` as minimatch and Nx's matcher (globset, literal separator)
+ * read it: `*`, one level.
+ */
+export function gluedGlobstarAsStar(glob: string): string {
+  const neg = glob.startsWith('!') ? '!' : ''
+  return (
+    neg +
+    glob
+      .slice(neg.length)
+      .replace(/[^/{},]+/g, (seg) => (glued(seg) ? seg.replace(/\*{2,}/g, '*') : seg))
+  )
+}
+
 /**
  * `list` without a literal that one of its `!` entries takes back, and
  * without a repeat. Turbo, Nx and vx all subtract an exclusion wherever it
@@ -53,6 +98,43 @@ export function withoutTakenBack<T>(entries: readonly T[]): T[] {
   })
 }
 
+/**
+ * Could a path match both globs? False only when, before either reaches a
+ * wildcard, a segment of one differs from the other's; a literal also
+ * matches its directory's files, as a `!` entry takes them back.
+ */
+function mayOverlap(a: string, b: string): boolean {
+  const wild = /[*?{}[\]\\]/
+  const sa = a.replace(/^\.\//, '').split('/')
+  const sb = b.replace(/^\.\//, '').split('/')
+  for (let i = 0; i < Math.min(sa.length, sb.length); i++) {
+    if (wild.test(sa[i]!) || wild.test(sb[i]!)) return true
+    if (sa[i] !== sb[i]) return false
+  }
+  return true
+}
+
+/**
+ * Two lists core reads as one, each with its own `!` entries: Turbo
+ * subtracts a task's exclusions from the task's own inputs only, and a
+ * `globalDependencies` exclusion from the global hash only. One list in
+ * vx subtracts every `!` from every entry, so each list loses an exclusion
+ * that may reach a positive entry of the other: it keys more files (a
+ * missed hit), where kept it keyed fewer (a stale one).
+ */
+export function apartTakeBacks<T>(a: readonly T[], b: readonly T[]): [T[], T[]] {
+  const positives = (l: readonly T[]) =>
+    l.flatMap((e) => (typeof e === 'string' && !e.startsWith('!') ? [e] : []))
+  const keep = (l: readonly T[], other: readonly string[]) =>
+    l.filter(
+      (e) =>
+        typeof e !== 'string' ||
+        !e.startsWith('!') ||
+        !other.some((p) => mayOverlap(e.slice(1), p)),
+    )
+  return [keep(a, positives(b)), keep(b, positives(a))]
+}
+
 /**
  * A path from the file system as a task glob that names only itself: a dir
  * named `my{app}` read as a brace matched `myapp` instead, and `app/[id]` a

package/src/migrate-nx.ts

@@ -3,7 +3,12 @@
 
 import { stat } from 'node:fs/promises'
 import path from 'node:path'
-import { type GeneratedProject, type MigrationFormat, type MigrationPlan } from '@vzn/vx'
+import {
+  type GeneratedProject,
+  type MigrationFormat,
+  type MigrationPlan,
+  quoteTsLiteral,
+} from '@vzn/vx'
 import type { PackageMeta } from './packages.js'
 import { mapNxWorkspace, parseNxGraph, readNxJson } from './nx/nx-map.js'
 import { spareTrackedOutputs, trackedFiles, trackedKinds } from './tracked-outputs.js'
@@ -172,8 +177,6 @@ export interface NxWorkspaceField {
   readonly note: string
 }
 
-const quoted = (s: string) => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
-
 /**
  * nx.json's run-wide settings `nx()` applies live: each a field of the
  * written `.vx/workspace.ts`, or a migrated repo that ran one task at a time
@@ -202,7 +205,7 @@ export function nxWorkspaceFields(json: Record<string, unknown> | undefined): Nx
     const branch = base.trim().replace(/^origin\//, '')
     out.push({
       field: 'baseBranch',
-      source: quoted(branch),
+      source: quoteTsLiteral(branch),
       note: `nx.json \`defaultBase\` ${JSON.stringify(base.trim())}: add \`baseBranch: ${JSON.stringify(branch)}\` to .vx/workspace.ts`,
     })
   }

package/src/migrate-scripts.ts

@@ -39,6 +39,7 @@ import {
 } from '@vzn/vx'
 import type { PackageMeta } from './packages.js'
 import { relPosix } from './paths.js'
+import { type Owner, ownerOf, runsScriptHooks } from './script-command.js'
 
 /**
  * Task names that conventionally never exit. Every mapper guesses the same
@@ -128,19 +129,24 @@ const LIFECYCLE = /^(pre|post)(install|publish|pack|version)$|^(prepare|prepubli
 /**
  * The script a command delegates to when it is NOTHING but a package-manager
  * invocation of another script: `npm run x`, `pnpm x`, `yarn run x`, `bun run
- * x`, plus npm's bare `npm test` / `npm start`. Flags, arguments or a chain
- * make it a real command again, which is left verbatim.
+ * x`, plus npm's bare `npm test` / `npm start` / `npm stop`. npm's aliases
+ * (`run-script`, `rum`, `urn`; `t`, `tst`) and pnpm's (`run-script`; `t`,
+ * `tst`) are the same commands: read verbatim, `npm run-script build` built
+ * again beside the `build` task. Flags, arguments or a chain make it a real
+ * command again, which is left verbatim.
  */
 export function delegatedScript(command: string): string | null {
   const m =
-    /^(?:(?:npm run|(pnpm|pn|yarn|bun)(?: (run))?) ([^\s&|;<>()$`'"\\]+)|npm (test|start))$/.exec(
+    /^(?:(?:npm (?:run|run-script|rum|urn)|(pnpm|pn|yarn|bun)(?: (run|run-script))?) ([^\s&|;<>()$`'"\\]+)|npm (test|t|tst|start|stop))$/.exec(
       command.trim(),
     )
   if (m === null) return null
-  if (m[4] !== undefined) return m[4]
+  if (m[4] !== undefined) return m[4] === 't' || m[4] === 'tst' ? 'test' : m[4]
   const [, alias, run, name] = m
   // `pn` is pnpm's own short name (pnpm 11; pnpm/pnpm's scripts run it).
   const manager = alias === 'pn' ? 'pnpm' : alias
+  if (run === 'run-script' && manager !== 'pnpm') return null
+  if (manager === 'pnpm' && run === undefined && (name === 't' || name === 'tst')) return 'test'
   // Bare, the manager's own command wins over a script of that name:
   // `bun test` is Bun's test runner and `bun build` its bundler, never the
   // `test` / `build` script, and a group over the script ran the wrong
@@ -177,104 +183,6 @@ const OWN_COMMANDS: Readonly<Record<string, ReadonlySet<string>>> = {
   ),
 }
 
-/**
- * The package manager that owns `dir`, when it runs `pre` / `post` hooks
- * around a script; null when it runs none. The manager is the nearest `packageManager` field or
- * lockfile, and its settings are read beside it, as each reads them for a
- * member too. Probed with a `prebuild` / `build` / `postbuild` trio: Yarn
- * 2+ runs none (D-31); npm runs none under `ignore-scripts=true` in
- * `.npmrc`; pnpm runs none under `enable-pre-post-scripts=false` there or
- * `enablePrePostScripts: false` in `pnpm-workspace.yaml` (D-33); Bun and
- * Yarn 1 run them whatever those say. No manager found is npm's default.
- */
-function runsScriptHooks(dir: string, memo: Map<string, Owner>): string | null {
-  const { manager, at } = ownerOf(dir, memo)
-  const read = (f: string): string | undefined => {
-    try {
-      return readFileSync(path.join(at, f), 'utf8')
-    } catch {
-      return undefined
-    }
-  }
-  const npmrc = read('.npmrc') ?? ''
-  const set = (key: string, value: string): boolean =>
-    new RegExp(`^\\s*${key}\\s*=\\s*${value}\\s*$`, 'm').test(npmrc)
-  const runs =
-    manager === 'berry'
-      ? false
-      : manager === 'npm'
-        ? !set('ignore-scripts', 'true')
-        : manager === 'pnpm'
-          ? !set('enable-pre-post-scripts', 'false') && !pnpmSkipsHooks(read('pnpm-workspace.yaml'))
-          : true
-  return runs ? manager : null
-}
-
-/**
- * `enablePrePostScripts: false` in `pnpm-workspace.yaml`, read as pnpm reads
- * it, as YAML: a line regex missed `false # hooks off` and a flow mapping,
- * which pnpm 10 honours, and folded hooks pnpm does not run.
- */
-function pnpmSkipsHooks(yaml: string | undefined): boolean {
-  if (yaml === undefined) return false
-  try {
-    const parsed = Bun.YAML.parse(yaml) as { enablePrePostScripts?: unknown } | null
-    return parsed?.enablePrePostScripts === false
-  } catch {
-    return false
-  }
-}
-
-/** The package manager that owns a directory, and the directory that says so. */
-interface Owner {
-  manager: string
-  at: string
-}
-
-/**
- * The nearest `packageManager` field or lockfile from `dir` up: `berry` for
- * Yarn 2+, `yarn` for Yarn 1, else the manager's name; none found is npm.
- */
-function ownerOf(dir: string, memo: Map<string, Owner>): Owner {
-  const known = memo.get(dir)
-  if (known !== undefined) return known
-  const read = (f: string): string | undefined => {
-    try {
-      return readFileSync(path.join(dir, f), 'utf8')
-    } catch {
-      return undefined
-    }
-  }
-  let manager: string | undefined
-  try {
-    // A byte-order mark is stripped, as npm, pnpm and discovery strip it:
-    // JSON.parse threw on one and the field went unread.
-    const manifest = (read('package.json') ?? '').replace(/^\uFEFF/, '')
-    const pm = (JSON.parse(manifest) as { packageManager?: unknown }).packageManager
-    // A manager vx knows nothing of (zod's `nub@0.8.3`) says nothing about
-    // hooks: the lockfile beside it does, and "nub ran `postbuild`" was a
-    // claim nothing had checked (D-96).
-    if (typeof pm === 'string' && /^(npm|pnpm|yarn|bun)@/.test(pm))
-      manager = /^yarn@([2-9]|\d{2,})/.test(pm) ? 'berry' : pm.split('@')[0]
-  } catch {}
-  if (manager === undefined) {
-    const yarnLock = read('yarn.lock')
-    if (yarnLock !== undefined) manager = yarnLock.includes('\n__metadata:') ? 'berry' : 'yarn'
-    else if (existsSync(path.join(dir, 'pnpm-lock.yaml'))) manager = 'pnpm'
-    else if (existsSync(path.join(dir, 'package-lock.json'))) manager = 'npm'
-    else if (['bun.lock', 'bun.lockb'].some((f) => existsSync(path.join(dir, f)))) manager = 'bun'
-  }
-  const up = path.dirname(dir)
-  const owner =
-    manager !== undefined
-      ? { manager, at: dir }
-      : up === dir
-        ? { manager: 'npm', at: dir }
-        : ownerOf(up, memo)
-  memo.set(dir, owner)
-  return owner
-}
-
 /**
  * Yarn 2+ runs a script in its own shell, where `run <script>` is `yarn
  * run <script>`; vx's shell has no `run`, and 23 of berry's scripts

package/src/migrate.ts

@@ -3,7 +3,7 @@
 // existing Turbo or Nx setup (`--keep`: the workspace file that reads it
 // live instead), from Vite Task, or from package.json scripts, and vx
 // installed with the repo's manager. `vx init` hands every repo with a
-// package.json here (M, 2026-10-14: core reads no package.json).
+// package.json here (2026-10-14: core reads no package.json).
 // Without either mode flag a terminal is asked; anything else is native. Source auto-detect: turbo.json → Turbo;
 // .nx/workspace-data/project-graph.json, nx.json or a Lerna-on-Nx lerna.json → Nx (the resolved
 // graph, exported by nx if absent); `vite-plus` in the root package.json → Vite Task:
@@ -19,6 +19,7 @@ import path from 'node:path'
 import {
   applyMigration,
   findWorkspaceRoot,
+  isStarterConfig,
   isUserError,
   VERSION,
   type MigrationFormat,
@@ -101,8 +102,10 @@ export function parseMigrateArgs(args: readonly string[]): MigrateArgs {
     else if (a === '--no-install') out.noInstall = true
     else if (a === '--format' || a?.startsWith('--format=')) {
       const v = a === '--format' ? args[++i] : a.slice('--format='.length)
+      if (v === undefined || v === '')
+        return { ...out, error: '--format requires a value: pretty or json' }
       if (v !== 'json' && v !== 'pretty') {
-        return { ...out, error: `--format must be pretty or json (got ${v ?? 'nothing'})` }
+        return { ...out, error: `--format must be pretty or json (got ${v})` }
       }
       out.json = v === 'json'
     } else if (a === '--native' || a === '--keep') {
@@ -113,8 +116,10 @@ export function parseMigrateArgs(args: readonly string[]): MigrateArgs {
       out.mode = mode
     } else if (a === '--from' || a?.startsWith('--from=')) {
       const v = a === '--from' ? args[++i] : a.slice('--from='.length)
+      if (v === undefined || v === '')
+        return { ...out, error: '--from requires a value: turbo, nx, vite-task or scripts' }
       if (v !== 'turbo' && v !== 'nx' && v !== 'vite-task' && v !== 'scripts') {
-        return { ...out, error: '--from must be turbo, nx, vite-task or scripts' }
+        return { ...out, error: `--from must be turbo, nx, vite-task or scripts (got ${v})` }
       }
       out.from = v
     } else if (a === '--help' || a === '-h') return { ...out, help: true }
@@ -143,13 +148,11 @@ async function noRootReason(cwd: string, err: Error): Promise<Error> {
 export async function migrateCmd(args: readonly string[]): Promise<number> {
   const parsed = parseMigrateArgs(args)
   if (parsed.help) {
-    process.stdout.write(`${USAGE}\n`)
+    ui.say('info', USAGE, 'out')
     return 0
   }
-  if (parsed.error) {
-    process.stderr.write(`vx-migrate: ${parsed.error}\n`)
-    return 1
-  }
+  // Thrown, so the bin answers it as JSON too when that was asked.
+  if (parsed.error) throw new UserError(parsed.error, 'VX_E_USAGE')
   const reads: LoadReads = new Map()
   // An Nx repo with no package.json (Nx pinned in `.nx/installation`):
   // nothing is installable, so its configs run on core alone.
@@ -162,7 +165,13 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
   })
   const workspace = bare ? { root, packageGlobs: [] } : await loadPackageWorkspace(root, reads)
   const nameless: string[] = []
-  const metas = bare ? [] : await discoverPackages(workspace, nameless)
+  // `vx init`'s starter at the root holds no task: mapped as if absent, so
+  // the root's own scripts become its tasks.
+  const metas = bare
+    ? []
+    : (await discoverPackages(workspace, nameless)).filter(
+        (m) => !(m.dir === root && m.configPath !== null && isStarterConfig(m.configPath)),
+      )
 
   const turboFile = await turboConfigFile(root)
   const hasTurbo = turboFile !== null
@@ -357,7 +366,7 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
   // adoption's install of it is dropped with turbo() / nx().
   const finalWorkspace = workspaceText ?? readFileSync(path.join(root, existingWorkspace!), 'utf8')
   // Imports parsed, not matched: a formatter's double quotes hid it, and
-  // the file still imported the package removed (owner, 2026-10-16).
+  // the file still imported the package removed (2026-10-16).
   const imported = importedPackages(finalWorkspace)
   const needsSelf = runsBins || imported.includes('@vzn/vx-migrate')
   const cacheNote =
@@ -385,7 +394,7 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
             needsSelf ? [] : ['@vzn/vx-migrate'],
           )),
         ]
-  return applyMigration({
+  const code = await applyMigration({
     root,
     metas,
     plan,
@@ -400,6 +409,7 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
     // The written workspace file imports plugins `--no-install` left out.
     ...(parsed.noInstall === true ? {} : { lock: lockWorkspace }),
   })
+  return exitAfter(code, steps)
 }
 
 /**
@@ -417,8 +427,10 @@ async function lockWorkspace(root: string): Promise<{ code: number; said: string
     p.exited,
   ])
   // A success's warnings print above the report; a refusal is said whole.
+  // A success is a report row, matched as text: the colour FORCE_COLOR
+  // gave the child would hide its `✓ vx lock` mark from that match.
   if (code === 0) process.stderr.write(err)
-  return { code, said: code === 0 ? out : out + err }
+  return { code, said: code === 0 ? Bun.stripANSI(out) : out + err }
 }
 
 /** A report row: what the tool did, e.g. `['ran', 'bun add -d …']`. */
@@ -499,17 +511,36 @@ async function prepareRepo(
   const missing = missingPackages(root, all, version)
   if (missing.length > 0) {
     steps.push(
-      args.dry ? ['install', missing.join(' ')] : ['ran', await install(root, missing, version)],
+      args.dry ? ['install', missing.join(' ')] : await ran(() => install(root, missing, version)),
     )
   }
   // Last: the package removed may be the one running this.
   const listed = listedPackages(root, unwanted)
   if (listed.length > 0) {
-    steps.push(args.dry ? ['remove', listed.join(' ')] : ['ran', await uninstall(root, listed)])
+    steps.push(args.dry ? ['remove', listed.join(' ')] : await ran(() => uninstall(root, listed)))
   }
   return steps
 }
 
+/**
+ * A manager step's row. Its failure is a `failed` row, not the end of the
+ * migration: the configs are still written and the report names what to
+ * re-run, where a throw left a repo with neither.
+ */
+async function ran(step: () => Promise<string>): Promise<Step> {
+  try {
+    return ['ran', await step()]
+  } catch (e) {
+    if (!isUserError(e)) throw e
+    return ['failed', e.message]
+  }
+}
+
+/** The exit a migration ends with: 1 when a manager step failed, whatever the rest did. */
+function exitAfter(code: number, steps: readonly Step[]): number {
+  return code === 0 && steps.some(([label]) => label === 'failed') ? 1 : code
+}
+
 /**
  * `--keep`: `.vx/workspace.ts` declaring `turbo()` or `nx()`, so the
  * runner's own config stays the source, beside the plugins the repo calls
@@ -553,7 +584,7 @@ async function keep(
     args,
   )
   if (args.json)
-    for (const [label, value] of steps) process.stderr.write(`vx-migrate: ${label}: ${value}\n`)
+    for (const [label, value] of steps) ui.say('info', `vx-migrate: ${label}: ${value}`)
   const ignore = existsSync(path.join(root, '.vx', '.gitignore')) ? [] : ['.vx/.gitignore']
   if (!args.dry) {
     if (before === undefined) {
@@ -602,7 +633,7 @@ async function keep(
     )
     return 0
   }
-  if (args.dry && before === undefined) process.stdout.write(`── ${name} ──\n${text}\n`)
+  if (args.dry && before === undefined) ui.print('out', ui.excerpt(name, text))
   // A run reads only the lock; with the plugins installed it is written
   // now, else `next` names `vx lock` after the install.
   const lock = !args.dry && !next.includes(' lock && ') ? await lockWorkspace(root) : undefined
@@ -625,7 +656,7 @@ async function keep(
     ],
   ]
   ui.print('out', ui.report(`vx-migrate ${VERSION}`, rows))
-  return lock?.code ?? 0
+  return exitAfter(lock?.code ?? 0, steps)
 }
 
 /** `vx lock`'s outcome as the report's row. */
@@ -658,7 +689,7 @@ export function adoptionNext(
     (p) => !existsSync(path.join(root, 'node_modules', p, 'package.json')),
   )
   // `vx init` installs vx globally first: vx alone, never a package
-  // manager's runner (owner, 2026-10-22: vx owns the command).
+  // manager's runner (2026-10-22: vx owns the command).
   const run = `vx run ${firstTask(path.join(root, source), runner)} --all`
   if (missing.length === 0) return run
   const pinned = version === null ? missing : missing.map((p) => `${p}@${version}`)
@@ -687,7 +718,7 @@ function firstTask(file: string, runner: 'turbo' | 'nx'): string {
 /**
  * package.json scripts → one vx.config.ts per package, and the workspace
  * file declaring the lockfile plugin its lockfile calls for: `vx init`'s
- * mapper until core stopped reading package.json (M, 2026-10-14).
+ * mapper until core stopped reading package.json (2026-10-14).
  */
 async function scripts(
   root: string,
@@ -725,12 +756,8 @@ async function scripts(
           `the workspace globs (${globs.map((g) => `"${g}"`).join(', ')}) match no package.json: add a package under one, or fix the glob`,
         ]
       : []
-  const installed = await prepareRepo(
-    root,
-    plugins.map((p) => p.pkg),
-    args,
-  )
-  return applyMigration({
+  const installed = await prepareRepo(root, [...new Set(plugins.map((p) => p.pkg))], args)
+  const code = await applyMigration({
     root,
     metas,
     plan,
@@ -748,6 +775,7 @@ async function scripts(
     plugins,
     ...(args.noInstall === true ? {} : { lock: lockWorkspace }),
   })
+  return exitAfter(code, installed)
 }
 
 /**