@vzn/vx 0.0.18 → 0.0.21

package/src/cli/cache.ts

@@ -1,6 +1,8 @@
-import { Cache } from '../cache/index.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { seeHelp } from './help.js'
 import { parseDecimalInt, parseSize } from '../util/index.js'
-import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/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
 }
 
@@ -60,9 +65,25 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
           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) {
@@ -85,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()

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,5 +1,32 @@
-export function printHelp(pluginCommands: readonly string[] = []): void {
-  process.stdout.write(helpText(pluginCommands))
+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 {
@@ -9,16 +36,15 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '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 cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--cache-dir <path>]',
     '  vx lock [--check]',
-    '  vx init [--dry] [--force]',
-    '  vx migrate [--from turbo|nx|scripts] [--dry] [--force]',
+    '  vx init [--dry] [--force] [--mjs]',
     '  vx upgrade [tag]',
-    '  vx show [PROJECT[#TASK]] [--format pretty|json]',
-    '  vx info',
-    '  vx why [TASK | PKG#TASK] [--run <runId>] [--format pretty|json]',
-    '  vx last [RUNID] [--list[=N]] [--format pretty|json]',
-    '  vx prune PROJECT [--out-dir <dir>] [--docker]',
+    '  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',
     '',
@@ -33,8 +59,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     "  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.',
+    '      --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>',
@@ -50,23 +76,11 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '      --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 | 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=quiet, 1=verbose summary, 2+=debug (reserved).',
+    '      --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.',
@@ -97,6 +111,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '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).',
     '',
@@ -105,20 +121,18 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     "  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 prune <project>   Emit a self-contained workspace SUBSET — the project +',
-    '                       its transitive workspace deps, root manifests, and the',
-    '                       (unpruned) lockfile — for Docker builds. --docker splits',
-    '                       json/ (manifests, the cacheable install layer) from full/.',
     "  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.',
@@ -127,14 +141,17 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '',
     'Migration:',
     '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
-    '                       from package.json scripts (= vx migrate --from scripts).',
-    '  vx migrate           Generate vx.config.ts per package from turbo.json or an',
-    '                       Nx project graph (.nx/workspace-data/project-graph.json);',
-    '                       with neither present, from package.json scripts.',
-    '                       Unmappable settings become TODO(vx-migrate) comments;',
-    '                       turbo global fields become a shared vx-preset.ts.',
+    '                       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.* / vx-preset.ts files.',
+    '      --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',
@@ -150,6 +167,15 @@ export function helpText(pluginCommands: readonly string[] = []): string {
   ].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 —
@@ -166,3 +192,5 @@ export function documentedFlags(verb: string): string[] {
   }
   return [...flags]
 }
+
+export { CORE_VERBS } from '../util/index.js'

package/src/cli/index.ts

@@ -4,9 +4,9 @@
 
 import { VERSION } from '../version.js'
 import { runCmd } from './run.js'
-import { printHelp } from './help.js'
-import { pluginCommandHelp, resolvePluginCommand } from './plugin-commands.js'
-import { UserError } from '../util/index.js'
+import { CORE_VERBS, printHelp } from './help.js'
+import { pluginCommandHelp, resolvePluginCommand, pluginVerbs } from './plugin-commands.js'
+import { MOVED_VERBS, nearest, UserError } from '../util/index.js'
 
 // Every verb but `run` is imported when invoked. `vx run` is the hot path
 // and nearly every invocation; the other verbs' modules are code that
@@ -18,6 +18,16 @@ import { UserError } from '../util/index.js'
 export async function run(argv: readonly string[]): Promise<number> {
   const [command, ...rest] = argv
 
+  // `vx <verb> --help` is the universal reflex, and every verb answered
+  // `unknown flag: --help` and exited 1 (walkthrough, 2026-09-04). Only args
+  // BEFORE a `--` count: `vx run build -- --help` forwards it to the task,
+  // which is the one place `--help` is not being asked of vx. Core verbs
+  // only — a plugin verb owns its own arguments, `--help` included.
+  if (command !== undefined && wantsHelp(command, rest)) {
+    printHelp(await pluginCommandHelp(), command)
+    return 0
+  }
+
   switch (command) {
     case undefined:
     case '--help':
@@ -37,13 +47,8 @@ export async function run(argv: readonly string[]): Promise<number> {
       return await (await import('./cache.js')).cacheCmd(rest)
     case 'lock':
       return await (await import('./lock.js')).lockCmd(rest)
-    case 'migrate':
-      return await (await import('./migrate.js')).migrateCmd(rest)
     case 'init':
-      // A workspace from nowhere: package.json scripts are the source.
-      return await (
-        await import('./migrate.js')
-      ).migrateCmd(['--from', 'scripts', ...rest], { init: true })
+      return await (await import('./init.js')).initCmd(rest)
     case 'upgrade':
       return await (await import('./upgrade.js')).upgradeCmd(rest)
     case 'show':
@@ -55,8 +60,8 @@ export async function run(argv: readonly string[]): Promise<number> {
       return await (await import('./why.js')).whyCmd(rest)
     case 'last':
       return await (await import('./last.js')).lastCmd(rest)
-    case 'prune':
-      return await (await import('./prune.js')).pruneWorkspaceCmd(rest)
+    case 'completions':
+      return await (await import('./completions.js')).completionsCmd(rest, await pluginVerbs())
     default: {
       // Not a core verb: a plugin declared in the workspace around the cwd
       // may own it (`VxPlugin.commands`). Core verbs were matched above, so
@@ -82,6 +87,14 @@ export async function run(argv: readonly string[]): Promise<number> {
         resolved !== null && 'loadError' in resolved
           ? `\n  (plugin verbs could not be looked up: vx.workspace failed to load: ${resolved.loadError})`
           : ''
+      // A verb core owned once (`migrate`, `prune`) and a package owns now:
+      // the pointer, but only after the plugins had their chance — a
+      // workspace that declares a plugin verb of that name keeps it.
+      const moved = MOVED_VERBS[command]
+      if (moved !== undefined) {
+        process.stderr.write(`${moved}${loadNote}\n`)
+        return 1
+      }
       if (command === 'serve' || command === 'dev') {
         // vx core is only a task runner — it has no service layer of its
         // own. A dashboard, remote cache, distributed execution, etc. are
@@ -97,7 +110,7 @@ export async function run(argv: readonly string[]): Promise<number> {
         )
         return 1
       }
-      process.stderr.write(`vx: unknown command: ${command}${loadNote}\n`)
+      process.stderr.write(`vx: unknown command: ${command}${didYouMeanVerb(command)}${loadNote}\n`)
       printHelp()
       return 1
     }
@@ -105,12 +118,38 @@ export async function run(argv: readonly string[]): Promise<number> {
 }
 
 // Re-exports for tests + programmatic embedders.
-export { detectFlow, parseRunArgs, resolveRunOptions, type RunArgs } from './run.js'
+export {
+  detectFlow,
+  parseConcurrency,
+  parseRunArgs,
+  resolveRunOptions,
+  type RunArgs,
+} from './run.js'
 export { parsePruneArgs, parseDuration, parseSize } from './cache.js'
 export { parseLockArgs, type LockArgs } from './lock.js'
-export { parseMigrateArgs, type MigrateArgs } from './migrate.js'
+export { parseInitArgs, type InitArgs } from './init.js'
 export { parseShowArgs, type ShowArgs } from './show.js'
 export { parseWhyArgs } from './why.js'
 export { parseLastArgs } from './last.js'
-export { parsePruneWorkspaceArgs } from './prune.js'
 export { formatBytes } from './format.js'
+export { registerCoreAlias } from './core-alias.js'
+
+/**
+ * Is this invocation asking for help rather than work? See the call site for
+ * why the scan stops at `--`, and why plugin verbs are excluded.
+ */
+function wantsHelp(command: string, rest: readonly string[]): boolean {
+  if (!(CORE_VERBS as readonly string[]).includes(command)) return false
+  const sep = rest.indexOf('--')
+  const own = sep === -1 ? rest : rest.slice(0, sep)
+  return own.includes('--help') || own.includes('-h')
+}
+
+/** ` Did you mean run?` for a verb within two edits of a core one — the same
+ *  hint a task or flag typo gets. Plugin verbs are not listed: resolving
+ *  them loads the workspace, and this path is reached only when that
+ *  lookup found nothing. */
+function didYouMeanVerb(verb: string): string {
+  const best = nearest(verb, CORE_VERBS)
+  return best === undefined ? '' : `. Did you mean ${best}?`
+}