@vzn/vx 0.0.637 → 0.0.639

package/src/util/ui.ts

@@ -0,0 +1,197 @@
+// vx's output components (org/devex/log-design.md). A verb or a plugin
+// composes these instead of writing raw lines: each component owns its
+// color, indent and spacing, so every surface shares one look. Colors
+// are decided at print time, per stream.
+
+import {
+  detectColors,
+  ERROR,
+  identityColor,
+  paint,
+  SUCCESS,
+  WARN,
+  type ColorSupport,
+} from './colors.js'
+import { gradientRule } from './report.js'
+
+export type Tone = 'ok' | 'warn' | 'error' | 'info'
+
+const INFO = '#06b6d4'
+const HUE: Record<Tone, string> = { ok: SUCCESS, warn: WARN, error: ERROR, info: INFO }
+const SYMBOL: Record<Tone, string> = { ok: '✓', warn: '!', error: '✗', info: '›' }
+const INDENT = '  '
+const LABEL_MIN = 8
+
+type Style = Tone | 'dim' | 'bold' | 'id'
+
+/** Styled text inside a component: a plain string, a token, or a run of them. */
+export type Inline = string | { readonly style: Style; readonly text: string } | readonly Inline[]
+
+/** A laid-out piece of output; `render` and `print` space blocks apart. */
+export interface Block {
+  readonly lines: (colors: ColorSupport) => string[]
+}
+
+/** A `project` or `project#task` id, each half in its name's hue, the `#` dim. */
+export const id = (text: string): Inline => ({ style: 'id', text })
+/** A path, glob or file: bold. */
+export const path = (text: string): Inline => ({ style: 'bold', text })
+/** A command to type: bold. */
+export const cmd = (text: string): Inline => ({ style: 'bold', text })
+/** A secondary fact. */
+export const dim = (text: string): Inline => ({ style: 'dim', text })
+/** Text in a tone's color. */
+export const tone = (t: Tone, text: string): Inline => ({ style: t, text })
+
+function inline(x: Inline, c: ColorSupport): string {
+  if (typeof x === 'string') return x
+  if (Array.isArray(x)) return (x as readonly Inline[]).map((p) => inline(p, c)).join('')
+  const { style, text } = x as { style: Style; text: string }
+  switch (style) {
+    case 'dim':
+      return paint('', text, c, { dim: true })
+    case 'bold':
+      return paint('', text, c, { bold: true })
+    case 'id': {
+      const hash = text.lastIndexOf('#')
+      if (hash < 0) return paint(identityColor(text), text, c)
+      const task = text.slice(hash + 1)
+      return (
+        paint(identityColor(text.slice(0, hash)), text.slice(0, hash), c) +
+        paint('', '#', c, { dim: true }) +
+        paint(identityColor(task), task, c)
+      )
+    }
+    default:
+      return paint(HUE[style], text, c)
+  }
+}
+
+const block = (lines: (c: ColorSupport) => string[]): Block => ({ lines })
+const lines = (x: Inline, c: ColorSupport): string[] => inline(x, c).split('\n')
+const visible = (s: string): number => Bun.stringWidth(s)
+
+/** `✗ vx lock  lock not written`: the tone's symbol, the bold verb, the headline. */
+export function status(t: Tone, verb: string, headline: Inline): Block {
+  return block((c) => [
+    `${paint(HUE[t], SYMBOL[t], c)} ${paint('', verb, c, { bold: true })}  ${inline(headline, c)}`,
+  ])
+}
+
+/** Indented short lines: what is wrong, or what happened. */
+export function text(...items: Inline[]): Block {
+  return block((c) => items.flatMap((i) => lines(i, c).map((l) => `${INDENT}${l}`)))
+}
+
+/** An indented dim line: why it matters. */
+export function why(line: Inline): Block {
+  return block((c) => lines(line, c).map((l) => `${INDENT}${paint('', l, c, { dim: true })}`))
+}
+
+/** A label and its values; values after the first sit under it. `null` is a blank line. */
+export type FieldRow = readonly [label: string, ...values: Inline[]] | null
+
+/** A dim label column with the values aligned beside it; `next` and `fix` are bold. */
+export function fields(rows: readonly FieldRow[]): Block {
+  return block((c) => {
+    const width = Math.max(LABEL_MIN, ...rows.map((r) => (r === null ? 0 : r[0].length)))
+    const out: string[] = []
+    for (const row of rows) {
+      if (row === null) {
+        out.push('')
+        continue
+      }
+      const [label, ...values] = row
+      const strong = label === 'next' || label === 'fix'
+      values
+        .flatMap((v) => lines(v, c))
+        .forEach((v, i) => {
+          const head =
+            i === 0 ? paint('', label.padEnd(width), c, { dim: true }) : ' '.repeat(width)
+          const value = strong ? paint('', v, c, { bold: true }) : v
+          out.push(`${INDENT}${head}  ${value}`.trimEnd())
+        })
+    }
+    return out
+  })
+}
+
+/** `fix  <action>`: what to do about it. */
+export function fix(action: Inline): Block {
+  return labelled('fix', action)
+}
+
+/** `next  <command>`: the command to type next. */
+export function next(command: Inline): Block {
+  return labelled('next', command)
+}
+
+function labelled(label: string, value: Inline): Block {
+  return block((c) => [
+    `${INDENT}${paint('', label, c, { dim: true })}  ${paint('', inline(value, c), c, { bold: true })}`,
+  ])
+}
+
+/** A report: a blank line, the brand rule naming `mark`, then its fields. */
+export function report(mark: string, rows: readonly FieldRow[]): Block {
+  return block((c) => ['', gradientRule(c, mark), ...fields(rows).lines(c)])
+}
+
+/** Aligned columns under a dim header. */
+export function table(columns: readonly string[], rows: readonly (readonly Inline[])[]): Block {
+  return block((c) => {
+    const cells = rows.map((r) => r.map((x) => inline(x, c)))
+    const widths = columns.map((h, i) =>
+      Math.max(h.length, ...cells.map((r) => visible(r[i] ?? ''))),
+    )
+    const pad = (s: string, i: number): string =>
+      i === columns.length - 1 ? s : s + ' '.repeat(widths[i]! - visible(s))
+    return [
+      `${INDENT}${paint('', columns.map((h, i) => pad(h, i)).join('  '), c, { dim: true })}`.trimEnd(),
+      ...cells.map((r) => `${INDENT}${r.map(pad).join('  ')}`.trimEnd()),
+    ]
+  })
+}
+
+/** A source frame (`> 1 | …` and its caret), indented. */
+export function code(frame: string): Block {
+  return block(() => frame.split('\n').map((l) => (l === '' ? '' : `${INDENT}${l}`)))
+}
+
+export interface NoticeParts {
+  tone: Tone
+  verb: string
+  headline: Inline
+  /** What is wrong, one fact a line. */
+  what?: readonly Inline[]
+  why?: Inline
+  /** A source frame, below the facts. */
+  code?: string
+  fix?: Inline
+}
+
+/** A refusal or a warning: status, then what and why, the frame, and the fix, a blank line apart. */
+export function notice(p: NoticeParts): Block {
+  return block((c) => {
+    const parts: Block[] = [status(p.tone, p.verb, p.headline)]
+    const body = [
+      ...(p.what !== undefined ? [text(...p.what)] : []),
+      ...(p.why !== undefined ? [why(p.why)] : []),
+    ]
+    if (body.length > 0) parts.push(block((cc) => body.flatMap((b) => b.lines(cc))))
+    if (p.code !== undefined) parts.push(code(p.code))
+    if (p.fix !== undefined) parts.push(fix(p.fix))
+    return parts.flatMap((b, i) => (i === 0 ? b.lines(c) : ['', ...b.lines(c)]))
+  })
+}
+
+/** The blocks as text, a blank line apart, ending in a newline. */
+export function render(blocks: readonly Block[], colors: ColorSupport): string {
+  return `${blocks.map((b) => b.lines(colors).join('\n')).join('\n\n')}\n`
+}
+
+/** Write the blocks to stdout (`out`) or stderr (`err`), colored for that stream. */
+export function print(stream: 'out' | 'err', ...blocks: Block[]): void {
+  const s = stream === 'out' ? process.stdout : process.stderr
+  s.write(render(blocks, detectColors(s)))
+}

package/src/workspace/affected.ts

@@ -143,6 +143,8 @@ export interface AffectedChanges {
   /** Project → its changed paths, relative to the project's directory. */
   paths: ReadonlyMap<string, readonly string[]>
   whole: ReadonlySet<string>
+  /** A whole project → the workspace-wide file that made it so (a workspace config, a claimed root file). */
+  wholeBy?: ReadonlyMap<string, string>
   /**
    * The changed paths that are nested repositories (a submodule, an
    * embedded repository), workspace-relative: each stands for every file
@@ -269,11 +271,17 @@ export async function affectedChanges(
   // itself, so an unclaimed one is a path like any other.
   //
   // Selection is not hashed, so widening it here changes no cache key.
-  const everything = (): AffectedChanges => {
+  const everything = (file: string): AffectedChanges => {
     const all = new Set(args.projects.map((p) => p.name))
-    return { projects: all, changed, paths: new Map(), whole: all }
+    const wholeBy = new Map([...all].map((n) => [n, file]))
+    return { projects: all, changed, paths: new Map(), whole: all, wholeBy }
   }
-  if (workspaceConfigChanged(changed)) return everything()
+  // The workspace config's plugins shape every project's resolved config,
+  // so its edit can re-key any task and selection cannot tell which (item
+  // 953). No key folds the file; selection is not hashed, so widening here
+  // changes no key.
+  const wsConfig = WORKSPACE_CONFIG_FILENAMES.find((n) => changed.includes(n))
+  if (wsConfig !== undefined) return everything(wsConfig)
   // Loading the workspace file costs an evaluation; only a changed ROOT
   // name can be claimed, so a diff inside the projects never loads it.
   let claims: FingerprintClaims | undefined
@@ -287,12 +295,13 @@ export async function affectedChanges(
     const lock = await bytesOrNull(path.join(args.workspaceRoot, 'bun.lock'))
     if (lock !== null) {
       const patches = new Set(bunPatchFiles(lock))
-      if (changed.some((p) => patches.has(p)) && (await loadClaims())?.files.has('bun.lock')) {
-        return everything()
+      const patch = changed.find((p) => patches.has(p))
+      if (patch !== undefined && (await loadClaims())?.files.has('bun.lock')) {
+        return everything(patch)
       }
     }
   }
-  const claimedOwned = new Set<string>()
+  const claimedOwned = new Map<string, string>()
   const rootNamesChanged = changed.filter((p) => !p.includes('/'))
   const claimed = rootNamesChanged.length > 0 ? await loadClaims() : undefined
   for (const file of rootNamesChanged) {
@@ -302,8 +311,8 @@ export async function affectedChanges(
       before: await gitBytesAt(args.workspaceRoot, base, file),
       after: await bytesOrNull(path.join(args.workspaceRoot, file)),
     })
-    if (answer === undefined) return everything()
-    for (const name of answer) claimedOwned.add(name)
+    if (answer === undefined) return everything(file)
+    for (const name of answer) if (!claimedOwned.has(name)) claimedOwned.set(name, file)
   }
 
   const realDirs = new Map(
@@ -312,7 +321,7 @@ export async function affectedChanges(
     ),
   )
   const paths = new Map<string, string[]>()
-  const whole = new Set<string>(claimedOwned)
+  const whole = new Set<string>(claimedOwned.keys())
   const owned = projectsContaining(
     args.workspaceRoot,
     changed,
@@ -330,7 +339,7 @@ export async function affectedChanges(
         }
       : undefined,
   )
-  for (const name of claimedOwned) owned.add(name)
+  for (const name of claimedOwned.keys()) owned.add(name)
 
   // A config that makes an existing directory a project took files from
   // the project above it.
@@ -367,6 +376,7 @@ export async function affectedChanges(
     changed,
     paths,
     whole,
+    ...(claimedOwned.size > 0 ? { wholeBy: claimedOwned } : {}),
     ...(nestedDirs.length > 0 ? { nested: nestedDirs } : {}),
   })
   if (changed.length === 0 || args.workspaceGlobOwners === undefined) return done()
@@ -462,19 +472,6 @@ async function gitBlobsAt(
   return blobs
 }
 
-/**
- * Whether `changed` holds the workspace config. Its plugins' `config` and
- * `project` stages shape every project's resolved config, so such an edit
- * can re-key any task, and selection cannot tell which: an edit that
- * changed every key selected nothing (item 953). No key folds the file
- * (its placement plugins must not split a cache between machines); a
- * stage it installs re-keys through the resolved configs instead.
- * Selection is not hashed, so widening here changes no key.
- */
-function workspaceConfigChanged(changed: readonly string[]): boolean {
-  return WORKSPACE_CONFIG_FILENAMES.some((n) => changed.includes(n))
-}
-
 /**
  * A root file's bytes at `ref`, or null when the ref has no such file.
  * `./` anchors the path to the cwd (the workspace root) rather than the

package/src/workspace/dependency-rules.ts

@@ -1,5 +1,5 @@
 import type { DependencyRule } from '../config.js'
-import { UserError } from '../util/index.js'
+import { refusal } from '../util/index.js'
 import { compileNameGlob } from './filter.js'
 import type { PackageGraph } from './package-graph.js'
 
@@ -40,9 +40,17 @@ export function checkDependencyRules(
     }
   }
   if (broken.length === 0) return
-  throw new UserError(
-    `${broken.length === 1 ? '1 dependency breaks' : `${broken.length} dependencies break`} run.rules.dependencies:\n${broken.map((b) => `  ${b}`).join('\n')}\nDrop the dependency, or change the project's tags or the rule.`,
-    'VX_E_DEPENDENCY_RULE',
+  const headline = `${broken.length === 1 ? '1 dependency breaks' : `${broken.length} dependencies break`} run.rules.dependencies`
+  throw refusal(
+    {
+      headline,
+      what: broken,
+      fix: "drop the dependency, or change the project's tags or the rule",
+    },
+    {
+      code: 'VX_E_DEPENDENCY_RULE',
+      message: `${headline}:\n${broken.map((b) => `  ${b}`).join('\n')}\nDrop the dependency, or change the project's tags or the rule.`,
+    },
   )
 }
 

package/src/workspace/migration.ts

@@ -9,7 +9,8 @@ import { existsSync, readFileSync } from 'node:fs'
 import { unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { workspaceFileWritten } from '../handoff.js'
-import { DOT_VX_GITIGNORE, executablePath, gitEnv, relPosix, UserError } from '../util/index.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'
 
 /**
@@ -136,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[]
 }
 
@@ -177,7 +180,7 @@ export interface ApplyMigrationArgs {
    * 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
@@ -205,11 +208,14 @@ export interface ApplyMigrationArgs {
   /**
    * 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). Prints its own line. A refusal (a graph rule, a
-   * plugin not installed yet) is printed and the migration still succeeds:
-   * its files are written, and `vx lock` is the step to re-run.
+   * (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<number>
+  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[]
 }
@@ -363,89 +369,20 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   )
   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[] = []
-  const emptyReason = empty ? args.emptyReason : undefined
-  if (emptyReason !== undefined) {
-    report.push(
-      `${verb}: ${emptyReason}`,
-      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.`,
-      ...[...(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} → ${[...new Set(names.values())].join(', ') || configName}`)
-    for (const n of [...(args.notes ?? []), ...ignoredNote, ...formatted]) 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:')
-    report.push(...fileLines(files.map((f) => 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,
@@ -460,6 +397,14 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     ...(!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({
@@ -471,24 +416,75 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
         todos: [...todos].map(([reason, tasks]) => ({ reason, tasks })),
         notes: [
           ...(emptyReason === undefined ? [] : [emptyReason]),
-          ...(args.notes ?? []),
-          ...ignoredNote,
-          ...plan.headerNotes,
-          ...plan.notes,
+          ...(args.steps ?? []).map(([label, value]) => `${label}: ${value}`),
+          ...notes,
         ],
         next,
       })}\n`,
     )
     return 0
   }
-  if (dry || args.lock === undefined) {
-    report.push('', `next: ${next}`)
-    process.stdout.write(`${report.join('\n')}\n`)
-    return 0
+
+  // 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(),
+    ])
   }
-  process.stdout.write(`${report.join('\n')}\n\n`)
-  const locked = (await args.lock(root)) === 0
-  process.stdout.write(`\nnext: ${locked ? next : `fix the above and run vx lock, then ${next}`}\n`)
+  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
 }
 
@@ -615,10 +611,9 @@ export function vxInvocation(userAgent: string | undefined, installed: boolean):
 const FILES_SHOWN = 10
 
 function fileLines(paths: readonly string[]): string[] {
-  if (paths.length <= FILES_SHOWN) return paths.map((p) => `  ${p}`)
+  if (paths.length <= FILES_SHOWN) return [...paths]
   const root = paths.filter((p) => !p.includes('/') || p.startsWith('.vx/'))
-  const more = paths.length - root.length
-  return [...root.map((p) => `  ${p}`), `  and ${more} more in package directories`]
+  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). */
@@ -691,6 +686,7 @@ 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(p.tasks.length === 0 ? '  tasks: {},' : '  tasks: {')
   for (const t of p.tasks) {

package/src/workspace/workspace.ts

@@ -15,6 +15,7 @@ import {
   gitSpawnRefusal,
   isExecutableMissing,
   isOutOfFds,
+  refusal,
   relPosix,
   UserError,
 } from '../util/index.js'
@@ -75,10 +76,10 @@ export async function findWorkspaceRoot(
   start = path.resolve(start)
   const file = await workspaceFile(start)
   if (file === null) {
-    throw new UserError(
-      `no .vx/workspace.ts in ${start} or a parent${(await gitTop(start)) === null ? '' : ' up to the git root'} — ` +
-        'run `vx init` to create one',
-      'VX_E_NO_WORKSPACE',
+    const headline = `no .vx/workspace.ts in ${start} or a parent${(await gitTop(start)) === null ? '' : ' up to the git root'}`
+    throw refusal(
+      { headline, fix: 'vx init' },
+      { code: 'VX_E_NO_WORKSPACE', message: `${headline} — run \`vx init\` to create one` },
     )
   }
   const root = workspaceRootOf(file)