@vzn/vx 0.0.594 → 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)
     }
@@ -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 } : {}) }
@@ -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
   }
 

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[],
@@ -471,7 +496,9 @@ export async function pickTask(
     )
     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')
@@ -486,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

@@ -12,6 +12,7 @@ import { declaredTask } from '../graph/index.js'
 import { isDefaultBuild } from '../orchestrator/index.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,
@@ -24,16 +25,27 @@ import {
 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')
@@ -103,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
   }
 
@@ -124,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
   }
 
@@ -239,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/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

package/src/cli/watch-fs.ts

@@ -77,10 +77,10 @@ export function pollWatcher(
    */
   skipDir: (rel: string) => boolean = (rel) => POLL_SKIP.has(path.basename(rel)),
 ): WatchHandle {
-  let previous = new Map<string, number>()
+  let previous = new Map<string, string>()
   let first = true
   const scan = (): void => {
-    const current = new Map<string, number>()
+    const current = new Map<string, string>()
     const walk = (abs: string, rel: string): void => {
       let entries: fs.Dirent[]
       try {
@@ -95,15 +95,23 @@ export function pollWatcher(
           if (recursive && !skipDir(childRel)) walk(path.join(abs, e.name), childRel)
           continue
         }
-        if (!e.isFile()) continue
+        // A link is an input as its target string (watch-judge.ts), so that
+        // string is sampled, never the target's times: a retarget inside
+        // one clock tick carries the same times.
+        const link = e.isSymbolicLink()
+        if (!e.isFile() && !link) continue
         try {
           // The later of the two clocks, as `modifiedBefore` reads them: a
           // replacement that carries the old file's mtime (`cp -p`, `rsync
           // -a`, `mv` of a file stamped the same) moved nothing under mtime
           // alone, and the poller never ran it where the native watcher did.
           // A rename or a write moves ctime, and no process can set it.
-          const st = fs.statSync(path.join(abs, e.name))
-          current.set(childRel, Math.max(st.mtimeMs, st.ctimeMs))
+          const p = path.join(abs, e.name)
+          if (link) current.set(childRel, `link:${fs.readlinkSync(p)}`)
+          else {
+            const st = fs.statSync(p)
+            current.set(childRel, String(Math.max(st.mtimeMs, st.ctimeMs)))
+          }
         } catch {
           // raced with a delete; the next scan settles it
         }
@@ -111,8 +119,8 @@ export function pollWatcher(
     }
     walk(dir, '')
     if (!first) {
-      for (const [rel, mtime] of current) {
-        if (previous.get(rel) !== mtime) onEvent(rel)
+      for (const [rel, stamp] of current) {
+        if (previous.get(rel) !== stamp) onEvent(rel)
       }
       for (const rel of previous.keys()) {
         if (!current.has(rel)) onEvent(rel)

package/src/cli/watch-judge.ts

@@ -77,7 +77,7 @@ export class ChangeJudge {
   // are judged one window after the run ends, all together — an edit made
   // meanwhile still differs from what the loop last saw and re-runs.
   readonly pending = new Map<string, string>()
-  /** The last cycle's wall window; a write inside it is the run's own. */
+  /** The last cycle's window, its start on the mtime clock (`fsClockNow`); a write inside it is the run's own. */
   lastCycle: { start: number; end: number } | undefined
   // Declared outputs are ignored by PATH above. A task with no `cache`
   // block declares none and still writes into its project, and the

package/src/cli/watch.ts

@@ -86,7 +86,7 @@ export function watchRefusal(parsed: RunArgs): string | null {
 export async function watchCmd(args: readonly string[]): Promise<number> {
   const parsed = parseRunArgs(args, 'watch')
   if (parsed.error) {
-    process.stderr.write(`vx watch: ${parsed.error}\n`)
+    process.stderr.write(`vx watch: ${parsed.error}${seeHelp('watch')}\n`)
     return 1
   }
 
@@ -137,10 +137,13 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   // worth; every cycle after an edit must load and list live.
   delete opts.staged
   delete opts.discovered
-  process.once('SIGINT', () => {
-    process.stdout.write('\nvx watch: stopped\n')
-    stop.abort('SIGINT')
-  })
+  process.once('SIGINT', () => stop.abort('SIGINT'))
+  // Said once the loop is down, the last line: written as the signal
+  // landed, the aborted cycle's summary printed below it.
+  const stopped = (): number => {
+    if (stop.signal.reason === 'SIGINT') process.stdout.write('\nvx watch: stopped\n')
+    return 0
+  }
   process.once('SIGTERM', () => stop.abort('SIGTERM'))
   // A task runs in its own session (exec/kill-tree.ts): the terminal
   // closing reaches the loop alone, and the loop passes it on.
@@ -206,7 +209,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   }
   if (stop.signal.aborted) {
     await held?.stop(forwardedSignal(stop.signal.reason))
-    return 0
+    return stopped()
   }
   if (refusedToStart) return 1
   // After the initial run, so a `pkg#task` naming no project gets the
@@ -234,7 +237,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
       ...fingerprintClaims(plugins).keys(),
       ...(opts.frozen === true ? [LOCKFILE_NAME] : []),
     ])
-  return await runWatchLoop({
+  await runWatchLoop({
     opts,
     held,
     stop: stop.signal,
@@ -285,6 +288,7 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
     // The RESOLVED cache dir, not the `.vx` literal — see `makeWatchIgnore`.
     cacheDir: opts.cacheDir ?? ws.cacheDir,
   })
+  return stopped()
 }
 
 interface WatchLoopArgs {
@@ -345,7 +349,7 @@ interface Rediscovered {
   fenceDirs: readonly string[]
 }
 
-async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
+async function runWatchLoop(args: WatchLoopArgs): Promise<void> {
   const { opts, stop, workspaceRoot, projects, cacheDir } = args
   // The watched set as of the last cycle: `rearm` replaces these after an
   // event that can change it, and every filter below reads the current one.
@@ -403,7 +407,10 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
           await held?.stop()
           held = undefined
           restartTimings()
-          const start = Date.now()
+          // On the mtime clock, as the arm is: from `Date.now()` a write the
+          // run made within a tick of it carried an earlier mtime and read as
+          // an edit (WD-20). The end needs no stamp: an mtime never leads it.
+          const start = fsClockNow(cacheDir)
           const cycle = await runOrchestrator(opts)
           held = cycle.persistent
           if (cycle.refused !== undefined) process.stderr.write(`vx watch: ${cycle.refused}\n`)
@@ -838,7 +845,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
 
   process.stdout.write(`\n${watchingLine(projects.length)}; press Ctrl+C to stop\n`)
 
-  return await new Promise<number>((resolve) => {
+  return await new Promise<void>((resolve) => {
     const cleanup = async (): Promise<void> => {
       pool.closeAll()
       if (debounceTimer) clearTimeout(debounceTimer)
@@ -846,7 +853,7 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       // it has returned, so the process never exits over a live child.
       await inFlight
       await held?.stop(forwardedSignal(stop.reason))
-      resolve(0)
+      resolve()
     }
     if (stop.aborted) {
       void cleanup()

package/src/config.ts

@@ -510,9 +510,9 @@ export interface CacheInputs {
    * project files" (gitignore-aware), or narrow as needed. An empty
    * array means no file inputs at all.
    *
-   * Declared outputs and any nested-project files are excluded
-   * automatically — a task cannot invalidate itself, and cannot read
-   * across project boundaries.
+   * Declared outputs (both `outputs` fields) and any nested-project
+   * files are excluded automatically — a task cannot invalidate itself,
+   * and cannot read across project boundaries.
    */
   files: string[]
   /**
@@ -525,8 +525,8 @@ export interface CacheInputs {
    * NO project-boundary rule applies: these globs may match files
    * inside other projects' directories. Deliberate escape hatch —
    * prefer project-relative `files` declarations where possible.
-   * Declared `outputs.workspaceFiles` are excluded automatically (a
-   * task cannot invalidate itself).
+   * Declared outputs (both `outputs` fields) are excluded
+   * automatically (a task cannot invalidate itself).
    */
   workspaceFiles?: string[]
   /**

package/src/exec/env.ts

@@ -33,6 +33,11 @@ export const ESSENTIAL_ENV: readonly string[] = [
   'NO_COLOR',
   'CI',
   'NODE_OPTIONS',
+  // Where corepack and pnpm keep their own binaries, as HOME is: a machine
+  // path, never task output. Without them a corepack shim re-downloads its
+  // manager (offline or sandboxed: fails) and pnpm loses its global dir.
+  'COREPACK_HOME',
+  'PNPM_HOME',
 ]
 
 /**

package/src/exec/index.ts

@@ -18,6 +18,7 @@ export {
   exitSignal,
   type CaptureConfig,
   execWord,
+  maskCaptured,
 } from './runner.js'
 export {
   initSandbox,

package/src/exec/proc-sample.ts

@@ -134,12 +134,16 @@ async function psTable(): Promise<Map<number, Proc> | undefined> {
   return table
 }
 
-/** `ps`'s `time`: `[[dd-]hh:]mm:ss[.cc]`, macOS printing hundredths. */
+/**
+ * `ps`'s `time`: `[[dd-]hh:]mm:ss[.cc]`, macOS printing hundredths after
+ * the locale's decimal point — `0:01,50` under a German or French locale.
+ */
 export function psTimeMs(s: string): number | undefined {
   const dash = s.indexOf('-')
   const days = dash === -1 ? 0 : Number(s.slice(0, dash))
   const parts = s
     .slice(dash + 1)
+    .replace(',', '.')
     .split(':')
     .map(Number)
   if (parts.length < 2 || parts.some((n) => !Number.isFinite(n)) || !Number.isFinite(days)) {