@vzn/vx 0.0.594 → 0.0.596

package/src/cache/zstd.ts

@@ -194,15 +194,21 @@ export async function decodedTar(
     }
     return oneChunk(await zstdDecompressBounded(source, hash, cap))
   }
+  // A BunFile reads no further than the size its first stat cached, and a
+  // save or ingest of the same key may rename a longer copy over the path
+  // after that stat: the read came back cut short, the restore called the
+  // new artifact corrupt and dropped it. The size only picks the decode;
+  // each read goes through a handle that has not stat the path yet.
+  const fresh = (): Bun.BunFile => Bun.file(source.name!)
   if (source.size <= STREAM_DECODE_FROM) {
-    const bytes = await source.bytes()
+    const bytes = await fresh().bytes()
     if (assertDeclaredSize(bytes, hash, cap) === null || !isOneFrame(bytes)) {
-      return zstdDecodeStream(source, hash, cap)
+      return zstdDecodeStream(new Blob([bytes]), hash, cap)
     }
     return oneChunk(await zstdDecompressBounded(bytes, hash, cap))
   }
-  assertDeclaredSize(await source.slice(0, 32).bytes(), hash, cap)
-  return zstdDecodeStream(source, hash, cap)
+  assertDeclaredSize(await fresh().slice(0, 32).bytes(), hash, cap)
+  return zstdDecodeStream(fresh(), hash, cap)
 }
 
 /**

package/src/cli/cache.ts

@@ -85,10 +85,15 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
     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)` }
+        return {
+          error: `--older-than requires a value: a duration like 30d, 24h or 60m${seeHelp('cache')}`,
+        }
       }
       const ms = parseDuration(v)
-      if (ms === null) return { error: `invalid duration: ${v} (e.g. 30d, 24h, 60m)` }
+      if (ms === null)
+        return {
+          error: `--older-than must be a duration like 30d, 24h or 60m (got ${v})${seeHelp('cache')}`,
+        }
       // `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
@@ -102,10 +107,11 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
     } 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)` }
+        return { error: `--max-size requires a value: a size like 500M or 1G${seeHelp('cache')}` }
       }
       const bytes = parseSize(v)
-      if (bytes === null) return { error: `invalid size: ${v} (e.g. 500M, 1G)` }
+      if (bytes === null)
+        return { error: `--max-size must be a size like 500M or 1G (got ${v})${seeHelp('cache')}` }
       if (bytes === 0) {
         return {
           error: `--max-size 0 would evict every entry — to clear the cache, delete the cache store \`vx info\` names`,
@@ -185,19 +191,9 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
     printPruned({ evicted: 0, bytesFreed: 0, orphans: 0, orphanBytes: 0 }, dry, json)
     return 0
   }
-  if (parsed.dryRun === true) {
-    const earlier = await Cache.orphansBeforeReset(dir)
-    if (earlier !== null) {
-      warnToStderr(
-        `[vx] the cache index is schema ${earlier.found} from another vx version: the prune resets it first, and every artifact past the hour's grace is then an orphan`,
-      )
-      printPruned({ evicted: 0, bytesFreed: 0, ...earlier }, true, json)
-      return 0
-    }
-  }
   const cache =
     parsed.dryRun === true
-      ? new Cache(dir, undefined, undefined, undefined, 'inspect', storeRoot)
+      ? new Cache(dir, undefined, undefined, undefined, 'preview', storeRoot)
       : new Cache(dir, undefined, root, undefined, 'open', storeRoot)
   // A prune deletes rows and artifacts; a cache this user cannot write is
   // refused up front with the directory named, as a run refuses it, rather

package/src/cli/completions.ts

@@ -8,6 +8,13 @@
 import { acceptedFlags, CORE_VERBS, flagHint, seeHelp } from './help.js'
 import { nearest } from '../util/index.js'
 
+/** A flag whose value is one of a fixed set; the tests hold each to its parser. */
+export const FLAG_VALUES: Readonly<Record<string, readonly string[]>> = {
+  '--format': ['pretty', 'json'],
+  '--output-logs': ['full', 'errors-only', 'hash-only', 'none'],
+  '--download': ['all', 'toplevel', 'none'],
+}
+
 export type CompletionShell = 'bash' | 'zsh' | 'fish'
 const SHELLS: readonly CompletionShell[] = ['bash', 'zsh', 'fish']
 
@@ -36,6 +43,14 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
       ...((CORE_VERBS as readonly string[]).includes(v) ? verbFlags(v) : ['--help']),
     ],
   }))
+  // `vx run --output-logs <Tab>` offered the flags again; a flag with a
+  // fixed value set offers that set.
+  const values = table.flatMap((t) =>
+    t.words.flatMap((w) => {
+      const vs = FLAG_VALUES[w]
+      return vs === undefined ? [] : [{ verb: t.verb, flag: w, values: vs.join(' ') }]
+    }),
+  )
   switch (shell) {
     case 'bash':
       return [
@@ -43,10 +58,23 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         '_vx() {',
         '  local cur="${COMP_WORDS[COMP_CWORD]}"',
         '  local verb="${COMP_WORDS[1]}"',
+        '  local prev="${COMP_WORDS[COMP_CWORD-1]}"',
         '  if [ "$COMP_CWORD" -eq 1 ]; then',
         `    COMPREPLY=($(compgen -W "${verbs.join(' ')}" -- "$cur"))`,
         '    return',
         '  fi',
+        // bash splits `--format=js` at the `=` (COMP_WORDBREAKS).
+        '  if [ "$cur" = "=" ]; then',
+        '    cur=""',
+        '  elif [ "$prev" = "=" ]; then',
+        '    prev="${COMP_WORDS[COMP_CWORD-2]}"',
+        '  fi',
+        '  case "$verb $prev" in',
+        ...values.map(
+          (v) =>
+            `    "${v.verb} ${v.flag}") COMPREPLY=($(compgen -W "${v.values}" -- "$cur")); return ;;`,
+        ),
+        '  esac',
         '  case "$verb" in',
         ...table.map(
           (t) => `    ${t.verb}) COMPREPLY=($(compgen -W "${t.words.join(' ')}" -- "$cur")) ;;`,
@@ -66,6 +94,9 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         `    compadd -- ${verbs.join(' ')}`,
         '    return',
         '  fi',
+        '  case "${words[2]} ${words[CURRENT-1]}" in',
+        ...values.map((v) => `    "${v.verb} ${v.flag}") compadd -- ${v.values}; return ;;`),
+        '  esac',
         '  case "${words[2]}" in',
         ...table.map((t) => `    ${t.verb}) compadd -- ${t.words.join(' ')} ;;`),
         '  esac',
@@ -86,11 +117,14 @@ export function completionScript(shell: CompletionShell, verbs: readonly string[
         '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}`,
-          ),
+          t.words.map((w) => {
+            const on = `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}"`
+            if (!w.startsWith('--')) return `${on} -a ${w}`
+            const vs = FLAG_VALUES[w]
+            return vs === undefined
+              ? `${on} -l ${w.slice(2)}`
+              : `${on} -l ${w.slice(2)} -x -a "${vs.join(' ')}"`
+          }),
         ),
         '',
       ].join('\n')
@@ -111,7 +145,9 @@ export async function completionsCmd(
       return 1
     }
     const one = shell !== undefined && args.length === 1
-    const best = one ? nearest(shell, SHELLS) : undefined
+    // One edit: shell names are three or four letters, so two edits took
+    // `tcsh` to `bash`, a different shell.
+    const best = one ? nearest(shell, SHELLS, 1) : undefined
     process.stderr.write(
       `vx completions: expected one shell — bash, zsh or fish${one ? ` (got ${shell})` : ''}${best === undefined ? '' : `. Did you mean ${best}?`}${seeHelp('completions')}\n`,
     )

package/src/cli/foreign-flags.ts

@@ -36,6 +36,17 @@ const list = (v: string | undefined): string[] =>
     .map((s) => s.trim())
     .filter((s) => s !== '')
 
+// Nx's `--projects` labels (find-matching-projects, 23.2.1): `name:` and
+// `directory:` say which match to make; vx's filter says it by form. `tag:`
+// is a filter form already.
+const nxPattern = (p: string): string => {
+  const neg = p.startsWith('!') ? '!' : ''
+  const s = neg === '' ? p : p.slice(1)
+  if (s.startsWith('name:')) return `${neg}${s.slice(5)}`
+  if (s.startsWith('directory:')) return `${neg}./${s.slice(10)}`
+  return p
+}
+
 const GRAPH_IMAGE = /\.(svg|png|jpe?g|pdf|json|html|mermaid)$/i
 
 export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
@@ -142,7 +153,14 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     outcome: 'same',
     vx: '`--output-logs full|errors-only|hash-only|none`',
   },
-  { runner: 'turbo', names: ['--no-cache'], value: false, outcome: 'same', vx: '`--no-cache`' },
+  {
+    runner: 'turbo',
+    names: ['--no-cache'],
+    value: false,
+    outcome: 'same',
+    // Turbo 2.11's own help: "Equivalent to `--cache=local:r,remote:r`".
+    vx: "`--no-cache` reads nothing either; Turbo's (reads, no writes) is `--cache local:r,remote:r`",
+  },
   {
     runner: 'turbo',
     names: ['--cache'],
@@ -357,7 +375,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['--preflight'],
     value: false,
     outcome: 'refuse',
-    vx: '`turboCache()` sends no CORS preflight: drop it',
+    vx: 'set `turboCache({ preflight: true })` or `TURBO_PREFLIGHT=1`',
   },
   {
     runner: 'turbo',
@@ -407,12 +425,15 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['-p', '--projects'],
     value: true,
     outcome: 'alias',
-    vx: "`--filter <pattern>`, one per project; a list opening with `!` starts from all (`--filter '*'`)",
+    vx: "`--filter <pattern>`, one per project (`directory:<d>` is `./<d>`, `name:<n>` is `<n>`); a list opening with `!` starts from all (`--filter '*'`)",
     // Nx reads a leading exclusion as "all projects but": `-p '!b,a'` is
     // every project except b, where vx's filters alone would select a.
     to: (v) => {
       const ps = list(v)
-      return [...(ps[0]?.startsWith('!') ? ['*'] : []), ...ps].flatMap((p) => ['--filter', p])
+      return [...(ps[0]?.startsWith('!') ? ['*'] : []), ...ps].flatMap((p) => [
+        '--filter',
+        nxPattern(p),
+      ])
     },
   },
   {
@@ -421,7 +442,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     value: true,
     outcome: 'alias',
     vx: "`--filter '!<pattern>'`, one per project",
-    to: (v) => list(v).flatMap((p) => ['--filter', `!${p}`]),
+    to: (v) => list(v).flatMap((p) => ['--filter', `!${nxPattern(p)}`]),
   },
   {
     runner: 'nx',

package/src/cli/help.ts

@@ -111,7 +111,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx lock [--check]',
     '  vx init [--dry] [--force] [--mjs] [--plugin <seam>]',
     '  vx upgrade [TAG]',
-    '  vx show [PROJECT[#TASK] | TASK] [--format pretty|json]',
+    '  vx show [PROJECT[#TASK] | TASK] [--filter <pattern>] [--affected[=<ref>]] [--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]] [--failed] [--format pretty|json] [--cache-dir <path>]',
@@ -140,8 +140,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                                  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.',
+    '      --cache-dir <path>          Cache directory override (cwd-relative). Beats VX_CACHE_DIR,',
+    '                                  the workspace cacheDir field and the ~/.vx/<id>/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.',
@@ -209,6 +209,8 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       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.',
+    "      --filter <pattern>  The list (or a task's projects) as `vx run --filter` selects.",
+    '      --affected[=<ref>]  Only what `vx run --affected` selects: changed and dependents.',
     '      --format <fmt>   pretty (default) | json.',
     '  vx info              Workspace doctor: vx/bun/git versions, project +',
     '                       task counts, cache dir/entries/size, recent runs,',

package/src/cli/init.ts

@@ -369,7 +369,7 @@ function namelessNotes(root: string, dirs: readonly string[]): string[] {
   const withScripts = dirs
     .filter((dir) => {
       const scripts = (
-        JSON.parse(readText(path.join(dir, 'package.json')) || '{}') as {
+        JSON.parse(readText(path.join(dir, 'package.json')).replace(/^\uFEFF/, '') || '{}') as {
           scripts?: unknown
         }
       ).scripts

package/src/cli/last.ts

@@ -60,7 +60,10 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       if (spaced) i++
       const n = Number(lv)
       if (!Number.isInteger(n) || n < 1 || n > 500) {
-        return { ...out, error: `invalid --list: ${lv} (expected 1..500)` }
+        return {
+          ...out,
+          error: `--list must be a whole number from 1 to 500 (got ${lv})${seeHelp('last')}`,
+        }
       }
       out.list = n
       continue

package/src/cli/plan-format.ts

@@ -29,6 +29,7 @@ export function formatPlanText(plan: RunPlan): string {
   let miss = 0
   let nocache = 0
   let noop = 0
+  let idle = 0
   for (const t of real) {
     // `@noop`: the run succeeds it without running, whatever its key says.
     const skipped = t.executor === 'noop'
@@ -56,6 +57,7 @@ export function formatPlanText(plan: RunPlan): string {
     else if (t.cacheStatus === 'hit-remote') remote++
     else if (t.cacheStatus === 'miss') miss++
     else if (t.cacheStatus === 'no-cache') nocache++
+    else if (t.cacheStatus === 'not-started') idle++
   }
 
   const hitParts: string[] = []
@@ -67,6 +69,7 @@ export function formatPlanText(plan: RunPlan): string {
   if (miss > 0) summary.push(`${miss} would run`)
   if (nocache > 0) summary.push(`${nocache} no-cache`)
   if (noop > 0) summary.push(`${noop} noop`)
+  if (idle > 0) summary.push(`${idle} not started`)
   lines.push('')
   lines.push(summary.join(', ') + '.')
 
@@ -199,6 +202,8 @@ function symbolFor(s: CacheStatus): string {
       return '·'
     case 'group':
       return '○'
+    case 'not-started':
+      return '−'
   }
 }
 
@@ -214,6 +219,8 @@ function describe(s: CacheStatus): string {
       return 'no-cache (would exec)'
     case 'group':
       return 'group task'
+    case 'not-started':
+      return 'not started (unneeded)'
   }
 }
 
@@ -229,5 +236,7 @@ function dotColor(s: CacheStatus): string {
       return '#e5e7eb' // gray-200
     case 'group':
       return '#f5d0fe' // fuchsia-200
+    case 'not-started':
+      return '#ffffff'
   }
 }

package/src/cli/plugin-templates.ts

@@ -20,8 +20,8 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
   },
   executor: {
     plugin:
-      "// `executor`: where a task's command runs. This one runs it here, in a\n// shell of its own, and stops the shell's whole process group when core\n// aborts the request (a stop, or `exec.timeout`): core cannot reach a\n// process an executor spawned.\nimport { definePlugin, type TaskExecutor, type VxPlugin } from '@vzn/vx'\n\nexport function shellExecutor(): VxPlugin {\n  const executor: TaskExecutor = {\n    name: 'shell',\n    async execute(req) {\n      const started = Date.now()\n      // vx's own `sh`: a bare name is looked up on `req.env`'s PATH, which\n      // leads with the project's node_modules/.bin, where a dependency's\n      // `sh` would run every command.\n      const sh = Bun.which('sh') ?? '/bin/sh'\n      const child = Bun.spawn([sh, '-c', [req.command, ...req.forwardArgs].join(' ')], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const stop = (): void => {\n        try {\n          process.kill(-child.pid, 'SIGTERM')\n        } catch {\n          // already gone\n        }\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const decoder = new TextDecoder()\n        let all = ''\n        for await (const chunk of stream) {\n          const text = decoder.decode(chunk, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const [stdout, stderr, exitCode] = await Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n        child.exited,\n      ])\n      req.signal?.removeEventListener('abort', stop)\n      return {\n        exitCode,\n        durationMs: Date.now() - started,\n        stdout,\n        stderr,\n        violations: [],\n        where: 'shell',\n      }\n    },\n  }\n  return definePlugin(import.meta, { executor: () => executor })\n}\n",
-    test: "// A test for the example `executor` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-executor-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `shellExecutor()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'executor.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { shellExecutor } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('runs the command and says where; stops it on exec.timeout', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: {\n      hello: { exec: { command: 'echo hi > out.txt' } },\n      slow: { exec: { command: 'exec sleep 30', timeout: 300 } },\n    } }`,\n  )\n  await workspace('shellExecutor()')\n  const ok = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(ok.outcomes.map((o) => [o.node.id, o.status, o.where])).toEqual([\n    ['a#hello', 'success', 'shell'],\n  ])\n  expect(await Bun.file(path.join(dir, 'out.txt')).text()).toBe('hi\\n')\n  const started = Date.now()\n  const slow = await run({ cwd: root, tasks: ['slow'], log: log(), handleSignals: false })\n  expect(slow.outcomes.map((o) => [o.node.id, o.status, o.timedOut === true])).toEqual([\n    ['a#slow', 'failed', true],\n  ])\n  expect(Date.now() - started).toBeLessThan(10_000)\n}, 20_000)\n\nit(\"runs the command through this machine's sh, not a project's node_modules/.bin sh\", async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { hello: { exec: { command: 'echo real' } } } }`,\n  )\n  await mkdir(path.join(dir, 'node_modules', '.bin'), { recursive: true })\n  await writeFile(path.join(dir, 'node_modules', '.bin', 'sh'), '#!/bin/sh\\necho planted\\n', {\n    mode: 0o755,\n  })\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['hello'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], 'real\\n'])\n}, 20_000)\n",
+      "// `executor`: where a task's command runs. This one runs it here, in a\n// shell of its own, and stops the shell's whole process group when core\n// aborts the request (a stop, or `exec.timeout`): core cannot reach a\n// process an executor spawned.\nimport { definePlugin, withForwardArgs, type TaskExecutor, type VxPlugin } from '@vzn/vx'\n\nexport function shellExecutor(): VxPlugin {\n  const executor: TaskExecutor = {\n    name: 'shell',\n    async execute(req) {\n      const started = Date.now()\n      // vx's own `sh`: a bare name is looked up on `req.env`'s PATH, which\n      // leads with the project's node_modules/.bin, where a dependency's\n      // `sh` would run every command.\n      const sh = Bun.which('sh') ?? '/bin/sh'\n      // The args after `--`, quoted and placed as the local executor places\n      // them (before a trailing comment, never on a heredoc's terminator).\n      const command = withForwardArgs(req.command, req.forwardArgs)\n      const child = Bun.spawn([sh, '-c', command], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const stop = (): void => {\n        try {\n          process.kill(-child.pid, 'SIGTERM')\n        } catch {\n          // already gone\n        }\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const decoder = new TextDecoder()\n        let all = ''\n        for await (const chunk of stream) {\n          const text = decoder.decode(chunk, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const [stdout, stderr, exitCode] = await Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n        child.exited,\n      ])\n      req.signal?.removeEventListener('abort', stop)\n      return {\n        exitCode,\n        durationMs: Date.now() - started,\n        stdout,\n        stderr,\n        violations: [],\n        where: 'shell',\n      }\n    },\n  }\n  return definePlugin(import.meta, { executor: () => executor })\n}\n",
+    test: "// A test for the example `executor` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-executor-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `shellExecutor()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'executor.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { shellExecutor } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('runs the command and says where; stops it on exec.timeout', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: {\n      hello: { exec: { command: 'echo hi > out.txt' } },\n      slow: { exec: { command: 'exec sleep 30', timeout: 300 } },\n    } }`,\n  )\n  await workspace('shellExecutor()')\n  const ok = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(ok.outcomes.map((o) => [o.node.id, o.status, o.where])).toEqual([\n    ['a#hello', 'success', 'shell'],\n  ])\n  expect(await Bun.file(path.join(dir, 'out.txt')).text()).toBe('hi\\n')\n  const started = Date.now()\n  const slow = await run({ cwd: root, tasks: ['slow'], log: log(), handleSignals: false })\n  expect(slow.outcomes.map((o) => [o.node.id, o.status, o.timedOut === true])).toEqual([\n    ['a#slow', 'failed', true],\n  ])\n  expect(Date.now() - started).toBeLessThan(10_000)\n}, 20_000)\n\nit(\"runs the command through this machine's sh, not a project's node_modules/.bin sh\", async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { hello: { exec: { command: 'echo real' } } } }`,\n  )\n  await mkdir(path.join(dir, 'node_modules', '.bin'), { recursive: true })\n  await writeFile(path.join(dir, 'node_modules', '.bin', 'sh'), '#!/bin/sh\\necho planted\\n', {\n    mode: 0o755,\n  })\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['hello'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], 'real\\n'])\n}, 20_000)\n\nit('puts the args after -- on the command as the local executor does', async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { say: { exec: { command: \"printf '<%s>' # each arg\" } } } }`,\n  )\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['say'],\n    forwardArgs: [\"it's\", 'a b'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], \"<it's><a b>\"])\n}, 20_000)\n",
   },
   graph: {
     plugin:

package/src/cli/run.ts

@@ -3,7 +3,6 @@ import path from 'node:path'
 import { isatty } from 'node:tty'
 import { translateForeign } from './foreign-flags.js'
 import { flagHint, seeHelp } from './help.js'
-import { defaultAffectedBase, findWorkspaceRoot } from '../workspace/index.js'
 import {
   planRun,
   formatRunReportMarkdown,
@@ -13,12 +12,11 @@ import {
   type RunOptions,
   type RunResult,
 } from '../orchestrator/index.js'
-import type { ContinueMode } from '../graph/index.js'
+import type { ContinueMode, TaskOutcome } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
-import { findCwdSelection, pickTask, resolveFilters } from './select.js'
+import { affectedFilterFor, findCwdSelection, pickTask, resolveFilters } from './select.js'
 import { nxTargetHint, taskNamesHere } from './task-verb.js'
-import { loadCliWorkspace } from './workspace-config.js'
-import { MAX_TIMEOUT_MS, isUserError, parseDecimalInt, machineParallelism } from '../util/index.js'
+import { MAX_TIMEOUT_MS, parseDecimalInt, machineParallelism } from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
 
 export interface RunArgs {
@@ -113,7 +111,7 @@ export function parseConcurrency(v: string, cpus = machineParallelism()): number
 }
 
 /** `verb` is the one being parsed for: `vx watch` reads `vx run`'s flags, and
- * its refusals pointed at `vx run --help` (M-58). */
+ * its flag hints named `vx run` (M-58). The caller appends the help pointer. */
 export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' = 'run'): RunArgs {
   const out: RunArgs = {
     tasks: [],
@@ -185,7 +183,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
     } else if (RETIRED_EXCLUDE_DEPENDENCIES.test(a ?? '')) {
       return {
         ...out,
-        error: `unknown flag: ${a} (the flag is --exclude-dependencies)${seeHelp(verb)}`,
+        error: `unknown flag: ${a} (the flag is --exclude-dependencies)`,
       }
     } else if (a === '--exclude-dependencies') {
       out.excludeDependencies = 'all'
@@ -215,7 +213,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
         return { ...out, error: `--retry requires a value (a non-negative integer)` }
       const n = parseDecimalInt(v)
       if (n === null) {
-        return { ...out, error: `--retry must be a non-negative integer, got: ${v}` }
+        return { ...out, error: `--retry must be a non-negative integer (got ${v})` }
       }
       out.retries = n
     } else if (a === '--timeout' || a?.startsWith('--timeout=')) {
@@ -234,19 +232,31 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
         }
       }
       if (n === null || n <= 0) {
-        return { ...out, error: `--timeout must be a positive integer (ms), got: ${v}` }
+        return { ...out, error: `--timeout must be a positive integer in ms (got ${v})` }
       }
       out.timeout = n
     } else if (a === '--output-logs' || a?.startsWith('--output-logs=')) {
       const v = a === '--output-logs' ? before[++i] : a.slice('--output-logs='.length)
+      if (v === undefined || v === '') {
+        return {
+          ...out,
+          error: `--output-logs requires a value (full, errors-only, hash-only, or none)`,
+        }
+      }
       if (v !== 'full' && v !== 'errors-only' && v !== 'none' && v !== 'hash-only') {
-        return { ...out, error: `--output-logs must be full, errors-only, hash-only, or none` }
+        return {
+          ...out,
+          error: `--output-logs must be full, errors-only, hash-only, or none (got ${v})`,
+        }
       }
       out.outputLogs = v
     } else if (a === '--download' || a?.startsWith('--download=')) {
       const v = a === '--download' ? before[++i] : a.slice('--download='.length)
+      if (v === undefined || v === '') {
+        return { ...out, error: `--download requires a value (all, toplevel, or none)` }
+      }
       if (v !== 'all' && v !== 'toplevel' && v !== 'none') {
-        return { ...out, error: `--download must be all, toplevel, or none` }
+        return { ...out, error: `--download must be all, toplevel, or none (got ${v})` }
       }
       out.download = v
     } else if (a === '--cache-dir' || a?.startsWith('--cache-dir=')) {
@@ -301,8 +311,11 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
       out.continueMode = 'always'
     } else if (a?.startsWith('--continue=')) {
       const v = a.slice('--continue='.length)
+      if (v === '') {
+        return { ...out, error: `--continue= requires a mode (never, deps-ok, or always)` }
+      }
       if (v !== 'never' && v !== 'deps-ok' && v !== 'always') {
-        return { ...out, error: `--continue must be never, deps-ok, or always` }
+        return { ...out, error: `--continue must be never, deps-ok, or always (got ${v})` }
       }
       out.continueMode = v
     } else if (a === '--verbosity' || a?.startsWith('--verbosity=')) {
@@ -366,7 +379,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
       }
       out.report = fmt
     } else if (a !== undefined && a.startsWith('-')) {
-      return { ...out, error: `unknown flag: ${a}${flagHint(verb, a)}${seeHelp(verb)}` }
+      return { ...out, error: `unknown flag: ${a}${flagHint(verb, a)}` }
     } else if (a !== undefined) {
       out.tasks.push(a)
     }
@@ -446,20 +459,9 @@ async function scopeFilters(
   const filterStrings = [...parsed.filters]
   let affectedFilter: string | undefined
   if (parsed.affected !== undefined) {
-    const root = await findWorkspaceRoot(cwd)
-    let base = parsed.affected
-    // The workspace's `affectedBase` — or a plugin's `config` stage, from
-    // nx.json's `defaultBase` or `TURBO_SCM_BASE` — comes before the guess.
-    if (base === '') base = (await loadCliWorkspace(root)).workspaceConfig?.affectedBase ?? ''
-    if (base === '') {
-      try {
-        base = await defaultAffectedBase(root)
-      } catch (err) {
-        if (!isUserError(err)) throw err
-        return { error: err.message }
-      }
-    }
-    affectedFilter = `...[${base}]`
+    const f = await affectedFilterFor(cwd, parsed.affected)
+    if (typeof f === 'object') return f
+    affectedFilter = f
     filterStrings.unshift(affectedFilter)
   }
   return { filterStrings, ...(affectedFilter !== undefined ? { affectedFilter } : {}) }
@@ -484,6 +486,7 @@ export async function resolveRunOptions(
   parsed: RunArgs,
   cwd: string,
   tasks: readonly string[],
+  verb: 'run' | 'watch' = 'run',
 ): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
   for (const t of tasks) {
     const idx = t.indexOf('#')
@@ -555,8 +558,7 @@ export async function resolveRunOptions(
       const nx = await nxTargetHint(tasks, cwd)
       if (nx !== null) return { error: nx }
       return {
-        error:
-          'not inside a project. Pass --all for every project, --filter <pattern> to filter, or run from within a project directory.',
+        error: `not inside a project: run from a project directory, or pass --all or --filter <pattern>${seeHelp(verb)}`,
       }
     }
     projects = [cwdProject.name]
@@ -612,7 +614,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}\n`)
+    process.stderr.write(`vx run: ${parsed.error}${seeHelp('run')}\n`)
     return 1
   }
 
@@ -724,6 +726,25 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     return 0
   }
 
+  // The report prints above the footer: nothing prints below it (owner).
+  // Rendered once, however many sinks asked for it; a kept server's crash
+  // after the footer re-renders the file's copy (C-53).
+  const wantsReport = parsed.report === 'markdown' || parsed.reportFile !== undefined
+  let reported: { outcomes: readonly TaskOutcome[]; md: string } | undefined
+  if (wantsReport) {
+    opts.beforeFooter = (outcomes, ok) => {
+      reported = {
+        outcomes,
+        md: formatRunReportMarkdown({ ok, outcomes: outcomes.map(projectOutcome) }),
+      }
+      // `--report` writes stdout. The report ITSELF is machine-clean, but
+      // stdout is not vx's alone — the status logger writes there too, so
+      // `--report=markdown >> "$GITHUB_STEP_SUMMARY"` captures every frame,
+      // meter bar and `::group::` command above the table. `--report-file`
+      // is the redirect-free form.
+      return parsed.report === 'markdown' ? reported.md : ''
+    }
+  }
   // A run executes in THIS process, always. Where an individual task's
   // command runs is the `executor` capability's business (per task, with
   // the scheduler, cache, retries and telemetry unchanged above it); there
@@ -733,17 +754,14 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx run: ${summary.refused}\n`)
     return 1
   }
-  const result: RunResult = { ok: summary.ok, outcomes: summary.outcomes.map(projectOutcome) }
-  // Report generation is post-run, gated on the flags — zero cost when
-  // both are absent. Rendered once, however many sinks asked for it.
-  if (parsed.report === 'markdown' || parsed.reportFile !== undefined) {
-    const md = formatRunReportMarkdown(result)
-    // `--report` writes stdout. The report ITSELF is machine-clean, but
-    // stdout is not vx's alone — the status logger writes there too, so
-    // `--report=markdown >> "$GITHUB_STEP_SUMMARY"` captures every frame,
-    // meter bar and `::group::` command above the table. `--report-file`
-    // is the redirect-free form.
-    if (parsed.report === 'markdown') process.stdout.write(md)
+  if (wantsReport) {
+    const md =
+      reported?.outcomes === summary.outcomes
+        ? reported.md
+        : formatRunReportMarkdown({
+            ok: summary.ok,
+            outcomes: summary.outcomes.map(projectOutcome),
+          })
     if (parsed.reportFile !== undefined) {
       const target = path.resolve(cwd, parsed.reportFile)
       try {
@@ -766,5 +784,5 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       }
     }
   }
-  return result.ok ? 0 : 1
+  return summary.ok ? 0 : 1
 }