@vzn/vx 0.0.0 → 0.0.12

package/src/cache/tar.ts

@@ -0,0 +1,343 @@
+// In-process tar reader (POSIX ustar) for cache-hit restore.
+//
+// We replace `Bun.spawn(['tar', '-xf', ...])` on the cache-hit path
+// to save a per-restore fork+exec (~5-10ms on Linux). At 200 cached
+// tasks per run, that's 1-2s of pure overhead reclaimed.
+//
+// Tar layout we accept (produced by GNU/BSD `tar -cf - -C stage X Y Z`):
+//   - 512-byte POSIX ustar headers
+//   - name        : bytes 0..99    (null-padded)
+//   - mode        : bytes 100..107 (octal ASCII, null-padded)
+//   - mtime       : bytes 136..147 (octal ASCII seconds since epoch)
+//   - size        : bytes 124..135 (octal ASCII)
+//   - typeflag    : byte 156       ('0' or '\0' = file, '5' = dir,
+//                                   '2' = symlink, 'L' = GNU longname,
+//                                   'x' / 'g' / 'X' = PAX extended
+//                                   header — metadata for the next
+//                                   entry, not a file itself)
+//   - data        : `size` bytes, padded up to next 512-byte block
+//   - end         : two 512-byte zero blocks
+//
+// We tolerate the GNU longname extension (typeflag 'L') because some
+// tar binaries emit it for paths > 100 chars even when ustar's
+// prefix+name (256 chars) would suffice. PAX extended-header records
+// ('x' / 'g' / 'X') are SKIPPED — BSD tar (macOS default) emits one
+// per entry for xattrs / mtime-nanos / SCHILY metadata. We don't
+// need any of that; treating the headers as regular files would put
+// `PaxHeaders/foo` junk entries into the restored tree.
+//
+// AppleDouble files (`._<name>`) are also SKIPPED — macOS Finder /
+// `cp -p` leave these resource-fork siblings around (e.g. `._main.js`
+// next to `main.js`). They're not real outputs; filtering at parse
+// time prevents them from showing up in restored trees even when an
+// older / contaminated cache entry includes them. The matching
+// input-side filter lives in `src/cache/inputs.ts:ALWAYS_IGNORE`.
+//
+// We DO NOT support sparse files, character/block devices, or
+// hardlinks — they don't appear in build outputs.
+
+import { lstat, mkdir, chmod, realpath, unlink, utimes } from 'node:fs/promises'
+import path from 'node:path'
+
+export interface TarHeader {
+  /** Full archive-relative name, e.g. "outputs/dist/index.js" or "manifest.json". */
+  name: string
+  size: number
+  /** File permission bits, e.g. 0o644. */
+  mode: number
+  /** Modification time in ms since epoch (seconds-resolution from tar). */
+  mtimeMs: number
+  isDir: boolean
+  /** Offset in `tarBytes` where the file's data starts. */
+  dataOffset: number
+}
+
+/**
+ * Walk a tar archive's headers and return them in source order.
+ * Cheap: only reads 512-byte blocks; never decodes file bodies.
+ */
+export function parseTarHeaders(tarBytes: Uint8Array): TarHeader[] {
+  const headers: TarHeader[] = []
+  const dec = new TextDecoder('utf-8')
+  let off = 0
+  let pendingLongName: string | null = null
+
+  while (off + 512 <= tarBytes.length) {
+    const header = tarBytes.subarray(off, off + 512)
+    // End-of-archive marker: 512 zero bytes (tar pads two such blocks).
+    let zero = true
+    for (let i = 0; i < 512 && zero; i++) {
+      if (header[i] !== 0) zero = false
+    }
+    if (zero) break
+
+    let nameEnd = 0
+    while (nameEnd < 100 && header[nameEnd] !== 0) nameEnd++
+    const rawName = dec.decode(header.subarray(0, nameEnd)).replace(/^\.\//, '')
+
+    const modeStr = dec.decode(header.subarray(100, 108)).trim().replace(/ +$/, '')
+    const mode = parseInt(modeStr, 8) || 0o644
+
+    const sizeStr = dec.decode(header.subarray(124, 136)).trim().replace(/ +$/, '')
+    const size = parseInt(sizeStr, 8) || 0
+
+    const mtimeStr = dec.decode(header.subarray(136, 148)).trim().replace(/ +$/, '')
+    const mtimeMs = (parseInt(mtimeStr, 8) || 0) * 1000
+
+    const typeFlag = header[156]
+    const isDir = typeFlag === 0x35 /* '5' */ || rawName.endsWith('/')
+
+    const dataStart = off + 512
+    const padded = Math.ceil(size / 512) * 512
+
+    if (typeFlag === 0x4c /* 'L' — GNU longname */) {
+      // The data block carries the next entry's full name (null-
+      // terminated). Stash it; the actual file header follows.
+      // Strip the null terminator(s) without writing a regex that lint
+      // flags as a control-char match.
+      const raw = dec.decode(tarBytes.subarray(dataStart, dataStart + size))
+      let endIdx = raw.length
+      while (endIdx > 0 && raw.charCodeAt(endIdx - 1) === 0) endIdx--
+      pendingLongName = raw.slice(0, endIdx)
+      off = dataStart + padded
+      continue
+    }
+
+    // PAX extended headers: metadata about the next entry (long
+    // names, large sizes, nanosecond mtime, BSD xattrs, etc). Their
+    // own entry name is something like `PaxHeaders/<basename>` or
+    // `./PaxHeader.NNNN/<basename>` — definitely not a file we want
+    // to write to disk. Skip the whole record (header + padded data)
+    // and let the next entry through unchanged.
+    if (
+      typeFlag === 0x78 /* 'x' — per-entry PAX */ ||
+      typeFlag === 0x67 /* 'g' — global PAX */ ||
+      typeFlag === 0x58 /* 'X' — Solaris extended */
+    ) {
+      off = dataStart + padded
+      continue
+    }
+
+    // Reject typeflags we don't support: hardlink (1), symlink (2),
+    // char device (3), block device (4), FIFO (6), contiguous (7).
+    // Build outputs are regular files + directories; anything else
+    // is either a producer bug or a smuggled non-file artifact (a
+    // symlink to /etc/passwd, a /dev/null mapping, etc.). Reject
+    // explicitly so future extractors can't be tricked into honoring
+    // these by accident.
+    if (typeFlag === 0x31 /* '1' */) {
+      throw new TarSecurityError(`tar entry typeflag 'hardlink' is unsupported: ${rawName}`)
+    }
+    if (typeFlag === 0x32 /* '2' */) {
+      throw new TarSecurityError(`tar entry typeflag 'symlink' is unsupported: ${rawName}`)
+    }
+    if (typeFlag === 0x33 /* '3' */) {
+      throw new TarSecurityError(`tar entry typeflag 'chardev' is unsupported: ${rawName}`)
+    }
+    if (typeFlag === 0x34 /* '4' */) {
+      throw new TarSecurityError(`tar entry typeflag 'blockdev' is unsupported: ${rawName}`)
+    }
+    if (typeFlag === 0x36 /* '6' */) {
+      throw new TarSecurityError(`tar entry typeflag 'fifo' is unsupported: ${rawName}`)
+    }
+    if (typeFlag === 0x37 /* '7' */) {
+      throw new TarSecurityError(`tar entry typeflag 'contiguous' is unsupported: ${rawName}`)
+    }
+
+    const name = pendingLongName ?? rawName
+    pendingLongName = null
+
+    if (name.length === 0) {
+      off = dataStart + padded
+      continue
+    }
+
+    // Path-traversal defense. We only ever want to extract entries
+    // under `outputs/<rel>` where `<rel>` is project-relative and
+    // contains no `..` segments and no absolute prefix. Reject at
+    // parse time so a malicious cache artifact can't write outside
+    // the destination (zip-slip class). Mirrors Turbo's
+    // restore.rs:check_path normalization.
+    if (name.startsWith('/')) {
+      throw new TarSecurityError(`tar entry name is absolute (unsafe): ${name}`)
+    }
+    if (hasParentSegment(name)) {
+      throw new TarSecurityError(`tar entry name escapes via '..' (unsafe): ${name}`)
+    }
+    if (name.includes('//')) {
+      throw new TarSecurityError(`tar entry name has empty path component (unsafe): ${name}`)
+    }
+    // Windows-shaped paths are categorically unsafe to extract on
+    // POSIX hosts (and vice versa): backslash separators, drive
+    // letters, extended-length prefixes. Reject before we touch
+    // anything.
+    if (name.includes('\\')) {
+      throw new TarSecurityError(`tar entry uses backslash separators (windows-unsafe): ${name}`)
+    }
+    if (/^[A-Za-z]:[\\/]/.test(name)) {
+      throw new TarSecurityError(`tar entry has windows drive prefix (unsafe): ${name}`)
+    }
+
+    // AppleDouble resource-fork siblings — basename starting with
+    // `._`. macOS Finder / `cp -p` leave these next to real files
+    // (e.g. `._main.js` shadowing `main.js`). They carry xattrs we
+    // don't care about; restoring them just pollutes the tree.
+    const basename = name.slice(name.lastIndexOf('/') + 1)
+    if (basename.startsWith('._')) {
+      off = dataStart + padded
+      continue
+    }
+
+    headers.push({ name, size, mode, mtimeMs, isDir, dataOffset: dataStart })
+    off = dataStart + padded
+  }
+  return headers
+}
+
+/**
+ * Thrown by `parseTarHeaders` when an entry's name would let it
+ * escape the extraction destination (absolute path, `..` traversal,
+ * doubled separators). Callers should treat this as a corrupt /
+ * malicious artifact — log it, drop the cache entry, and re-run.
+ */
+export class TarSecurityError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'TarSecurityError'
+  }
+}
+
+function hasParentSegment(p: string): boolean {
+  if (p === '..' || p.startsWith('../') || p.endsWith('/..')) return true
+  return p.includes('/../')
+}
+
+/**
+ * Read a single tar entry's text body. Returns '' for missing entries.
+ * Used to extract `stdout` / `stderr` inline.
+ */
+export function readTarText(tarBytes: Uint8Array, headers: TarHeader[], name: string): string {
+  const h = headers.find((e) => e.name === name)
+  if (!h) return ''
+  return new TextDecoder('utf-8').decode(tarBytes.subarray(h.dataOffset, h.dataOffset + h.size))
+}
+
+/**
+ * Extract a tar's `outputs/<rel>` entries into `destDir/<rel>` (strips
+ * the `outputs/` prefix), and — when `workspaceDest` is given — its
+ * `workspace-outputs/<rel>` entries into `workspaceDest/<rel>`.
+ * Entries in neither namespace are ignored; workspace entries are
+ * also ignored when no `workspaceDest` is supplied.
+ */
+export async function extractOutputs(
+  tarBytes: Uint8Array,
+  destDir: string,
+  workspaceDest?: string,
+): Promise<void> {
+  const headers = parseTarHeaders(tarBytes)
+
+  await mkdir(destDir, { recursive: true })
+
+  // Each namespace anchors at its own destination dir.
+  const destFor = (name: string): { base: string; rel: string } | null => {
+    if (name.startsWith('outputs/')) {
+      return { base: destDir, rel: name.slice('outputs/'.length) }
+    }
+    if (workspaceDest !== undefined && name.startsWith('workspace-outputs/')) {
+      return { base: workspaceDest, rel: name.slice('workspace-outputs/'.length) }
+    }
+    return null
+  }
+
+  // Two passes: directories first (depth-first via sort), then files.
+  // Keeps file writes from racing with their parent dir creation.
+  const dirEntries = headers
+    .filter((h) => h.isDir)
+    .map((h) => destFor(h.name))
+    .filter((d): d is { base: string; rel: string } => d !== null && d.rel.length > 0)
+    .sort((a, b) => (a.rel < b.rel ? -1 : 1))
+  for (const d of dirEntries) {
+    await mkdir(path.join(d.base, d.rel), { recursive: true })
+  }
+
+  const fileEntries = headers
+    .map((h) => ({ h, dest: destFor(h.name) }))
+    .filter(
+      (e): e is { h: TarHeader; dest: { base: string; rel: string } } =>
+        e.dest !== null && !e.h.isDir && e.dest.rel.length > 0,
+    )
+
+  // The REAL path of each base dir (symlinks resolved), memoized. Used to
+  // catch a symlinked ANCESTOR under the output tree: the lexical check
+  // below stops a `..` name, but if `<dest>/dist` is already an on-disk
+  // symlink pointing outside (planted in the repo or by a dependency
+  // postinstall), a lexically-contained entry `dist/x` would follow it and
+  // escape. Both sides are realpath'd, so a legitimate symlinked ANCESTOR of
+  // the base dir itself (e.g. macOS /tmp → /private/tmp) resolves
+  // consistently and is not flagged.
+  const realBaseCache = new Map<string, string>()
+  const realBaseOf = async (base: string): Promise<string> => {
+    const key = path.resolve(base)
+    let r = realBaseCache.get(key)
+    if (r === undefined) {
+      r = await realpath(key).catch(() => key)
+      realBaseCache.set(key, r)
+    }
+    return r
+  }
+
+  await Promise.all(
+    fileEntries.map(async ({ h, dest }) => {
+      const destResolved = path.resolve(dest.base)
+      const target = path.join(dest.base, dest.rel)
+      // Defense in depth — parseTarHeaders already rejects `..` /
+      // absolute paths, but if a future glitch lets one through we
+      // catch it here. path.resolve normalizes `..` components in
+      // the joined path so the comparison is sound.
+      const targetResolved = path.resolve(target)
+      if (targetResolved !== destResolved && !targetResolved.startsWith(destResolved + path.sep)) {
+        throw new TarSecurityError(`tar entry escapes destDir (unsafe): ${h.name}`)
+      }
+
+      // Ensure the parent dir exists. Cheap because mkdir(recursive)
+      // is a no-op when the dir is already there.
+      await mkdir(path.dirname(target), { recursive: true })
+
+      // Symlinked-parent escape check: the parent dir now exists — resolve
+      // its real path and require it to still sit inside the real base dir.
+      // A poisoned artifact whose entry lands under a pre-existing symlinked
+      // directory is refused before any bytes are written outside the tree.
+      const realBase = await realBaseOf(dest.base)
+      const realParent = await realpath(path.dirname(target)).catch(() => path.dirname(target))
+      if (realParent !== realBase && !realParent.startsWith(realBase + path.sep)) {
+        throw new TarSecurityError(`tar entry escapes destDir via a symlinked parent: ${h.name}`)
+      }
+
+      // Symlink TOCTOU defense: if the target IS a symlink, unlink
+      // it first so the upcoming write doesn't follow the link and
+      // clobber whatever the link points to (e.g. an attacker placed
+      // `<dest>/link -> /etc/passwd` to redirect our write). lstat
+      // doesn't follow the symlink, so we can detect the link itself.
+      try {
+        const ls = await lstat(target)
+        if (ls.isSymbolicLink()) await unlink(target)
+      } catch {
+        // Target doesn't exist — that's the common case; fall through.
+      }
+
+      const body = tarBytes.subarray(h.dataOffset, h.dataOffset + h.size)
+      // Bun.write benchmarks ~2× faster than fs/promises.writeFile
+      // for these per-entry restore writes (167µs vs 361µs per 1KB
+      // on the dev box; ~1.6× in batched Promise.all over 50 files).
+      // Native fast path; same correctness contract.
+      await Bun.write(target, body)
+      // Permission bits + mtime restoration — keeps a re-tar of the
+      // restored tree byte-identical to the original artifact.
+      if ((h.mode & 0o777) !== 0) await chmod(target, h.mode & 0o777)
+      if (h.mtimeMs > 0) {
+        const t = h.mtimeMs / 1000
+        await utimes(target, t, t)
+      }
+    }),
+  )
+}

package/src/cli/backend.ts

@@ -0,0 +1,23 @@
+// Execution as a pluggable backend — the same idea as the cache's
+// local/remote split, applied to running tasks. `vx run` resolves a
+// backend and calls `run(request)`; it neither knows nor cares whether the
+// work happened in-process or was delegated to a service. The DEFAULT is
+// pure in-process; routing to a service (local or hosted) is a `backend`
+// plugin capability, never core.
+
+import {
+  run as runOrchestrator,
+  projectOutcome,
+  requestToOptions,
+  type RunBackend,
+} from '../orchestrator/index.js'
+
+/** Run in-process via `run()` — core's default backend. Byte-identical to a plain `run()`. */
+export function localBackend(): RunBackend {
+  return {
+    async run(request) {
+      const summary = await runOrchestrator(requestToOptions(request))
+      return { ok: summary.ok, outcomes: summary.outcomes.map(projectOutcome) }
+    },
+  }
+}

package/src/cli/cache.ts

@@ -0,0 +1,101 @@
+import { Cache } from '../cache/index.js'
+import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+import { formatBytes } from './format.js'
+
+export async function cacheCmd(args: readonly string[]): Promise<number> {
+  const [sub, ...rest] = args
+  switch (sub) {
+    case 'prune':
+      return await pruneCmd(rest)
+    case undefined:
+      process.stderr.write('vx cache: missing subcommand. Try `vx cache prune`.\n')
+      return 1
+    default:
+      process.stderr.write(`vx cache: unknown subcommand: ${sub}\n`)
+      return 1
+  }
+}
+
+interface PruneArgs {
+  olderThanMs?: number
+  maxBytes?: number
+  error?: string
+}
+
+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)` }
+      const ms = parseDuration(v)
+      if (ms === null) return { error: `invalid duration: ${v}` }
+      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)` }
+      const bytes = parseSize(v)
+      if (bytes === null) return { error: `invalid size: ${v}` }
+      out.maxBytes = bytes
+    } else {
+      return { error: `unknown argument: ${a}` }
+    }
+  }
+  if (out.olderThanMs === undefined && out.maxBytes === undefined) {
+    return { error: 'must pass --older-than <duration> or --max-size <bytes>' }
+  }
+  return out
+}
+
+async function pruneCmd(args: readonly string[]): Promise<number> {
+  const parsed = parsePruneArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx cache prune: ${parsed.error}\n`)
+    return 1
+  }
+  const cwd = process.cwd()
+  let root: string
+  try {
+    root = await findWorkspaceRoot(cwd)
+  } catch (err) {
+    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))
+  try {
+    const opts: { olderThanMs?: number; maxBytes?: number } = {}
+    if (parsed.olderThanMs !== undefined) opts.olderThanMs = parsed.olderThanMs
+    if (parsed.maxBytes !== undefined) opts.maxBytes = parsed.maxBytes
+    const result = await cache.prune(opts)
+    process.stdout.write(
+      `Pruned ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)} freed)\n`,
+    )
+  } finally {
+    cache.close()
+  }
+  return 0
+}
+
+export function parseDuration(input: string): number | null {
+  const m = input.match(/^(\d+)([smhd])$/)
+  if (!m) return null
+  const n = Number(m[1])
+  const unit = m[2]
+  const mult = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000
+  return n * mult
+}
+
+export function parseSize(input: string): number | null {
+  const m = input.match(/^(\d+)([KMGT])?B?$/i)
+  if (!m) return null
+  const n = Number(m[1])
+  const u = (m[2] ?? '').toUpperCase()
+  const mult =
+    u === '' ? 1 : u === 'K' ? 1024 : u === 'M' ? 1024 * 1024 : u === 'G' ? 1024 ** 3 : 1024 ** 4
+  return n * mult
+}

package/src/cli/format.ts

@@ -0,0 +1,15 @@
+/**
+ * Human-readable byte size with KB/MB/GB/TB/PB suffixes and one
+ * decimal of precision below 10 of any unit. Used by `vx stats` and
+ * `vx cache prune` output.
+ */
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`
+  const units = ['KB', 'MB', 'GB', 'TB']
+  let v = n / 1024
+  for (const u of units) {
+    if (v < 1024) return `${v.toFixed(v < 10 ? 1 : 0)} ${u}`
+    v /= 1024
+  }
+  return `${v.toFixed(0)} PB`
+}

package/src/cli/help.ts

@@ -0,0 +1,123 @@
+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.',
+      '      --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.',
+      '                                  all: both. 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 + remote-cache 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'),
+  )
+}