@vzn/vx 0.0.596 → 0.0.598

package/src/cache/layered-cache.ts

@@ -82,7 +82,8 @@ export interface RemoteCacheLayer {
   /**
    * Store an artifact (fire-and-forget from LayeredCache's perspective).
    * `body` is file-backed (`Bun.file`) when the local store holds the
-   * artifact, so a plugin that streams it never holds it whole.
+   * artifact, so a plugin that streams it never holds it whole, and every
+   * read of it sees the same bytes.
    */
   put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void>
 }
@@ -549,12 +550,12 @@ export class LayeredCache implements CacheLayer {
     // succeeded; we don't fail it on cache-server issues.
     //
     // The job hands the plugin a file-backed Blob over the local artifact,
-    // opened when the plugin reads it: a queued job holds a path, not a
-    // buffer, and a plugin that streams the Blob never holds it whole. The
-    // artifact is content-addressed and immutable, so a deferred read sees
-    // the same bytes; if a concurrent `vx cache prune` removed it first the
-    // plugin's read throws and this upload is skipped — the never-fail
-    // contract.
+    // pinned under a private name when the job starts (`pinArtifact`): a
+    // queued job holds a path, not a buffer, a plugin that streams the Blob
+    // never holds it whole, and every read of it sees the same bytes though
+    // a re-save of the key renames others over the live name. If a
+    // concurrent `vx cache prune` removed the artifact first the pin throws
+    // and this upload is skipped — the never-fail contract.
     const hash = args.hash
     const durationMs = args.entry.durationMs
     // Local writes disabled (`--cache=local:,remote:rw`): there is no
@@ -575,9 +576,11 @@ export class LayeredCache implements CacheLayer {
     this.enqueueUpload(async () => {
       const tally = this.local.uploads
       const start = performance.now()
+      let release: (() => Promise<void>) | undefined
       try {
-        const body =
-          packed !== undefined ? new Blob([packed]) : Bun.file(this.local.outputsPath(hash))
+        let body: Blob
+        if (packed !== undefined) body = new Blob([packed])
+        else ({ body, release } = this.local.pinArtifact(hash))
         await this.wire.put(hash, body, { durationMs })
         tally.count++
         tally.bytes += body.size
@@ -585,6 +588,8 @@ export class LayeredCache implements CacheLayer {
       } catch (err) {
         tally.failed++
         this.reportRemoteError('upload', hash, err)
+      } finally {
+        await release?.()
       }
     })
   }

package/src/cache/output-index.ts

@@ -336,13 +336,18 @@ export class OutputIndex {
     if (this.pendingStamps.size > 0) {
       const stamps = [...this.pendingStamps]
       this.pendingStamps.clear()
-      this.db.transaction(() => {
-        for (const [hash, rows] of stamps) {
-          // A stamp outlives nothing: an entry pruned since has no rows to vouch for.
-          if (this.entryExists.get(hash) === null) continue
-          for (const [rel, ino, ctime] of rows) this.stampOutputFile.run(hash, rel, ino, ctime)
-        }
-      })()
+      // IMMEDIATE: the body reads `entries` before it writes, and a
+      // deferred transaction that did could not wait for the lock
+      // (run-history.ts).
+      this.db
+        .transaction(() => {
+          for (const [hash, rows] of stamps) {
+            // A stamp outlives nothing: an entry pruned since has no rows to vouch for.
+            if (this.entryExists.get(hash) === null) continue
+            for (const [rel, ino, ctime] of rows) this.stampOutputFile.run(hash, rel, ino, ctime)
+          }
+        })
+        .immediate()
     }
     if (this.pendingDirs.size === 0) return
     const pending = [...this.pendingDirs]

package/src/cache/run-history.ts

@@ -69,10 +69,9 @@ export class RunHistory {
       this.insertRun.run(...bindRun(runs[0]!, this.digestValue))
       return
     }
-    // `bun:sqlite`'s `transaction()` returns a callable that wraps the
-    // body in BEGIN/COMMIT, fsyncing once at the end. For a 200-task
-    // run that's one fsync instead of 200.
-    this.db.transaction(() => this.insertRuns(runs))()
+    // One transaction, one fsync: for a 200-task run, one instead of 200.
+    // IMMEDIATE, as `recordRunBundle` explains.
+    this.db.transaction(() => this.insertRuns(runs)).immediate()
   }
 
   /** `runs` as few INSERTs; each distinct forward-args list digested once. */
@@ -99,10 +98,19 @@ export class RunHistory {
     // the entry-save transaction (`save`/`ingest`) so a warm
     // all-cache-hit run — which writes no `runs`-vs-`entry_inputs`
     // mismatch — pays nothing for the moat it isn't refreshing.
-    this.db.transaction(() => {
-      this.insertRuns(bundle.runs)
-      this.insertInvocation.run(...bindInvocation(bundle.invocation))
-    })()
+    //
+    // IMMEDIATE: the write lock is taken at BEGIN, where the busy timeout
+    // waits for it. A run's rows digest their forward args under a salt
+    // the body READS first (`[]` from every CLI run), and a deferred
+    // transaction that read before it wrote could not wait: 13 of 48 runs
+    // on one shared cache dir lost their history to `database is locked`
+    // in 2–60 ms (BUSY_SNAPSHOT, a retry passing at once).
+    this.db
+      .transaction(() => {
+        this.insertRuns(bundle.runs)
+        this.insertInvocation.run(...bindInvocation(bundle.invocation))
+      })
+      .immediate()
   }
 
   /**

package/src/cli/cache.ts

@@ -140,13 +140,13 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
         return {
           error: `${refusedWord(a ?? '')}: ${a}${flagHint('cache prune', a ?? '')}${seeHelp('cache')}`,
         }
-      if ('error' in cd) return { error: cd.error }
+      if ('error' in cd) return { error: `${cd.error}${seeHelp('cache')}` }
       out.cacheDir = cd.cacheDir
       i = cd.next
     }
   }
   if (out.olderThanMs === undefined && out.maxBytes === undefined) {
-    return { error: 'must pass --older-than <duration> or --max-size <bytes>' }
+    return { error: `needs --older-than <duration> or --max-size <size>${seeHelp('cache')}` }
   }
   return out
 }

package/src/cli/foreign-flags.ts

@@ -1,4 +1,4 @@
-// What a Turbo or Nx user's hands type, and what `vx run` does with it.
+// What a Turbo, Nx or Vite Task (`vp run`) user's hands type, and what `vx run` does with it.
 // Every flag here has one outcome: vx takes it as it is (`same`), takes it
 // as another spelling (`alias`, rewritten before the parse), or refuses it
 // with the vx way to say it (`refuse`). Nothing is dropped in silence: a
@@ -7,7 +7,7 @@
 // cli.md's parity section (`renderForeignFlags`), pinned by a test.
 
 interface ForeignFlag {
-  runner: 'turbo' | 'nx'
+  runner: 'turbo' | 'nx' | 'vp'
   /** Every spelling, first the one shown. */
   names: readonly string[]
   /** It takes a value: `--flag <v>` or `--flag=<v>`. */
@@ -598,6 +598,60 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     outcome: 'refuse',
     vx: 'vx has no cloud: drop it',
   },
+  {
+    runner: 'vp',
+    names: ['-r', '--recursive'],
+    value: false,
+    outcome: 'alias',
+    vx: '`--all`',
+    to: () => ['--all'],
+  },
+  {
+    runner: 'vp',
+    names: ['-w', '--workspace-root'],
+    value: false,
+    outcome: 'alias',
+    vx: '`--filter //` (the root project)',
+    to: () => ['--filter', '//'],
+  },
+  {
+    runner: 'vp',
+    names: ['--concurrency-limit'],
+    value: true,
+    outcome: 'alias',
+    vx: '`--concurrency <n>`',
+    to: (v) => (v === undefined ? ['--concurrency'] : ['--concurrency', v]),
+  },
+  {
+    runner: 'vp',
+    names: ['--ignore-depends-on'],
+    value: false,
+    outcome: 'alias',
+    vx: '`--exclude-dependencies`',
+    to: () => ['--exclude-dependencies'],
+  },
+  {
+    runner: 'vp',
+    names: ['--fail-if-no-match'],
+    value: false,
+    outcome: 'alias',
+    vx: 'nothing: a filter that matches nothing already fails the run',
+    to: () => [],
+  },
+  {
+    runner: 'vp',
+    names: ['--log'],
+    value: true,
+    outcome: 'refuse',
+    vx: 'vx frames each task’s output: `--output-logs <mode>` sets how much',
+  },
+  {
+    runner: 'vp',
+    names: ['--last-details'],
+    value: false,
+    outcome: 'refuse',
+    vx: '`vx last` prints the last run',
+  },
 ]
 
 /** Nx's verbs, as its users type them: `vx run` takes their flags. */

package/src/cli/info.ts

@@ -29,7 +29,7 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
     }
     const cd = parseCacheDirFlag(args, i)
     if (cd !== null) {
-      if ('error' in cd) return { ...out, error: cd.error }
+      if ('error' in cd) return { ...out, error: `${cd.error}${seeHelp('info')}` }
       out.cacheDir = cd.cacheDir
       i = cd.next
       continue

package/src/cli/init.ts

@@ -42,7 +42,7 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
       if (seam === undefined || !Object.hasOwn(PLUGIN_TEMPLATES, seam)) {
         return {
           ...out,
-          error: `--plugin takes a seam: one of ${seams}${seam === undefined ? '' : ` (got '${seam}')`}`,
+          error: `--plugin takes a seam: one of ${seams}${seam === undefined ? '' : ` (got '${seam}')`}${seeHelp('init')}`,
         }
       }
       out.plugin = seam
@@ -56,7 +56,7 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
   if (out.plugin !== undefined && out.mjs) {
     return {
       ...out,
-      error: '--mjs does not combine with --plugin: the plugin templates are TypeScript',
+      error: `--mjs does not combine with --plugin: the plugin templates are TypeScript${seeHelp('init')}`,
     }
   }
   return out

package/src/cli/last.ts

@@ -80,7 +80,7 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
     }
     const cd = parseCacheDirFlag(args, i)
     if (cd !== null) {
-      if ('error' in cd) return { ...out, error: cd.error }
+      if ('error' in cd) return { ...out, error: `${cd.error}${seeHelp('last')}` }
       out.cacheDir = cd.cacheDir
       i = cd.next
       continue
@@ -99,11 +99,14 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
   if (out.runId !== undefined && out.list !== undefined) {
     return {
       ...out,
-      error: `a run id and --list do not combine: replay ${out.runId}, or list runs`,
+      error: `a run id and --list do not combine: replay ${out.runId}, or list runs${seeHelp('last')}`,
     }
   }
   if (out.runId !== undefined && out.failed === true) {
-    return { ...out, error: `a run id and --failed do not combine: replay ${out.runId}` }
+    return {
+      ...out,
+      error: `a run id and --failed do not combine: replay ${out.runId}${seeHelp('last')}`,
+    }
   }
   return out
 }

package/src/cli/lock.ts

@@ -83,9 +83,11 @@ function bareNote(bare: number): string {
 
 async function writeLock(root: string, metas: ConfiguredMeta[], bare: number): Promise<number> {
   const entries = await Promise.all(metas.map((m) => evaluateEntry(root, m)))
-  const projects: Record<string, LockfileEntry> = {}
-  // `listProjects` sorts by name — stable lockfile diffs for free.
-  for (let i = 0; i < metas.length; i++) projects[metas[i]!.name] = entries[i]!
+  // `listProjects` sorts by name — stable lockfile diffs for free. Defined,
+  // not assigned: a project named `__proto__` set the map's prototype (D-152).
+  const projects: Record<string, LockfileEntry> = Object.fromEntries(
+    metas.map((m, i) => [m.name, entries[i]!]),
+  )
   const leaks = secretsIn(projects)
   if (leaks.length > 0) {
     process.stderr.write(

package/src/cli/plan-format.ts

@@ -1,7 +1,7 @@
 // Formatters for `--dry-run` (human / JSON) and `--graph` (DOT).
 
 import type { CacheStatus, RunPlan } from '../orchestrator/index.js'
-import { formatDuration } from '../orchestrator/index.js'
+import { formatElapsed, maskedCommand } from '../util/index.js'
 
 /**
  * Human-readable preview. One line per real task (groups hidden, same
@@ -37,7 +37,7 @@ export function formatPlanText(plan: RunPlan): string {
     const desc = skipped ? 'noop — would not run' : describe(t.cacheStatus)
     const shortHash = t.hash ? t.hash.slice(0, 8) : ''
     const executes = !skipped && (t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache')
-    const eta = executes && t.p50Ms !== undefined ? `  ~${formatDuration(t.p50Ms)}` : ''
+    const eta = executes && t.p50Ms !== undefined ? `  ~${formatElapsed(t.p50Ms)}` : ''
     // Placement, by EXECUTOR NAME rather than a local/remote word: the
     // summary line below already spends "local" and "remote" on the cache
     // tier, and a task placed on a named executor is what the reader can
@@ -48,7 +48,7 @@ export function formatPlanText(plan: RunPlan): string {
     )
     // Optional one-line description from the task config, indented
     // under the id so the eye picks up the task → blurb mapping.
-    const taskDesc = t.node.config.description
+    const taskDesc = shownDescription(t)
     if (taskDesc) {
       lines.push(`     ${' '.repeat(idWidth)}  ${taskDesc}`)
     }
@@ -94,8 +94,8 @@ export function formatPlanText(plan: RunPlan): string {
   const p = plan.predicted
   const executes = miss + nocache
   if (p !== undefined && executes > 0 && executes > p.unknownCount) {
-    const parts = [`predicted: ~${formatDuration(p.wallMs)} wall`]
-    parts.push(`~${formatDuration(p.workMs)} total execution`)
+    const parts = [`predicted: ~${formatElapsed(p.wallMs)} wall`]
+    parts.push(`~${formatElapsed(p.workMs)} total execution`)
     if (p.unknownCount > 0) {
       parts.push(`${p.unknownCount} task${p.unknownCount === 1 ? '' : 's'} without history (+?)`)
     }
@@ -104,6 +104,12 @@ export function formatPlanText(plan: RunPlan): string {
   return lines.join('\n') + '\n'
 }
 
+/** A TS config may build the description from `process.env` (L-11). */
+function shownDescription(t: RunPlan['tasks'][number]): string | undefined {
+  const { description, exec } = t.node.config
+  return description === undefined ? undefined : maskedCommand(description, exec?.env)
+}
+
 /** One task of `vx run --dry=json`: the wire, stated by `schemas/plan.json`. */
 export interface PlanTaskJson {
   id: string
@@ -122,21 +128,21 @@ export function formatPlanJson(plan: RunPlan): string {
   return (
     JSON.stringify(
       {
-        tasks: plan.tasks.map((t): PlanTaskJson => ({
-          id: t.node.id,
-          project: t.node.projectName,
-          task: t.node.taskName,
-          hash: t.hash,
-          cacheStatus: t.cacheStatus,
-          deps: t.deps,
-          ...(t.p50Ms !== undefined ? { p50Ms: t.p50Ms } : {}),
-          ...(t.executor !== undefined ? { executor: t.executor } : {}),
-          ...(t.download !== undefined ? { download: t.download } : {}),
-
-          ...(t.node.config.description !== undefined
-            ? { description: t.node.config.description }
-            : {}),
-        })),
+        tasks: plan.tasks.map((t): PlanTaskJson => {
+          const description = shownDescription(t)
+          return {
+            id: t.node.id,
+            project: t.node.projectName,
+            task: t.node.taskName,
+            hash: t.hash,
+            cacheStatus: t.cacheStatus,
+            deps: t.deps,
+            ...(t.p50Ms !== undefined ? { p50Ms: t.p50Ms } : {}),
+            ...(t.executor !== undefined ? { executor: t.executor } : {}),
+            ...(t.download !== undefined ? { download: t.download } : {}),
+            ...(description !== undefined ? { description } : {}),
+          }
+        }),
         ...(plan.predicted !== undefined ? { predicted: plan.predicted } : {}),
         // The gate's refusals belong on the SCRIPTING surface too: a CI job
         // asking "did --download=none actually defer anything, and if not

package/src/cli/run.ts

@@ -1,6 +1,7 @@
 import { appendFileSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
 import { isatty } from 'node:tty'
+import { findWorkspaceRoot } from '../workspace/index.js'
 import { translateForeign } from './foreign-flags.js'
 import { flagHint, seeHelp } from './help.js'
 import {
@@ -13,7 +14,12 @@ import {
   type RunResult,
 } from '../orchestrator/index.js'
 import type { ContinueMode, TaskOutcome } from '../graph/index.js'
-import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
+import {
+  type CachePolicy,
+  FULL_CACHE_POLICY,
+  gitRefusal,
+  parseCachePolicy,
+} from '../cache/index.js'
 import { affectedFilterFor, findCwdSelection, pickTask, resolveFilters } from './select.js'
 import { nxTargetHint, taskNamesHere } from './task-verb.js'
 import { MAX_TIMEOUT_MS, parseDecimalInt, machineParallelism } from '../util/index.js'
@@ -175,7 +181,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
       if (n === null)
         return {
           ...out,
-          error: `invalid concurrency: ${v} (a positive integer, or a share of the cores such as 50%)`,
+          error: `--concurrency must be a positive integer, or a share of the cores such as 50% (got ${v})`,
         }
       out.concurrency = n
     } else if (a === '--all') {
@@ -261,14 +267,17 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
       out.download = v
     } else if (a === '--cache-dir' || a?.startsWith('--cache-dir=')) {
       const v = a === '--cache-dir' ? before[++i] : a.slice('--cache-dir='.length)
-      if (v === undefined || v === '') return { ...out, error: `--cache-dir requires a value` }
+      if (v === undefined || v === '') return { ...out, error: `--cache-dir requires a path` }
       // Unlike every other value flag, a cache dir is an arbitrary
       // string — nothing about its shape rejects a swallowed flag. An
       // unquoted empty shell var (`--cache-dir $EMPTY --force`) would
       // otherwise create a directory literally named `--force` and drop
       // the flag. A path starting with `-` needs the `=` form.
       if (a === '--cache-dir' && v.startsWith('-')) {
-        return { ...out, error: `--cache-dir requires a path, got flag: ${v}` }
+        return {
+          ...out,
+          error: `--cache-dir requires a path (got flag ${v}; a path that starts with - needs --cache-dir=${v})`,
+        }
       }
       out.cacheDir = v
     } else if (a === '--cache' || a?.startsWith('--cache=')) {
@@ -323,14 +332,15 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
       if (v === undefined)
         return { ...out, error: `--verbosity requires a value (a non-negative integer)` }
       const n = parseDecimalInt(v)
-      if (n === null) return { ...out, error: `invalid verbosity: ${v} (a non-negative integer)` }
+      if (n === null)
+        return { ...out, error: `--verbosity must be a non-negative integer (got ${v})` }
       out.verbosity = n
     } else if (a === '--dry') {
       out.dry = 'text'
     } else if (a?.startsWith('--dry=')) {
       const fmt = a.slice('--dry='.length)
       if (fmt !== 'text' && fmt !== 'json') {
-        return { ...out, error: `invalid --dry value: ${fmt} (text or json)` }
+        return { ...out, error: `--dry must be text or json (got ${fmt})` }
       }
       out.dry = fmt
     } else if (a === '--graph') {
@@ -358,7 +368,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
       if (raw === undefined) return { ...out, error: `${a} requires a value (k=v)` }
       // Split on the FIRST `=` so values may contain `=` (e.g. a URL).
       const eq = raw.indexOf('=')
-      if (eq <= 0) return { ...out, error: `invalid --tag (expected k=v): ${raw}` }
+      if (eq <= 0) return { ...out, error: `--tag must be k=v (got ${raw})` }
       out.tags[raw.slice(0, eq)] = raw.slice(eq + 1)
     } else if (a === '--report-file' || a?.startsWith('--report-file=')) {
       const v = a === '--report-file' ? before[++i] : a.slice('--report-file='.length)
@@ -367,7 +377,10 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
       // nothing about its shape rejects a swallowed flag. A path starting
       // with `-` needs the `=` form.
       if (a === '--report-file' && v.startsWith('-')) {
-        return { ...out, error: `--report-file requires a path, got flag: ${v}` }
+        return {
+          ...out,
+          error: `--report-file requires a path (got flag ${v}; a path that starts with - needs --report-file=${v})`,
+        }
       }
       out.reportFile = v
     } else if (a === '--report') {
@@ -375,7 +388,7 @@ export function parseRunArgs(rawArgs: readonly string[], verb: 'run' | 'watch' =
     } else if (a?.startsWith('--report=')) {
       const fmt = a.slice('--report='.length)
       if (fmt !== 'markdown') {
-        return { ...out, error: `invalid --report value: ${fmt} (only markdown)` }
+        return { ...out, error: `--report must be markdown (got ${fmt})` }
       }
       out.report = fmt
     } else if (a !== undefined && a.startsWith('-')) {
@@ -620,6 +633,7 @@ export async function runCmd(args: readonly string[]): Promise<number> {
 
   const cwd = process.cwd()
   let tasks = [...parsed.tasks]
+  let picked: string | undefined
 
   // No positionals → interactive picker (TTY only). Yields a single
   // anchored pkg#task; the rest of the pipeline treats it like any
@@ -638,6 +652,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       )
       return 1
     }
+    // Every run needs git: refused here, not after the user has chosen.
+    const refusal = gitRefusal(await findWorkspaceRoot(cwd))
+    if (refusal !== undefined) {
+      process.stderr.write(`${refusal.message}\n`)
+      return 1
+    }
     const load = {
       ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
       ...(parsed.frozen ? { frozen: true } : {}),
@@ -662,10 +682,11 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       }
       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}`]
+    const chosen = await pickTask(cwd, {}, load, only)
+    if (chosen === 'interrupted') return 130
+    if (!chosen) return 1
+    picked = `${chosen.project}#${chosen.task}`
+    tasks = [picked]
   }
 
   const resolved = await resolveRunOptions(parsed, cwd, tasks)
@@ -680,8 +701,14 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   const opts = resolved
   // The raw invocation, recorded on the `invocations` row so dashboards
   // show what was actually run. `args` is everything after `run`, quoted
-  // so `vx last` replays one paste-able line.
-  opts.command = ['vx', 'run', ...args.map(shellQuote)].join(' ')
+  // so `vx last` replays one paste-able line; a picked task is named in
+  // it, or the line would open the picker again.
+  opts.command = [
+    'vx',
+    'run',
+    ...(picked !== undefined ? [shellQuote(picked)] : []),
+    ...args.map(shellQuote),
+  ].join(' ')
 
   // Planning paths short-circuit execution. Both build the full task
   // graph + probe the cache; the difference is just the formatter.

package/src/cli/select.ts

@@ -26,8 +26,15 @@ import {
 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 { isUserError, listed, maskedLine, nearest, UserError } from '../util/index.js'
+import { declaresInput, workspaceFilesReachInto } from '../cache/index.js'
+import {
+  isUserError,
+  listed,
+  maskedCommand,
+  maskedLine,
+  nearest,
+  UserError,
+} from '../util/index.js'
 import {
   claimedAffected,
   fingerprintClaims,
@@ -60,12 +67,15 @@ export async function workspaceGlobOwners(
   load: CliLoadOptions = {},
   stagedLoad: () => Promise<ReadonlyMap<string, ProjectEntry>> = () =>
     loadCliProjects(root, projects, 'all', load),
+  /** The changed nested repositories (`AffectedChanges.nested`). */
+  nested: readonly string[] = [],
 ): Promise<string[]> {
   const declaresMatch = (config: ProjectConfig): boolean => {
     for (const task of Object.values(config.tasks ?? {})) {
       const cache = task.cache
       if (cache === undefined) continue
       if (changed.some((rel) => declaresInput(cache, null, rel))) return true
+      if (nested.some((dir) => workspaceFilesReachInto(cache, dir))) return true
     }
     return false
   }
@@ -319,8 +329,8 @@ export async function resolveFilters(
         workspaceRoot: root,
         since: f.gitSince,
         projects,
-        workspaceGlobOwners: (changed: readonly string[]) =>
-          workspaceGlobOwners(root, projects, changed, load, stagedOnce),
+        workspaceGlobOwners: (changed: readonly string[], nested: readonly string[]) =>
+          workspaceGlobOwners(root, projects, changed, load, stagedOnce, nested),
         fingerprintClaims: () => workspaceFingerprintClaims(root, projects, load),
         taskEdges: async () => edges ?? taskEdgesFrom(await stagedOnce()),
         ...(git !== undefined ? { untracked: async () => (await git.start()).untracked } : {}),
@@ -480,7 +490,11 @@ export async function pickTask(
       .filter((t) => !isDefaultBuild(config.tasks?.[t]))
       .sort()
     for (const t of taskNames) {
-      const desc = config.tasks?.[t]?.description
+      const task = config.tasks?.[t]
+      const desc =
+        task?.description === undefined
+          ? undefined
+          : maskedCommand(task.description, task.exec?.env)
       entries.push({ project: meta.name, task: t, ...(desc ? { description: desc } : {}) })
     }
   }

package/src/cli/show.ts

@@ -41,7 +41,12 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
     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)' }
+      // `--filter --format json` took `--format` as the pattern; no filter opens with `--`.
+      if (v === undefined || v === '' || v.startsWith('--'))
+        return {
+          ...out,
+          error: `--filter requires a value: a project name, glob or path${seeHelp('show')}`,
+        }
       out.filters.push(v)
     } else if (a.startsWith('--filter=')) out.filters.push(a.slice('--filter='.length))
     else if (a === '--affected') out.affected = ''
@@ -55,7 +60,8 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
       return { ...out, error: `unexpected argument: ${a}${seeHelp('show')}` }
     // An empty name is a part of every name: its "did you mean" listed the
     // whole workspace.
-    else if (a === '') return { ...out, error: 'empty target (omit it to list every project)' }
+    else if (a === '')
+      return { ...out, error: `empty target (omit it to list every project)${seeHelp('show')}` }
     else out.target = a
 
     if (format !== undefined) {
@@ -215,33 +221,21 @@ function projectDir(root: string, meta: ProjectMeta): string {
 }
 
 /**
- * A task as `vx show` prints it: a secret variable's value masked
- * wherever it appears, in `env.define` and in the command a TS config
- * built from `process.env` (L-11).
+ * A task as `vx show` prints it: a secret variable's value masked in every
+ * string it holds, where a TS config that builds one from `process.env`
+ * put it (the command, `env.define`, a runtime probe, `readyWhen`, the
+ * description) (L-11).
  */
 function shownTask(task: TaskConfig): TaskConfig {
-  const exec = task.exec
-  if (exec === undefined) return task
-  const define = exec.env?.define
-  const secrets = secretMask([process.env, define], exec.env?.secret)
-  if (secrets === null) return task
-  return {
-    ...task,
-    exec: {
-      ...exec,
-      ...(exec.command !== undefined ? { command: secrets.mask(exec.command) } : {}),
-      ...(define !== undefined
-        ? {
-            env: {
-              ...exec.env,
-              define: Object.fromEntries(
-                Object.entries(define).map(([k, v]) => [k, secrets.mask(v)]),
-              ),
-            },
-          }
-        : {}),
-    },
-  }
+  const secrets = secretMask([process.env, task.exec?.env?.define], task.exec?.env?.secret)
+  return secrets === null ? task : (maskStrings(task, secrets.mask) as TaskConfig)
+}
+
+function maskStrings(value: unknown, mask: (text: string) => string): unknown {
+  if (typeof value === 'string') return mask(value)
+  if (Array.isArray(value)) return value.map((v) => maskStrings(v, mask))
+  if (typeof value !== 'object' || value === null) return value
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskStrings(v, mask)]))
 }
 
 /** A project config with each task as `shownTask` prints it. */