@vzn/vx 0.0.590 → 0.0.594

package/src/cli/info.ts

@@ -5,12 +5,12 @@
 // too; this file parses the flags and renders the rows.
 
 import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
-import { flagHint, refusedWord, seeHelp } from './help.js'
+import { flagHint, formatValue, refusedWord, seeHelp } from './help.js'
 import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 import { MIN_BUN } from '../util/index.js'
 
-export interface InfoArgs {
+interface InfoArgs {
   format: 'pretty' | 'json'
   /** `--cache-dir`: report on the cache a run with the same flag uses. */
   cacheDir?: string
@@ -22,10 +22,8 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '--format' || a?.startsWith('--format=')) {
-      const v = a === '--format' ? args[++i] : a.slice('--format='.length)
-      if (v !== 'pretty' && v !== 'json') {
-        return { ...out, error: `--format must be pretty or json${seeHelp('info')}` }
-      }
+      const v = formatValue(a === '--format' ? args[++i] : a.slice('--format='.length), 'info')
+      if (typeof v === 'object') return { ...out, ...v }
       out.format = v
       continue
     }

package/src/cli/init.ts

@@ -11,7 +11,7 @@ import { mkdir, unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
 import { PLUGIN_TEMPLATES } from './plugin-templates.js'
-import { isUserError, UserError } from '../util/index.js'
+import { isUserError, relPosix, UserError } from '../util/index.js'
 import {
   applyMigration,
   discoverProjects,
@@ -22,7 +22,7 @@ import {
   WORKSPACE_CONFIG_FILENAMES,
 } from '../workspace/index.js'
 
-export interface InitArgs {
+interface InitArgs {
   dry: boolean
   force: boolean
   /** `vx.config.mjs` instead of `.ts` — see `ApplyMigrationArgs.format`. */
@@ -379,7 +379,7 @@ function namelessNotes(root: string, dirs: readonly string[]): string[] {
         Object.values(scripts).some((v) => typeof v === 'string' && v !== '')
       )
     })
-    .map((dir) => path.relative(root, dir).split(path.sep).join('/'))
+    .map((dir) => relPosix(root, dir))
     .sort()
     // The root's own manifest is the empty relative path: a nameless
     // single-package repo read `not mapped:  — its package.json…` (M-54).

package/src/cli/last.ts

@@ -1,4 +1,4 @@
-// `vx last [runId]` — replay a recorded run's summary from the terminal,
+// `vx last [RUNID]` — replay a recorded run's summary from the terminal,
 // without re-executing anything. Comparison gap #12: with the dashboard's
 // run-detail page gone (the 2026-08-23 cloud removal), the local run
 // history in cache.db is the only replay surface, and this verb reads it.
@@ -7,7 +7,7 @@
 import type { Database } from 'bun:sqlite'
 import { Cache } from '../cache/index.js'
 import { formatBytes } from './format.js'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, seeHelp } from './help.js'
 import {
   exitSignal,
   getInvocation,
@@ -70,16 +70,8 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       continue
     }
     if (a === '--format' || a.startsWith('--format=')) {
-      const fv = a === '--format' ? args[++i] : a.slice(9)
-      if (fv !== 'pretty' && fv !== 'json') {
-        return {
-          ...out,
-          error:
-            fv === undefined || fv === ''
-              ? '--format requires a value (pretty | json)'
-              : `invalid --format: ${fv} (expected pretty | json)`,
-        }
-      }
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice(9), 'last')
+      if (typeof fv === 'object') return { ...out, ...fv }
       out.format = fv
       continue
     }
@@ -241,6 +233,47 @@ function hitsLine(
   return `${hits} (${inv.upToDateCount} up-to-date, ${restored} restored${layers})`
 }
 
+/**
+ * `vx last --list`'s rows, in columns: the counts vary with what a run
+ * hit and failed, so unpadded they pushed each run's duration and command
+ * to a different column and the list could not be scanned down.
+ */
+export function formatRunList(
+  runs: readonly {
+    inv: Pick<
+      InvocationDetail,
+      | 'exitOk'
+      | 'startedAt'
+      | 'taskCount'
+      | 'failedCount'
+      | 'totalDurationMs'
+      | 'command'
+      | 'hitCount'
+      | 'upToDateCount'
+      | 'restoredLocalCount'
+      | 'restoredRemoteCount'
+    >
+    id: string
+  }[],
+): string[] {
+  const rows = runs.map(({ inv, id }) => ({
+    head: `${inv.exitOk ? 'ok    ' : 'FAILED'} ${fmtWhen(inv.startedAt)}`,
+    id,
+    counts:
+      `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${hitsLine(inv)}` +
+      (inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''),
+    ms: fmtMs(inv.totalDurationMs),
+    command: inv.command,
+  }))
+  const idW = Math.max(...rows.map((r) => r.id.length))
+  const countsW = Math.max(...rows.map((r) => r.counts.length))
+  const msW = Math.max(...rows.map((r) => r.ms.length))
+  return rows.map(
+    (r) =>
+      `${r.head}  ${r.id.padEnd(idW)}  ${r.counts.padEnd(countsW)}  ${r.ms.padStart(msW)}  $ ${r.command}`,
+  )
+}
+
 export async function lastCmd(args: readonly string[]): Promise<number> {
   const parsed = parseLastArgs(args)
   if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`)
@@ -269,14 +302,10 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         )
         return 0
       }
-      for (const inv of invocations) {
-        const verdict = inv.exitOk ? 'ok    ' : 'FAILED'
-        process.stdout.write(
-          `${verdict} ${fmtWhen(inv.startedAt)}  ${shortRunId(db, inv.runId)}  ` +
-            `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${hitsLine(inv)}` +
-            `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''} · ${fmtMs(inv.totalDurationMs)}  $ ${inv.command}\n`,
-        )
-      }
+      const lines = formatRunList(
+        invocations.map((inv) => ({ inv, id: shortRunId(db, inv.runId) })),
+      )
+      process.stdout.write(`${lines.join('\n')}\n`)
       return 0
     }
 

package/src/cli/lock.ts

@@ -20,7 +20,7 @@ import {
   type ProjectMeta,
 } from '../workspace/index.js'
 
-export interface LockArgs {
+interface LockArgs {
   check: boolean
   error?: string
 }
@@ -99,7 +99,7 @@ async function writeLock(root: string, metas: ConfiguredMeta[], bare: number): P
   await writeLockfile(root, lock)
   const n = metas.length
   process.stdout.write(
-    `vx: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}\n`,
+    `vx lock: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}\n`,
   )
   return 0
 }
@@ -199,6 +199,6 @@ async function checkLock(root: string, metas: ConfiguredMeta[], bare: number): P
   const n = metas.length
   const audited = `${n} project${n === 1 ? '' : 's'}`
   const skipped = bare === 0 ? '' : `; ${bare} without a vx.config not audited`
-  process.stdout.write(`vx: lock is up to date (${audited}${skipped})\n`)
+  process.stdout.write(`vx lock --check: up to date (${audited}${skipped})\n`)
   return 0
 }

package/src/cli/run.ts

@@ -428,37 +428,11 @@ function onCI(v: string | undefined): boolean {
   return v !== undefined && v !== '' && v !== '0' && v !== 'false'
 }
 
-/**
- * Resolve parsed `vx run` argv into the `RunOptions` the orchestrator
- * consumes. Shared between `runCmd` and `watchCmd` so both subcommands
- * honor the same selection semantics (cwd / `--all` / `--filter` /
- * `--affected` / anchored positionals).
- *
- * Returns the resolved options, an error message, or `nothingSelected` —
- * the selection legitimately resolved to zero projects (nothing changed
- * since the `--affected` base), which is a clean exit, not a failure. The
- * caller prefixes messages with its subcommand name (`vx run: <msg>` /
- * `vx watch: <msg>`).
- *
- * Assumes the caller has already populated `parsed.tasks` (e.g. via
- * the interactive picker for `vx run`).
- */
-export async function resolveRunOptions(
+/** The filters a run's scope comes from: `--filter`s, with `--affected` as its `...[<base>]`. */
+async function scopeFilters(
   parsed: RunArgs,
   cwd: string,
-  tasks: readonly string[],
-): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
-  for (const t of tasks) {
-    const idx = t.indexOf('#')
-    if (idx >= 0) {
-      const project = t.slice(0, idx)
-      const task = t.slice(idx + 1)
-      if (!project || !task) {
-        return { error: `invalid pkg#task: ${t}` }
-      }
-    }
-  }
-
+): Promise<{ filterStrings: string[]; affectedFilter?: string } | { error: string }> {
   // `--affected[=<base>]` is sugar for `--filter '...[<base>]'`: the
   // changed projects AND their dependents — what a CI gate must run, what
   // the flag's name says, what the guides promised while the sugar was the
@@ -488,6 +462,43 @@ export async function resolveRunOptions(
     affectedFilter = `...[${base}]`
     filterStrings.unshift(affectedFilter)
   }
+  return { filterStrings, ...(affectedFilter !== undefined ? { affectedFilter } : {}) }
+}
+
+/**
+ * Resolve parsed `vx run` argv into the `RunOptions` the orchestrator
+ * consumes. Shared between `runCmd` and `watchCmd` so both subcommands
+ * honor the same selection semantics (cwd / `--all` / `--filter` /
+ * `--affected` / anchored positionals).
+ *
+ * Returns the resolved options, an error message, or `nothingSelected` —
+ * the selection legitimately resolved to zero projects (nothing changed
+ * since the `--affected` base), which is a clean exit, not a failure. The
+ * caller prefixes messages with its subcommand name (`vx run: <msg>` /
+ * `vx watch: <msg>`).
+ *
+ * Assumes the caller has already populated `parsed.tasks` (e.g. via
+ * the interactive picker for `vx run`).
+ */
+export async function resolveRunOptions(
+  parsed: RunArgs,
+  cwd: string,
+  tasks: readonly string[],
+): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
+  for (const t of tasks) {
+    const idx = t.indexOf('#')
+    if (idx >= 0) {
+      const project = t.slice(0, idx)
+      const task = t.slice(idx + 1)
+      if (!project || !task) {
+        return { error: `invalid pkg#task: ${t}` }
+      }
+    }
+  }
+
+  const scope = await scopeFilters(parsed, cwd)
+  if ('error' in scope) return scope
+  const { filterStrings, affectedFilter } = scope
 
   // Project scope applies to bare task names only. Anchored entries
   // (pkg#task) resolve directly to their own project regardless.
@@ -625,14 +636,31 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       )
       return 1
     }
-    const picked = await pickTask(
-      cwd,
-      {},
-      {
-        ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
-        ...(parsed.frozen ? { frozen: true } : {}),
-      },
-    )
+    const load = {
+      ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+      ...(parsed.frozen ? { frozen: true } : {}),
+    }
+    // `--filter` / `--affected` scope the menu, as they scope a bare task:
+    // the menu listed every project and the anchored pick ran outside it.
+    const scope = await scopeFilters(parsed, cwd)
+    if ('error' in scope) {
+      process.stderr.write(`vx run: ${scope.error}\n`)
+      return 1
+    }
+    let only: ReadonlySet<string> | undefined
+    if (scope.filterStrings.length > 0) {
+      const selected = await resolveFilters(cwd, scope.filterStrings, load, scope.affectedFilter)
+      if ('error' in selected) {
+        process.stderr.write(`vx run: ${selected.error}\n`)
+        return 1
+      }
+      if ('empty' in selected) {
+        process.stderr.write(`vx run: ${selected.empty}\n`)
+        return 0
+      }
+      only = new Set(selected.names)
+    }
+    const picked = await pickTask(cwd, {}, load, only)
     if (picked === 'interrupted') return 130
     if (!picked) return 1
     tasks = [`${picked.project}#${picked.task}`]

package/src/cli/select.ts

@@ -243,7 +243,10 @@ export async function resolveFilters(
   } catch (err) {
     return { error: err instanceof Error ? err.message : String(err) }
   }
-  const walksGraph = parsed.some((f) => f.withDeps || f.withDependents || f.onlyDeps)
+  // `sinceViaDeps` (`e2e...[main]`) walks the changed projects' dependents.
+  const walksGraph = parsed.some(
+    (f) => f.withDeps || f.withDependents || f.onlyDeps || f.sinceViaDeps === true,
+  )
   // A filter that diffs against git starts the run's whole-tree walk now:
   // the diff reads its untracked files from it (one walk where it spawned
   // its own), and the run reuses it with the discovery (I-26).
@@ -422,7 +425,7 @@ export async function resolveFilters(
   }
 }
 
-export interface PickedTask {
+interface PickedTask {
   project: string
   task: string
   description?: string
@@ -436,6 +439,8 @@ export async function pickTask(
   cwd: string,
   io: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream } = {},
   load: CliLoadOptions = {},
+  /** The projects `--filter` / `--affected` selected; every project when absent. */
+  only?: ReadonlySet<string>,
 ): Promise<PickedTask | null | 'interrupted'> {
   const projects = await loadWorkspaceProjects(cwd)
   // The staged load: a task a `project` plugin gave a config-less package
@@ -443,6 +448,7 @@ export async function pickTask(
   const staged = await loadCliProjects(await findWorkspaceRoot(cwd), projects, 'all', load)
   const entries: PickedTask[] = []
   for (const meta of projects) {
+    if (only !== undefined && !only.has(meta.name)) continue
     const config = staged.get(meta.name)?.config
     if (config === undefined) continue
     const taskNames = Object.keys(config.tasks ?? {})
@@ -453,6 +459,12 @@ export async function pickTask(
       entries.push({ project: meta.name, task: t, ...(desc ? { description: desc } : {}) })
     }
   }
+  if (entries.length === 0 && only !== undefined) {
+    process.stderr.write(
+      `vx run: no tasks declared in the selected projects (${[...only].sort().join(', ')})\n`,
+    )
+    return null
+  }
   if (entries.length === 0) {
     process.stderr.write(
       'vx run: no tasks declared in any project; declare one under `tasks` in a vx.config, or run `vx init` to write them from package.json scripts\n',

package/src/cli/show.ts

@@ -10,7 +10,7 @@ import path from 'node:path'
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
 import { isDefaultBuild } from '../orchestrator/index.js'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, seeHelp } from './help.js'
 import { listed, nearMatches, relPosix, secretMask, UserError } from '../util/index.js'
 import { discoverCliProjects, loadCliProjects } from './workspace-config.js'
 import {
@@ -21,7 +21,7 @@ import {
   type ProjectMeta,
 } from '../workspace/index.js'
 
-export interface ShowArgs {
+interface ShowArgs {
   target?: string
   format: 'pretty' | 'json'
   error?: string
@@ -47,10 +47,9 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
     else out.target = a
 
     if (format !== undefined) {
-      if (format !== 'pretty' && format !== 'json') {
-        return { ...out, error: '--format must be pretty or json' }
-      }
-      out.format = format
+      const fv = formatValue(format, 'show')
+      if (typeof fv === 'object') return { ...out, ...fv }
+      out.format = fv
     }
   }
   return out

package/src/cli/upgrade.ts

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

package/src/cli/watch-filter.ts

@@ -185,7 +185,7 @@ export function gitIgnored(workspaceRoot: string, paths: readonly string[]): Set
     }
     // Each record: source, line, pattern, path. No source: no pattern
     // matched; a `!` pattern: re-included. Either way not ignored.
-    const fields = new TextDecoder().decode(proc.stdout).split('\0')
+    const fields = new TextDecoder('utf-8', { ignoreBOM: true }).decode(proc.stdout).split('\0')
     const records = Math.floor(fields.length / 4)
     for (let i = 0; i < records; i++) {
       const [source, , pattern, p] = fields.slice(i * 4, i * 4 + 4)
@@ -232,10 +232,11 @@ export function makeRootEventFilter(
   fenced: (ownDir: string, abs: string) => boolean = () => false,
 ): (filename: string) => boolean {
   const dirs = projectDirs.map((d) => path.resolve(d))
-  const globs = workspaceInputs
-    .map(normalizeGlob)
-    .filter((g) => !g.startsWith('!'))
-    .map((g) => taskGlob(g))
+  // A literal is its tree, as the key resolves it: `shared` matched only
+  // the directory's own event and no edit under it ran a cycle (WD-2).
+  const globs = asTrees(workspaceInputs.filter((g) => !normalizeGlob(g).startsWith('!'))).map((g) =>
+    taskGlob(g),
+  )
   return (filename: string): boolean => {
     const rel = filename.split(path.sep).join('/')
     // The depth test is a READING AID, not a guard: both predicates below
@@ -359,7 +360,7 @@ export function gitFiles(workspaceRoot: string): Set<string> | undefined {
   }
   if (proc.exitCode !== 0) return undefined
   const files = new Set<string>()
-  for (const p of new TextDecoder().decode(proc.stdout).split('\0')) {
+  for (const p of new TextDecoder('utf-8', { ignoreBOM: true }).decode(proc.stdout).split('\0')) {
     if (p.length === 0) continue
     // An untracked nested repository is listed as `dir/`.
     let abs = path.join(workspaceRoot, p.endsWith('/') ? p.slice(0, -1) : p)

package/src/cli/watch-fs.ts

@@ -237,6 +237,12 @@ export function armWatcher(
  */
 function treeWatcher(root: string, listener: (filename: string) => void): WatchHandle {
   const watchers = new Map<string, fs.FSWatcher>()
+  // Which directory each watch holds: inotify follows the inode, so a name
+  // removed and made again before its event is handled stats as a
+  // directory still, and the watch on the deleted one heard nothing more.
+  // The birth time too: a freed inode number goes to the next directory.
+  const held = new Map<string, string>()
+  const idOf = (st: fs.Stats): string => `${st.dev}:${st.ino}:${st.birthtimeMs}`
   let closed = false
   let armed = false
   let warned = false
@@ -249,6 +255,7 @@ function treeWatcher(root: string, listener: (filename: string) => void): WatchH
       if (key !== rel && !key.startsWith(rel + '/')) continue
       w.close()
       watchers.delete(key)
+      held.delete(key)
     }
   }
   const watchDir = (rel: string, report: boolean): void => {
@@ -269,7 +276,10 @@ function treeWatcher(root: string, listener: (filename: string) => void): WatchH
           return
         }
         if (!st.isDirectory()) return
-        if (watchers.has(child)) return
+        if (watchers.has(child)) {
+          if (held.get(child) === idOf(st)) return
+          drop(child)
+        }
         watchDir(child, true)
       })
     } catch (err) {
@@ -289,6 +299,11 @@ function treeWatcher(root: string, listener: (filename: string) => void): WatchH
     }
     w.on('error', () => drop(rel))
     watchers.set(rel, w)
+    try {
+      held.set(rel, idOf(fs.statSync(abs)))
+    } catch {
+      held.set(rel, '')
+    }
     let entries: fs.Dirent[]
     try {
       entries = fs.readdirSync(abs, { withFileTypes: true })
@@ -314,6 +329,7 @@ function treeWatcher(root: string, listener: (filename: string) => void): WatchH
       closed = true
       for (const w of watchers.values()) w.close()
       watchers.clear()
+      held.clear()
     },
   }
 }

package/src/cli/watch.ts

@@ -55,6 +55,12 @@ function sayCannot(what: string, err: unknown): void {
 
 /** Wait this long after the last filesystem event before re-running. */
 const DEBOUNCE_MS = 150
+/**
+ * ...but no longer than this after the first: a writer that never pauses
+ * for a window (a dev server logging into its project every 50 ms) reset
+ * the timer forever, and an edit made meanwhile never ran.
+ */
+const DEBOUNCE_MAX_MS = 1_000
 
 /**
  * The run flags a watch loop cannot honour, as the refusal line it prints; null
@@ -365,11 +371,15 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
   /** The cycle in flight, so the stop path can wait for its teardown before resolving. */
   let inFlight: Promise<void> = Promise.resolve()
   let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  let windowOpened = 0
 
   const trigger = (label: string, abs: string): void => {
     if (!changes.pending.has(abs)) changes.pending.set(abs, label)
     if (running) return
-    if (debounceTimer) clearTimeout(debounceTimer)
+    if (debounceTimer) {
+      if (Date.now() - windowOpened >= DEBOUNCE_MAX_MS) return
+      clearTimeout(debounceTimer)
+    } else windowOpened = Date.now()
     debounceTimer = setTimeout(() => {
       debounceTimer = null
       if (running) return
@@ -491,7 +501,9 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
       const handle = arm(proj.dir, true, (filename) => {
         const abs = path.join(proj.dir, filename)
         if (isIgnoredPath(proj.dir, filename) || fenced(proj.dir, abs)) return
-        if (shapesWatchedSet(filename)) reread = true
+        // A module the config imports from inside the project is the config
+        // too: its edit can add an output or a `workspaceFiles` input.
+        if (shapesWatchedSet(filename) || configImportFiles.includes(abs)) reread = true
         trigger(`${proj.name} ${filename}`, abs)
       })
       perProject.set(proj.dir, handle)
@@ -512,8 +524,14 @@ async function runWatchLoop(args: WatchLoopArgs): Promise<number> {
           // / .git / .vx and declared outputs out of what remains.
           arm(workspaceRoot, true, (filename) => {
             if (!matters(filename) || isIgnoredPath(workspaceRoot, filename)) return
-            if (shapesWatchedSet(filename) || filename === LOCKFILE_NAME) reread = true
-            trigger(`root ${filename}`, path.join(workspaceRoot, filename))
+            const abs = path.join(workspaceRoot, filename)
+            if (
+              shapesWatchedSet(filename) ||
+              filename === LOCKFILE_NAME ||
+              configImportFiles.includes(abs)
+            )
+              reread = true
+            trigger(`root ${filename}`, abs)
           })
         : // The root itself, non-recursive, beside the per-project arms, so
           // lockfile + pnpm-workspace.yaml edits trigger re-runs even when

package/src/cli/why.ts

@@ -7,7 +7,7 @@
 
 import path from 'node:path'
 import { Cache } from '../cache/index.js'
-import { flagHint, seeHelp } from './help.js'
+import { flagHint, formatValue, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
@@ -70,17 +70,8 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
       continue
     }
     if (a === '--format' || a.startsWith('--format=')) {
-      const fv = a === '--format' ? args[++i] : a.slice(9)
-      if (fv !== 'pretty' && fv !== 'json') {
-        // An omitted value reads as empty, not as the literal word "undefined".
-        return {
-          ...out,
-          error:
-            fv === undefined || fv === ''
-              ? '--format requires a value (pretty | json)'
-              : `invalid --format: ${fv} (expected pretty | json)`,
-        }
-      }
+      const fv = formatValue(a === '--format' ? args[++i] : a.slice(9), 'why')
+      if (typeof fv === 'object') return { ...out, ...fv }
       out.format = fv
       continue
     }
@@ -235,7 +226,7 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     const why = whyDidThisRerun(db, runId, taskId)
     if (!why.found) {
       throw new UserError(
-        `vx why: run ${runId} has no row for ${taskId}; \`vx last --list\` shows the recorded runs, \`vx last <runId>\` what one ran`,
+        `vx why: run ${runId} has no row for ${taskId}; \`vx last --list\` shows the recorded runs, \`vx last RUNID\` what one ran`,
       )
     }
     const diff = cacheKeyDiff(db, runId, taskId)

package/src/cli/workspace-config.ts

@@ -23,7 +23,7 @@ import {
   resolveStoreRoot,
 } from '../workspace/index.js'
 
-export interface CliWorkspace {
+interface CliWorkspace {
   workspaceConfig: WorkspaceConfig | null
   plugins: readonly VxPlugin[]
   cacheDir: string

package/src/exec/env.ts

@@ -125,11 +125,9 @@ export function packageManagerPath(root: string): string | null {
   if (known !== undefined) return known
   let name: string | undefined
   try {
-    const field = (
-      JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')) as {
-        packageManager?: unknown
-      }
-    ).packageManager
+    // A byte-order mark is stripped, as npm and discovery strip it.
+    const manifest = readFileSync(path.join(root, 'package.json'), 'utf8').replace(/^\uFEFF/, '')
+    const field = (JSON.parse(manifest) as { packageManager?: unknown }).packageManager
     if (typeof field === 'string') name = MANAGERS.find((m) => field.startsWith(`${m}@`))
   } catch {}
   name ??= LOCKFILES.find(([f]) => existsSync(path.join(root, f)))?.[1]