@vzn/vx 0.0.636 → 0.0.638

package/src/workspace/migration.ts

@@ -1,16 +1,16 @@
 // The migration seam: what any adoption tool needs once it has a plan —
 // the plan's shape, TS emission, the overwrite guard, the writes and the
-// report. `vx init` (package.json scripts, in core) and `@vzn/vx-migrate`
-// (Turbo, Nx) share it, so a generated config reads the same whichever
-// tool wrote it. Core knows no source format here: a mapper returns a
+// report. `@vzn/vx-migrate` (package.json scripts, Turbo, Nx) and any
+// other adoption tool share it, so a generated config reads the same
+// whichever tool wrote it. Core knows no source format here: a mapper returns a
 // `MigrationPlan` and this file does the rest.
 
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { unlink } from 'node:fs/promises'
 import path from 'node:path'
-import { executablePath, relPosix, UserError } from '../util/index.js'
-import type { ProjectMeta } from './workspace.js'
-import { loadWorkspace, reachesManifest, unreachedHint, unreachedPackages } from './workspace.js'
+import { workspaceFileWritten } from '../handoff.js'
+import { DOT_VX_GITIGNORE, executablePath, gitEnv, relPosix, UserError, ui } from '../util/index.js'
+import { VERSION } from '../version.js'
 import { WORKSPACE_CONFIG_FILENAMES } from './project-loader.js'
 
 /**
@@ -29,19 +29,6 @@ export function quoteTsLiteral(s: string): string {
     .replaceAll('\r', '\\r')}'`
 }
 
-/**
- * Task names that conventionally never exit. Every mapper guesses the same
- * way from a name — a source that SAYS a task is long-running (turbo's
- * `persistent: true`, an Nx dev-server executor) is believed instead.
- */
-export const PERSISTENT_TASK_NAMES: ReadonlySet<string> = new Set([
-  'dev',
-  'start',
-  'serve',
-  'watch',
-  'preview',
-])
-
 /**
  * A package.json script with the `pre<name>` / `post<name>` hooks npm runs
  * around it, as ONE sh command. Each part runs in its own subshell, so a
@@ -80,73 +67,6 @@ const QUOTE_ARGS =
   `vx_r="$vx_r\${vx_s%%"$vx_q"*}'\\''"; vx_s=\${vx_s#*"$vx_q"};; *) break;; esac; done; ` +
   `vx_a="$vx_a '$vx_r$vx_s'"; done`
 
-/**
- * Where a framework's build writes by default, for the cache TODO: the
- * hint said `dist/**` to every build, `next build` included, which writes
- * `.next`. Each tool's documented default; anything else keeps `dist/**`.
- */
-const BUILD_OUTPUTS: readonly [RegExp, readonly string[]][] = [
-  [/\snext build\s/, ['.next/**', '!.next/cache/**']],
-  [/\snux[ti] build\s/, ['.output/**']],
-  [/\s(?:remix|react-router|react-scripts|docusaurus) build\s/, ['build/**']],
-  [/\sgatsby build\s/, ['public/**']],
-  [/\s(?:storybook build|build-storybook)\s/, ['storybook-static/**']],
-]
-
-/** A directory a TODO may name: relative, plain, no hidden or tool dir. */
-const OUTPUT_DIR = /^(?:\.\/)?((?![./])[\w@-][\w@./-]*?)\/?$/
-
-/**
- * The directory the command says it writes, when no tool above names one:
- * an out-dir flag (`tsc --outDir lib`, `babel -d lib`), else the
- * directories it cleans first (`del-cli distribution`, `rimraf dist
- * types`). ky's build writes `distribution/`, and the TODO said `dist/**`
- * (D-90). A file (`tsconfig.tsbuildinfo`) and `node_modules` are no output.
- */
-function namedOutputs(command: string): string[] | undefined {
-  const dir = (w: string | undefined): string | undefined => {
-    const m = w === undefined ? null : OUTPUT_DIR.exec(w.replace(/^(["'])(.*)\1$/, '$2'))
-    if (m === null) return undefined
-    const d = m[1]!
-    return /\.[a-z]+$/i.test(d) || d.split('/').includes('node_modules') ? undefined : d
-  }
-  const flag = /\s(?:--outDir|--out-dir|--outdir|-d)[\s=](\S+)/.exec(` ${command} `)
-  const out = dir(flag?.[1])
-  if (out !== undefined) return [`${out}/**`]
-  for (const segment of command.split(/[;&|()]+/)) {
-    const words = segment.trim().split(/\s+/)
-    const at =
-      words[0] === 'rimraf' || words[0] === 'del-cli' || words[0] === 'del'
-        ? 1
-        : words[0] === 'rm' || (words[0] === 'shx' && words[1] === 'rm')
-          ? words.indexOf('rm') + 1
-          : -1
-    if (at < 0) continue
-    const args = words.slice(at).filter((w) => !w.startsWith('-'))
-    // A dir the command makes again (kit's `rm -rf ./missing_ids && mkdir
-    // ./missing_ids && vite build`) is a scratch dir it prepares, not output.
-    const made = new Set([...command.matchAll(/\bmkdir\s+(?:-p\s+)?(\S+)/g)].map((m) => dir(m[1])))
-    const dirs = args
-      .map(dir)
-      .filter((d): d is string => d !== undefined)
-      .filter((d) => !made.has(d))
-    // Every cleaned path a directory vx can name, or the guess is not this.
-    return dirs.length > 0 && dirs.length === args.filter((w) => !/\.[a-z]+$/i.test(w)).length
-      ? dirs.map((d) => `${d}/**`)
-      : undefined
-  }
-  return undefined
-}
-
-/** The cache block the task that builds `command` should declare, as a TODO on it. */
-export function cacheTodo(command: string): string {
-  // Padded, separators as spaces: `next build && …` and `(next build)` match.
-  const words = ` ${command.replace(/[;&|()]/g, ' ')} `
-  const hit = BUILD_OUTPUTS.find(([re]) => re.test(words))
-  const outputs = (hit?.[1] ?? namedOutputs(command) ?? ['dist/**']).map((o) => `'${o}'`).join(', ')
-  return `cache: add \`cache: { inputs: { files: ['src/**'] }, outputs: { files: [${outputs}] } }\` with this package's real inputs and outputs — without it the task always runs and every file here, what it writes included, folds into the key its dependents fold; a block with EMPTY outputs would be a cached no-op, not an uncached task`
-}
-
 const isCacheTodo = (todo: string): boolean => todo.startsWith('cache: add `cache: {')
 
 /** The one wording every mapper emits for a task it made persistent. */
@@ -217,6 +137,8 @@ export interface GeneratedProject {
   importLines: string[]
   /** The project's `tags` (an Nx project's); none written when empty. */
   tags?: readonly string[]
+  /** Writes `name`: no manifest names the project, so its path would. */
+  writeName?: boolean
   tasks: GeneratedTask[]
 }
 
@@ -230,9 +152,21 @@ export interface MigrationPlan {
   notes: string[]
 }
 
+/**
+ * A project the adoption tool found: its name, directory and the vx config
+ * it already has. `packageJson.type` picks `vx.config.mts` for a CommonJS
+ * TypeScript package.
+ */
+export interface MigrationMember {
+  readonly name: string
+  readonly dir: string
+  readonly configPath: string | null
+  readonly packageJson?: object
+}
+
 export interface ApplyMigrationArgs {
   root: string
-  metas: readonly ProjectMeta[]
+  metas: readonly MigrationMember[]
   plan: MigrationPlan
   /** Named in the report and the generated header, e.g. `turbo.json`. */
   source: string
@@ -241,12 +175,12 @@ export interface ApplyMigrationArgs {
   dry: boolean
   force: boolean
   /**
-   * `vx init` on a workspace with no scripts still has a job (the workspace
-   * file, and a worked example); a migration with nothing to convert is an
-   * error. Default false.
+   * A scripts migration (what `vx init` hands over) on a workspace with no
+   * scripts still has a job (the workspace file, and a worked example); a
+   * migration with nothing to convert is an error. Default false.
    */
   init?: boolean
-  /** Report lines printed under the source line (e.g. "turbo.json found and not read"). */
+  /** The report's `note` lines (e.g. "turbo.json found and not read"). */
   notes?: readonly string[]
   /**
    * Scripts exist but no project can carry them (a member without a
@@ -254,6 +188,11 @@ export interface ApplyMigrationArgs {
    * of them (M-59).
    */
   unmapped?: boolean
+  /**
+   * Why an `init` plan is empty, when the tool knows (members its globs
+   * never reach): the report's one line in place of the example config.
+   */
+  emptyReason?: string
   /**
    * `ts` (default) writes `vx.config.ts` with the type-only import and
    * `satisfies`; `mjs` writes `vx.config.mjs` — the same object, untyped —
@@ -266,6 +205,24 @@ export interface ApplyMigrationArgs {
    * of the files and the report, so an agent reads the plan as data.
    */
   json?: boolean
+  /**
+   * Run after the files are written (not under `dry`): `vx lock`'s step, so
+   * the migrated workspace has its .vx/projects.lock.json and its graph rules checked
+   * (owner, 2026-10-14). On success `said` is its line, shown as the
+   * report's `lock` row; a refusal (a graph rule, a plugin not installed
+   * yet) prints above the report and the migration still succeeds: its
+   * files are written, and `vx lock` is the step to re-run.
+   */
+  lock?: (root: string) => Promise<{ code: number; said: string }>
+  /** Rows of what the tool did before the write, e.g. `['ran', 'bun add -d …']`. */
+  steps?: readonly (readonly [label: string, value: string])[]
+  /** What the written workspace file declares, e.g. `pnpm()` from `@vzn/vx-lockfile`. */
+  plugins?: readonly WorkspacePlugin[]
+}
+
+export interface WorkspacePlugin {
+  readonly pkg: string
+  readonly factory: string
 }
 
 export type MigrationFormat = 'ts' | 'mjs'
@@ -279,15 +236,25 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   const init = args.init === true
   const format: MigrationFormat = args.format ?? 'ts'
   const configName = `vx.config.${format}`
-  const workspaceName = `vx.workspace.${format}`
+  const workspaceName = `.vx/workspace.${format}`
   const empty = plan.projects.length === 0
-  // `vx init` never overwrites a member's config: a half-adopted workspace
+  // An `init` migration never overwrites a member's config: a half-adopted workspace
   // keeps each one it has, by name, and gets the rest (M-52). It refused
   // the whole workspace, and `--force` would have replaced the hand-written
   // file; `--force` still replaces, as asked.
   const kept: string[] = []
-  const projects = plan.projects.filter((p) => {
-    if (!init || force || p.tasks.length === 0) return true
+  // Every project gets a config, a task-less one too (owner, 2026-10-14:
+  // "no skips. every project gets a config"): solidjs/solid's solid-ssr,
+  // with no script Turbo runs, was left with none and read as a project
+  // whose tasks are not locked.
+  const planned = new Set(plan.projects.map((p) => p.dir))
+  const unplanned: GeneratedProject[] = metas
+    .filter((m) => !planned.has(m.dir))
+    .map((m) => ({ name: m.name, dir: m.dir, importLines: [], tasks: [] }))
+  const projects = [...plan.projects, ...unplanned].filter((p) => {
+    // An empty config never replaces one a project has, --force or not.
+    if (p.tasks.length === 0) return !metas.some((m) => m.dir === p.dir && m.configPath)
+    if (!init || force) return true
     const existing = metas.find((m) => m.dir === p.dir)?.configPath
     if (!existing) return true
     kept.push(relPosix(root, existing))
@@ -305,14 +272,14 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     )
   }
 
+  const names = new Map(projects.map((p) => [p.dir, projectConfigName(p.dir, metas, format)]))
   const files: { relPath: string; abs: string; contents: string }[] = []
   for (const p of projects) {
-    if (p.tasks.length === 0) continue
-    const abs = path.join(p.dir, configName)
+    const abs = path.join(p.dir, names.get(p.dir)!)
     files.push({
       relPath: relPosix(root, abs),
       abs,
-      contents: renderConfigFile(p, format),
+      contents: renderConfigFile(ownConfigNamed(p, names.get(p.dir)!, format), format),
     })
   }
   for (const f of plan.extraFiles) {
@@ -328,7 +295,17 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   // A plan may bring its own (vx-migrate declares the plugins it detects).
   if (!hasWorkspaceFile && !plan.extraFiles.some((f) => f.relPath === workspaceName)) {
     const abs = path.join(root, workspaceName)
-    files.push({ relPath: relPosix(root, abs), abs, contents: workspaceFile(format) })
+    files.push({
+      relPath: relPosix(root, abs),
+      abs,
+      contents: workspaceFile(format, args.plugins ?? []),
+    })
+  }
+  // `.vx/.gitignore` keeps the machine-local `.vx/cache` out of git and the
+  // workspace config and lock in; one already there is the user's.
+  const dotVxIgnore = path.join(root, '.vx', '.gitignore')
+  if (!(await Bun.file(dotVxIgnore).exists())) {
+    files.push({ relPath: '.vx/.gitignore', abs: dotVxIgnore, contents: DOT_VX_GITIGNORE })
   }
 
   if (!dry && !force) {
@@ -336,7 +313,6 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     // A discovered project with ANY existing vx config (.ts/.mjs/.js) — refuse
     // so we never shadow a hand-written config with a fresh .ts.
     for (const p of projects) {
-      if (p.tasks.length === 0) continue
       const meta = metas.find((m) => m.dir === p.dir)
       if (meta?.configPath) conflicts.add(relPosix(root, meta.configPath))
     }
@@ -361,9 +337,8 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   // (item 1033).
   const replaced: string[] = []
   for (const p of projects) {
-    if (p.tasks.length === 0) continue
     const existing = metas.find((m) => m.dir === p.dir)?.configPath
-    if (existing && existing !== path.join(p.dir, configName)) replaced.push(existing)
+    if (existing && existing !== path.join(p.dir, names.get(p.dir)!)) replaced.push(existing)
   }
   if (dry && args.json !== true) {
     for (const f of files) {
@@ -372,7 +347,16 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   } else if (!dry) {
     for (const f of files) await Bun.write(f.abs, f.contents)
     for (const f of replaced) await unlink(f)
+    // The lock that follows loads its plugins from the file just written.
+    workspaceFileWritten()
   }
+  const formatted = dry
+    ? []
+    : formatWritten(
+        root,
+        // A formatter has no parser for `.vx/.gitignore`.
+        files.map((f) => f.relPath).filter((f) => /\.[cm]?[jt]s$/.test(f)),
+      )
 
   // One reason, its tasks: on a Turbo template the same two-line cache TODO
   // printed five times and the persistent one eight (the first-five-minutes
@@ -383,120 +367,44 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     root,
     files.map((f) => f.relPath),
   )
-  const ignoredNote =
-    ignored.length === 0
-      ? []
-      : [
-          `.gitignore drops ${ignored.length} file${ignored.length === 1 ? '' : 's'} this ${dry ? 'would write' : 'wrote'} (${ignored.slice(0, TODO_IDS_SHOWN).join(', ')}${ignored.length > TODO_IDS_SHOWN ? ', …' : ''}): add ${[...new Set(ignored.map((f) => `!${path.posix.basename(f)}`))].join(' and ')} to .gitignore, or commit them with git add -f`,
-        ]
+  const ignoredNote = ignored.length === 0 ? [] : [ignoreAdvice(root, ignored, dry)]
   const todos = new Map<string, string[]>()
-  let todoCount = 0
   let clean = 0
-  let cached = false
+  let todo = 0
   for (const p of projects) {
     for (const t of p.tasks) {
       if (t.todos.length === 0 && t.task !== null) clean++
-      if (t.task !== null && 'cache' in t.task) cached = true
+      if (t.todos.length > 0) todo++
       for (const reason of t.todos) {
-        todoCount++
         const ids = todos.get(reason) ?? []
         ids.push(`${p.name}#${t.name}`)
         todos.set(reason, ids)
       }
     }
   }
-  const report: string[] = []
-  // Single-project mode with packages the root's missing `workspaces` never
-  // reaches: the scripts exist, the globs do not (item 248).
-  const workspace = empty ? await loadWorkspace(root) : undefined
-  const unreached = workspace === undefined ? [] : await unreachedPackages(workspace)
-  // Globs that reach no package: "no scripts" was true and named nothing
-  // to fix (M-42).
-  const globs = workspace?.packageGlobs.filter((g) => g !== '.') ?? []
-  // Asked of the globs, not of `metas`: a nameless or shared-name member
-  // is matched yet absent from `metas` (M-46).
-  const noMembers =
-    workspace !== undefined && globs.length > 0 && !(await reachesManifest(workspace))
-      ? [
-          `the workspace globs (${globs.map((g) => `"${g}"`).join(', ')}) match no package.json: add a package under one, or fix the glob`,
-        ]
-      : []
-  if (empty && unreached.length > 0) {
-    report.push(
-      `${verb}: ${unreachedHint(unreached, root)}`,
-      hasWorkspaceFile
-        ? `${workspaceName} already exists.`
-        : dry
-          ? `would write ${workspaceName} (dry run, nothing written).`
-          : `wrote ${workspaceName}.`,
-    )
-  } else if (empty) {
-    report.push(
-      args.unmapped === true
-        ? `${verb}: no package.json scripts became tasks.`
-        : `${verb}: no package.json scripts to turn into tasks.`,
-      ...[...noMembers, ...(args.notes ?? []), ...ignoredNote].map((n) => `note: ${n}`),
-      hasWorkspaceFile
-        ? `${workspaceName} already exists.`
-        : dry
-          ? `would write ${workspaceName} (dry run, nothing written).`
-          : `wrote ${workspaceName}.`,
-      `Declare tasks in a ${configName} beside a package.json — your own command, for example:`,
-      '',
-      ...exampleConfig(format)
-        .trimEnd()
-        .split('\n')
-        .map((l) => `  ${l}`),
-    )
-  } else {
-    report.push(`${verb}: ${source} → ${configName}`)
-    for (const n of [...(args.notes ?? []), ...ignoredNote]) report.push(`note: ${n}`)
-    for (const n of plan.headerNotes) report.push(`note: ${n}`)
-    report.push(
-      '',
-      `${clean} task${clean === 1 ? '' : 's'} migrated clean, ` +
-        `${todoCount} TODO${todoCount === 1 ? '' : 's'}${todoCount > 0 ? ':' : ''}`,
-    )
-    for (const [reason, ids] of todos) {
-      if (ids.length === 1) report.push(`  ${ids[0]}: ${reason}`)
-      else {
-        const shown = ids.slice(0, TODO_IDS_SHOWN).join(', ')
-        const more = ids.length - TODO_IDS_SHOWN
-        report.push(`  ${shown}${more > 0 ? ` and ${more} more` : ''}:`, `    ${reason}`)
-      }
-    }
-    report.push(...plan.notes)
-    if (files.length === 0) report.push(dry ? 'no files (dry run)' : 'no files written')
-    else report.push(dry ? 'files (dry run, nothing written):' : 'files written:')
-    for (const f of files) report.push(`  ${f.relPath}`)
-    if (kept.length > 0) {
-      report.push('kept (each already has a vx config):')
-      for (const f of kept) report.push(`  ${f}`)
-    }
-    if (replaced.length > 0) {
-      report.push(dry ? 'would replace (dry run):' : 'replaced:')
-      for (const f of replaced) report.push(`  ${relPosix(root, f)}`)
-    }
-  }
   const firstTask = nextTask(plan.projects.flatMap((p) => p.tasks))
-  // A run of tasks none of which caches is never a hit, and a first try
-  // that runs twice to see the cache work saw it run twice.
-  if (!cached && [...todos.keys()].some(isCacheTodo)) {
-    report.push(
-      '',
-      'no task caches yet: uncomment the cache line in each TODO task with its real globs, and a second run hits',
-    )
-  }
   const installed = existsSync(path.join(root, 'node_modules', '@vzn', 'vx', 'package.json'))
   // The line is the next thing to type, so it names what that run would
   // refuse without: a git work tree (vx keys inputs on git's view) and,
   // with no scripts mapped, a task to run.
-  const run = `${vxInvocation(process.env['npm_config_user_agent'], installed)} run ${firstTask} --all`
+  const vx = vxInvocation(process.env['npm_config_user_agent'], installed)
+  const run = `${vx} run ${firstTask} --all`
+  // A run reads configs only from the lock; with no lock step here
+  // (`--no-install`), that run stopped with "no lock: run `vx lock`".
   const steps = [
     ...(inGitWorkTree(root) ? [] : ['git init']),
     ...(empty ? [`declare a task as the example shows`] : []),
+    ...(!dry && args.lock === undefined ? [`${vx} lock`] : []),
   ]
   const next = steps.length === 0 ? run : `${steps.join(', ')}, then ${run}`
+  const emptyReason = empty ? args.emptyReason : undefined
+  const notes = [
+    ...(args.notes ?? []),
+    ...ignoredNote,
+    ...formatted,
+    ...plan.headerNotes,
+    ...plan.notes,
+  ]
   if (args.json === true) {
     process.stdout.write(
       `${JSON.stringify({
@@ -507,29 +415,117 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
         replaced: replaced.map((f) => relPosix(root, f)),
         todos: [...todos].map(([reason, tasks]) => ({ reason, tasks })),
         notes: [
-          ...(empty && unreached.length > 0 ? [unreachedHint(unreached, root)] : []),
-          ...(empty ? noMembers : []),
-          ...(args.notes ?? []),
-          ...ignoredNote,
-          ...plan.headerNotes,
-          ...plan.notes,
+          ...(emptyReason === undefined ? [] : [emptyReason]),
+          ...(args.steps ?? []).map(([label, value]) => `${label}: ${value}`),
+          ...notes,
         ],
         next,
       })}\n`,
     )
     return 0
   }
-  report.push('', `next: ${next}`)
-  process.stdout.write(`${report.join('\n')}\n`)
+
+  // The lock's own words become a row; a refusal prints above the report.
+  const lock = dry || args.lock === undefined ? undefined : await args.lock(root)
+  if (lock !== undefined && lock.code !== 0) process.stderr.write(lock.said)
+
+  const rows: ui.FieldRow[] = [['from', source]]
+  if (dry) rows.push(['dry run', 'nothing written'])
+  for (const [label, value] of args.steps ?? []) rows.push([label, value])
+  if (empty) {
+    const why =
+      emptyReason ??
+      (args.unmapped === true
+        ? 'no package.json script became a task'
+        : 'no package.json scripts to turn into tasks')
+    rows.push(['tasks', [ui.dim('none'), `: ${why}`]])
+  } else {
+    const parts = [
+      ...(clean > 0 ? [ui.tone('ok', `${clean} clean`)] : []),
+      ...(todo > 0 ? [ui.tone('warn', `${todo} todo`)] : []),
+    ]
+    if (parts.length > 0)
+      rows.push(['tasks', parts.flatMap((p, i) => (i === 0 ? [p] : [ui.dim(' · '), p]))])
+    const todoLines: string[] = []
+    for (const [reason, ids] of todos) {
+      if (ids.length === 1) todoLines.push(`${ids[0]}: ${reason}`)
+      else {
+        const shown = ids.slice(0, TODO_IDS_SHOWN).join(', ')
+        const more = ids.length - TODO_IDS_SHOWN
+        todoLines.push(`${shown}${more > 0 ? ` and ${more} more` : ''}:`, `  ${reason}`)
+      }
+    }
+    if (todoLines.length > 0) rows.push(['todo', ...todoLines])
+  }
+  if (files.length > 0) rows.push(['files', ...fileLines(files.map((f) => f.relPath))])
+  const keptLines = [
+    ...kept.map((f) => `${f} (has a vx config)`),
+    ...(empty && hasWorkspaceFile ? [workspaceName] : []),
+  ]
+  if (keptLines.length > 0) rows.push(['kept', ...keptLines])
+  if (replaced.length > 0) rows.push(['replaced', ...replaced.map((f) => relPosix(root, f))])
+  if (lock !== undefined) {
+    rows.push([
+      'lock',
+      lock.code === 0
+        ? lock.said.trim().replace(/^✓ vx lock\s+/, '')
+        : ui.tone('error', 'not written'),
+    ])
+  }
+  if (notes.length > 0) rows.push(['note', ...notes])
+  if (empty && emptyReason === undefined) {
+    rows.push([
+      'example',
+      `a ${configName} beside a package.json, with your own command:`,
+      '',
+      exampleConfig(format).trimEnd(),
+    ])
+  }
+  const said =
+    lock === undefined || lock.code === 0 ? next : `fix the above, then vx lock and ${next}`
+  rows.push(null, ['next', said])
+  ui.print('out', ui.report(`${verb} ${VERSION}`, rows))
   return 0
 }
 
+/**
+ * What to do about written files .gitignore drops. A `!file` line cures a
+ * file, but git re-includes nothing inside an ignored directory: an
+ * old-layout `/.vx/` line (when `.vx` held only the cache) hides the
+ * workspace config and lock, so that advice names the directory instead.
+ */
+function ignoreAdvice(root: string, ignored: readonly string[], dry: boolean): string {
+  const ancestors = (f: string): string[] =>
+    f
+      .split('/')
+      .slice(0, -1)
+      .map((_, i, parts) => `${parts.slice(0, i + 1).join('/')}/`)
+  const dirs = new Set(gitIgnored(root, [...new Set(ignored.flatMap(ancestors))]))
+  const blocking = new Set<string>()
+  const names = new Set<string>()
+  for (const f of ignored) {
+    const dir = ancestors(f).find((d) => dirs.has(d))
+    if (dir === undefined) names.add(`!${path.posix.basename(f)}`)
+    else blocking.add(dir)
+  }
+  const cures = [
+    ...(names.size === 0 ? [] : [`add ${[...names].join(' and ')} to .gitignore`]),
+    ...(blocking.size === 0
+      ? []
+      : [
+          `stop ignoring ${[...blocking].join(' and ')} (a ! line cannot re-include a file inside an ignored directory)`,
+        ]),
+  ]
+  return `.gitignore drops ${ignored.length} file${ignored.length === 1 ? '' : 's'} this ${dry ? 'would write' : 'wrote'} (${ignored.slice(0, TODO_IDS_SHOWN).join(', ')}${ignored.length > TODO_IDS_SHOWN ? ', …' : ''}): ${cures.join(', ')}, or commit them with git add -f`
+}
+
 /** The paths (root-relative) git's ignore rules drop; none outside a work tree. */
 function gitIgnored(root: string, relPaths: readonly string[]): string[] {
   if (relPaths.length === 0) return []
   try {
     const r = Bun.spawnSync({
       cmd: [executablePath('git'), 'check-ignore', '--stdin', '-z'],
+      env: gitEnv(),
       cwd: root,
       stdin: Buffer.from(relPaths.map((p) => `${p}\0`).join('')),
       stdout: 'pipe',
@@ -551,6 +547,7 @@ function inGitWorkTree(root: string): boolean {
     return (
       Bun.spawnSync({
         cmd: [executablePath('git'), 'rev-parse', '--is-inside-work-tree'],
+        env: gitEnv(),
         cwd: root,
         stdout: 'pipe',
         stderr: 'ignore',
@@ -583,21 +580,22 @@ function nextTask(tasks: readonly GeneratedTask[]): string {
 }
 
 /**
- * How the user runs vx, for the report's `next:` line. After `npx vx init`
+ * How the user runs vx, for the report's `next:` line. After `npx @vzn/vx init`
  * or `bunx @vzn/vx init` a bare `vx` is on no PATH (the first-five-minutes
  * walk, 2026-09-28), so the line names the runner that started this
  * process — npx, pnpm, yarn and Bun each set `npm_config_user_agent` — and
- * the spec it resolves: the installed bin, else the package, since a bare
- * `bunx vx` or `npx vx` would fetch an unrelated package named `vx`. No
+ * the spec it resolves. npx and bunx always name the package, which runs
+ * the installed bin when there is one: their bare `vx` fetches an unrelated
+ * package named `vx` wherever vx is not installed. No
  * runner (a global install, the compiled binary): `vx`.
  */
 export function vxInvocation(userAgent: string | undefined, installed: boolean): string {
   const runner = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? '')?.[1]
   switch (runner) {
     case 'npm':
-      return installed ? 'npx vx' : 'npx @vzn/vx'
+      return 'npx @vzn/vx'
     case 'bun':
-      return installed ? 'bunx vx' : 'bunx @vzn/vx'
+      return 'bunx @vzn/vx'
     case 'pnpm':
       return installed ? 'pnpm vx' : 'pnpm dlx @vzn/vx'
     case 'yarn':
@@ -609,6 +607,15 @@ export function vxInvocation(userAgent: string | undefined, installed: boolean):
   }
 }
 
+/** Files named one per line; past this, the root's and a count (TanStack form: 97). */
+const FILES_SHOWN = 10
+
+function fileLines(paths: readonly string[]): string[] {
+  if (paths.length <= FILES_SHOWN) return [...paths]
+  const root = paths.filter((p) => !p.includes('/') || p.startsWith('.vx/'))
+  return [...root, `and ${paths.length - root.length} more in package directories`]
+}
+
 /** Ids named per shared TODO; the files carry each one (sveltejs/kit: 92 persistent tasks). */
 const TODO_IDS_SHOWN = 5
 
@@ -635,12 +642,12 @@ function exampleConfig(format: MigrationFormat): string {
 // into every run — measured 2026-09-09 at ~17 ms on a two-package
 // workspace, a fifth of the whole run — for an identity function.
 // No explanatory comment: the file is the user's (owner, 2026-10-06).
-const WORKSPACE_BODY = `export default { plugins: [] }`
-
-function workspaceFile(format: MigrationFormat): string {
+function workspaceFile(format: MigrationFormat, plugins: readonly WorkspacePlugin[]): string {
+  const imports = plugins.map((p) => `import { ${p.factory} } from '${p.pkg}'\n`).join('')
+  const body = `export default { plugins: [${plugins.map((p) => `${p.factory}()`).join(', ')}] }`
   return format === 'ts'
-    ? `import type { WorkspaceConfig } from '@vzn/vx/config'\n\n${WORKSPACE_BODY} satisfies WorkspaceConfig\n`
-    : `${WORKSPACE_BODY}\n`
+    ? `import type { WorkspaceConfig } from '@vzn/vx/config'\n${imports}\n${body} satisfies WorkspaceConfig\n`
+    : `${imports}${imports === '' ? '' : '\n'}${body}\n`
 }
 
 const IDENT = /^[A-Za-z_$][\w$]*$/
@@ -679,8 +686,9 @@ function renderConfigFile(p: GeneratedProject, format: MigrationFormat): string
   if (p.importLines.length > 0) lines.push(...p.importLines)
   if (lines.length > 0) lines.push('')
   lines.push('export default {')
+  if (p.writeName === true) lines.push(`  name: ${quoteTsLiteral(p.name)},`)
   if (p.tags !== undefined && p.tags.length > 0) lines.push(`  tags: ${renderValue(p.tags, '  ')},`)
-  lines.push('  tasks: {')
+  lines.push(p.tasks.length === 0 ? '  tasks: {},' : '  tasks: {')
   for (const t of p.tasks) {
     // A reason can quote a manifest's own text (an Nx `env` key), and a
     // line break there ended the comment: the rest was code in the file
@@ -709,6 +717,90 @@ function renderConfigFile(p: GeneratedProject, format: MigrationFormat): string
       `    ${key}: ${block === undefined ? rendered : rendered.replace('{\n', `{\n      // ${block},\n`)},`,
     )
   }
-  lines.push('  },', format === 'ts' ? '} satisfies ProjectConfig' : '}', '')
+  if (p.tasks.length > 0) lines.push('  },')
+  lines.push(format === 'ts' ? '} satisfies ProjectConfig' : '}', '')
   return lines.join('\n')
 }
+
+/**
+ * `vx.config.mts` in a TypeScript package that is CommonJS: tsc (node16 /
+ * nodenext) reads a `.ts` there as CommonJS, and its type-only import of
+ * the ESM `@vzn/vx/config` fails (TS1479, TS1541: medusa's plugin builds).
+ */
+function projectConfigName(
+  dir: string,
+  metas: readonly MigrationMember[],
+  format: MigrationFormat,
+): string {
+  if (format !== 'ts' || !existsSync(path.join(dir, 'tsconfig.json'))) return `vx.config.${format}`
+  const meta = metas.find((m) => m.dir === dir)
+  const manifest = (meta?.packageJson as { type?: unknown } | undefined) ?? readManifest(dir)
+  return manifest?.type === 'module' ? 'vx.config.ts' : 'vx.config.mts'
+}
+
+/**
+ * The plan takes the config back from an output as `!vx.config.<format>`;
+ * where the file written is the `.mts`, the take-back names it, or a `*`
+ * output covers it and `vx lock` refuses the config (medusa, 80 of 84).
+ */
+function ownConfigNamed(
+  p: GeneratedProject,
+  name: string,
+  format: MigrationFormat,
+): GeneratedProject {
+  const planned = `!vx.config.${format}`
+  if (name === `vx.config.${format}`) return p
+  return {
+    ...p,
+    tasks: p.tasks.map((t) => {
+      const outputs = (t.task?.['cache'] as { outputs?: { files?: unknown } } | undefined)?.outputs
+      if (!Array.isArray(outputs?.files) || !outputs.files.includes(planned)) return t
+      const cache = t.task!['cache'] as Record<string, unknown>
+      const files = outputs.files.map((f: unknown) => (f === planned ? `!${name}` : f))
+      return { ...t, task: { ...t.task, cache: { ...cache, outputs: { ...outputs, files } } } }
+    }),
+  }
+}
+
+function readManifest(dir: string): { type?: unknown } | undefined {
+  try {
+    return JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8')) as { type?: unknown }
+  } catch {
+    return undefined
+  }
+}
+
+/** The formatters a repo installs at its root, each with its write command. */
+const FORMATTERS: readonly (readonly [string, readonly string[]])[] = [
+  ['prettier', ['--write']],
+  ['biome', ['format', '--write']],
+  ['oxfmt', []],
+  ['dprint', ['fmt']],
+]
+
+/**
+ * Runs the repo's own formatter over the files just written, as Nx's
+ * generators do: create-t3-turbo's `prettier --check` failed on the quotes
+ * of a config vx wrote. Returns the report's note.
+ */
+function formatWritten(root: string, relPaths: readonly string[]): string[] {
+  if (relPaths.length === 0) return []
+  for (const [name, args] of FORMATTERS) {
+    const bin = path.join(root, 'node_modules', '.bin', name)
+    if (!existsSync(bin)) continue
+    const r = Bun.spawnSync({
+      cmd: [bin, ...args, ...relPaths],
+      cwd: root,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: 60_000,
+    })
+    if (r.exitCode === 0) {
+      return [`formatted ${relPaths.length} file${relPaths.length === 1 ? '' : 's'} with ${name}`]
+    }
+    const why = (r.stderr.toString() || r.stdout.toString()).trim().split('\n')[0] ?? ''
+    return [`${name} did not format the written files (exit ${r.exitCode ?? 'signal'}): ${why}`]
+  }
+  return []
+}