@vzn/vx 0.0.630 → 0.0.632

package/src/cli/init.ts

@@ -1,8 +1,9 @@
-// `vx init [--dry] [--force] [--mjs]` — a workspace from nowhere: one vx.config.ts
-// per package from its package.json scripts, and the workspace file every
-// run needs. In a Turbo or Nx repo it writes only the workspace file,
-// declaring `turbo()` or `nx()` from `@vzn/vx-migrate`, which read the
-// runner's own config live (`adopt`).
+// `vx init [--dry] [--force] [--mjs] [--native|--keep]` — a workspace from nowhere:
+// one vx.config.ts per package from its package.json scripts, and the
+// workspace file every run needs. In a Turbo or Nx repo it hands over to
+// `@vzn/vx-migrate` (`migrate`), which asks a terminal whether to write
+// native config; `--keep` writes only the workspace file, declaring
+// `turbo()` or `nx()`, which read the runner's own config live (`adopt`).
 // `vx init --plugin <seam>` writes a runnable plugin for one seam and its
 // test instead (plugin-templates.ts, the examples the gate runs).
 
@@ -11,6 +12,8 @@ import { mkdir, unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
+import { isCompiledBinary } from './upgrade.js'
+import { VERSION } from '../version.js'
 import { isUserError, relPosix, UserError } from '../util/index.js'
 import {
   applyMigration,
@@ -29,6 +32,8 @@ interface InitArgs {
   mjs: boolean
   /** `--plugin <seam>`: scaffold that seam'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'
   error?: string
 }
 
@@ -49,10 +54,22 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
     } else if (a === '--dry') out.dry = true
     else if (a === '--force') out.force = true
     else if (a === '--mjs') out.mjs = true
-    else if (a.startsWith('-'))
+    else if (a === '--native' || a === '--keep') {
+      const mode = a === '--native' ? 'native' : 'keep'
+      if (out.mode !== undefined && out.mode !== mode) {
+        return {
+          ...out,
+          error: `--native and --keep are two answers to one question; pass one${seeHelp('init')}`,
+        }
+      }
+      out.mode = mode
+    } else if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('init', a)}${seeHelp('init')}` }
     else return { ...out, error: `unexpected argument: ${a}${seeHelp('init')}` }
   }
+  if (out.plugin !== undefined && out.mode !== undefined) {
+    return { ...out, error: `--${out.mode} does not combine with --plugin${seeHelp('init')}` }
+  }
   if (out.plugin !== undefined && out.mjs) {
     return {
       ...out,
@@ -73,7 +90,7 @@ export async function initCmd(args: readonly string[]): Promise<number> {
   // "a workspace from nowhere" still needs a package.json to start from,
   // and the lookup's own refusal named no next step.
   const root = await findWorkspaceRoot(process.cwd(), reads).catch((err: unknown) => {
-    if (isUserError(err) && err.message.startsWith('Could not find a workspace root')) {
+    if (isUserError(err) && err.code === 'VX_E_NO_WORKSPACE') {
       throw new UserError(
         'vx init: no package.json here or in any parent directory; create one (`bun init` or `npm init -y`) and run vx init again',
       )
@@ -95,14 +112,42 @@ export async function initCmd(args: readonly string[]): Promise<number> {
       break
     }
   }
-  // A Turbo or Nx repo already says its tasks: the runner's own config is
-  // the source, and `turbo()` / `nx()` read it live. Writing a config per
-  // package from the scripts dropped every edge turbo.json declares (the
-  // first-five-minutes walk, 2026-09-28); the workspace file alone is the
-  // whole adoption, and `bunx @vzn/vx-migrate` stays for freezing it.
-  if (turbo !== undefined) return adopt(root, 'turbo', turbo, parsed)
-  if (await Bun.file(path.join(root, 'nx.json')).exists()) {
-    return adopt(root, 'nx', 'nx.json', parsed)
+  // A Turbo or Nx repo already says its tasks: writing a config per package
+  // from the scripts dropped every edge turbo.json declares (the
+  // first-five-minutes walk, 2026-09-28). vx-migrate maps the runner's own
+  // config, so `vx init` is the one command (M, 2026-10-08); its `--keep`
+  // comes back here for the workspace file alone.
+  const runner: ['turbo' | 'nx', string] | undefined =
+    turbo !== undefined
+      ? ['turbo', turbo]
+      : (await Bun.file(path.join(root, 'nx.json')).exists())
+        ? ['nx', 'nx.json']
+        : undefined
+  if (runner !== undefined) {
+    if (parsed.mode === 'keep') return adopt(root, ...runner, parsed)
+    // A second `vx init` after the native migration refused to overwrite
+    // the configs it wrote, exit 1, after a package fetch: the first-run
+    // walk (2026-10-09). Set up is an answer, with the next step.
+    const existing = WORKSPACE_CONFIG_FILENAMES.find((f) => existsSync(path.join(root, f)))
+    if (
+      existing !== undefined &&
+      !parsed.force &&
+      !parsed.dry &&
+      parsed.mode === undefined &&
+      metas.some((m) => m.configPath !== null) &&
+      !readFileSync(path.join(root, existing), 'utf8').includes(`${runner[0]}(`)
+    ) {
+      process.stdout.write(
+        `vx is already set up here (${existing} and the projects' vx.config files); --force regenerates them from ${runner[1]}.\n\nnext: ${adoptionNext(root, ...runner, ['@vzn/vx'])}\n`,
+      )
+      return 0
+    }
+    return migrate(root, parsed)
+  }
+  if (parsed.mode !== undefined) {
+    throw new UserError(
+      `vx init: --${parsed.mode} answers a Turbo or Nx repo's question, and no turbo.json or nx.json is at ${relPosix(process.cwd(), root) || '.'}`,
+    )
   }
   const unmapped = namelessNotes(root, nameless)
   return applyMigration({
@@ -156,7 +201,35 @@ async function scaffoldPlugin(seam: string, args: InitArgs): Promise<number> {
 }
 
 /**
- * `vx init` in a Turbo or Nx repo: `vx.workspace.ts` declaring the plugin
+ * `vx init` in a Turbo or Nx repo runs `@vzn/vx-migrate`: the installed one,
+ * else this version's through `bun x`. It asks a terminal native or keep,
+ * installs what it writes, and runs `vx init --keep` for keep.
+ */
+async function migrate(root: string, args: InitArgs): Promise<number> {
+  const flags = [
+    args.dry && '--dry',
+    args.force && '--force',
+    args.mjs && '--mjs',
+    args.mode === 'native' && '--native',
+  ].filter((f): f is string => typeof f === 'string')
+  return Bun.spawn(migrateCommand(root, flags), {
+    cwd: root,
+    stdio: ['inherit', 'inherit', 'inherit'],
+    // A compiled vx is a Bun runtime only when told so.
+    env: isCompiledBinary() ? { ...process.env, BUN_BE_BUN: '1' } : process.env,
+  }).exited
+}
+
+export function migrateCommand(root: string, flags: readonly string[]): string[] {
+  const installed = path.join(root, 'node_modules', '@vzn', 'vx-migrate', 'src', 'bin.ts')
+  if (existsSync(installed)) return [process.execPath, '--no-install', installed, ...flags]
+  // A source checkout is 0.0.0, which npm never had.
+  const version = VERSION === '0.0.0' ? 'latest' : VERSION
+  return [process.execPath, 'x', `@vzn/vx-migrate@${version}`, ...flags]
+}
+
+/**
+ * `vx init --keep` in a Turbo or Nx repo: `vx.workspace.ts` declaring the plugin
  * that runs the repo as it is, nothing else, and the one command that gets
  * from here to a run.
  */
@@ -206,7 +279,7 @@ async function adopt(
           ? ''
           : `${cache}(): ${remote}, so vx shares that remote cache (inert where the variable is unset).\n`
   process.stdout.write(
-    `vx init: ${source} found — ${runner}() from @vzn/vx-migrate, a temporary start until bunx @vzn/vx-migrate writes native config; nothing else written.\n` +
+    `vx init: ${source} found — ${runner}() from @vzn/vx-migrate, a temporary start until vx init --native writes native config; nothing else written.\n` +
       `${wrote}\n${cacheLine}\nnext: ${adoptionNext(root, runner, source)}\n`,
   )
   return 0
@@ -320,9 +393,14 @@ const INSTALL: Record<PackageManager, string> = {
 const EXEC: Record<PackageManager, string> = { pnpm: 'pnpm', yarn: 'yarn', bun: 'bunx', npm: 'npx' }
 
 /** Install what the workspace file imports, if missing, then run the repo's build. */
-export function adoptionNext(root: string, runner: 'turbo' | 'nx', source: string): string {
+export function adoptionNext(
+  root: string,
+  runner: 'turbo' | 'nx',
+  source: string,
+  needs: readonly string[] = ['@vzn/vx', '@vzn/vx-migrate'],
+): string {
   const pm = LOCKFILES.find(([f]) => existsSync(path.join(root, f)))?.[1] ?? 'npm'
-  const missing = ['@vzn/vx', '@vzn/vx-migrate'].filter(
+  const missing = needs.filter(
     (p) => !existsSync(path.join(root, 'node_modules', p, 'package.json')),
   )
   // A global vx (no runner started this one) runs the workspace's plugins as they are.

package/src/cli/last.ts

@@ -17,7 +17,9 @@ import {
   outcomeWord,
   type RunSummaryRow,
   resolveRunId,
+  runFailures,
   shortRunId,
+  taskLog,
 } from '../orchestrator/index.js'
 import { formatElapsed, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
@@ -29,6 +31,8 @@ interface LastArgs {
   /** Only runs that failed: the latest one replayed, or the list narrowed. */
   failed?: boolean
   format: 'pretty' | 'json'
+  /** `--log <task>`: that task's output in the run, not the run's summary. */
+  log?: string
   /** `--cache-dir`: read the history a run with the same flag wrote. */
   cacheDir?: string
   error?: string
@@ -72,6 +76,14 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       out.failed = true
       continue
     }
+    if (a === '--log' || a.startsWith('--log=')) {
+      const v = a === '--log' ? args[++i] : a.slice('--log='.length)
+      if (v === undefined || v === '' || v.startsWith('-')) {
+        return { ...out, error: `--log requires a task id, like app#build${seeHelp('last')}` }
+      }
+      out.log = v
+      continue
+    }
     if (a === '--format' || a.startsWith('--format=')) {
       const fv = formatValue(a === '--format' ? args[++i] : a.slice(9), 'last')
       if (typeof fv === 'object') return { ...out, ...fv }
@@ -102,6 +114,12 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       error: `a run id and --list do not combine: replay ${out.runId}, or list runs${seeHelp('last')}`,
     }
   }
+  if (out.log !== undefined && (out.list !== undefined || out.failed === true)) {
+    return {
+      ...out,
+      error: `--log reads one task's output and combines only with a run id${seeHelp('last')}`,
+    }
+  }
   if (out.runId !== undefined && out.failed === true) {
     return {
       ...out,
@@ -282,10 +300,11 @@ export function formatRunList(
 
 export async function lastCmd(args: readonly string[]): Promise<number> {
   const parsed = parseLastArgs(args)
-  if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`)
+  if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`, 'VX_E_USAGE')
 
   const root = await findWorkspaceRoot(process.cwd())
-  const cache = Cache.inspect(await cliCacheDir(root, parsed.cacheDir))
+  const cacheDir = await cliCacheDir(root, parsed.cacheDir)
+  const cache = Cache.inspect(cacheDir)
   try {
     const db = cache.dbHandle()
     // Nothing recorded at all is its own answer: `--failed` said "no
@@ -293,6 +312,30 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
     // nothing, while `--list --failed` past green runs said there were none.
     const noRuns = (): boolean => listInvocations(db, { limit: 1 }).length === 0
 
+    if (parsed.log !== undefined) {
+      const runId =
+        parsed.runId === undefined
+          ? undefined
+          : (resolveRunId(db, parsed.runId, 'vx last') ?? parsed.runId)
+      const log = taskLog(cacheDir, db, parsed.log, runId)
+      if (log === null) {
+        throw new UserError(
+          `vx last: no recorded run of ${parsed.log}${parsed.runId === undefined ? '' : ` in run ${parsed.runId}`} (a task id is project#task)`,
+        )
+      }
+      if (parsed.format === 'json') {
+        process.stdout.write(`${JSON.stringify(log)}\n`)
+        return 0
+      }
+      if (log.source === null) {
+        process.stderr.write(
+          `vx last: ${log.taskId} ended ${log.status}; vx keeps output only for failed and cached tasks\n`,
+        )
+      }
+      process.stdout.write(log.output)
+      return 0
+    }
+
     if (parsed.list !== undefined) {
       const invocations =
         parsed.failed === true
@@ -330,12 +373,20 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
             : parsed.failed === true
               ? 'vx last: no recorded run failed'
               : 'vx last: no recorded runs yet — run something first',
+        'VX_E_NO_HISTORY',
       )
     }
     const detail = getRun(db, inv.runId)
 
     if (parsed.format === 'json') {
-      process.stdout.write(`${JSON.stringify({ invocation: inv, tasks: detail?.tasks ?? [] })}\n`)
+      const failures = new Map(
+        (runFailures(cacheDir, db, inv.runId)?.tasks ?? []).map((f) => [f.taskId, f]),
+      )
+      const tasks = (detail?.tasks ?? []).map((t) => {
+        const f = failures.get(`${t.project}#${t.task}`)
+        return f === undefined ? t : { ...t, output: f.output, locations: f.locations }
+      })
+      process.stdout.write(`${JSON.stringify({ invocation: inv, tasks })}\n`)
       return 0
     }
 

package/src/cli/plan-format.ts

@@ -1,6 +1,6 @@
 // Formatters for `--dry-run` (human / JSON) and `--graph` (DOT).
 
-import type { CacheStatus, RunPlan } from '../orchestrator/index.js'
+import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
 import { formatElapsed, maskedCommand } from '../util/index.js'
 
 /**
@@ -52,6 +52,9 @@ export function formatPlanText(plan: RunPlan): string {
     if (taskDesc) {
       lines.push(`     ${' '.repeat(idWidth)}  ${taskDesc}`)
     }
+    if (t.affected !== undefined) {
+      lines.push(`     ${' '.repeat(idWidth)}  affected: ${describeReason(t.affected)}`)
+    }
     if (skipped) noop++
     else if (t.cacheStatus === 'hit-local') local++
     else if (t.cacheStatus === 'hit-remote') remote++
@@ -104,6 +107,23 @@ export function formatPlanText(plan: RunPlan): string {
   return lines.join('\n') + '\n'
 }
 
+/** One `--affected --dry` reason line: the cause, then the edge chain that carried it. */
+function describeReason(r: AffectedReason): string {
+  const cause =
+    r.kind === 'named'
+      ? 'named on the command line'
+      : r.kind === 'selected'
+        ? 'its project is selected outright'
+        : r.kind === 'package'
+          ? `a ^ edge passes changed package ${r.project}`
+          : r.kind === 'input'
+            ? `${r.file} changed (an input)`
+            : r.file !== undefined
+              ? `${r.file} changed (in its project)`
+              : 'its project changed as a whole'
+  return r.via === undefined ? cause : `${cause}, via ${r.via.join(' ← ')}`
+}
+
 /** A TS config may build the description from `process.env` (L-11). */
 function shownDescription(t: RunPlan['tasks'][number]): string | undefined {
   const { description, exec } = t.node.config
@@ -122,6 +142,7 @@ export interface PlanTaskJson {
   executor?: string
   download?: 'deferred'
   description?: string
+  affected?: AffectedReason
 }
 
 export function formatPlanJson(plan: RunPlan): string {
@@ -141,6 +162,7 @@ export function formatPlanJson(plan: RunPlan): string {
             ...(t.executor !== undefined ? { executor: t.executor } : {}),
             ...(t.download !== undefined ? { download: t.download } : {}),
             ...(description !== undefined ? { description } : {}),
+            ...(t.affected !== undefined ? { affected: t.affected } : {}),
           }
         }),
         ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),

package/src/cli/plugin-commands.ts

@@ -99,6 +99,9 @@ export async function resolvePluginCommand(
         workspaceRoot: ws.workspaceRoot,
         cacheDir: ws.cacheDir,
         concurrency: ws.concurrency,
+        vx: (await import('./upgrade.js')).isCompiledBinary()
+          ? [process.execPath]
+          : [process.execPath, Bun.main],
         warn: (m) => process.stderr.write(`${maskedLine(m)}\n`),
       },
     }

package/src/cli/plugin-templates.ts

@@ -16,7 +16,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   commands: {
     plugin:
       "// `commands`: a CLI verb. `vx cache-dir` prints where this workspace's cache\n// lives. The verb's return value is the exit code.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function cacheDirVerb(): VxPlugin {\n  return definePlugin(import.meta, {\n    commands: {\n      'cache-dir': {\n        description: \"print this workspace's cache directory\",\n        run(argv, ctx) {\n          if (argv.length > 0) {\n            console.error(`vx cache-dir: takes no arguments, got ${argv.join(' ')}`)\n            return 2\n          }\n          console.log(ctx.cacheDir)\n          return 0\n        },\n      },\n    },\n  })\n}\n",
-    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = { workspaceRoot: '/ws', cacheDir: '/ws/.vx/cache', warn() {}, concurrency: 1 }\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
+    test: "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n",
   },
   executor: {
     plugin:

package/src/cli/run.ts

@@ -3,7 +3,7 @@ import path from 'node:path'
 import { isatty } from 'node:tty'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { translateForeign } from './foreign-flags.js'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import {
   planRun,
   formatRunReportMarkdown,
@@ -69,6 +69,8 @@ export interface RunArgs {
   forwardArgs: string[]
   verbosity: number
   dry: 'text' | 'json' | undefined
+  /** `--format json`: the run's result document on stdout, every other line on stderr. */
+  format: 'pretty' | 'json'
   graph: string | undefined
   summarize: string | undefined
   profile: string | undefined
@@ -132,6 +134,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
     forwardArgs: [],
     verbosity: 0,
     dry: undefined,
+    format: 'pretty',
     graph: undefined,
     summarize: undefined,
     profile: undefined,
@@ -342,6 +345,10 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
         return { ...out, error: `--dry must be text or json (got ${fmt})` }
       }
       out.dry = fmt
+    } else if (a === '--format' || a?.startsWith('--format=')) {
+      const f = formatValue(a === '--format' ? before[++i] : a.slice('--format='.length), verb)
+      if (typeof f !== 'string') return { ...out, error: f.error }
+      out.format = f
     } else if (a === '--graph') {
       out.graph = ''
     } else if (a?.startsWith('--graph=')) {
@@ -429,6 +436,21 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
   if (out.graph !== undefined && needsRun) {
     return { ...out, error: `--graph skips execution; ${runOnly}` }
   }
+  if (out.format === 'json') {
+    // Each of these prints something else on stdout, which the document owns.
+    if (out.dry !== undefined)
+      return { ...out, error: '--format json runs the tasks; --dry=json prints the plan' }
+    if (out.graph === '')
+      return {
+        ...out,
+        error: '--format json and --graph both print on stdout; give --graph a file',
+      }
+    if (out.report === 'markdown')
+      return {
+        ...out,
+        error: '--format json and --report=markdown both print on stdout; use --report-file',
+      }
+  }
   return out
 }
 
@@ -614,6 +636,7 @@ export async function resolveRunOptions(
   if (parsed.cacheDir !== undefined) opts.cacheDir = parsed.cacheDir
   if (parsed.concurrency !== undefined) opts.concurrency = parsed.concurrency
   if (parsed.summarize !== undefined) opts.summarize = parsed.summarize
+  if (parsed.format === 'json') opts.json = true
   if (parsed.profile !== undefined) opts.profile = parsed.profile
   if (Object.keys(parsed.tags).length > 0) opts.tags = parsed.tags
 
@@ -626,8 +649,7 @@ const TASKS_SHOWN = 12
 export async function runCmd(args: readonly string[]): Promise<number> {
   const parsed = parseRunArgs(args)
   if (parsed.error) {
-    process.stderr.write(`vx run: ${parsed.error}${seeHelp('run')}\n`)
-    return 1
+    return refuse('run', args, `${parsed.error}${seeHelp('run')}`, 'VX_E_USAGE')
   }
 
   const cwd = process.cwd()
@@ -638,7 +660,10 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // anchored pkg#task; the rest of the pipeline treats it like any
   // explicit anchored positional.
   if (tasks.length === 0) {
-    if (!process.stdin.isTTY) {
+    // A JSON answer is for a program, which cannot pick from a menu: an
+    // agent on a pty waited at the picker forever.
+    const forProgram = parsed.format === 'json' || parsed.dry === 'json'
+    if (!process.stdin.isTTY || forProgram) {
       const names = await taskNamesHere(cwd)
       const shown = (names ?? []).slice(0, TASKS_SHOWN)
       const more = (names?.length ?? 0) - shown.length
@@ -646,10 +671,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
         shown.length === 0
           ? 'vx run <task>, e.g. vx run build'
           : `tasks here: ${shown.join(', ')}${more > 0 ? ` and ${more} more` : ''}`
-      process.stderr.write(
-        `vx run: missing task name (stdin is not a TTY, so no picker; ${tasksHere})${seeHelp('run')}\n`,
+      return refuse(
+        'run',
+        args,
+        `missing task name (${forProgram ? 'a JSON answer opens' : 'stdin is not a TTY, so'} no picker; ${tasksHere})${seeHelp('run')}`,
+        'VX_E_USAGE',
       )
-      return 1
     }
     // Every run needs git: refused here, not after the user has chosen.
     const refusal = gitRefusal(await findWorkspaceRoot(cwd))
@@ -664,17 +691,11 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     // `--filter` / `--affected` scope the menu, as they scope a bare task:
     // the menu listed every project and the anchored pick ran outside it.
     const scope = await scopeFilters(parsed, cwd)
-    if ('error' in scope) {
-      process.stderr.write(`vx run: ${scope.error}\n`)
-      return 1
-    }
+    if ('error' in scope) return refuse('run', args, scope.error, 'VX_E_USAGE')
     let only: ReadonlySet<string> | undefined
     if (scope.filterStrings.length > 0) {
       const selected = await resolveFilters(cwd, scope.filterStrings, load, scope.affectedFilter)
-      if ('error' in selected) {
-        process.stderr.write(`vx run: ${selected.error}\n`)
-        return 1
-      }
+      if ('error' in selected) return refuse('run', args, selected.error, 'VX_E_USAGE')
       if ('empty' in selected) {
         process.stderr.write(`vx run: ${selected.empty}\n`)
         return 0
@@ -689,10 +710,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   }
 
   const resolved = await resolveRunOptions(parsed, cwd, tasks)
-  if ('error' in resolved) {
-    process.stderr.write(`vx run: ${resolved.error}\n`)
-    return 1
-  }
+  if ('error' in resolved) return refuse('run', args, resolved.error, 'VX_E_USAGE')
   if ('nothingSelected' in resolved) {
     process.stderr.write(`vx run: ${resolved.nothingSelected}\n`)
     return 0
@@ -783,8 +801,8 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // is no whole-run delegation seam to consult.
   const summary = await runOrchestrator(opts)
   if (summary.refused !== undefined) {
-    process.stderr.write(`vx run: ${summary.refused}\n`)
-    return 1
+    const unknown = summary.refused.startsWith('no projects declare')
+    return refuse('run', args, summary.refused, unknown ? 'VX_E_UNKNOWN_TASK' : 'VX_E_REFUSED')
   }
   if (wantsReport) {
     const md =
@@ -816,5 +834,6 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       }
     }
   }
+  if (summary.json !== undefined) process.stdout.write(`${JSON.stringify(summary.json, null, 2)}\n`)
   return summary.ok ? 0 : 1
 }

package/src/cli/show.ts

@@ -10,7 +10,7 @@ import path from 'node:path'
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
 import { affectedTaskProjects, isDefaultBuild } from '../orchestrator/index.js'
-import { flagHint, formatValue, seeHelp } from './help.js'
+import { flagHint, formatValue, refuse, seeHelp } from './help.js'
 import { listed, nearMatches, relPosix, secretMask, UserError } from '../util/index.js'
 import { affectedFilterFor, resolveFilters } from './select.js'
 import {
@@ -82,10 +82,7 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
 
 export async function showCmd(args: readonly string[]): Promise<number> {
   const parsed = parseShowArgs(args)
-  if (parsed.error) {
-    process.stderr.write(`vx show: ${parsed.error}\n`)
-    return 1
-  }
+  if (parsed.error) return refuse('show', args, parsed.error, 'VX_E_USAGE')
   const reads: LoadReads = new Map()
   const root = await findWorkspaceRoot(process.cwd(), reads)
   const metas = await discoverCliProjects(await loadWorkspace(root, reads))
@@ -98,6 +95,7 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     if (rootMeta === undefined) {
       throw new UserError(
         `vx show: "${parsed.target}" names the workspace root's project, and the root is no project here`,
+        'VX_E_USAGE',
       )
     }
     parsed.target = `${rootMeta.name}${parsed.target.slice(2)}`
@@ -114,12 +112,14 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     const list = projectName === '' ? 'vx show' : `vx show ${projectName}`
     throw new UserError(
       `vx show: missing task name after '#' in "${parsed.target}" (${list} lists the tasks)`,
+      'VX_E_USAGE',
     )
   }
   if (projectName !== undefined && (taskName !== undefined || byName.has(projectName))) {
     if (!byName.has(projectName)) {
       throw new UserError(
         `vx show: unknown project: "${projectName}"${suggest(projectName, [...byName.keys()], '', 'projects')}`,
+        'VX_E_UNKNOWN_PROJECT',
       )
     }
   }
@@ -138,18 +138,19 @@ export async function showCmd(args: readonly string[]): Promise<number> {
     if (scope !== 'all') {
       throw new UserError(
         'vx show: --filter and --affected narrow a list: `vx show` or `vx show <task>`',
+        'VX_E_USAGE',
       )
     }
     const raw = [...parsed.filters]
     let affected: string | undefined
     if (parsed.affected !== undefined) {
       const f = await affectedFilterFor(process.cwd(), parsed.affected)
-      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`)
+      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`, 'VX_E_USAGE')
       affected = f
       raw.unshift(f)
     }
     const r = await resolveFilters(process.cwd(), raw, { noCreate: true }, affected)
-    if ('error' in r) throw new UserError(`vx show: ${r.error}`)
+    if ('error' in r) throw new UserError(`vx show: ${r.error}`, 'VX_E_USAGE')
     if ('empty' in r) process.stderr.write(`vx show: ${r.empty}\n`)
     selected = new Set('empty' in r ? [] : r.names)
     if ('names' in r && r.affected !== undefined)
@@ -181,6 +182,7 @@ export async function showCmd(args: readonly string[]): Promise<number> {
       const nx = projectName === 'projects' ? ' (`nx show projects` is `vx show` here)' : ''
       throw new UserError(
         `vx show: unknown project or task: "${projectName}"${nx}${suggest(projectName!, [...byName.keys(), ...names], '', 'projects and tasks')}`,
+        'VX_E_UNKNOWN_TASK',
       )
     }
     let shown = declaring.filter((p) => inSelection(p.name))
@@ -224,6 +226,7 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   if (task === undefined) {
     throw new UserError(
       `vx show: unknown task: "${meta.name}#${taskName}"${suggest(taskName, Object.keys(config?.tasks ?? {}), `${meta.name}#`, 'its tasks')}`,
+      'VX_E_UNKNOWN_TASK',
     )
   }
   process.stdout.write(renderTask(meta.name, dir, taskName, task, parsed.format))

package/src/cli/upgrade.ts

@@ -38,7 +38,7 @@ export function isBunfsPath(p: string): boolean {
  * upgrade` refused with "running from source". `Bun.main` stays the
  * bunfs path under every compile-flag combination.
  */
-function isCompiledBinary(): boolean {
+export function isCompiledBinary(): boolean {
   return (
     isBunfsPath(Bun.main) || isBunfsPath(process.argv[1] ?? '') || isBunfsPath(import.meta.path)
   )

package/src/cli/watch.ts

@@ -78,8 +78,13 @@ export function watchRefusal(parsed: RunArgs): string | null {
   // All three format ONE run's result and are consumed by `runCmd` alone, so
   // a watch loop silently ignored them. `--verbosity 0` is not rejected: it
   // asks for the output watch already gives.
-  if (parsed.report !== undefined || parsed.reportFile !== undefined || parsed.verbosity > 0) {
-    return 'vx watch: --report / --report-file / --verbosity are not supported in watch mode (they report a single run)'
+  if (
+    parsed.report !== undefined ||
+    parsed.reportFile !== undefined ||
+    parsed.verbosity > 0 ||
+    parsed.format !== 'pretty'
+  ) {
+    return 'vx watch: --report / --report-file / --verbosity / --format are not supported in watch mode (they report a single run)'
   }
   return null
 }