@vzn/vx 0.0.16 → 0.0.21

package/src/cli/cache.ts

@@ -1,6 +1,8 @@
-import { Cache } from '../cache/index.js'
-import { parseSize } from '../util/index.js'
-import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { seeHelp } from './help.js'
+import { parseDecimalInt, parseSize } from '../util/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
+import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 
 // parseSize moved to `util` (the orchestrator's resource resolver needs it
@@ -16,7 +18,7 @@ export async function cacheCmd(args: readonly string[]): Promise<number> {
       process.stderr.write('vx cache: missing subcommand. Try `vx cache prune`.\n')
       return 1
     default:
-      process.stderr.write(`vx cache: unknown subcommand: ${sub}\n`)
+      process.stderr.write(`vx cache: unknown subcommand: ${sub}${seeHelp('cache')}\n`)
       return 1
   }
 }
@@ -24,6 +26,9 @@ export async function cacheCmd(args: readonly string[]): Promise<number> {
 interface PruneArgs {
   olderThanMs?: number
   maxBytes?: number
+  dryRun?: boolean
+  /** `--cache-dir`: prune the cache a run with the same flag uses. */
+  cacheDir?: string
   error?: string
 }
 
@@ -31,20 +36,54 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
   const out: PruneArgs = {}
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
-    if (a === '--older-than') {
-      const v = args[++i]
-      if (v === undefined) return { error: `${a} requires a value (e.g. 30d, 24h, 60m)` }
+    if (a === '--older-than' || a?.startsWith('--older-than=')) {
+      const v = a === '--older-than' ? args[++i] : a.slice('--older-than='.length)
+      if (v === undefined || v === '') {
+        return { error: `--older-than requires a value (e.g. 30d, 24h, 60m)` }
+      }
       const ms = parseDuration(v)
       if (ms === null) return { error: `invalid duration: ${v}` }
+      // `0d` evicts everything ever cached. That is far more often a
+      // computed-to-zero retention than an intent, and no other flag
+      // combination expresses "wipe the cache" — so refuse it and name
+      // the deliberate way to do it.
+      if (ms === 0) {
+        return {
+          error: `--older-than 0 would evict every entry — delete the cache directory instead`,
+        }
+      }
       out.olderThanMs = Date.now() - ms
-    } else if (a === '--max-size') {
-      const v = args[++i]
-      if (v === undefined) return { error: `${a} requires a value (e.g. 500M, 1G)` }
+    } else if (a === '--max-size' || a?.startsWith('--max-size=')) {
+      const v = a === '--max-size' ? args[++i] : a.slice('--max-size='.length)
+      if (v === undefined || v === '') {
+        return { error: `--max-size requires a value (e.g. 500M, 1G)` }
+      }
       const bytes = parseSize(v)
       if (bytes === null) return { error: `invalid size: ${v}` }
+      if (bytes === 0) {
+        return {
+          error: `--max-size 0 would evict every entry — delete the cache directory instead`,
+        }
+      }
+      // A bare number is bytes to `parseSize` (a computed size needs that),
+      // but nobody caps a cache at 10 bytes: `--max-size 10`
+      // meant 10G or 10M and would evict everything, the same class of
+      // destructive typo the zero bound above refuses. An explicit `10B`
+      // still passes.
+      if (/^\d+$/.test(v)) {
+        return {
+          error: `--max-size ${v} would read as ${v} bytes and evict nearly everything — give a unit (e.g. ${v}M, ${v}G)`,
+        }
+      }
       out.maxBytes = bytes
+    } else if (a === '--dry-run') {
+      out.dryRun = true
     } else {
-      return { error: `unknown argument: ${a}` }
+      const cd = parseCacheDirFlag(args, i)
+      if (cd === null) return { error: `unknown argument: ${a}${seeHelp('cache')}` }
+      if ('error' in cd) return { error: cd.error }
+      out.cacheDir = cd.cacheDir
+      i = cd.next
     }
   }
   if (out.olderThanMs === undefined && out.maxBytes === undefined) {
@@ -67,18 +106,25 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx cache prune: ${(err as Error).message}\n`)
     return 1
   }
-  // Honor `defineWorkspace({ cacheDir: '...' })` — `vx run` and
-  // `vx cache prune` must operate on the same directory or prune
-  // silently no-ops against the wrong path.
-  const workspaceConfig = await loadWorkspaceConfig(root)
-  const cache = new Cache(resolveCacheDir(root, workspaceConfig))
+  // Honor `--cache-dir`, `defineWorkspace({ cacheDir: '...' })` and a
+  // `config` plugin's edit of it — `vx run` and `vx cache prune` must
+  // operate on the same directory or prune silently no-ops against the
+  // wrong path.
+  const cache = new Cache(await cliCacheDir(root, parsed.cacheDir))
+  noteSchemaReset(cache, warnToStderr)
   try {
-    const opts: { olderThanMs?: number; maxBytes?: number } = {}
+    const opts: { olderThanMs?: number; maxBytes?: number; dryRun?: boolean } = {}
     if (parsed.olderThanMs !== undefined) opts.olderThanMs = parsed.olderThanMs
     if (parsed.maxBytes !== undefined) opts.maxBytes = parsed.maxBytes
+    if (parsed.dryRun) opts.dryRun = true
     const result = await cache.prune(opts)
+    const dry = parsed.dryRun === true
+    const orphans =
+      result.orphans > 0
+        ? `, ${dry ? 'would reap' : 'reaped'} ${result.orphans} orphaned artifact${result.orphans === 1 ? '' : 's'} (${formatBytes(result.orphanBytes)})`
+        : ''
     process.stdout.write(
-      `Pruned ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)} freed)\n`,
+      `${dry ? 'Would prune' : 'Pruned'} ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)}${dry ? '' : ' freed'})${orphans}\n`,
     )
   } finally {
     cache.close()
@@ -86,11 +132,19 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
   return 0
 }
 
+/**
+ * Parse `<n><unit>` where unit is s/m/h/d, case-insensitively (`parseSize`
+ * has always been case-insensitive; this matched only lowercase, so `30D`
+ * was rejected while `1GB` and `1gb` both worked).
+ */
 export function parseDuration(input: string): number | null {
-  const m = input.match(/^(\d+)([smhd])$/)
+  const m = input.match(/^(\d+)([smhd])$/i)
   if (!m) return null
-  const n = Number(m[1])
-  const unit = m[2]
+  const n = parseDecimalInt(m[1]!)
+  if (n === null) return null
+  // Lowercase before the switch: with the /i flag an uppercase `M` would
+  // otherwise fall through to the days branch.
+  const unit = m[2]!.toLowerCase()
   const mult = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000
   return n * mult
 }

package/src/cli/completions.ts

@@ -0,0 +1,104 @@
+// `vx completions <shell>` — a bash / zsh / fish script over the verb table
+// and each verb's help cut, so the verbs and every flag of each complete
+// from the one text `vx <verb> --help` prints. Plugin verbs of the
+// workspace around the cwd are included at generation time; task and
+// project names are not (a completion that evaluates configs on every
+// Tab is the wrong price).
+
+import { CORE_VERBS, seeHelp, verbHelpText } from './help.js'
+
+export type CompletionShell = 'bash' | 'zsh' | 'fish'
+const SHELLS: readonly CompletionShell[] = ['bash', 'zsh', 'fish']
+
+/** Every `--flag` the verb's help cut names, plus `--help`; deduped, in order of appearance. */
+export function verbFlags(verb: string): string[] {
+  const flags = new Set<string>(['--help'])
+  for (const f of verbHelpText(verb).match(/--[a-zA-Z][a-zA-Z-]*/g) ?? []) flags.add(f)
+  return [...flags]
+}
+
+/** The words that follow `vx <verb>` besides flags: subcommands and fixed choices. */
+const VERB_WORDS: Readonly<Record<string, readonly string[]>> = {
+  cache: ['prune'],
+  completions: [...SHELLS],
+}
+
+export function completionScript(shell: CompletionShell, verbs: readonly string[]): string {
+  const table = verbs.map((v) => ({
+    verb: v,
+    // A plugin verb owns its own arguments; only `--help` is known here.
+    words: [
+      ...(VERB_WORDS[v] ?? []),
+      ...((CORE_VERBS as readonly string[]).includes(v) ? verbFlags(v) : ['--help']),
+    ],
+  }))
+  switch (shell) {
+    case 'bash':
+      return [
+        '# vx completions — generated by `vx completions bash`',
+        '_vx() {',
+        '  local cur="${COMP_WORDS[COMP_CWORD]}"',
+        '  local verb="${COMP_WORDS[1]}"',
+        '  if [ "$COMP_CWORD" -eq 1 ]; then',
+        `    COMPREPLY=($(compgen -W "${verbs.join(' ')}" -- "$cur"))`,
+        '    return',
+        '  fi',
+        '  case "$verb" in',
+        ...table.map(
+          (t) => `    ${t.verb}) COMPREPLY=($(compgen -W "${t.words.join(' ')}" -- "$cur")) ;;`,
+        ),
+        '    *) COMPREPLY=() ;;',
+        '  esac',
+        '}',
+        'complete -F _vx vx',
+        '',
+      ].join('\n')
+    case 'zsh':
+      return [
+        '#compdef vx',
+        '# vx completions — generated by `vx completions zsh`',
+        '_vx() {',
+        '  if (( CURRENT == 2 )); then',
+        `    compadd -- ${verbs.join(' ')}`,
+        '    return',
+        '  fi',
+        '  case "${words[2]}" in',
+        ...table.map((t) => `    ${t.verb}) compadd -- ${t.words.join(' ')} ;;`),
+        '  esac',
+        '}',
+        'compdef _vx vx',
+        '',
+      ].join('\n')
+    case 'fish':
+      return [
+        '# vx completions — generated by `vx completions fish`',
+        'complete -c vx -f',
+        ...verbs.map((v) => `complete -c vx -n __fish_use_subcommand -a ${v}`),
+        ...table.flatMap((t) =>
+          t.words.map((w) =>
+            w.startsWith('--')
+              ? `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}" -l ${w.slice(2)}`
+              : `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}" -a ${w}`,
+          ),
+        ),
+        '',
+      ].join('\n')
+  }
+}
+
+export async function completionsCmd(
+  args: readonly string[],
+  pluginVerbs: readonly string[],
+): Promise<number> {
+  const shell = args[0]
+  if (args.length !== 1 || !(SHELLS as readonly string[]).includes(shell ?? '')) {
+    process.stderr.write(
+      `vx completions: expected one shell — bash, zsh or fish${shell !== undefined && args.length === 1 ? ` (got ${shell})` : ''}${seeHelp('completions')}\n`,
+    )
+    return 1
+  }
+  const verbs = [...CORE_VERBS.filter((v) => v !== 'help' && v !== 'version'), 'help', 'version']
+  for (const v of pluginVerbs) if (!verbs.includes(v)) verbs.push(v)
+  process.stdout.write(completionScript(shell as CompletionShell, verbs))
+  return 0
+}

package/src/cli/core-alias.ts

@@ -0,0 +1,25 @@
+/**
+ * One core per process. A plugin package, a `vx.workspace.ts`, a
+ * `vx.config.ts` all `import … from '@vzn/vx'`, and that specifier
+ * resolves through node_modules — to a SECOND copy of core when the host
+ * is the compiled binary (whose own copy lives under the bunfs root) or
+ * an install with its own nested `@vzn/vx`. The second copy is core's
+ * whole source transpiled again, per process: ~20 ms per plugin package
+ * in the binary (measured 2026-09-10, `@vzn/vx-otel`: 20–25 ms → 2–3 ms),
+ * and two module states — two `definePlugin` memos, two of everything
+ * keyed by identity rather than by registry symbol.
+ *
+ * The alias is a Bun virtual module for the exact specifier `@vzn/vx`,
+ * served from the host's own façade, loaded lazily on the first import
+ * so a verb that never loads a plugin never loads the façade. The
+ * source form (`bun src/bin.ts`) resolves the specifier to the same file
+ * anyway; the alias makes that a guarantee rather than a layout fact.
+ */
+export function registerCoreAlias(load: () => Promise<Record<string, unknown>>): void {
+  Bun.plugin({
+    name: 'vx-core-alias',
+    setup(build) {
+      build.module('@vzn/vx', async () => ({ exports: await load(), loader: 'object' }))
+    },
+  })
+}

package/src/cli/help.ts

@@ -1,129 +1,196 @@
-export function printHelp(): void {
-  process.stdout.write(
-    [
-      'vx — open, extensible monorepo task runner',
-      '',
-      'Usage:',
-      '  vx run [OPTIONS] [TASK | PKG#TASK] [-- forwarded-args...]',
-      '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
-      '  vx cache prune [--older-than <duration>] [--max-size <bytes>]',
-      '  vx lock [--check]',
-      '  vx migrate [--from turbo|nx] [--dry] [--force]',
-      '  vx upgrade [tag]',
-      '  vx show [PROJECT[#TASK]] [--format pretty|json]',
-      '  vx info',
-      '  vx mcp [--stdio]',
-      '  vx help',
-      '  vx version',
-      '',
-      'Selection (for run):',
-      '  (default)                Run task in the project containing cwd.',
-      '      --all                Run task in every project that declares it.',
-      '      --filter <pat>       pnpm-style filter (repeatable). Examples:',
-      '                             foo, @scope/*, ./packages/foo, foo..., ...foo,',
-      '                             foo^..., !foo, [<since>]',
-      '      --affected[=<base>]  Sugar for --filter "[<base>]". Default base =',
-      '                             origin/HEAD (falls back to HEAD~1).',
-      "  pkg#task                 Run a specific project's task directly.",
-      '',
-      'Execution (for run):',
-      '      --concurrency <n>           Max parallel tasks (default: CPU count).',
-      '      --excludeDependencies[=names]  Skip dependsOn edges. No value = all; comma list = specific names.',
-      '      --no-cache                  Disable caching entirely (no reads, no writes, outputs left alone).',
-      '      --force                     Re-execute everything (skip reads) but still refresh the cache (writes on).',
-      '      --cache <spec>              Per-layer read/write control. Comma list of <layer>:<flags>',
-      '                                  (layer = local|remote, flags ⊆ rw). A named layer is set EXACTLY',
-      '                                  to its flags; unnamed layers keep their value. Examples:',
-      '                                  local:rw,remote:r (remote read-only), remote: (remote off),',
-      '                                  local:r (local read-only).',
-      '      --cache-dir <path>          Cache directory override (cwd-relative). Beats the workspace',
-      '                                  cacheDir field + the .vx/cache default.',
-      '      --retry <n>                 Re-run a failed task up to <n> more times (default for tasks',
-      "                                  without their own exec.retries; explicit config wins). Doesn't",
-      '                                  affect cache keys.',
-      '      --timeout <ms>              Default per-task timeout for tasks without their own exec.timeout',
-      '                                  (above VX_TASK_TIMEOUT env + workspace timeout). Kills + fails',
-      '                                  a runaway task. Per-task exec.timeout always wins.',
-      '      --memory <size>             Memory budget (e.g. 8GB) that exec.resources.memory reservations',
-      '                                  pack against. Default: total system RAM — pass this in',
-      '                                  cgroup-limited containers (the default reads the HOST RAM).',
-      '                                  Reservations are per-task config (exec.resources), not flags.',
-      '      --verify[=<what>]           Prove cache correctness. determinism (default): re-run each',
-      '                                  executed cacheable task + content-compare outputs. inputs: sandbox',
-      '                                  with the declared-input baseline + flag reads of undeclared inputs.',
-      '                                  fingerprint: ship output-tree fingerprints for the cross-machine',
-      '                                  diff on a connected serve (~1× exec — no re-run). all: everything.',
-      '                                  An unsafe task fails the run with the exact paths.',
-      '                                  ~2× exec (determinism); CI-shaped. inputs/all need the OS sandbox.',
-      '      --verify-allow <pkg#task,…> Exempt known-nondeterministic tasks from failing --verify.',
-      '      --frozen                    Load configs from vx-lock.json (CI; pair with vx lock --check).',
-      '      --output-logs <mode>        full | errors-only | none — overrides the flow default',
-      '                                  (focused without --all/--filter/--affected, broad with, full in CI).',
-      '      --verbosity <n>             0=quiet, 1=verbose summary, 2+=debug (reserved).',
-      '',
-      'Planning (for run — skips execution):',
-      '      --dry[=text|json]    Print the task graph + cache hit/miss prediction.',
-      '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
-      '',
-      'Artifacts (for run):',
-      '      --summarize[=<path>] Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
-      '      --profile[=<path>]   Write Chrome-trace JSON (default profile.json).',
-      '',
-      'Extensions (plugins):',
-      '  vx core runs tasks in-process and nothing else. A dashboard, remote',
-      '  cache, distributed execution, and telemetry export are provided by',
-      '  PLUGINS declared in vx.workspace.ts — first-party or your own. Core',
-      '  depends on none of them; a plain `vx run` never requires a plugin.',
-      '  See the plugin guide: https://vznjs.github.io/vx/guides/plugins/',
-      '',
-      'Argument forwarding (for run):',
-      "  Anything after `--` is forwarded (shell-quoted) to the task's exec",
-      '  command. The forwarded args are folded into the cache key.',
-      '',
-      'Watch mode:',
-      '  vx watch <task>            Initial run, then re-run on filesystem changes.',
-      '                             Uses the same flags as `vx run` except --dry /',
-      '                             --graph / --summarize / --profile. Press Ctrl+C',
-      '                             to stop. Cache means most re-runs are near-zero',
-      '                             cost (cache hits restore outputs + replay logs).',
-      '',
-      'Cache management:',
-      '  vx cache prune --older-than 30d     Evict entries last accessed > 30 days ago.',
-      '  vx cache prune --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
-      '',
-      '  Duration units: s, m, h, d. Size units: K, M, G, T (powers of 1024).',
-      '',
-      'Introspection:',
-      '  vx show              List every project: name, dir, declared task count.',
-      "  vx show <project>    Print the project's LIVE resolved config (fresh",
-      '                       evaluation, not the lock), one block per task.',
-      "  vx show <pkg>#<task> Print a single task's resolved config.",
-      '      --format <fmt>   pretty (default) | json.',
-      '  vx info              Workspace doctor: vx/bun/git versions, project +',
-      '                       task counts, cache dir/entries/size, recent runs,',
-      '                       lock status.',
-      '  vx stats             Deprecated: alias of vx info.',
-      '  vx mcp               Model Context Protocol server (stdio) — exposes inspector',
-      '                       RPCs as MCP tools for AI agents (Claude Code, Cursor, …).',
-      '',
-      'Migration:',
-      '  vx migrate           Generate vx.config.ts per package from turbo.json or an',
-      '                       Nx project graph (.nx/workspace-data/project-graph.json).',
-      '                       Unmappable settings become TODO(vx-migrate) comments;',
-      '                       turbo global fields become a shared vx-preset.ts.',
-      '      --dry            Print the generated files instead of writing them.',
-      '      --force          Overwrite existing vx.config.* / vx-preset.ts files.',
-      '',
-      'Config lock:',
-      '  vx lock              Evaluate every vx.config in the current environment and',
-      '                       freeze the resolved objects into vx-lock.json. Plain runs',
-      '                       always evaluate live; only `vx run --frozen` consumes the',
-      '                       lock (CI reproducibility, frozen-env semantics).',
-      '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
-      '                       re-evaluation compared against the frozen objects. Exits 1',
-      '                       on drift (e.g. configs that read env vars). Run it before',
-      '                       `vx run --frozen` in CI.',
-      '',
-    ].join('\n'),
-  )
+export function printHelp(pluginCommands: readonly string[] = [], verb?: string): void {
+  process.stdout.write(verb === undefined ? helpText(pluginCommands) : verbHelpText(verb))
 }
+
+/**
+ * `vx <verb> --help`: the reference cut to one verb — the title, the Usage
+ * lines that name it, and every section that is `(for <verb>)` or lists a
+ * `vx <verb>` form — read from the same text, so nothing can drift. A verb
+ * the reference does not know gets the whole thing.
+ */
+export function verbHelpText(verb: string): string {
+  const blocks = helpText().split('\n\n')
+  const title = blocks[0]!
+  const names = (line: string): boolean =>
+    new RegExp(`^\\s*vx ${verb}( |$)`).test(line) ||
+    line.includes(`(for ${verb})`) ||
+    line.includes(`(for ${verb} `)
+  const kept: string[] = []
+  for (const block of blocks.slice(1)) {
+    const lines = block.split('\n')
+    if (lines[0] === 'Usage:') {
+      const own = lines.slice(1).filter(names)
+      if (own.length > 0) kept.push(['Usage:', ...own].join('\n'))
+      continue
+    }
+    if (lines.some(names)) kept.push(block)
+  }
+  if (kept.length === 0) return helpText()
+  return [title, ...kept, 'Full reference: vx help', ''].join('\n\n')
+}
+
+export function helpText(pluginCommands: readonly string[] = []): string {
+  return [
+    'vx — open, extensible monorepo task runner',
+    '',
+    'Usage:',
+    '  vx run [OPTIONS] [TASK | PKG#TASK] [-- forwarded-args...]',
+    '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
+    '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--cache-dir <path>]',
+    '  vx lock [--check]',
+    '  vx init [--dry] [--force] [--mjs]',
+    '  vx upgrade [tag]',
+    '  vx show [PROJECT[#TASK] | TASK] [--format pretty|json]',
+    '  vx info [--format pretty|json] [--cache-dir <path>]',
+    '  vx why [TASK | PKG#TASK] [--run <runId>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx last [RUNID] [--list[=N]] [--format pretty|json] [--cache-dir <path>]',
+    '  vx completions bash|zsh|fish',
+    '  vx help',
+    '  vx version',
+    '',
+    'Selection (for run):',
+    '  (default)                Run task in the project containing cwd.',
+    '      --all                Run task in every project that declares it.',
+    '      --filter <pat>       pnpm-style filter (repeatable). Examples:',
+    '                             foo, @scope/*, ./packages/foo, foo..., ...foo,',
+    '                             foo^..., !foo, [<since>]',
+    '      --affected[=<base>]  Sugar for --filter "[<base>]". Default base =',
+    '                             origin/HEAD (falls back to HEAD~1).',
+    "  pkg#task                 Run a specific project's task directly.",
+    '',
+    'Execution (for run):',
+    '      --concurrency <n>           Max parallel tasks (default: the cores this process may use); `50%` = half of them.',
+    '      --exclude-dependencies[=names]  Skip dependsOn edges. No value = all; comma list = specific names.',
+    '      --no-cache                  Disable caching entirely (no reads, no writes, outputs left alone).',
+    '      --force                     Re-execute everything (skip reads) but still refresh the cache (writes on).',
+    '      --cache <spec>              Per-layer read/write control. Comma list of <layer>:<flags>',
+    '                                  (layer = local|remote, flags ⊆ rw). A named layer is set EXACTLY',
+    '                                  to its flags; unnamed layers keep their value. Examples:',
+    '                                  local:rw,remote:r (remote read-only), remote: (remote off),',
+    '                                  local:r (local read-only).',
+    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats the workspace',
+    '                                  cacheDir field + the .vx/cache default.',
+    '      --retry <n>                 Re-run a failed task up to <n> more times (default for tasks',
+    "                                  without their own exec.retries; explicit config wins). Doesn't",
+    '                                  affect cache keys.',
+    '      --timeout <ms>              Default per-task timeout for tasks without their own exec.timeout',
+    '                                  (above VX_TASK_TIMEOUT env + workspace timeout). Kills + fails',
+    '                                  a runaway task. Per-task exec.timeout always wins.',
+    '      --frozen                    Load configs from vx-lock.json (CI; pair with vx lock --check).',
+    '      --output-logs <mode>        full | errors-only | hash-only | none — overrides the flow default',
+    '      --download <mode>           all (default) | toplevel | none — where remote outputs land',
+    '                                  (focused without --all/--filter/--affected, broad with, full in CI).',
+    '      --verbosity <n>             0 (default) or 1+: print a per-task summary table after the run.',
+    '',
+    'Planning (for run — skips execution):',
+    '      --dry[=text|json]    Print the task graph + cache hit/miss prediction.',
+    '      --graph[=<path>]     Emit Graphviz DOT (stdout if no path).',
+    '',
+    'Artifacts (for run):',
+    '      --summarize[=<path>] Write per-run JSON to <cacheDir>/runs/<run_id>.json.',
+    '      --profile[=<path>]   Write Chrome-trace JSON (default profile.json).',
+    '',
+    'Extensions (plugins):',
+    '  vx core runs tasks in-process and nothing else. A dashboard, remote',
+    '  cache, distributed execution, and telemetry export are provided by',
+    '  PLUGINS declared in vx.workspace.ts — first-party or your own. Core',
+    '  depends on none of them; a plain `vx run` never requires a plugin.',
+    '  See the plugin guide: https://vznjs.github.io/vx/guides/plugins/',
+    '',
+    'Argument forwarding (for run):',
+    "  Anything after `--` is forwarded (shell-quoted) to the task's exec",
+    '  command. The forwarded args are folded into the cache key.',
+    '',
+    'Watch mode:',
+    '  vx watch <task>            Initial run, then re-run on filesystem changes.',
+    '                             Uses the same flags as `vx run` except --dry /',
+    '                             --graph / --summarize / --profile. Press Ctrl+C',
+    '                             to stop. Cache means most re-runs are near-zero',
+    '                             cost (cache hits restore outputs + replay logs).',
+    '',
+    'Cache management:',
+    '  vx cache prune --older-than 30d     Evict entries last accessed > 30 days ago.',
+    '  vx cache prune --max-size 1G        Keep total cache under 1 GB (LRU eviction).',
+    '      --dry-run                       Say what the policy would reap; delete nothing.',
+    '      --cache-dir <path>              The cache a run with the same flag uses (why, last, info too).',
+    '',
+    '  Duration units: s, m, h, d. Size units: K, M, G, T (powers of 1024).',
+    '',
+    'Introspection:',
+    '  vx show              List every project: name, dir, declared task count.',
+    "  vx show <project>    Print the project's LIVE resolved config (fresh",
+    '                       evaluation, not the lock), one block per task.',
+    "  vx show <pkg>#<task> Print a single task's resolved config.",
+    '  vx show <task>       That task in every project declaring it.',
+    '      --format <fmt>   pretty (default) | json.',
+    '  vx info              Workspace doctor: vx/bun/git versions, project +',
+    '                       task counts, cache dir/entries/size, recent runs,',
+    '                       lock status.',
+    '      --format <fmt>   pretty (default) | json.',
+    '  vx stats             Deprecated: alias of vx info.',
+    "  vx why <task>        Why did this task re-run? Compares the task's latest",
+    '                       run (or --run <id>) against its previous run: names the',
+    '                       exact changed cache-key components (files / env / runtime',
+    '                       / upstream) from the persisted input fingerprints.',
+    '      --format <fmt>   pretty (default) | json.',
+    "  vx last [runId]      Replay a recorded run's summary from the local history —",
+    '                       header (command, when, branch, counts) plus the per-task',
+    '                       table, failures first. No re-execution, no cache probe.',
+    '      --list[=N]       List the N most recent runs (default 10) with run ids.',
+    '      --format <fmt>   pretty (default) | json.',
+    '',
+    'Migration:',
+    '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
+    '                       from package.json scripts. Unmappable settings become',
+    '                       TODO(vx-migrate) comments.',
+    '      --dry            Print the generated files instead of writing them.',
+    '      --force          Overwrite existing vx.config.* files.',
+    '  From turbo.json or an Nx project graph: `bunx @vzn/vx-migrate` (its own package).',
+    '',
+    'Shell completions:',
+    '  vx completions <shell>   Print a completion script for bash, zsh or fish: the',
+    '                           verbs (plugin verbs of this workspace included) and',
+    '                           every flag of each. `eval "$(vx completions bash)"`,',
+    '                           or write it where the shell loads completions from.',
+    '',
+    'Config lock:',
+    '  vx lock              Evaluate every vx.config in the current environment and',
+    '                       freeze the resolved objects into vx-lock.json. Plain runs',
+    '                       always evaluate live; only `vx run --frozen` consumes the',
+    '                       lock (CI reproducibility, frozen-env semantics).',
+    '  vx lock --check      Audit the lock: file-changed hash report PLUS a full',
+    '                       re-evaluation compared against the frozen objects. Exits 1',
+    '                       on drift (e.g. configs that read env vars). Run it before',
+    '                       `vx run --frozen` in CI.',
+    '',
+    ...(pluginCommands.length > 0 ? ['Plugin commands:', ...pluginCommands, ''] : []),
+  ].join('\n')
+}
+
+/**
+ * Every argument error ends with this. `vx <verb> --help` prints the
+ * reference (2026-09-04); before that there was nowhere to send a user who
+ * got a flag wrong, so the errors just said no.
+ */
+export function seeHelp(verb: string): string {
+  return ` (see \`vx ${verb} --help\`)`
+}
+
+/**
+ * The documented `--flags` of one verb, read from the help text's
+ * sections headed `… (for <verb>):` so there is no second list to drift —
+ * and no hint that names another verb's flag.
+ */
+export function documentedFlags(verb: string): string[] {
+  const flags = new Set<string>()
+  let inVerb = false
+  for (const line of helpText().split('\n')) {
+    if (/^[A-Z][A-Za-z ]*(?: \(for [a-z]+\))?:$/.test(line))
+      inVerb = line.endsWith(`(for ${verb}):`)
+    if (!inVerb) continue
+    for (const f of line.match(/--[a-zA-Z][a-zA-Z-]*/g) ?? []) flags.add(f)
+  }
+  return [...flags]
+}
+
+export { CORE_VERBS } from '../util/index.js'