@vzn/vx 0.0.16 → 0.0.18

package/src/cli/last.ts

@@ -0,0 +1,140 @@
+// `vx last [runId]` — replay a recorded run's summary from the terminal,
+// without re-executing anything. Comparison gap #12: with the dashboard's
+// run-detail page gone (the 2026-08-23 cloud removal), the local run
+// history in cache.db is the only replay surface, and this verb reads it.
+// Read-only — no config evaluation, no re-hash, no cache probe.
+
+import { Cache } from '../cache/index.js'
+import { getInvocation, getRun, listInvocations } from '../orchestrator/index.js'
+import { UserError } from '../util/index.js'
+import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+
+interface LastArgs {
+  runId?: string
+  list?: number
+  format: 'pretty' | 'json'
+  error?: string
+}
+
+export function parseLastArgs(args: readonly string[]): LastArgs {
+  const out: LastArgs = { format: 'pretty' }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (a === '--list' || a.startsWith('--list=')) {
+      const lv = a === '--list' ? '10' : a.slice(7)
+      const n = Number(lv)
+      if (!Number.isInteger(n) || n < 1 || n > 500) {
+        return { ...out, error: `invalid --list: ${lv} (expected 1..500)` }
+      }
+      out.list = n
+      continue
+    }
+    if (a === '--format' || a.startsWith('--format=')) {
+      const fv = a === '--format' ? args[++i] : a.slice(9)
+      if (fv !== 'pretty' && fv !== 'json') {
+        return { ...out, error: `invalid --format: ${fv ?? ''} (expected pretty | json)` }
+      }
+      out.format = fv
+      continue
+    }
+    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
+    if (out.runId !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    out.runId = a
+  }
+  return out
+}
+
+const fmtWhen = (ms: number): string => new Date(ms).toISOString()
+
+function fmtMs(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  if (ms < 60_000) return `${(ms / 1000).toFixed(2)}s`
+  const m = Math.floor(ms / 60_000)
+  return `${m}m ${Math.round((ms - m * 60_000) / 1000)}s`
+}
+
+export async function lastCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseLastArgs(args)
+  if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`)
+
+  const root = await findWorkspaceRoot(process.cwd())
+  const cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
+  const cache = new Cache(cacheDir)
+  try {
+    const db = cache.dbHandle()
+
+    if (parsed.list !== undefined) {
+      const invocations = listInvocations(db, { limit: parsed.list })
+      if (parsed.format === 'json') {
+        process.stdout.write(`${JSON.stringify(invocations)}\n`)
+        return 0
+      }
+      if (invocations.length === 0) {
+        process.stdout.write('no recorded runs\n')
+        return 0
+      }
+      for (const inv of invocations) {
+        const verdict = inv.exitOk ? 'ok    ' : 'FAILED'
+        process.stdout.write(
+          `${verdict} ${fmtWhen(inv.startedAt)}  ${inv.runId}  ` +
+            `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${inv.hitCount} hit${inv.hitCount === 1 ? '' : 's'}` +
+            `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''} · ${fmtMs(inv.totalDurationMs)}  $ ${inv.command}\n`,
+        )
+      }
+      return 0
+    }
+
+    const inv =
+      parsed.runId !== undefined
+        ? getInvocation(db, parsed.runId)
+        : (listInvocations(db, { limit: 1 })[0] ?? null)
+    if (inv === null || inv === undefined) {
+      throw new UserError(
+        parsed.runId !== undefined
+          ? `vx last: no recorded run ${parsed.runId} (vx last --list shows recent runs)`
+          : 'vx last: no recorded runs yet — run something first',
+      )
+    }
+    const detail = getRun(db, inv.runId)
+
+    if (parsed.format === 'json') {
+      process.stdout.write(`${JSON.stringify({ invocation: inv, tasks: detail?.tasks ?? [] })}\n`)
+      return 0
+    }
+
+    const lines: string[] = []
+    lines.push(`run ${inv.runId} — ${inv.exitOk ? 'ok' : 'FAILED'}`)
+    lines.push(`  $ ${inv.command}`)
+    lines.push(
+      `  ${fmtWhen(inv.startedAt)} · ${fmtMs(inv.totalDurationMs)}` +
+        `${inv.branch !== null ? ` · ${inv.branch}` : ''}` +
+        `${inv.commitSha !== null ? ` @ ${inv.commitSha.slice(0, 8)}${inv.dirty === true ? '+dirty' : ''}` : ''}` +
+        `${inv.ci ? ` · CI${inv.ciProvider !== null ? ` (${inv.ciProvider})` : ''}` : ''}`,
+    )
+    lines.push(
+      `  ${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${inv.hitCount} hit${inv.hitCount === 1 ? '' : 's'}` +
+        ` (${inv.hitLocalCount} local, ${inv.hitRemoteCount} remote)` +
+        `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''}`,
+    )
+    const tasks = detail?.tasks ?? []
+    if (tasks.length > 0) {
+      lines.push('')
+      const failedFirst = [
+        ...tasks.filter((t) => t.status === 'failed'),
+        ...tasks.filter((t) => t.status !== 'failed'),
+      ]
+      const idW = Math.max(...tasks.map((t) => `${t.project}#${t.task}`.length), 4)
+      for (const t of failedFirst) {
+        const id = `${t.project}#${t.task}`
+        lines.push(
+          `  ${t.status.padEnd(17)} ${id.padEnd(idW)}  ${fmtMs(t.durationMs).padStart(8)}` +
+            `${t.hash !== '' ? `  ${t.hash}` : ''}`,
+        )
+      }
+    }
+    process.stdout.write(`${lines.join('\n')}\n`)
+    return 0
+  } finally {
+    cache.close()
+  }
+}

package/src/cli/migrate-emit.ts

@@ -0,0 +1,21 @@
+// Shared TS-literal emission helper for the migrate mappers. Lives in its own
+// leaf module so both migrate.ts (the config emitter) and migrate-turbo.ts (the
+// preset renderer) can escape strings identically without a dependency cycle
+// (migrate.ts already imports the turbo/nx mappers, so a back-import of a value
+// from migrate.ts would close a runtime cycle).
+
+/**
+ * Escape an arbitrary string into a single-quoted TS literal. Escapes
+ * backslash + quote AND raw newlines/CR — a value with an embedded newline
+ * (legal JSON, e.g. a script `"echo a\necho b"`, or a glob with a `'`) would
+ * otherwise splice into a single-quoted literal as an unterminated / malformed
+ * string that fails to load (generated files must round-trip through the
+ * loader).
+ */
+export function quote(s: string): string {
+  return `'${s
+    .replaceAll('\\', '\\\\')
+    .replaceAll("'", "\\'")
+    .replaceAll('\n', '\\n')
+    .replaceAll('\r', '\\r')}'`
+}

package/src/cli/migrate-nx.ts

@@ -416,6 +416,17 @@ function mapCommand(
     return PLACEHOLDER
   }
   if (executor === undefined && typeof target.command === 'string') return target.command
+  // The common executors wrap one CLI each; the task runs on the first
+  // try and the TODO still asks for a look, since executor options
+  // (config paths, watch flags) are not carried over.
+  const known = executor === undefined ? undefined : KNOWN_EXECUTORS[executor]
+  if (known !== undefined) {
+    todos.push(
+      `command ${JSON.stringify(known)} mapped from executor ${JSON.stringify(executor)} — ` +
+        `verify it against the executor's options: ${JSON.stringify(options)}`,
+    )
+    return known
+  }
   todos.push(
     `executor ${JSON.stringify(executor ?? '(none)')} has no shell equivalent — fill in the ` +
       `CLI command. options: ${JSON.stringify(options)}`,
@@ -423,6 +434,18 @@ function mapCommand(
   return PLACEHOLDER
 }
 
+/** Nx executors whose CLI is unambiguous; anything else is a placeholder. */
+const KNOWN_EXECUTORS: Record<string, string> = {
+  '@nx/vite:build': 'vite build',
+  '@nx/vite:dev-server': 'vite',
+  '@nx/vite:preview-server': 'vite preview',
+  '@nx/vite:test': 'vitest run',
+  '@nx/vitest:test': 'vitest run',
+  '@nx/jest:jest': 'jest',
+  '@nx/eslint:lint': 'eslint .',
+  '@nx/js:tsc': 'tsc -p tsconfig.json',
+}
+
 function countImplicitDeps(
   dependencies: unknown,
   metaByNode: ReadonlyMap<string, ProjectMeta>,

package/src/cli/migrate-scripts.ts

@@ -0,0 +1,127 @@
+// package.json scripts → vx tasks: the source for a workspace that comes
+// from nowhere (no turbo.json, no nx). `vx init` is this mapper.
+//
+// Scripts carry a command and nothing else, so the mapping is honest about
+// what it cannot know: every task gets `exec.command` verbatim; `build`
+// gets the conventional `dependsOn: ['^build']` and `test` / `lint` /
+// `typecheck` wait for `build` when the package has one; a dev-server
+// shaped script becomes persistent. Caching is opt-in and needs declared
+// inputs AND outputs, which a script cannot tell us — so `build` is
+// emitted with a cache block whose inputs are the whole project and whose
+// outputs are EMPTY, under a TODO naming what to fill in. A cache block
+// that guessed `dist/**` would restore the wrong tree for every package
+// that writes somewhere else, and a wrong restore is the worst failure
+// vx has.
+//
+// Two npm conventions are mapped rather than copied, because copying them
+// loses behaviour: `pre<x>` / `post<x>` hooks, which npm runs around `x`
+// without being named, are folded into `x`'s command in that order (a
+// standalone `prebuild` task is one `vx run build` never runs — and the
+// hook is usually `rimraf dist`); and a script that is nothing but
+// `<pm> run <other>` becomes a GROUP over `<other>`, so the graph sees the
+// dependency instead of a package-manager subprocess it cannot cache.
+
+import type { ProjectMeta } from '../workspace/index.js'
+import type { GeneratedProject, GeneratedTask, MigrationPlan } from './migrate.js'
+
+const PERSISTENT = new Set(['dev', 'start', 'serve', 'watch', 'preview'])
+const AFTER_BUILD = new Set(['test', 'lint', 'typecheck', 'check', 'e2e'])
+const LIFECYCLE = /^(pre|post)(install|publish|pack|version)$|^(prepare|prepublishOnly|install)$/
+
+/**
+ * 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.
+ */
+export function delegatedScript(command: string): string | null {
+  const m =
+    /^(?:(?:npm run|pnpm(?: run)?|yarn(?: run)?|bun(?: run)?) ([^\s&|;<>()$`'"\\]+)|npm (test|start))$/.exec(
+      command.trim(),
+    )
+  return m === null ? null : (m[1] ?? m[2])!
+}
+
+function scriptsOf(meta: ProjectMeta): Record<string, unknown> {
+  // package.json is a boundary: `scripts` is whatever the file holds. A
+  // string or an array would enumerate its indices as script names.
+  const raw = (meta.packageJson as unknown as { scripts?: unknown }).scripts
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return {}
+  return raw as Record<string, unknown>
+}
+
+export function migrateScripts(metas: readonly ProjectMeta[]): MigrationPlan {
+  const projects: GeneratedProject[] = []
+  for (const meta of metas) {
+    const scripts = scriptsOf(meta)
+    const names = Object.keys(scripts).filter(
+      (n) => typeof scripts[n] === 'string' && scripts[n] !== '',
+    )
+    if (names.length === 0) continue
+    const hasBuild = names.includes('build')
+    const has = (n: string): boolean => names.includes(n)
+    const tasks: GeneratedTask[] = []
+    for (const name of names) {
+      // Lifecycle hooks are npm's, not tasks anyone runs by name.
+      if (LIFECYCLE.test(name)) continue
+      // A hook of a script that exists rides inside that script's command.
+      const hookOf = /^(pre|post)(.+)$/.exec(name)
+      if (hookOf !== null && has(hookOf[2]!) && !LIFECYCLE.test(hookOf[2]!)) continue
+
+      const todos: string[] = []
+      const own = scripts[name] as string
+      const delegate = delegatedScript(own)
+      // npm lifecycle hooks (`prepack`, `prepublishOnly`, …) belong to the
+      // package manager and never ride inside a task — `pack` stays alone.
+      const hook = (h: string): boolean => has(h) && !LIFECYCLE.test(h)
+      const hooks = [`pre${name}`, `post${name}`].filter(hook)
+      if (delegate !== null && has(delegate) && delegate !== name && hooks.length === 0) {
+        // A group: no exec, the graph runs the target. `npm test` calling
+        // `vitest` through `npm run test:unit` is two tasks, not a subprocess.
+        const task: Record<string, unknown> = { dependsOn: [delegate] }
+        if (AFTER_BUILD.has(name) && hasBuild && delegate !== 'build') {
+          task['dependsOn'] = [delegate, 'build']
+        }
+        tasks.push({ name, todos, task })
+        continue
+      }
+
+      const command = [
+        ...(hook(`pre${name}`) ? [scripts[`pre${name}`] as string] : []),
+        own,
+        ...(hook(`post${name}`) ? [scripts[`post${name}`] as string] : []),
+      ].join(' && ')
+      if (hooks.length > 0) {
+        todos.push(
+          `npm ran ${hooks.map((h) => `\`${h}\``).join(' and ')} around this script without being asked; folded into the command in that order`,
+        )
+      }
+      const task: Record<string, unknown> = { exec: { command } }
+      if (PERSISTENT.has(name)) {
+        task['exec'] = { command, persistent: {} }
+        todos.push(
+          'persistent: add `readyWhen: "<line the server prints when ready>"` so dependents wait for it',
+        )
+      }
+      if (name === 'build') {
+        task['dependsOn'] = ['^build']
+        task['cache'] = { inputs: { files: ['**/*'] }, outputs: { files: [] } }
+        todos.push(
+          "cache: inputs default to the whole project ('**/*'); narrow them (e.g. 'src/**') and declare outputs (e.g. 'dist/**') — nothing is cached until outputs are declared",
+        )
+      } else if (AFTER_BUILD.has(name) && hasBuild) {
+        task['dependsOn'] = ['build']
+      }
+      tasks.push({ name, todos, task })
+    }
+    if (tasks.length > 0) projects.push({ name: meta.name, dir: meta.dir, importLines: [], tasks })
+  }
+  return {
+    headerNotes: [
+      'each script became a task with its command verbatim; caching needs declared inputs and outputs, so only `build` got a cache block, with empty outputs to fill in',
+    ],
+    projects,
+    extraFiles: [],
+    notes: [],
+  }
+}

package/src/cli/migrate-turbo.ts

@@ -8,6 +8,7 @@
 import path from 'node:path'
 import { relPosix, UserError } from '../util/index.js'
 import type { ProjectMeta } from '../workspace/index.js'
+import { quote } from './migrate-emit.js'
 import type { GeneratedProject, GeneratedTask, MigrationPlan, RawExpr } from './migrate.js'
 
 interface TurboTask {
@@ -63,8 +64,22 @@ function tasksOf(cfg: TurboJson): Record<string, TurboTask> {
   return cfg.tasks ?? cfg.pipeline ?? {}
 }
 
-function scriptsOf(meta: ProjectMeta): Record<string, string> {
-  return (meta.packageJson as unknown as { scripts?: Record<string, string> }).scripts ?? {}
+function scriptsOf(meta: ProjectMeta): Record<string, unknown> {
+  // package.json is a system boundary — a script value is whatever the
+  // file holds, not necessarily a string.
+  return (meta.packageJson as unknown as { scripts?: Record<string, unknown> }).scripts ?? {}
+}
+
+/** A script value that can become `exec.command` verbatim. */
+function usableScript(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0
+}
+
+function describeScript(value: unknown): string {
+  if (value === null) return 'null'
+  if (typeof value === 'string') return 'an empty string'
+  if (Array.isArray(value)) return 'an array'
+  return `a ${typeof value}`
 }
 
 /** Declared task names for a package: plain root keys, `pkg#name` keys
@@ -126,7 +141,7 @@ export async function migrateTurbo(
     const scripts = scriptsOf(meta)
     const set = new Set<string>()
     for (const name of taskNamesFor(meta.name, rootTasks, pkgTasksByName.get(meta.name))) {
-      if (scripts[name] !== undefined) set.add(name)
+      if (usableScript(scripts[name])) set.add(name)
     }
     emitted.set(meta.name, set)
   }
@@ -139,13 +154,32 @@ export async function migrateTurbo(
     const used = new Set<string>()
     const tasks: GeneratedTask[] = []
     for (const name of taskNamesFor(meta.name, rootTasks, pkgTasks)) {
-      if (!own.has(name)) continue
+      const script = scripts[name]
+      if (!usableScript(script)) {
+        // The turbo task exists and so does the script KEY, but its value
+        // can't become a command. Report it instead of emitting
+        // `command: 42` / `command: null` — the first writes a config that
+        // fails to load, the second used to abort the whole migration in
+        // the emitter, and both landed AFTER "migrated clean, 0 TODOs".
+        // An ABSENT script stays silent: turbo skips the task there too.
+        if (script !== undefined) {
+          tasks.push({
+            name,
+            todos: [
+              `package.json script ${JSON.stringify(name)} is ${describeScript(script)}, not a ` +
+                'non-empty command string — task skipped; write the command by hand',
+            ],
+            task: null,
+          })
+        }
+        continue
+      }
       const def: TurboTask = {
         ...rootTasks[name],
         ...rootTasks[`${meta.name}#${name}`],
         ...pkgTasks?.[name],
       }
-      tasks.push(buildTask(name, def, scripts[name]!, own, emitted, globals, used))
+      tasks.push(buildTask(name, def, script, own, emitted, globals, used))
     }
     projects.push({
       name: meta.name,
@@ -330,7 +364,10 @@ function presetImportLines(used: ReadonlySet<string>, root: string, dir: string)
 }
 
 function renderPreset(inputs: string[], env: string[], pass: string[]): string {
-  const arr = (xs: string[]): string => `[${xs.map((x) => `'${x}'`).join(', ')}]`
+  // Escape each entry via the shared `quote()` — a turbo.json global (a file
+  // glob, or an env name a user hand-wrote) may contain a `'`/`\`/newline that
+  // would otherwise splice into a malformed, unloadable `vx-preset.ts`.
+  const arr = (xs: string[]): string => `[${xs.map(quote).join(', ')}]`
   const lines = [
     '// Generated by `vx migrate` from turbo.json. TypeScript composition',
     "// replaces turbo's global fields: each vx.config.ts imports these",

package/src/cli/migrate.ts

@@ -8,13 +8,15 @@
 import path from 'node:path'
 import { relPosix, UserError } from '../util/index.js'
 import { findWorkspaceRoot, listProjects, loadWorkspace } from '../workspace/index.js'
+import { quote } from './migrate-emit.js'
 import { migrateNx } from './migrate-nx.js'
+import { migrateScripts } from './migrate-scripts.js'
 import { migrateTurbo } from './migrate-turbo.js'
 
 export interface MigrateArgs {
   dry: boolean
   force: boolean
-  from?: 'turbo' | 'nx'
+  from?: 'turbo' | 'nx' | 'scripts'
   error?: string
 }
 
@@ -26,7 +28,9 @@ export function parseMigrateArgs(args: readonly string[]): MigrateArgs {
     else if (a === '--force') out.force = true
     else if (a === '--from' || a?.startsWith('--from=')) {
       const v = a === '--from' ? args[++i] : a.slice('--from='.length)
-      if (v !== 'turbo' && v !== 'nx') return { ...out, error: `--from must be turbo or nx` }
+      if (v !== 'turbo' && v !== 'nx' && v !== 'scripts') {
+        return { ...out, error: `--from must be turbo, nx or scripts` }
+      }
       out.from = v
     } else if (a?.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
     else return { ...out, error: `unexpected argument: ${a}` }
@@ -67,7 +71,10 @@ export interface MigrationPlan {
   notes: string[]
 }
 
-export async function migrateCmd(args: readonly string[]): Promise<number> {
+export async function migrateCmd(
+  args: readonly string[],
+  opts: { init?: boolean } = {},
+): Promise<number> {
   const parsed = parseMigrateArgs(args)
   if (parsed.error) {
     process.stderr.write(`vx migrate: ${parsed.error}\n`)
@@ -94,7 +101,10 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
 
   let source: string
   let plan: MigrationPlan
-  if (parsed.from === 'nx' || (parsed.from === undefined && !hasTurbo)) {
+  if (parsed.from === 'scripts') {
+    source = 'package.json scripts'
+    plan = migrateScripts(metas)
+  } else if (parsed.from === 'nx' || (parsed.from === undefined && !hasTurbo)) {
     if (hasGraph) {
       source = '.nx/workspace-data/project-graph.json'
       plan = await migrateNx(root, metas)
@@ -106,13 +116,23 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
           '`nx graph --file=.nx/workspace-data/project-graph.json`, then re-run vx migrate',
       )
     } else {
-      throw new UserError('nothing to migrate: no turbo.json or nx.json at the workspace root')
+      // A workspace from nowhere: the scripts are the source (`vx init`).
+      source = 'package.json scripts'
+      plan = migrateScripts(metas)
     }
-  } else if (hasTurbo) {
+  } else {
     source = 'turbo.json'
     plan = await migrateTurbo(root, metas)
-  } else {
-    throw new UserError('nothing to migrate: no turbo.json or nx.json at the workspace root')
+  }
+  // `vx init` on a workspace with no scripts still has a job: the
+  // workspace file, which every run needs, and a worked example of the
+  // config the user writes next. `vx migrate` with nothing to convert is
+  // an error: the user asked for a conversion that has no input.
+  const empty = plan.projects.length === 0
+  if (empty && opts.init !== true) {
+    throw new UserError(
+      `nothing to migrate: no ${source === 'package.json scripts' ? 'package.json scripts in any workspace member' : 'tasks in ' + source}`,
+    )
   }
 
   const files: { relPath: string; abs: string; contents: string }[] = []
@@ -124,21 +144,41 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
   for (const f of plan.extraFiles) {
     files.push({ relPath: f.relPath, abs: path.join(root, f.relPath), contents: f.contents })
   }
+  // A migrated workspace must declare its executor and cache — nothing is
+  // applied by default. Emit the workspace file unless the repo already has
+  // one in any supported extension.
+  const hasWorkspaceFile = (
+    await Promise.all(
+      ['vx.workspace.ts', 'vx.workspace.mjs', 'vx.workspace.js'].map((n) =>
+        Bun.file(path.join(root, n)).exists(),
+      ),
+    )
+  ).some(Boolean)
+  if (!hasWorkspaceFile) {
+    const abs = path.join(root, 'vx.workspace.ts')
+    files.push({ relPath: relPosix(root, abs), abs, contents: WORKSPACE_FILE })
+  }
 
   if (!parsed.dry && !parsed.force) {
-    const conflicts: string[] = []
+    const conflicts = new Set<string>()
+    // 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 plan.projects) {
       if (p.tasks.length === 0) continue
       const meta = metas.find((m) => m.dir === p.dir)
-      if (meta?.configPath) conflicts.push(relPosix(root, meta.configPath))
+      if (meta?.configPath) conflicts.add(relPosix(root, meta.configPath))
     }
-    for (const f of plan.extraFiles) {
-      if (await Bun.file(path.join(root, f.relPath)).exists()) conflicts.push(f.relPath)
+    // ALSO stat every actual write target. A SYNTHESIZED project (e.g. the Nx
+    // workspace-root node, dir === root) has no discovered meta, so the meta
+    // scan alone would miss an existing vx.config.ts at that path and clobber
+    // it. This also covers the extraFiles (vx-preset.ts).
+    for (const f of files) {
+      if (await Bun.file(f.abs).exists()) conflicts.add(f.relPath)
     }
-    if (conflicts.length > 0) {
+    if (conflicts.size > 0) {
       throw new UserError(
         'refusing to overwrite existing files (pass --force to overwrite):\n' +
-          `  ${conflicts.join('\n  ')}`,
+          `  ${[...conflicts].join('\n  ')}`,
       )
     }
   }
@@ -159,28 +199,68 @@ export async function migrateCmd(args: readonly string[]): Promise<number> {
       for (const reason of t.todos) todoList.push(`${p.name}#${t.name}: ${reason}`)
     }
   }
-  const report: string[] = [`vx migrate: ${source} → vx.config.ts`]
-  for (const n of plan.headerNotes) report.push(`note: ${n}`)
-  report.push(
-    '',
-    `${clean} task${clean === 1 ? '' : 's'} migrated clean, ` +
-      `${todoList.length} TODO${todoList.length === 1 ? '' : 's'}${todoList.length > 0 ? ':' : ''}`,
-  )
-  for (const line of todoList) report.push(`  ${line}`)
-  report.push(...plan.notes)
-  report.push(parsed.dry ? 'files (dry run, nothing written):' : 'files written:')
-  for (const f of files) report.push(`  ${f.relPath}`)
+  const report: string[] = []
+  if (empty) {
+    report.push(
+      'vx init: no package.json scripts to turn into tasks.',
+      hasWorkspaceFile
+        ? 'vx.workspace.ts already exists.'
+        : parsed.dry
+          ? 'would write vx.workspace.ts (dry run, nothing written).'
+          : 'wrote vx.workspace.ts.',
+      'Declare tasks in a vx.config.ts beside a package.json — your own command, for example:',
+      '',
+      ...EXAMPLE_CONFIG.trimEnd()
+        .split('\n')
+        .map((l) => `  ${l}`),
+    )
+  } else {
+    report.push(`vx migrate: ${source} → vx.config.ts`)
+    for (const n of plan.headerNotes) report.push(`note: ${n}`)
+    report.push(
+      '',
+      `${clean} task${clean === 1 ? '' : 's'} migrated clean, ` +
+        `${todoList.length} TODO${todoList.length === 1 ? '' : 's'}${todoList.length > 0 ? ':' : ''}`,
+    )
+    for (const line of todoList) report.push(`  ${line}`)
+    report.push(...plan.notes)
+    report.push(parsed.dry ? 'files (dry run, nothing written):' : 'files written:')
+    for (const f of files) report.push(`  ${f.relPath}`)
+  }
+  const firstTask =
+    plan.projects.flatMap((p) => p.tasks.map((t) => t.name)).find((n) => n === 'build') ??
+    plan.projects[0]?.tasks[0]?.name ??
+    'build'
+  report.push('', `next: vx run ${firstTask} --all`)
   process.stdout.write(`${report.join('\n')}\n`)
   return 0
 }
 
+const EXAMPLE_CONFIG = `import type { ProjectConfig } from '@vzn/vx'
+
+export default {
+  tasks: {
+    build: {
+      exec: { command: 'tsc -b' },
+      dependsOn: ['^build'],
+      cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
+    },
+  },
+} satisfies ProjectConfig
+`
+
 // ─── TS emission ──────────────────────────────────────────────────────
 
-const IDENT = /^[A-Za-z_$][\w$]*$/
+const WORKSPACE_FILE = `import { defineWorkspace } from '@vzn/vx'
+import { localExecutorPlugin } from '@vzn/vx/plugins/local-executor'
+import { localCachePlugin } from '@vzn/vx/plugins/local-cache'
 
-function quote(s: string): string {
-  return `'${s.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`
-}
+// Nothing runs that is not declared here. Put a remote executor or cache
+// plugin BEFORE the local one to prefer it.
+export default defineWorkspace({ plugins: [localExecutorPlugin(), localCachePlugin()] })
+`
+
+const IDENT = /^[A-Za-z_$][\w$]*$/
 
 function isRawExpr(v: unknown): v is RawExpr {
   return typeof v === 'object' && v !== null && typeof (v as RawExpr).raw === 'string'
@@ -188,6 +268,10 @@ function isRawExpr(v: unknown): v is RawExpr {
 
 function renderValue(v: unknown, indent: string): string {
   if (isRawExpr(v)) return v.raw
+  // `Object.entries(null)` throws, which would abort the whole migration
+  // with a raw stack mid-write. Mappers no longer produce a null, but a
+  // literal is a readable thing to leave behind if one ever does.
+  if (v === null) return 'null'
   if (typeof v === 'string') return quote(v)
   if (typeof v === 'number' || typeof v === 'boolean') return String(v)
   if (Array.isArray(v)) return `[${v.map((x) => renderValue(x, indent)).join(', ')}]`
@@ -201,10 +285,12 @@ function renderValue(v: unknown, indent: string): string {
 }
 
 function renderConfigFile(source: string, p: GeneratedProject): string {
+  // A type-only import: the editor type-checks against the installed
+  // package, and Bun erases it, so the config loads in a workspace that
+  // runs the vx binary without the package installed.
   const lines: string[] = [
-    `// Generated by \`vx migrate\` from ${source}. Review the TODO(vx-migrate)`,
-    "// comments, then wrap the object in defineProject() from '@vzn/vx' for",
-    '// editor type-checking.',
+    `// Generated by \`vx migrate\` from ${source}. Review the TODO(vx-migrate) comments.`,
+    "import type { ProjectConfig } from '@vzn/vx'",
   ]
   if (p.importLines.length > 0) lines.push(...p.importLines)
   lines.push('', 'export default {', '  tasks: {')
@@ -214,6 +300,6 @@ function renderConfigFile(source: string, p: GeneratedProject): string {
     const key = IDENT.test(t.name) ? t.name : quote(t.name)
     lines.push(`    ${key}: ${renderValue(t.task, '    ')},`)
   }
-  lines.push('  },', '}', '')
+  lines.push('  },', '} satisfies ProjectConfig', '')
   return lines.join('\n')
 }