@vzn/vx 0.0.100 → 0.0.102

package/src/cli/run.ts

@@ -150,11 +150,19 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     const a = before[i]
     if (a === '--filter' || a?.startsWith('--filter=')) {
       const v = a === '--filter' ? before[++i] : a.slice('--filter='.length)
-      if (v === undefined || v === '') return { ...out, error: `--filter requires a value` }
+      if (v === undefined || v === '')
+        return {
+          ...out,
+          error: `--filter requires a value (a project name, glob or path, e.g. --filter app)`,
+        }
       out.filters.push(v)
     } else if (a === '--concurrency' || a?.startsWith('--concurrency=')) {
       const v = a === '--concurrency' ? before[++i] : a.slice('--concurrency='.length)
-      if (v === undefined) return { ...out, error: `--concurrency requires a value` }
+      if (v === undefined)
+        return {
+          ...out,
+          error: `--concurrency requires a value (a positive integer, or a share of the cores such as 50%)`,
+        }
       const n = parseConcurrency(v)
       if (n === null)
         return {
@@ -193,7 +201,8 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.frozen = true
     } else if (a === '--retry' || a?.startsWith('--retry=')) {
       const v = a === '--retry' ? before[++i] : a.slice('--retry='.length)
-      if (v === undefined) return { ...out, error: `--retry requires a value` }
+      if (v === undefined)
+        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}` }
@@ -201,7 +210,8 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.retries = n
     } else if (a === '--timeout' || a?.startsWith('--timeout=')) {
       const v = a === '--timeout' ? before[++i] : a.slice('--timeout='.length)
-      if (v === undefined) return { ...out, error: `--timeout requires a value` }
+      if (v === undefined)
+        return { ...out, error: `--timeout requires a value (a positive integer, in ms)` }
       const n = parseDecimalInt(v)
       if (n !== null && n > MAX_TIMEOUT_MS) {
         // Not "effectively no limit" — setTimeout reduces a delay past 2^31-1
@@ -243,7 +253,11 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.cacheDir = v
     } else if (a === '--cache' || a?.startsWith('--cache=')) {
       const v = a === '--cache' ? before[++i] : a.slice('--cache='.length)
-      if (v === undefined) return { ...out, error: `--cache requires a value` }
+      if (v === undefined)
+        return {
+          ...out,
+          error: `--cache requires a value (a spec like local:r, local:rw, remote:, or local:,remote:rw)`,
+        }
       // A spec with no segment at all applies NOTHING, so `--cache=`
       // (an empty shell var, or someone reaching for "no cache") left
       // all four axes ON — the opposite of the intent. Reject it; an
@@ -283,7 +297,8 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.continueMode = v
     } else if (a === '--verbosity' || a?.startsWith('--verbosity=')) {
       const v = a === '--verbosity' ? before[++i] : a.slice('--verbosity='.length)
-      if (v === undefined) return { ...out, error: `--verbosity requires a value` }
+      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)` }
       out.verbosity = n
@@ -317,7 +332,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.affected = a.slice('--affected='.length)
     } else if (a === '--tag' || a?.startsWith('--tag=')) {
       const raw = a === '--tag' ? before[++i] : a.slice('--tag='.length)
-      if (raw === undefined) return { ...out, error: `${a} requires a value` }
+      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}` }

package/src/cli/show.ts

@@ -9,7 +9,7 @@
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
 import { flagHint, seeHelp } from './help.js'
-import { nearMatches, relPosix, UserError } from '../util/index.js'
+import { nearMatches, relPosix, secretMask, UserError } from '../util/index.js'
 import { loadCliProjects } from './workspace-config.js'
 import {
   findWorkspaceRoot,
@@ -35,7 +35,8 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
     else if (a.startsWith('--format=')) format = a.slice('--format='.length)
     else if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('show', a)}${seeHelp('show')}` }
-    else if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    else if (out.target !== undefined)
+      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)' }
@@ -152,6 +153,45 @@ function projectDir(root: string, meta: ProjectMeta): string {
   return rel === '' ? '.' : rel
 }
 
+/**
+ * A task as `vx show` prints it: a secret-named variable's value masked
+ * wherever it appears, in `env.define` and in the command a TS config
+ * built from `process.env` (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)
+  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)]),
+              ),
+            },
+          }
+        : {}),
+    },
+  }
+}
+
+/** A project config with each task as `shownTask` prints it. */
+function shownConfig(config: ProjectConfig | null): ProjectConfig | null {
+  if (config?.tasks === undefined) return config
+  return {
+    ...config,
+    tasks: Object.fromEntries(Object.entries(config.tasks).map(([n, t]) => [n, shownTask(t)])),
+  }
+}
+
 function renderList(
   root: string,
   metas: readonly ProjectMeta[],
@@ -197,7 +237,8 @@ function renderProject(
   if (format === 'json') {
     // Round-trip so the printed object is exactly the JSON form of the
     // resolved config (drops `undefined` fields).
-    return `${JSON.stringify(JSON.parse(JSON.stringify({ name, dir, config })), null, 2)}\n`
+    const shown = shownConfig(config)
+    return `${JSON.stringify(JSON.parse(JSON.stringify({ name, dir, config: shown })), null, 2)}\n`
   }
   const head = `${name} — ${dir}`
   const tasks = Object.entries(config?.tasks ?? {})
@@ -215,7 +256,7 @@ function renderTask(
   format: 'pretty' | 'json',
 ): string {
   if (format === 'json') {
-    const obj = { name, dir, task: taskName, config: task }
+    const obj = { name, dir, task: taskName, config: shownTask(task) }
     return `${JSON.stringify(JSON.parse(JSON.stringify(obj)), null, 2)}\n`
   }
   return `${name} — ${dir}\n\n${taskBlock(taskName, task)}`
@@ -232,7 +273,7 @@ function renderTaskAcross(
       name: p.name,
       dir: relPosix(root, p.dir) || '.',
       task: taskName,
-      config: p.config.tasks![taskName],
+      config: shownTask(p.config.tasks![taskName]!),
     }))
     return `${JSON.stringify(JSON.parse(JSON.stringify(list)), null, 2)}\n`
   }
@@ -245,7 +286,8 @@ function renderTaskAcross(
 }
 
 /** Every field the run reads, in the order the schema declares them. */
-function taskBlock(taskName: string, task: TaskConfig): string {
+function taskBlock(taskName: string, raw: TaskConfig): string {
+  const task = shownTask(raw)
   const rows: [string, string][] = []
   const list = (xs: readonly string[] | undefined): string | undefined =>
     xs === undefined ? undefined : xs.join(', ')

package/src/cli/watch-set.ts

@@ -0,0 +1,182 @@
+// What `vx watch` watches: the projects a cycle can run, what their configs
+// declare (outputs to ignore, inputs, workspace-wide globs) and the member
+// directories a package glob can grow. Read at start and again whenever an
+// edit reshapes the set; the loop in watch.ts decides when.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import type { ProjectConfig } from '../config.js'
+import {
+  buildPackageGraph,
+  configImports,
+  loadProjectConfig,
+  WORKSPACE_CONFIG_FILENAMES,
+  type ProjectEntry,
+  type ProjectMeta,
+} from '../workspace/index.js'
+import { taskEdges, taskEdgesFrom } from './select.js'
+import { type CliLoadOptions, loadCliProjects } from './workspace-config.js'
+
+/**
+ * The projects a cycle can run, so both watcher arms cover the same dirs:
+ * the scope plus its transitive dependencies through the package graph
+ * and the cross-project `dependsOn` edges the task graph adds
+ * (`e2e` → `app` from `dependsOn: ['app#build']`). Before this, the
+ * per-project arm watched the filter's answer only, so
+ * `vx watch build --filter app` never re-ran on a `lib` edit that
+ * `vx run build --filter app` would have rebuilt. A whole-workspace
+ * scope is every project already and walks nothing. A config the loader
+ * rejects contributes no edges here; the run that just happened said so.
+ */
+export async function watchedProjects(
+  workspaceRoot: string,
+  allProjects: readonly ProjectMeta[],
+  scope: readonly ProjectMeta[],
+  load: CliLoadOptions = {},
+  staged: ReadonlyMap<string, ProjectEntry> | null = null,
+): Promise<ProjectMeta[]> {
+  if (scope.length === allProjects.length) return [...allProjects]
+  let edges: Map<string, string[]> | undefined
+  try {
+    edges =
+      staged !== null
+        ? taskEdgesFrom(staged)
+        : (await taskEdges(workspaceRoot, allProjects, load)).edges
+  } catch {
+    edges = undefined
+  }
+  const graph = buildPackageGraph([...allProjects], edges)
+  const names = new Set(scope.map((p) => p.name))
+  for (const p of scope) for (const d of graph.transitiveDeps(p.name)) names.add(d)
+  return allProjects.filter((p) => names.has(p.name))
+}
+
+/** What one sweep over every config tells the loop. */
+export interface ConfigSweep {
+  workspaceWide: boolean
+  workspaceInputs: string[]
+  outputs: Map<string, string[]>
+  /** Declared input globs per directory they are relative to, the counterweight to `outputs`. */
+  inputs: Map<string, string[]>
+  /** Projects with a task that has a command and no cache: it reads what it likes, git-ignored files included. */
+  uncached: Set<string>
+  /** Files the project configs import by relative path (item 949). */
+  configImports: string[]
+  /** Files the workspace config imports by relative path: loaded once per process (item 949). */
+  workspaceConfigImports: string[]
+  /** The staged load the sweep read, when the run path's load succeeded; `watchedProjects` reads the same one. */
+  staged: Map<string, ProjectEntry> | null
+}
+
+/**
+ * One sweep over every config for the two things the loop needs: whether
+ * any task declares `inputs.workspaceFiles` — globs with no project
+ * prefix, so the whole tree has to be watched — and every project's
+ * declared outputs, so their writes are not taken for edits. The run
+ * path's load (`loadProjects`): the plugin `project` stage applies, so an
+ * output a plugin gave a config-less package is ignored like a declared
+ * one, and a pure config is served from its cached evaluation rather than
+ * re-evaluated in a worker. A config that fails to load is out of this
+ * concern's scope — the run that just happened already said so, or will —
+ * and the sweep falls back to the files that do load, one by one.
+ */
+export async function sweepConfigs(
+  projects: readonly ProjectMeta[],
+  workspaceRoot: string,
+  load: CliLoadOptions = {},
+): Promise<ConfigSweep> {
+  const outputs = new Map<string, string[]>()
+  const inputs = new Map<string, string[]>()
+  const addTo = (
+    into: Map<string, string[]>,
+    dir: string,
+    globs: readonly string[] | undefined,
+  ): void => {
+    if (globs === undefined || globs.length === 0) return
+    into.set(dir, [...(into.get(dir) ?? []), ...globs])
+  }
+  const add = (dir: string, globs: readonly string[] | undefined): void =>
+    addTo(outputs, dir, globs)
+  const workspaceInputs = new Set<string>()
+  const uncached = new Set<string>()
+  const fold = (dir: string, config: ProjectConfig): void => {
+    for (const task of Object.values(config.tasks ?? {})) {
+      if (task.cache === undefined && task.exec !== undefined && task.exec.persistent === undefined)
+        uncached.add(dir)
+      for (const g of task.cache?.inputs?.workspaceFiles ?? []) workspaceInputs.add(g)
+      addTo(inputs, dir, task.cache?.inputs?.files)
+      addTo(inputs, workspaceRoot, task.cache?.inputs?.workspaceFiles)
+      add(dir, task.cache?.outputs?.files)
+      add(workspaceRoot, task.cache?.outputs?.workspaceFiles)
+    }
+  }
+  const result = (staged: Map<string, ProjectEntry> | null): ConfigSweep => ({
+    workspaceWide: workspaceInputs.size > 0,
+    workspaceInputs: [...workspaceInputs],
+    outputs,
+    inputs,
+    uncached,
+    configImports: [...projectImports],
+    workspaceConfigImports: [...wsImports],
+    staged,
+  })
+  const projectImports = new Set<string>()
+  const wsImports = new Set<string>()
+  await Promise.all([
+    ...projects.map(async (p) => {
+      if (p.configPath === null) return
+      for (const f of await configImports(p.configPath)) projectImports.add(f)
+    }),
+    ...WORKSPACE_CONFIG_FILENAMES.map(async (name) => {
+      for (const f of await configImports(path.join(workspaceRoot, name))) wsImports.add(f)
+    }),
+  ])
+  let staged: Map<string, ProjectEntry> | null = null
+  try {
+    staged = await loadCliProjects(workspaceRoot, projects, 'all', load)
+  } catch {
+    staged = null
+  }
+  if (staged !== null) {
+    for (const p of staged.values()) fold(p.dir, p.config)
+    return result(staged)
+  }
+  await Promise.all(
+    projects.map(async (p) => {
+      if (p.configPath === null) return
+      try {
+        fold(p.dir, await loadProjectConfig(p.configPath))
+      } catch {
+        // broken config — out of this concern's scope
+      }
+    }),
+  )
+  return result(null)
+}
+
+/**
+ * The directory entries under a package glob's directory that can be
+ * members: directories (or links) whose name is not dotted and not
+ * `node_modules`, the same rule discovery applies. A watcher on that
+ * directory reacts only when this set changes.
+ */
+export function memberEntries(base: string): ReadonlySet<string> {
+  const out = new Set<string>()
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(base, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || e.name === 'node_modules') continue
+    if (e.isDirectory() || e.isSymbolicLink()) out.add(e.name)
+  }
+  return out
+}
+
+export function sameMembers(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  if (a.size !== b.size) return false
+  for (const name of a) if (!b.has(name)) return false
+  return true
+}

package/src/cli/watch.ts

@@ -25,22 +25,15 @@ import {
   type RunOptions,
 } from '../orchestrator/index.js'
 import {
-  buildPackageGraph,
   findWorkspaceRoot,
   type LoadReads,
   listProjects,
-  loadProjectConfig,
   loadWorkspace,
   LOCKFILE_NAME,
   memberBaseDirs,
-  WORKSPACE_CONFIG_FILENAMES,
-  configImports,
-  type ProjectEntry,
   type ProjectMeta,
 } from '../workspace/index.js'
-import type { ProjectConfig } from '../config.js'
-import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './workspace-config.js'
-import { taskEdges, taskEdgesFrom } from './select.js'
+import { type CliLoadOptions, loadCliWorkspace } from './workspace-config.js'
 import {
   gitIgnored,
   isIgnoredWatchPath,
@@ -59,6 +52,7 @@ import {
   WATCH_PROBE_TIMEOUT_MS,
   type WatchHandle,
 } from './watch-fs.js'
+import { memberEntries, sameMembers, sweepConfigs, watchedProjects } from './watch-set.js'
 
 /** Wait this long after the last filesystem event before re-running. */
 const DEBOUNCE_MS = 150
@@ -264,151 +258,6 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   })
 }
 
-/**
- * The projects a cycle can run, so both watcher arms cover the same dirs:
- * the scope plus its transitive dependencies through the package graph
- * and the cross-project `dependsOn` edges the task graph adds
- * (`e2e` → `app` from `dependsOn: ['app#build']`). Before this, the
- * per-project arm watched the filter's answer only, so
- * `vx watch build --filter app` never re-ran on a `lib` edit that
- * `vx run build --filter app` would have rebuilt. A whole-workspace
- * scope is every project already and walks nothing. A config the loader
- * rejects contributes no edges here; the run that just happened said so.
- */
-export async function watchedProjects(
-  workspaceRoot: string,
-  allProjects: readonly ProjectMeta[],
-  scope: readonly ProjectMeta[],
-  load: CliLoadOptions = {},
-  staged: ReadonlyMap<string, ProjectEntry> | null = null,
-): Promise<ProjectMeta[]> {
-  if (scope.length === allProjects.length) return [...allProjects]
-  let edges: Map<string, string[]> | undefined
-  try {
-    edges =
-      staged !== null
-        ? taskEdgesFrom(staged)
-        : (await taskEdges(workspaceRoot, allProjects, load)).edges
-  } catch {
-    edges = undefined
-  }
-  const graph = buildPackageGraph([...allProjects], edges)
-  const names = new Set(scope.map((p) => p.name))
-  for (const p of scope) for (const d of graph.transitiveDeps(p.name)) names.add(d)
-  return allProjects.filter((p) => names.has(p.name))
-}
-
-/**
- * One sweep over every config for the two things the loop needs: whether
- * any task declares `inputs.workspaceFiles` — globs with no project
- * prefix, so the whole tree has to be watched — and every project's
- * declared outputs, so their writes are not taken for edits. The run
- * path's load (`loadProjects`): the plugin `project` stage applies, so an
- * output a plugin gave a config-less package is ignored like a declared
- * one, and a pure config is served from its cached evaluation rather than
- * re-evaluated in a worker. A config that fails to load is out of this
- * concern's scope — the run that just happened already said so, or will —
- * and the sweep falls back to the files that do load, one by one.
- */
-export async function sweepConfigs(
-  projects: readonly ProjectMeta[],
-  workspaceRoot: string,
-  load: CliLoadOptions = {},
-): Promise<{
-  workspaceWide: boolean
-  workspaceInputs: string[]
-  outputs: Map<string, string[]>
-  /** Declared input globs per directory they are relative to, the counterweight to `outputs`. */
-  inputs: Map<string, string[]>
-  /** Projects with a task that has a command and no cache: it reads what it likes, git-ignored files included. */
-  uncached: Set<string>
-  /** Files the project configs import by relative path (item 949). */
-  configImports: string[]
-  /** Files the workspace config imports by relative path: loaded once per process (item 949). */
-  workspaceConfigImports: string[]
-  /** The staged load the sweep read, when the run path's load succeeded; `watchedProjects` reads the same one. */
-  staged: Map<string, ProjectEntry> | null
-}> {
-  const outputs = new Map<string, string[]>()
-  const inputs = new Map<string, string[]>()
-  const addTo = (
-    into: Map<string, string[]>,
-    dir: string,
-    globs: readonly string[] | undefined,
-  ): void => {
-    if (globs === undefined || globs.length === 0) return
-    into.set(dir, [...(into.get(dir) ?? []), ...globs])
-  }
-  const add = (dir: string, globs: readonly string[] | undefined): void =>
-    addTo(outputs, dir, globs)
-  const workspaceInputs = new Set<string>()
-  const uncached = new Set<string>()
-  const fold = (dir: string, config: ProjectConfig): void => {
-    for (const task of Object.values(config.tasks ?? {})) {
-      if (task.cache === undefined && task.exec !== undefined && task.exec.persistent === undefined)
-        uncached.add(dir)
-      for (const g of task.cache?.inputs?.workspaceFiles ?? []) workspaceInputs.add(g)
-      addTo(inputs, dir, task.cache?.inputs?.files)
-      addTo(inputs, workspaceRoot, task.cache?.inputs?.workspaceFiles)
-      add(dir, task.cache?.outputs?.files)
-      add(workspaceRoot, task.cache?.outputs?.workspaceFiles)
-    }
-  }
-  const result = (
-    staged: Map<string, ProjectEntry> | null,
-  ): {
-    workspaceWide: boolean
-    workspaceInputs: string[]
-    outputs: Map<string, string[]>
-    inputs: Map<string, string[]>
-    uncached: Set<string>
-    configImports: string[]
-    workspaceConfigImports: string[]
-    staged: Map<string, ProjectEntry> | null
-  } => ({
-    workspaceWide: workspaceInputs.size > 0,
-    workspaceInputs: [...workspaceInputs],
-    outputs,
-    inputs,
-    uncached,
-    configImports: [...projectImports],
-    workspaceConfigImports: [...wsImports],
-    staged,
-  })
-  const projectImports = new Set<string>()
-  const wsImports = new Set<string>()
-  await Promise.all([
-    ...projects.map(async (p) => {
-      if (p.configPath === null) return
-      for (const f of await configImports(p.configPath)) projectImports.add(f)
-    }),
-    ...WORKSPACE_CONFIG_FILENAMES.map(async (name) => {
-      for (const f of await configImports(path.join(workspaceRoot, name))) wsImports.add(f)
-    }),
-  ])
-  let staged: Map<string, ProjectEntry> | null = null
-  try {
-    staged = await loadCliProjects(workspaceRoot, projects, 'all', load)
-  } catch {
-    staged = null
-  }
-  if (staged !== null) {
-    for (const p of staged.values()) fold(p.dir, p.config)
-    return result(staged)
-  }
-  await Promise.all(
-    projects.map(async (p) => {
-      if (p.configPath === null) return
-      try {
-        fold(p.dir, await loadProjectConfig(p.configPath))
-      } catch {
-        // broken config — out of this concern's scope
-      }
-    }),
-  )
-  return result(null)
-}
-
 interface WatchLoopArgs {
   opts: RunOptions
   /** The persistent tasks the initial run left running; the next cycle stops them before it starts. */
@@ -746,7 +595,20 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       watchers.push(pollWatcher(dir, recursive, onEvent, POLL_INTERVAL_MS, skipUnder(dir)))
       return handle
     }
-    const armed = armWatcher(dir, recursive, onEvent)
+    let armed: ReturnType<typeof armWatcher>
+    try {
+      armed = armWatcher(dir, recursive, onEvent)
+    } catch (err) {
+      // The OS's watch limit, not the directory: the loop said "watching"
+      // and never fired. The poller needs no watch slot.
+      const code = (err as NodeJS.ErrnoException).code
+      if (code !== 'ENOSPC' && code !== 'EMFILE') throw err
+      watchers.push(pollWatcher(dir, recursive, onEvent, POLL_INTERVAL_MS, skipUnder(dir)))
+      process.stderr.write(
+        `vx watch: ${dir}: the OS watch limit is reached (${code}); polling every ${POLL_INTERVAL_MS} ms instead — raise it (Linux: sysctl fs.inotify.max_user_watches) to watch natively\n`,
+      )
+      return handle
+    }
     watchers.push(armed.watcher)
     proofs.push(
       armed.ready.then((ok) => {
@@ -1099,30 +961,3 @@ export function pendingAfterCycle(
   const [abs, label] = [...pending][0]!
   return [abs, label]
 }
-
-/**
- * The directory entries under a package glob's directory that can be
- * members: directories (or links) whose name is not dotted and not
- * `node_modules`, the same rule discovery applies. A watcher on that
- * directory reacts only when this set changes.
- */
-export function memberEntries(base: string): ReadonlySet<string> {
-  const out = new Set<string>()
-  let entries: fs.Dirent[]
-  try {
-    entries = fs.readdirSync(base, { withFileTypes: true })
-  } catch {
-    return out
-  }
-  for (const e of entries) {
-    if (e.name.startsWith('.') || e.name === 'node_modules') continue
-    if (e.isDirectory() || e.isSymbolicLink()) out.add(e.name)
-  }
-  return out
-}
-
-function sameMembers(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
-  if (a.size !== b.size) return false
-  for (const name of a) if (!b.has(name)) return false
-  return true
-}

package/src/cli/why.ts

@@ -61,7 +61,8 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
     // got two different diagnoses depending on how it was typed.
     if (a === '--run' || a.startsWith('--run=')) {
       const rv = a === '--run' ? args[++i] : a.slice(6)
-      if (rv === undefined || rv === '') return { ...out, error: 'invalid --run: empty' }
+      if (rv === undefined || rv === '')
+        return { ...out, error: '--run requires a run id (`vx last --list` shows them)' }
       out.runId = rv
       continue
     }
@@ -71,7 +72,10 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
         // An omitted value reads as empty, not as the literal word "undefined".
         return {
           ...out,
-          error: `invalid --format: ${fv ?? ''} (expected pretty | json)`,
+          error:
+            fv === undefined || fv === ''
+              ? '--format requires a value (pretty | json)'
+              : `invalid --format: ${fv} (expected pretty | json)`,
         }
       }
       out.format = fv
@@ -86,7 +90,8 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
     }
     if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('why', a)}${seeHelp('why')}` }
-    if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    if (out.target !== undefined)
+      return { ...out, error: `unexpected argument: ${a}${seeHelp('why')}` }
     // Empty is no task: read as a query it matched every recorded one.
     if (a !== '') out.target = a
   }
@@ -239,7 +244,19 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
       const kinds = [...new Set(diff.entries.map((e) => e.kind))].filter((k) => k in WHAT_TO_DO)
       if (kinds.length > 0) {
         lines.push('', '  what to do:')
-        for (const k of kinds) lines.push(`    ${k.padEnd(kindW)}  ${WHAT_TO_DO[k]}`)
+        // An upstream row names the task to ask next: the command, not a
+        // placeholder to fill in from the row above.
+        const upstream = diff.entries.filter((e) => e.kind === 'upstream').map((e) => e.name)
+        for (const k of kinds) {
+          const todo =
+            k === 'upstream'
+              ? WHAT_TO_DO[k]!.replace(
+                  '`vx why <that task>`',
+                  upstream.map((n) => `\`vx why ${n}\``).join(', '),
+                )
+              : WHAT_TO_DO[k]
+          lines.push(`    ${k.padEnd(kindW)}  ${todo}`)
+        }
       }
     } else if (why.hashChanged === true) {
       lines.push(`  detail     ${diff.note}`)

package/src/exec/kill-tree.ts

@@ -78,6 +78,8 @@ const GUARD_SCRIPT = [
 function startGuard(): void {
   if (guardFd !== undefined) return
   guardFd = null
+  // The guard is an `sh` script over process groups; Windows has neither.
+  if (process.platform === 'win32') return
   try {
     const guard = Bun.spawn([executablePath('sh'), '-c', GUARD_SCRIPT], {
       argv0: 'vx-group-guard',