@vzn/vx 0.0.646 → 0.0.649

package/src/cli/index.ts

@@ -3,8 +3,9 @@
 
 import { VERSION } from '../version.js'
 import { checkSettingsEnv } from '../settings.js'
-import { CORE_VERBS, flagHint, printHelp, refusedWord, seeHelp } from './help.js'
+import { CORE_VERBS, flagHint, printHelp, refuse, refusedWord, seeHelp } from './help.js'
 import {
+  detectColors,
   errorDocument,
   hideEnvFromTasks,
   sayNotice,
@@ -14,6 +15,7 @@ import {
   maskedLine,
   nearest,
   refusalNotice,
+  thrownMessage,
   ui,
   UserError,
   wantsJson,
@@ -28,6 +30,7 @@ import {
 const plugins = () => import('./plugin-commands.js')
 
 export async function run(argv: readonly string[]): Promise<number> {
+  refuseLossyArgs(argv)
   const [command, ...rest] = argv
   await hideEnvFromTasks()
 
@@ -41,8 +44,11 @@ export async function run(argv: readonly string[]): Promise<number> {
     return 0
   }
   // Each setting's variable once, before any verb: a renamed one is named,
-  // and a deep reader trusts what it reads.
-  checkSettingsEnv()
+  // and a deep reader trusts what it reads. Not for help, as `vx run
+  // --help` above is not: help is where a setting's values are read. Nor
+  // for `vx info`, which reports a refused one (doctor.ts).
+  if (command !== 'help' && command !== '--help' && command !== '-h' && command !== 'info')
+    checkSettingsEnv()
 
   try {
     return await dispatch(command, rest)
@@ -51,9 +57,23 @@ export async function run(argv: readonly string[]): Promise<number> {
   }
 }
 
+/**
+ * Bun decodes argv as lossy UTF-8 and exposes no raw bytes on macOS, so
+ * `-- $'a\xfe'` and `-- $'a\xff'` both became `a` U+FFFD: the task got
+ * bytes nobody typed and the two runs shared a key (a stale hit). A real
+ * U+FFFD cannot be told from a replaced byte, so any arg holding one is refused.
+ */
+function refuseLossyArgs(argv: readonly string[]): void {
+  const at = argv.findIndex((a) => a.includes('�'))
+  if (at === -1) return
+  throw new UserError(
+    `argument ${at + 1} (${JSON.stringify(argv[at])}) is not valid UTF-8, or holds U+FFFD; vx cannot pass it on byte for byte`,
+  )
+}
+
 /**
  * A crash from a hand-broken lock entry is that entry's fault: runs validate
- * no entry, so it surfaced as a raw TypeError (M, 2026-10-14). The lock is
+ * no entry, so it surfaced as a raw TypeError (2026-10-14). The lock is
  * read only on the crash path, so a normal run pays nothing.
  */
 async function brokenLockNamed(err: unknown): Promise<unknown> {
@@ -61,7 +81,8 @@ async function brokenLockNamed(err: unknown): Promise<unknown> {
   try {
     const { findWorkspaceRoot, LOCK_INVALID, lockEntryBroken } =
       await import('../workspace/index.js')
-    if (lockEntryBroken(await findWorkspaceRoot(process.cwd()))) return new UserError(LOCK_INVALID)
+    if (lockEntryBroken(await findWorkspaceRoot(process.cwd())))
+      return new UserError(LOCK_INVALID, 'VX_E_LOCK')
   } catch {}
   return err
 }
@@ -85,13 +106,21 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
     }
     case '--help':
     case '-h':
+      if (rest.length > 0) return dispatch('help', rest)
       await printHelp(await (await plugins()).pluginCommandHelp())
       return 0
     case 'help': {
-      // `vx help run` is the same question as `vx run --help`. A plugin verb
-      // owns its own help, so anything but a core verb gets the whole
-      // reference, which lists the plugin verbs.
-      const verb = rest[0]
+      // `vx help run` is the same question as `vx run --help`, and so is
+      // `vx help <plugin verb>`: a plugin verb owns its own help.
+      const [verb, extra] = rest
+      if (extra !== undefined) {
+        return refuse(
+          'help',
+          rest,
+          `${refusedWord(extra)}: ${extra}${flagHint('help', extra)} (see \`vx help\`)`,
+          'VX_E_USAGE',
+        )
+      }
       const core = verb !== undefined && (CORE_VERBS as readonly string[]).includes(verb)
       if (verb !== undefined && !core) {
         // A name that is no verb here is the typo `vx rnu` is, not a request
@@ -99,22 +128,23 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         const resolved = await (await plugins()).resolvePluginCommand(verb)
         const unknown = resolved === null || 'declaredVerbs' in resolved
         if (unknown && verb.startsWith('-')) {
-          sayNotice(
-            'error',
-            'vx help',
+          return refuse(
+            'help',
+            rest,
             `unknown flag: ${verb}${flagHint('help', verb)} (see \`vx help\`)`,
+            'VX_E_USAGE',
           )
-          return 1
         }
         if (unknown) {
           const declared = resolved === null ? [] : resolved.declaredVerbs
-          sayNotice(
-            'error',
-            'vx help',
+          return refuse(
+            'help',
+            rest,
             `unknown command: ${verb}${didYouMeanVerb(verb, declared)} (see \`vx help\`)`,
+            'VX_E_UNKNOWN_COMMAND',
           )
-          return 1
         }
+        if (resolved !== null && !('loadError' in resolved)) return dispatch(verb, ['--help'])
       }
       await printHelp(await (await plugins()).pluginCommandHelp(), core ? verb : undefined)
       return 0
@@ -125,14 +155,17 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
       // takes no more of is refused, as every other verb refuses one.
       const extra = rest[0]
       if (extra !== undefined) {
-        sayNotice(
-          'error',
-          'vx version',
+        return refuse(
+          'version',
+          rest,
           `${refusedWord(extra)}: ${extra}${flagHint('version', extra)}${seeHelp('version')}`,
+          'VX_E_USAGE',
         )
-        return 1
       }
-      process.stdout.write(`vx ${VERSION}\n`)
+      // Painted, and the same words piped: a script reads `vx <version>`.
+      process.stdout.write(
+        `${ui.inline([ui.cmd('vx'), ' ', ui.tone('info', VERSION)], detectColors(process.stdout))}\n`,
+      )
       return 0
     }
     case 'run':
@@ -174,7 +207,7 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
           // A verb's own refusal is its one line; anything else is the
           // plugin's crash, named as every other stage names one.
           if (isUserError(err)) throw err
-          const message = err instanceof Error ? err.message : String(err)
+          const message = thrownMessage(err)
           throw new UserError(
             `plugin '${resolved.plugin.name}' failed in command '${command}': ${message}`,
           )
@@ -201,10 +234,12 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         text: string,
         code = 'VX_E_UNKNOWN_COMMAND',
         tone: 'error' | 'info' = 'error',
+        json = text.split('\n')[0]!,
       ): number => {
         sayNotice(tone, 'vx', text.replace(/^vx: /, '').trimEnd())
-        if (wantsJson(rest))
-          process.stdout.write(errorDocument(code, maskedLine(text.split('\n')[0]!)))
+        // `vx --format json` puts the flag where the verb goes.
+        if (wantsJson([command, ...rest]))
+          process.stdout.write(errorDocument(code, maskedLine(json)))
         return 1
       }
       const loadNote =
@@ -232,12 +267,13 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
         // provided by PLUGINS (declared in .vx/workspace.ts), never by core.
         // We keep this neutral hint for the common muscle-memory verbs, but
         // core names no specific plugin package: any package can provide
-        // these.
+        // these. The notice prints a line per fact, so each line is a
+        // whole sentence.
         return unknown(
-          `vx: '${command}' is not a vx core command.\n` +
-            `  vx core runs tasks in-process. A dashboard, remote cache, and\n` +
-            `  distributed execution come from plugins — not core. See the plugin\n` +
-            `  guide: https://vznjs.github.io/vx/guides/plugins/\n`,
+          `vx: \`${command}\` is not a vx core command.\n` +
+            `  vx core runs tasks in-process.\n` +
+            `  A dashboard, remote cache and distributed execution come from plugins, not core.\n` +
+            `  See the plugin guide: https://vznjs.github.io/vx/docs/plugins/\n`,
         )
       }
       // One line, as a verb's own unknown flag or subcommand gets; the full
@@ -259,9 +295,19 @@ async function dispatch(command: string | undefined, rest: string[]): Promise<nu
           'VX_E_USAGE',
         )
       }
+      // A workspace that does not load is the refusal to fix first: the
+      // verb may be its own plugin's.
+      if (resolved !== null && 'loadError' in resolved) {
+        return unknown(
+          `vx: unknown command: ${command}${guess}${loadNote} (see \`vx help\`)\n`,
+          'VX_E_CONFIG',
+          'error',
+          `vx: unknown command: ${command}; .vx/workspace failed to load: ${resolved.loadError}`,
+        )
+      }
       return unknown(
-        `vx: unknown command: ${command}${guess}${loadNote} (see \`vx help\`)\n` +
-          (guess === '' && loadNote === '' ? verbSourceNote(resolved, declaredVerbs) : ''),
+        `vx: unknown command: ${command}${guess} (see \`vx help\`)\n` +
+          (guess === '' ? verbSourceNote(resolved, declaredVerbs) : ''),
       )
     }
   }
@@ -298,6 +344,6 @@ function verbSourceNote(resolved: unknown, declaredVerbs: readonly string[]): st
   if (declaredVerbs.length > 0) {
     return `  This workspace's plugins declare: ${[...declaredVerbs].sort().join(', ')}.\n`
   }
-  const here = resolved === null ? 'there is no workspace here' : 'this workspace declares none'
+  const here = resolved === null ? 'there is no workspace here' : 'no plugin here adds one'
   return `  A plugin declared in .vx/workspace.ts can add verbs; ${here}.\n`
 }

package/src/cli/info.ts

@@ -113,20 +113,24 @@ export function renderInfo(f: InfoFacts, colors: ColorSupport = { enabled: false
     // the hits are a share of.
     [
       'task runs (24h)',
-      `${f.runs24h} (${f.hits24h} cache hits` +
+      `${f.runs24h} (${f.hits24h} cache hit${f.hits24h === 1 ? '' : 's'}` +
         (f.hits24h > 0
           ? `: ${f.hits24h - f.restored24h} up-to-date, ${f.restored24h} restored)`
           : ')'),
     ],
     ['flaky tasks', describeFlakyTasks(f.flakyTasks)],
     ['sandbox', describeSandbox(f.sandbox)],
-    ['projects lock', f.lockfile ? 'yes' : 'no'],
+    [
+      'projects lock',
+      typeof f.lockError === 'string' ? `refused: ${f.lockError}` : f.lockfile ? 'yes' : 'no',
+    ],
   ]
   return ui.report('vx info', rows).lines(colors).join('\n')
 }
 
-/** `812 (1.2 GB)`. */
+/** `812 (1.2 GB)`, or why the index cannot be read and its fix. */
 function describeEntries(f: InfoFacts): string {
+  if (f.cacheIndexError !== null) return `unreadable: ${f.cacheIndexError}`
   return `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`
 }
 
@@ -139,7 +143,7 @@ function describeSettings(settings: InfoFacts['settings']): string {
     .filter(([, s]) => s.source !== 'default')
     .map(
       ([path, s]) =>
-        `${path} ${String(s.value)} (${s.source === 'env' ? envName(path) : '.vx/workspace'})`,
+        `${path} ${String(s.value)} (${s.source === 'env' ? envName(path) : '.vx/workspace'}${s.refused === undefined ? '' : `, refused: ${s.refused}`})`,
     )
     .join(', ')
 }
@@ -169,9 +173,11 @@ function describeSandbox(s: InfoFacts['sandbox']): string {
 /** `4 — the CPU count`, `2 — cgroup CPU quota 2 of 8 cores`, `8 — .vx/workspace.ts (4 cores)`. */
 export function describeWorkers(w: InfoFacts['workers']): string {
   const quota = w.cpuQuota === null ? '' : `, cgroup CPU quota ${trimCores(w.cpuQuota)}`
-  if (w.source === 'workspace') return `${w.count} — .vx/workspace.ts (${w.cores} cores${quota})`
+  const cores = `${w.cores} core${w.cores === 1 ? '' : 's'}`
+  if (w.source === 'workspace') return `${w.count} — .vx/workspace.ts (${cores}${quota})`
+  if (w.source === 'env') return `${w.count} — ${envName('run.concurrency')} (${cores}${quota})`
   if (w.source === 'cgroup')
-    return `${w.count} — cgroup CPU quota ${trimCores(w.cpuQuota ?? w.count)} of ${w.cores} cores`
+    return `${w.count} — cgroup CPU quota ${trimCores(w.cpuQuota ?? w.count)} of ${cores}`
   return `${w.count} — the CPU count${quota}`
 }
 

package/src/cli/init.ts

@@ -1,12 +1,12 @@
 // `vx init [--dry [--format json]] [--force] [--mjs] [--native|--keep]` — a workspace from nowhere.
 // It installs vx globally and, where a package.json is, as its devDependency
-// (M, 2026-10-20). A Turbo or Nx repo is `@vzn/vx-migrate`'s, which maps it
+// (2026-10-20). A Turbo or Nx repo is `@vzn/vx-migrate`'s, which maps it
 // and installs what it writes (`migrate`); any other gets the workspace file
 // and an empty root project, then the lock (`starter`).
-// `vx init --plugin <seam>` writes a runnable plugin for one seam and its
+// `vx init --plugin <hook>` writes a runnable plugin for one hook and its
 // test instead (plugin-templates.ts, the examples the gate runs).
 
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { gitTop, workspaceFileWritten } from '../handoff.js'
@@ -22,10 +22,23 @@ import {
   type ManagedInstall,
 } from './upgrade.js'
 import { VERSION } from '../version.js'
-import { DOT_VX_GITATTRIBUTES, DOT_VX_GITIGNORE, ui, UserError, sayNotice } from '../util/index.js'
+import {
+  detectColors,
+  DOT_VX_GITATTRIBUTES,
+  DOT_VX_GITIGNORE,
+  paint,
+  refuseSymlink,
+  sayNotice,
+  SUCCESS,
+  ui,
+  UserError,
+  writeNoFollow,
+} from '../util/index.js'
 import {
   findWorkspaceRoot,
   PROJECT_CONFIG_FILENAMES,
+  renderWorkspace,
+  starterProject,
   WORKSPACE_CONFIG_FILENAMES,
 } from '../workspace/index.js'
 
@@ -34,7 +47,7 @@ interface InitArgs {
   force: boolean
   /** `vx.config.mjs` instead of `.ts` — see `ApplyMigrationArgs.format`. */
   mjs: boolean
-  /** `--plugin <seam>`: scaffold that seam's plugin instead of the workspace. */
+  /** `--plugin <hook>`: scaffold that hook's plugin instead of the workspace. */
   plugin?: string
   /** `--native` / `--keep` in a Turbo or Nx repo; unset, vx-migrate asks a terminal. */
   mode?: 'native' | 'keep'
@@ -53,7 +66,16 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
       if (seam === undefined || !Object.hasOwn(PLUGIN_TEMPLATES, seam)) {
         return {
           ...out,
-          error: `--plugin takes a seam: one of ${seams}${seam === undefined ? '' : ` (got '${seam}')`}${seeHelp('init')}`,
+          error:
+            seam === undefined || seam === ''
+              ? `--plugin requires a value: one of ${seams}${seeHelp('init')}`
+              : `--plugin must be one of ${seams} (got ${seam})${seeHelp('init')}`,
+        }
+      }
+      if (out.plugin !== undefined && out.plugin !== seam) {
+        return {
+          ...out,
+          error: `--plugin takes one hook; run vx init --plugin once per hook${seeHelp('init')}`,
         }
       }
       out.plugin = seam
@@ -116,16 +138,47 @@ export async function initCmd(args: readonly string[]): Promise<number> {
   if (dirs.some((d) => TOOL_CONFIGS.some((f) => existsSync(path.join(d, f))))) {
     return migrate(dirs, parsed)
   }
-  // The topmost package.json: a monorepo's root, wherever below it init ran.
-  const pkgRoot = dirs.findLast((d) => existsSync(path.join(d, 'package.json'))) ?? null
+  const pkgRoot = packageRoot(dirs, top !== null)
   return starter(marked ?? pkgRoot ?? cwd, pkgRoot, top === null, parsed)
 }
 
+/**
+ * Inside git, the topmost package.json: a monorepo's root, wherever below
+ * it init ran. Outside git `dirs` reach `/`, and the topmost took a stray
+ * package.json in the home directory (2026-10-28); there it is the nearest
+ * one, or the outermost above it that declares a workspace.
+ */
+function packageRoot(dirs: readonly string[], inGit: boolean): string | null {
+  const has = (d: string, f: string): boolean => existsSync(path.join(d, f))
+  if (inGit) return dirs.findLast((d) => has(d, 'package.json')) ?? null
+  const at = dirs.findIndex((d) => has(d, 'package.json'))
+  if (at === -1) return null
+  const outer = dirs
+    .slice(at + 1)
+    .findLast(
+      (d) => has(d, 'package.json') && (has(d, 'pnpm-workspace.yaml') || declaresWorkspaces(d)),
+    )
+  return outer ?? dirs[at]!
+}
+
+function declaresWorkspaces(dir: string): boolean {
+  try {
+    const pj = JSON.parse(
+      readFileSync(path.join(dir, 'package.json'), 'utf8').replace(/^\uFEFF/, ''),
+    ) as {
+      workspaces?: unknown
+    }
+    return pj.workspaces !== undefined
+  } catch {
+    return false
+  }
+}
+
 /** What makes a repo vx-migrate's to map: a Turbo or Nx config. */
 const TOOL_CONFIGS = ['turbo.json', 'turbo.jsonc', 'nx.json']
 
 /**
- * The installs `vx init` runs (M, 2026-10-20): vx at `version` globally,
+ * The installs `vx init` runs (2026-10-20): vx at `version` globally,
  * with the manager that started init, so a bare `vx` is on PATH, unless
  * the global vx already answers `version`; and, where `pkgRoot` has a
  * package.json, as its devDependency with the repo's own manager.
@@ -140,7 +193,9 @@ export function initInstalls(
 ): { argv: string[]; cwd: string | null }[] {
   const out: { argv: string[]; cwd: string | null }[] = []
   if (globalAt !== version) {
-    const runner = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? '')?.[1] ?? 'bun'
+    // Yarn 2+ has no `yarn global`: Bun, which vx needs anyway, as with no runner.
+    const ua = /^(npm|pnpm|yarn|bun)\/(\d+)/.exec(userAgent ?? '')
+    const runner = ua === null || (ua[1] === 'yarn' && Number(ua[2]) >= 2) ? 'bun' : ua[1]!
     const manager = runner as ManagedInstall['manager']
     out.push({ argv: upgradeArgv({ manager, scope: 'global', cwd: '' }, version), cwd: null })
   }
@@ -169,6 +224,21 @@ function globalVersion(): string | undefined {
   return undefined
 }
 
+/**
+ * The package a manager's output says the registry answered 404 for, as
+ * `name@version`: a release's platform tarball stays unserved for minutes
+ * after publish (v0.0.646, 2026-10-23). bun: `GET <url> - 404`; npm:
+ * `404 Not Found - GET <url>`; pnpm: `GET <url>: Not Found - 404`.
+ */
+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
+}
+
 /**
  * Run `initInstalls`, in order. A source checkout (0.0.0, which npm never
  * had) installs nothing: the release would replace the code under test.
@@ -200,22 +270,62 @@ async function install(
       'out',
       ui.text([ui.cmd(s.argv.join(' ')), ui.dim(s.cwd === null ? '' : ` in ${s.cwd}`)]),
     )
-    const proc = Bun.spawnSync({
+    const proc = Bun.spawn({
       cmd: [bin, ...s.argv.slice(1)],
       cwd: s.cwd ?? process.cwd(),
-      stdio: ['inherit', 'inherit', 'inherit'],
+      stdio: ['inherit', 'inherit', 'pipe'],
     })
-    if (proc.exitCode !== 0) {
-      throw new UserError(`vx init: ${s.argv.join(' ')} failed (exit ${proc.exitCode})`)
+    // Shown as it comes, and kept: a registry 404 is the cause to name.
+    let said = ''
+    const decoder = new TextDecoder()
+    for await (const chunk of proc.stderr) {
+      process.stderr.write(chunk)
+      said += decoder.decode(chunk, { stream: true })
+    }
+    const code = await proc.exited
+    if (code !== 0) {
+      const missing = notServed(said)
+      throw new UserError(
+        missing === undefined
+          ? `vx init: ${s.argv.join(' ')} failed (exit ${code})`
+          : `vx init: the npm registry does not serve ${missing} yet (404), as a release can take minutes to reach it; run bunx @vzn/vx init again`,
+      )
     }
   }
   return steps.map((s) => s.argv.join(' '))
 }
 
+const PLUGINS_MANIFEST = `${JSON.stringify({ name: 'workspace-plugins', private: true }, null, 2)}\n`
+
+/** Whether the nearest package.json above `dir` has a name, as `definePlugin` needs. */
+function ownerNamed(dir: string): boolean {
+  for (let d = dir; ; d = path.dirname(d)) {
+    let text: string
+    try {
+      text = readFileSync(path.join(d, 'package.json'), 'utf8').replace(/^/, '')
+    } catch {
+      if (path.dirname(d) === d) return false
+      continue
+    }
+    try {
+      const name = (JSON.parse(text) as { name?: unknown } | null)?.name
+      return typeof name === 'string' && name !== ''
+    } catch {
+      return false
+    }
+  }
+}
+
 /** Write `plugins/<seam>.ts` and its test under `root`: the workspace root, else the cwd. */
 async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promise<number> {
   const template = PLUGIN_TEMPLATES[seam]!
+  // `definePlugin` names the plugin by the nearest package.json, and a
+  // monorepo root often has no name: the plugin refused to load.
+  const manifest: [string, string][] = ownerNamed(path.join(root, 'plugins'))
+    ? []
+    : [[path.join('plugins', 'package.json'), PLUGINS_MANIFEST]]
   const files = [
+    ...manifest,
     [path.join('plugins', `${seam}.ts`), template.plugin],
     [path.join('plugins', `${seam}.test.ts`), template.test],
   ] as const
@@ -228,16 +338,26 @@ async function scaffoldPlugin(seam: string, root: string, args: InitArgs): Promi
     }
   }
   if (!args.dry) {
-    await mkdir(path.join(root, 'plugins'), { recursive: true })
+    await mkdir(path.join(root, 'plugins'), { recursive: true }).catch(
+      (err: NodeJS.ErrnoException) => {
+        if (err.code !== 'EEXIST' && err.code !== 'ENOTDIR') throw err
+        throw new UserError(
+          `vx init: cannot write ${files[0][0]}: plugins is a file, not a directory; move it and re-run`,
+        )
+      },
+    )
     for (const [rel, text] of files) await Bun.write(path.join(root, rel), text)
   }
   const factory = /^export function (\w+)/m.exec(template.plugin)![1]!
   const workspaceFile =
     WORKSPACE_CONFIG_FILENAMES.find((n) => existsSync(path.join(root, n))) ?? '.vx/workspace.ts'
+  const c = detectColors(process.stdout)
+  const dim = (t: string): string => paint('', t, c, { dim: true })
+  const bold = (t: string): string => paint('', t, c, { bold: true })
   process.stdout.write(
-    `${args.dry ? 'would write' : 'wrote'} ${files.map(([rel]) => rel).join(' and ')}\n` +
-      `Declare it in ${workspaceFile}: import { ${factory} } from '../plugins/${seam}.ts', then plugins: [${factory}(…)]\n` +
-      `Test it: bun test plugins/${seam}.test.ts (needs @vzn/vx installed)\n`,
+    `${paint(SUCCESS, args.dry ? 'would write' : 'wrote', c, { bold: true })} ${files.map(([rel]) => bold(rel)).join(' and ')}\n` +
+      `${dim('Declare it in')} ${workspaceFile}${dim(':')} ${bold(`import { ${factory} } from '../plugins/${seam}.ts'`)}${dim(', then')} ${bold(`plugins: [${factory}(…)]`)}\n` +
+      `${dim('Test it:')} ${bold(`bun test plugins/${seam}.test.ts`)} ${dim('(needs @vzn/vx installed)')}\n`,
   )
   return 0
 }
@@ -257,13 +377,30 @@ function lockfilePlugin(pkgRoot: string | null): 'pnpm' | 'bun' | 'yarn' | 'npm'
   return null
 }
 
-function workspaceSource(plugin: string | null): string {
-  if (plugin === null)
-    return "import { defineWorkspace } from '@vzn/vx'\n\nexport default defineWorkspace({ plugins: [] })\n"
-  return `import { defineWorkspace } from '@vzn/vx'\nimport { ${plugin} } from '@vzn/vx-lockfile'\n\nexport default defineWorkspace({ plugins: [${plugin}()] })\n`
+/**
+ * Whether `pkgRoot` has package.json scripts to map: its own, or a
+ * workspace's members (`workspaces`, `pnpm-workspace.yaml`). Core maps none
+ * (2026-10-20), so `next` names the tool that does.
+ */
+function hasScripts(pkgRoot: string | null): boolean {
+  if (pkgRoot === null) return false
+  if (existsSync(path.join(pkgRoot, 'pnpm-workspace.yaml'))) return true
+  try {
+    // A byte-order mark is stripped, as npm strips it.
+    const pj = JSON.parse(
+      readFileSync(path.join(pkgRoot, 'package.json'), 'utf8').replace(/^/, ''),
+    ) as {
+      scripts?: unknown
+      workspaces?: unknown
+    }
+    return (
+      pj.workspaces !== undefined ||
+      (typeof pj.scripts === 'object' && pj.scripts !== null && Object.keys(pj.scripts).length > 0)
+    )
+  } catch {
+    return false
+  }
 }
-const PROJECT =
-  "import { defineProject } from '@vzn/vx'\n\nexport default defineProject({ tasks: {} })\n"
 
 /**
  * No Turbo or Nx config: the installs, then `.vx/workspace.ts` declaring
@@ -280,6 +417,7 @@ async function starter(
   if (args.mode !== undefined) {
     throw new UserError(
       `vx init: --${args.mode} answers a Turbo or Nx repo's question, and there is no turbo.json or nx.json here`,
+      'VX_E_USAGE',
     )
   }
   // A source checkout installs nothing, so it declares the plugin only where one is.
@@ -298,8 +436,12 @@ async function starter(
   const kept: string[] = []
   const replaced: string[] = []
   for (const [names, name, contents] of [
-    [WORKSPACE_CONFIG_FILENAMES, `.vx/workspace.${ext}`, workspaceSource(plugin)],
-    [PROJECT_CONFIG_FILENAMES, config, PROJECT],
+    [
+      WORKSPACE_CONFIG_FILENAMES,
+      `.vx/workspace.${ext}`,
+      renderWorkspace(ext, plugin === null ? [] : [{ pkg: '@vzn/vx-lockfile', factory: plugin }]),
+    ],
+    [PROJECT_CONFIG_FILENAMES, config, starterProject(ext)],
   ] as const) {
     const existing = names.find((n) => existsSync(path.join(root, n)))
     if (existing !== undefined && !args.force) kept.push(existing)
@@ -315,7 +457,8 @@ async function starter(
   ] as const) {
     if (!existsSync(path.join(root, name))) files.push({ path: name, contents })
   }
-  const next = `${noGit ? 'git init, ' : ''}declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then vx lock && vx run <task>`
+  const declare = `declare a task in ${kept.find((f) => f.startsWith('vx.config.')) ?? config}, then vx lock && vx run <task>`
+  const next = `${noGit ? 'git init, ' : ''}${hasScripts(pkgRoot) ? `bunx @vzn/vx-migrate${args.mjs ? ' --mjs' : ''} to make package.json scripts tasks, or ${declare}` : declare}`
   if (args.json === true) {
     process.stdout.write(
       `${JSON.stringify({ dry: true, source: 'no turbo.json or nx.json', files, kept, replaced, todos: [], notes: [], next, installs })}\n`,
@@ -323,19 +466,30 @@ async function starter(
     return 0
   }
   const rows: ui.FieldRow[] = [['from', 'no turbo.json or nx.json: one project, the root']]
+  // The files are root-relative: a root above the cwd is named, or they read as written here.
+  if (root !== process.cwd()) rows.push(['root', root])
   if (args.dry) rows.push(['dry run', 'nothing written'])
   if (installs.length > 0) rows.push(['install', ...installs])
   if (files.length > 0) rows.push(['files', ...files.map((f) => f.path)])
   if (kept.length > 0) rows.push(['kept', ...kept])
   if (replaced.length > 0) rows.push(['replaced', ...replaced])
   if (args.dry) {
-    for (const f of files) process.stdout.write(`── ${f.path} ──\n${f.contents}\n`)
+    for (const f of files) ui.print('out', ui.excerpt(f.path, f.contents))
     ui.print('out', ui.report(`vx init ${VERSION}`, [...rows, null, ['next', next]]))
     return 0
   }
+  for (const f of files) refuseSymlink(path.join(root, f.path))
   const ran = await install(pkgRoot, false, plugins)
   if (ran.length > 0) rows.push(['installed', ...ran])
-  for (const f of files) await Bun.write(path.join(root, f.path), f.contents)
+  for (const f of files) {
+    await writeNoFollow(path.join(root, f.path), f.contents).catch((err: NodeJS.ErrnoException) => {
+      // writeNoFollow's mkdir of a parent that is a file says EEXIST.
+      if (err.code !== 'ENOTDIR' && err.code !== 'EEXIST') throw err
+      throw new UserError(
+        `vx init: cannot write ${f.path}: ${path.dirname(f.path)} is a file, not a directory; move it and re-run`,
+      )
+    })
+  }
   for (const f of replaced) await unlink(path.join(root, f))
   // The lock that follows loads the workspace file just written.
   workspaceFileWritten()
@@ -345,14 +499,15 @@ async function starter(
     lock.code === 0 ? next : `fix the above, then vx lock and ${next}`,
   ])
   ui.print('out', ui.report(`vx init ${VERSION}`, rows))
-  return 0
+  // A run reads only the lock: init without one is not done, as vx-migrate exits.
+  return lock.code === 0 ? 0 : 1
 }
 
 /**
  * A Turbo or Nx repo is `@vzn/vx-migrate`'s, after the global install, at the latest
  * release: it installs @vzn/vx and every @vzn/vx-* plugin the root lists
  * at its own version, so init always lands on latest with all of them
- * together, as `vx upgrade` moves them (M, 2026-10-16: an installed 0.0.637
+ * together, as `vx upgrade` moves them (2026-10-16: an installed 0.0.637
  * pinned core back from 0.0.639). It finds the root itself, asks a
  * terminal native or keep in a Turbo or Nx repo, and installs what it writes.
  */