@vzn/vx 0.0.591 → 0.0.595

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,
@@ -15,10 +14,9 @@ import {
 } from '../orchestrator/index.js'
 import type { ContinueMode } 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)
     }
@@ -428,6 +441,32 @@ function onCI(v: string | undefined): boolean {
   return v !== undefined && v !== '' && v !== '0' && v !== 'false'
 }
 
+/** The filters a run's scope comes from: `--filter`s, with `--affected` as its `...[<base>]`. */
+async function scopeFilters(
+  parsed: RunArgs,
+  cwd: string,
+): Promise<{ filterStrings: string[]; affectedFilter?: string } | { error: string }> {
+  // `--affected[=<base>]` is sugar for `--filter '...[<base>]'`: the
+  // changed projects AND their dependents — what a CI gate must run, what
+  // the flag's name says, what the guides promised while the sugar was the
+  // changed-only `[<base>]` (item 287). `--filter '[<base>]'` stays the
+  // "only what I touched" form. Merging it into the filter list means the
+  // same code path handles plain filter use, --affected alone, and the combo.
+  // Its place does not change the selection: `applyFilters` takes every
+  // include before any exclude (item 979), so `--affected --filter '!app'`
+  // drops app from either side (item 955 had put it first for that). First
+  // it stays, so a message naming the filters names it first.
+  const filterStrings = [...parsed.filters]
+  let affectedFilter: string | undefined
+  if (parsed.affected !== undefined) {
+    const f = await affectedFilterFor(cwd, parsed.affected)
+    if (typeof f === 'object') return f
+    affectedFilter = f
+    filterStrings.unshift(affectedFilter)
+  }
+  return { filterStrings, ...(affectedFilter !== undefined ? { affectedFilter } : {}) }
+}
+
 /**
  * Resolve parsed `vx run` argv into the `RunOptions` the orchestrator
  * consumes. Shared between `runCmd` and `watchCmd` so both subcommands
@@ -459,35 +498,9 @@ export async function resolveRunOptions(
     }
   }
 
-  // `--affected[=<base>]` is sugar for `--filter '...[<base>]'`: the
-  // changed projects AND their dependents — what a CI gate must run, what
-  // the flag's name says, what the guides promised while the sugar was the
-  // changed-only `[<base>]` (item 287). `--filter '[<base>]'` stays the
-  // "only what I touched" form. Merging it into the filter list means the
-  // same code path handles plain filter use, --affected alone, and the combo.
-  // Its place does not change the selection: `applyFilters` takes every
-  // include before any exclude (item 979), so `--affected --filter '!app'`
-  // drops app from either side (item 955 had put it first for that). First
-  // it stays, so a message naming the filters names it first.
-  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}]`
-    filterStrings.unshift(affectedFilter)
-  }
+  const scope = await scopeFilters(parsed, cwd)
+  if ('error' in scope) return scope
+  const { filterStrings, affectedFilter } = scope
 
   // Project scope applies to bare task names only. Anchored entries
   // (pkg#task) resolve directly to their own project regardless.
@@ -601,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
   }
 
@@ -625,14 +638,31 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       )
       return 1
     }
-    const picked = await pickTask(
-      cwd,
-      {},
-      {
-        ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
-        ...(parsed.frozen ? { frozen: true } : {}),
-      },
-    )
+    const load = {
+      ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+      ...(parsed.frozen ? { frozen: true } : {}),
+    }
+    // `--filter` / `--affected` scope the menu, as they scope a bare task:
+    // the menu listed every project and the anchored pick ran outside it.
+    const scope = await scopeFilters(parsed, cwd)
+    if ('error' in scope) {
+      process.stderr.write(`vx run: ${scope.error}\n`)
+      return 1
+    }
+    let only: ReadonlySet<string> | undefined
+    if (scope.filterStrings.length > 0) {
+      const selected = await resolveFilters(cwd, scope.filterStrings, load, scope.affectedFilter)
+      if ('error' in selected) {
+        process.stderr.write(`vx run: ${selected.error}\n`)
+        return 1
+      }
+      if ('empty' in selected) {
+        process.stderr.write(`vx run: ${selected.empty}\n`)
+        return 0
+      }
+      only = new Set(selected.names)
+    }
+    const picked = await pickTask(cwd, {}, load, only)
     if (picked === 'interrupted') return 130
     if (!picked) return 1
     tasks = [`${picked.project}#${picked.task}`]

package/src/cli/select.ts

@@ -12,6 +12,7 @@ import {
   refIsHead,
   applyFilters,
   buildPackageGraph,
+  defaultAffectedBase,
   findWorkspaceRoot,
   type LoadReads,
   type FingerprintClaims,
@@ -26,7 +27,7 @@ import type { ProjectConfig } from '../config.js'
 import type { ProjectEntry } from '../workspace/index.js'
 import { parseDependencySpec } from '../graph/index.js'
 import { declaresInput } from '../cache/index.js'
-import { listed, maskedLine, nearest, UserError } from '../util/index.js'
+import { isUserError, listed, maskedLine, nearest, UserError } from '../util/index.js'
 import {
   claimedAffected,
   fingerprintClaims,
@@ -228,6 +229,30 @@ export function taskEdgesFrom(staged: ReadonlyMap<string, ProjectEntry>): Map<st
   return out
 }
 
+/**
+ * The filter `--affected[=<base>]` stands for: `...[<base>]`, the changed
+ * projects and their dependents. An empty base is the workspace's
+ * `affectedBase` (or a plugin's `config` stage, from nx.json's
+ * `defaultBase` or `TURBO_SCM_BASE`), then the guess.
+ */
+export async function affectedFilterFor(
+  cwd: string,
+  affected: string,
+): Promise<string | { error: string }> {
+  const root = await findWorkspaceRoot(cwd)
+  let base = affected
+  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 }
+    }
+  }
+  return `...[${base}]`
+}
+
 export async function resolveFilters(
   cwd: string,
   raw: string[],
@@ -243,7 +268,10 @@ export async function resolveFilters(
   } catch (err) {
     return { error: err instanceof Error ? err.message : String(err) }
   }
-  const walksGraph = parsed.some((f) => f.withDeps || f.withDependents || f.onlyDeps)
+  // `sinceViaDeps` (`e2e...[main]`) walks the changed projects' dependents.
+  const walksGraph = parsed.some(
+    (f) => f.withDeps || f.withDependents || f.onlyDeps || f.sinceViaDeps === true,
+  )
   // A filter that diffs against git starts the run's whole-tree walk now:
   // the diff reads its untracked files from it (one walk where it spawned
   // its own), and the run reuses it with the discovery (I-26).
@@ -422,7 +450,7 @@ export async function resolveFilters(
   }
 }
 
-export interface PickedTask {
+interface PickedTask {
   project: string
   task: string
   description?: string
@@ -436,6 +464,8 @@ export async function pickTask(
   cwd: string,
   io: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream } = {},
   load: CliLoadOptions = {},
+  /** The projects `--filter` / `--affected` selected; every project when absent. */
+  only?: ReadonlySet<string>,
 ): Promise<PickedTask | null | 'interrupted'> {
   const projects = await loadWorkspaceProjects(cwd)
   // The staged load: a task a `project` plugin gave a config-less package
@@ -443,6 +473,7 @@ export async function pickTask(
   const staged = await loadCliProjects(await findWorkspaceRoot(cwd), projects, 'all', load)
   const entries: PickedTask[] = []
   for (const meta of projects) {
+    if (only !== undefined && !only.has(meta.name)) continue
     const config = staged.get(meta.name)?.config
     if (config === undefined) continue
     const taskNames = Object.keys(config.tasks ?? {})
@@ -453,13 +484,21 @@ export async function pickTask(
       entries.push({ project: meta.name, task: t, ...(desc ? { description: desc } : {}) })
     }
   }
+  if (entries.length === 0 && only !== undefined) {
+    process.stderr.write(
+      `vx run: no tasks declared in the selected projects (${[...only].sort().join(', ')})\n`,
+    )
+    return null
+  }
   if (entries.length === 0) {
     process.stderr.write(
       'vx run: no tasks declared in any project; declare one under `tasks` in a vx.config, or run `vx init` to write them from package.json scripts\n',
     )
     return null
   }
-  const out = io.output ?? process.stdout
+  // The menu is a conversation with the terminal, not the run's output: on
+  // stdout, `vx run > out.txt` put it in the file and asked a blank screen.
+  const out = io.output ?? process.stderr
   const numW = String(entries.length).length
   const idW = Math.max(...entries.map((e) => `${e.project}#${e.task}`.length))
   out.write('Tasks:\n')
@@ -474,7 +513,7 @@ export async function pickTask(
   const readline = await import('node:readline/promises')
   const rl = readline.createInterface({
     input: io.input ?? process.stdin,
-    output: io.output ?? process.stdout,
+    output: out,
   })
   // On a terminal readline takes Ctrl-C and Ctrl-D itself, raw, and
   // rejects the pending question with an AbortError — which reached the

package/src/cli/show.ts

@@ -10,8 +10,9 @@ import path from 'node:path'
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
 import { isDefaultBuild } from '../orchestrator/index.js'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, seeHelp } from './help.js'
 import { listed, nearMatches, relPosix, secretMask, UserError } from '../util/index.js'
+import { affectedFilterFor, resolveFilters } from './select.js'
 import { discoverCliProjects, loadCliProjects } from './workspace-config.js'
 import {
   findWorkspaceRoot,
@@ -21,19 +22,30 @@ import {
   type ProjectMeta,
 } from '../workspace/index.js'
 
-export interface ShowArgs {
+interface ShowArgs {
   target?: string
   format: 'pretty' | 'json'
+  /** `--filter`, as `vx run` reads it: which projects the list shows. */
+  filters: string[]
+  /** `--affected[=<base>]`: `''` is the default base. */
+  affected?: string
   error?: string
 }
 
 export function parseShowArgs(args: readonly string[]): ShowArgs {
-  const out: ShowArgs = { format: 'pretty' }
+  const out: ShowArgs = { format: 'pretty', filters: [] }
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!
     let format: string | undefined
     if (a === '--format') format = args[++i] ?? ''
     else if (a.startsWith('--format=')) format = a.slice('--format='.length)
+    else if (a === '--filter') {
+      const v = args[++i]
+      if (v === undefined) return { ...out, error: '--filter requires a value (a pattern)' }
+      out.filters.push(v)
+    } else if (a.startsWith('--filter=')) out.filters.push(a.slice('--filter='.length))
+    else if (a === '--affected') out.affected = ''
+    else if (a.startsWith('--affected=')) out.affected = a.slice('--affected='.length)
     else if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('show', a)}${seeHelp('show')}` }
     else if (out.target === 'project')
@@ -47,10 +59,9 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
     else out.target = a
 
     if (format !== undefined) {
-      if (format !== 'pretty' && format !== 'json') {
-        return { ...out, error: '--format must be pretty or json' }
-      }
-      out.format = format
+      const fv = formatValue(format, 'show')
+      if (typeof fv === 'object') return { ...out, ...fv }
+      out.format = fv
     }
   }
   return out
@@ -104,10 +115,35 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   const bareTask = projectName !== undefined && taskName === undefined && !byName.has(projectName)
   const scope = projectName === undefined || bareTask ? 'all' : [projectName]
 
+  // `turbo ls --filter` / `nx show projects --affected`: the list, and a
+  // task's projects, narrowed by the selection `vx run` would make.
+  let selected: Set<string> | undefined
+  if (parsed.filters.length > 0 || parsed.affected !== undefined) {
+    if (scope !== 'all') {
+      throw new UserError(
+        'vx show: --filter and --affected narrow a list: `vx show` or `vx show <task>`',
+      )
+    }
+    const raw = [...parsed.filters]
+    let affected: string | undefined
+    if (parsed.affected !== undefined) {
+      const f = await affectedFilterFor(process.cwd(), parsed.affected)
+      if (typeof f === 'object') throw new UserError(`vx show: ${f.error}`)
+      affected = f
+      raw.unshift(f)
+    }
+    const r = await resolveFilters(process.cwd(), raw, { noCreate: true }, affected)
+    if ('error' in r) throw new UserError(`vx show: ${r.error}`)
+    if ('empty' in r) process.stderr.write(`vx show: ${r.empty}\n`)
+    selected = new Set('empty' in r ? [] : r.names)
+  }
+  const inSelection = (name: string): boolean => selected === undefined || selected.has(name)
+
   const projects = await loadCliProjects(root, metas, scope, { noCreate: true, closure: true })
 
   if (parsed.target === undefined) {
-    process.stdout.write(renderList(root, metas, projects, parsed.format))
+    const shown = metas.filter((m) => inSelection(m.name))
+    process.stdout.write(renderList(root, shown, projects, parsed.format))
     return 0
   }
 
@@ -125,7 +161,8 @@ export async function showCmd(args: readonly string[]): Promise<number> {
         `vx show: unknown project or task: "${projectName}"${nx}${suggest(projectName!, [...byName.keys(), ...names], '', 'projects and tasks')}`,
       )
     }
-    process.stdout.write(renderTaskAcross(root, declaring, projectName!, parsed.format))
+    const shown = declaring.filter((p) => inSelection(p.name))
+    process.stdout.write(renderTaskAcross(root, shown, projectName!, parsed.format))
     return 0
   }
 
@@ -240,6 +277,7 @@ function renderList(
       2,
     )}\n`
   }
+  if (rows.length === 0) return ''
   const nameW = Math.max(...rows.map((r) => r.name.length))
   const dirW = Math.max(...rows.map((r) => r.dir.length))
   const lines = rows.map((r) => {

package/src/cli/upgrade.ts

@@ -1,4 +1,4 @@
-// `vx upgrade [tag]` — self-update the compiled binary in place.
+// `vx upgrade [TAG]` — self-update the compiled binary in place.
 // Asks the GitHub release API for the asset of this os/arch and the
 // SHA-256 digest it publishes, downloads the asset, verifies the digest,
 // writes next to the current executable, atomic rename over it. The
@@ -299,8 +299,7 @@ export async function upgradeCmd(args: readonly string[]): Promise<number> {
   }
   if (!isCompiledBinary()) {
     throw new UserError(
-      'vx upgrade only works for the compiled binary. ' +
-        'You are running from source — use git pull instead. ' +
+      'vx upgrade: only the compiled binary upgrades itself; this vx runs from source — use git pull ' +
         '(npm installs update with: npm install -g @vzn/vx@latest)',
     )
   }

package/src/cli/watch-filter.ts

@@ -8,6 +8,7 @@ import {
   isLiteralPattern,
   normalizeGlob,
   outputMatcher,
+  realPath,
   staticPrefix,
   taskGlob,
 } from '../util/index.js'
@@ -54,7 +55,9 @@ export function makeWatchIgnore(
   outputs: ReadonlyMap<string, readonly string[]> = new Map(),
   inputs: ReadonlyMap<string, ReadonlyArray<readonly string[]>> = new Map(),
 ): (base: string, filename: string) => boolean {
-  const cacheAbs = path.resolve(cacheDir)
+  // Watchers report under the real root; a cache dir named through a link
+  // (`VX_CACHE_DIR`, macOS `/var` -> `/private/var`) is matched as its target.
+  const cacheAbs = realThrough(path.resolve(cacheDir))
   // A task's own outputs are not edits: without this every cycle that
   // writes `dist/` (or `out.txt`) re-runs once more, reporting
   // "up-to-date" for the trouble. Matched under the directory the globs
@@ -132,6 +135,16 @@ export function makeWatchIgnore(
   }
 }
 
+/** `p` with its longest existing prefix realpath'd: the cache dir may not exist yet. */
+function realThrough(p: string): string {
+  try {
+    return realPath(p)
+  } catch {
+    const up = path.dirname(p)
+    return up === p ? p : path.join(realThrough(up), path.basename(p))
+  }
+}
+
 /**
  * The literal directory a glob's matches live under (`''` when the glob
  * starts with a pattern, or negates). A literal entry is a file or its
@@ -185,7 +198,7 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
     }
     // Each record: source, line, pattern, path. No source: no pattern
     // matched; a `!` pattern: re-included. Either way not ignored.
-    const fields = new TextDecoder().decode(proc.stdout).split('\0')
+    const fields = new TextDecoder('utf-8', { ignoreBOM: true }).decode(proc.stdout).split('\0')
     const records = Math.floor(fields.length / 4)
     for (let i = 0; i < records; i++) {
       const [source, , pattern, p] = fields.slice(i * 4, i * 4 + 4)
@@ -232,10 +245,11 @@ export function makeRootEventFilter(
   fenced: (ownDir: string, abs: string) => boolean = () => false,
 ): (filename: string) => boolean {
   const dirs = projectDirs.map((d) => path.resolve(d))
-  const globs = workspaceInputs
-    .map(normalizeGlob)
-    .filter((g) => !g.startsWith('!'))
-    .map((g) => taskGlob(g))
+  // A literal is its tree, as the key resolves it: `shared` matched only
+  // the directory's own event and no edit under it ran a cycle (WD-2).
+  const globs = asTrees(workspaceInputs.filter((g) => !normalizeGlob(g).startsWith('!'))).map((g) =>
+    taskGlob(g),
+  )
   return (filename: string): boolean => {
     const rel = filename.split(path.sep).join('/')
     // The depth test is a READING AID, not a guard: both predicates below
@@ -359,7 +373,7 @@ export function gitFiles(workspaceRoot: string): Set<string> | undefined {
   }
   if (proc.exitCode !== 0) return undefined
   const files = new Set<string>()
-  for (const p of new TextDecoder().decode(proc.stdout).split('\0')) {
+  for (const p of new TextDecoder('utf-8', { ignoreBOM: true }).decode(proc.stdout).split('\0')) {
     if (p.length === 0) continue
     // An untracked nested repository is listed as `dir/`.
     let abs = path.join(workspaceRoot, p.endsWith('/') ? p.slice(0, -1) : p)