@vzn/vx 0.0.15 → 0.0.18

package/src/cli/run.ts

@@ -1,5 +1,7 @@
 import readline from 'node:readline/promises'
+import { appendFile } from 'node:fs/promises'
 import path from 'node:path'
+import { documentedFlags } from './help.js'
 import {
   affectedProjects,
   applyFilters,
@@ -9,26 +11,25 @@ import {
   listProjects,
   loadProjectConfig,
   loadWorkspace,
-  loadWorkspaceConfig,
   parseFilter,
-  resolveCacheDir,
+  readLockfile,
+  workspaceGlobsMatch,
   type ProjectMeta,
 } from '../workspace/index.js'
 import {
   planRun,
   formatRunReportMarkdown,
-  optionsToRequest,
-  resolveBackend as resolvePluginBackend,
+  projectOutcome,
+  run as runOrchestrator,
   type OutcomeView,
   type RunOptions,
   type RunResult,
-  type VxPlugin,
 } from '../orchestrator/index.js'
+import type { ProjectConfig } from '../config.js'
 import type { ContinueMode } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
-import { parseSize } from '../util/index.js'
+import { MAX_TIMEOUT_MS, parseDecimalInt, parseSize, editDistance } from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
-import { localBackend } from './backend.js'
 
 export interface RunArgs {
   /** Failure propagation (`--continue[=never|deps-ok|always]`). */
@@ -85,7 +86,8 @@ export interface RunArgs {
    */
   verify: { determinism: boolean; inputs: boolean; fingerprint: boolean } | undefined
   verifyAllow: string[]
-  outputLogs?: 'full' | 'errors-only' | 'none'
+  outputLogs?: 'full' | 'errors-only' | 'none' | 'hash-only'
+  download?: 'all' | 'toplevel' | 'none'
   forwardArgs: string[]
   verbosity: number
   dry: 'text' | 'json' | undefined
@@ -102,6 +104,12 @@ export interface RunArgs {
   tags: Record<string, string>
   /** `--report[=markdown]`. Undefined when the flag wasn't passed. */
   report: 'markdown' | undefined
+  /**
+   * `--report-file=<path>`. Undefined when the flag wasn't passed. Writes
+   * the same markdown as `--report`, but to a file — because redirecting
+   * vx's stdout captures the whole run log, not just the report.
+   */
+  reportFile: string | undefined
   error?: string
 }
 
@@ -129,6 +137,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     affected: undefined,
     tags: {},
     report: undefined,
+    reportFile: undefined,
   }
 
   const sepIdx = args.indexOf('--')
@@ -146,22 +155,34 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
 
   for (let i = 0; i < before.length; i++) {
     const a = before[i]
-    if (a === '--filter') {
-      const v = before[++i]
-      if (v === undefined) return { ...out, error: `${a} requires a value` }
+    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` }
       out.filters.push(v)
-    } else if (a === '--concurrency') {
-      const v = before[++i]
-      if (v === undefined) return { ...out, error: `${a} requires a value` }
-      const n = Number(v)
-      if (!Number.isFinite(n) || n < 1) return { ...out, error: `invalid concurrency: ${v}` }
-      out.concurrency = Math.floor(n)
+    } 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` }
+      const n = parseDecimalInt(v)
+      if (n === null || n < 1) return { ...out, error: `invalid concurrency: ${v}` }
+      out.concurrency = n
     } else if (a === '--all') {
       out.all = true
     } else if (a === '--excludeDependencies') {
       out.excludeDependencies = 'all'
     } else if (a?.startsWith('--excludeDependencies=')) {
       const raw = a.slice('--excludeDependencies='.length)
+      // An empty value is genuinely ambiguous — "drop every edge" (the
+      // bare flag) and "drop none" (an empty list) are equally defensible
+      // readings, and silently picking either does the opposite of what
+      // half the callers mean. Reject and name both explicit forms; the
+      // sibling value flags (--retry=, --timeout=, --memory=, --cache-dir=)
+      // reject an empty `=` value the same way.
+      if (raw === '') {
+        return {
+          ...out,
+          error: `--excludeDependencies= needs a value — pass bare --excludeDependencies to drop every dependsOn edge, or omit the flag to keep them`,
+        }
+      }
       out.excludeDependencies = raw
         .split(',')
         .map((s) => s.trim())
@@ -171,16 +192,26 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     } 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` }
-      const n = Number(v)
-      if (v === '' || !Number.isInteger(n) || n < 0) {
+      const n = parseDecimalInt(v)
+      if (n === null) {
         return { ...out, error: `--retry must be a non-negative integer, got: ${v}` }
       }
       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` }
-      const n = Number(v)
-      if (v === '' || !Number.isInteger(n) || n <= 0) {
+      const n = parseDecimalInt(v)
+      if (n !== null && n > MAX_TIMEOUT_MS) {
+        // Not "effectively no limit" — setTimeout reduces a delay past 2^31-1
+        // to 1 ms, so this would kill every task the moment it spawned.
+        return {
+          ...out,
+          error:
+            `--timeout ${n} exceeds the maximum timer delay (${MAX_TIMEOUT_MS} ms, ~24.8 days); ` +
+            `larger values are silently reduced to 1 ms. Omit --timeout for no limit.`,
+        }
+      }
+      if (n === null || n <= 0) {
         return { ...out, error: `--timeout must be a positive integer (ms), got: ${v}` }
       }
       out.timeout = n
@@ -208,32 +239,56 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
           error: `--verify must be determinism | inputs | fingerprint | all (or bare --verify), got: ${what}`,
         }
       }
-    } else if (a?.startsWith('--verify-allow=')) {
-      out.verifyAllow = a
-        .slice('--verify-allow='.length)
+    } else if (a === '--verify-allow' || a?.startsWith('--verify-allow=')) {
+      const v = a === '--verify-allow' ? before[++i] : a.slice('--verify-allow='.length)
+      if (v === undefined) return { ...out, error: `--verify-allow requires a value` }
+      // A flag-shaped space-form value is always a lost flag (task ids
+      // never start with `-`), never a value the user meant.
+      if (a === '--verify-allow' && v.startsWith('-')) {
+        return { ...out, error: `--verify-allow requires a value, got flag: ${v}` }
+      }
+      out.verifyAllow = v
         .split(',')
         .map((s) => s.trim())
         .filter((s) => s.length > 0)
-    } else if (a === '--output-logs') {
-      const v = before[++i]
-      if (v !== 'full' && v !== 'errors-only' && v !== 'none') {
-        return { ...out, error: `--output-logs must be full, errors-only, or none` }
+    } else if (a === '--output-logs' || a?.startsWith('--output-logs=')) {
+      const v = a === '--output-logs' ? before[++i] : a.slice('--output-logs='.length)
+      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` }
       }
       out.outputLogs = v
+    } else if (a === '--download' || a?.startsWith('--download=')) {
+      const v = a === '--download' ? before[++i] : a.slice('--download='.length)
+      if (v !== 'all' && v !== 'toplevel' && v !== 'none') {
+        return { ...out, error: `--download must be all, toplevel, or none` }
+      }
+      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` }
+      // 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}` }
+      }
       out.cacheDir = v
-    } else if (a === '--cache') {
-      const v = before[++i]
-      if (v === undefined) return { ...out, error: `${a} requires a value` }
-      try {
-        cachePolicy = parseCachePolicy(v, cachePolicy)
-      } catch (err) {
-        cacheSpecError = err instanceof Error ? err.message : String(err)
+    } 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` }
+      // 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
+      // empty flag list for a NAMED layer (`local:`) stays valid and
+      // means that layer off.
+      if (!v.split(',').some((seg) => seg.trim().length > 0)) {
+        return {
+          ...out,
+          error: `--cache needs a spec like local:r, local:rw, remote:, or local:,remote:rw — pass --no-cache to disable every axis`,
+        }
       }
-    } else if (a?.startsWith('--cache=')) {
-      const v = a.slice('--cache='.length)
       try {
         cachePolicy = parseCachePolicy(v, cachePolicy)
       } catch (err) {
@@ -252,11 +307,11 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
         return { ...out, error: `--continue must be never, deps-ok, or always` }
       }
       out.continueMode = v
-    } else if (a === '--verbosity') {
-      const v = before[++i]
-      if (v === undefined) return { ...out, error: `${a} requires a value` }
-      const n = Number(v)
-      if (!Number.isInteger(n) || n < 0) return { ...out, error: `invalid verbosity: ${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` }
+      const n = parseDecimalInt(v)
+      if (n === null) return { ...out, error: `invalid verbosity: ${v}` }
       out.verbosity = n
     } else if (a === '--dry') {
       out.dry = 'text'
@@ -277,7 +332,11 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     } else if (a === '--profile') {
       out.profile = 'profile.json'
     } else if (a?.startsWith('--profile=')) {
-      out.profile = a.slice('--profile='.length)
+      // An optional-value flag: an empty `=` means "no value given", so it
+      // takes the same documented default as the bare form. Resolving ''
+      // against cwd would name the cwd DIRECTORY and die with EISDIR after
+      // the whole run — and `--summarize=` already degrades to its default.
+      out.profile = a.slice('--profile='.length) || 'profile.json'
     } else if (a === '--affected') {
       out.affected = ''
     } else if (a?.startsWith('--affected=')) {
@@ -289,6 +348,16 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       const eq = raw.indexOf('=')
       if (eq <= 0) return { ...out, error: `invalid --tag (expected k=v): ${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)
+      if (v === undefined || v === '') return { ...out, error: `--report-file requires a path` }
+      // Same reasoning as --cache-dir: a path is an arbitrary string, so
+      // 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}` }
+      }
+      out.reportFile = v
     } else if (a === '--report') {
       out.report = 'markdown'
     } else if (a?.startsWith('--report=')) {
@@ -298,7 +367,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       }
       out.report = fmt
     } else if (a !== undefined && a.startsWith('-')) {
-      return { ...out, error: `unknown flag: ${a}` }
+      return { ...out, error: `unknown flag: ${a}${didYouMeanFlag(a)}` }
     } else if (a !== undefined) {
       out.tasks.push(a)
     }
@@ -351,9 +420,11 @@ export function detectFlow(
  * honor the same selection semantics (cwd / `--all` / `--filter` /
  * `--affected` / anchored positionals).
  *
- * Returns either the resolved options or an error message string. The
- * caller is responsible for prefixing the message with its subcommand
- * name (`vx run: <msg>` / `vx watch: <msg>`) and exiting non-zero.
+ * 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`).
@@ -362,7 +433,7 @@ export async function resolveRunOptions(
   parsed: RunArgs,
   cwd: string,
   tasks: readonly string[],
-): Promise<RunOptions | { error: string }> {
+): Promise<RunOptions | { error: string } | { nothingSelected: string }> {
   for (const t of tasks) {
     const idx = t.indexOf('#')
     if (idx >= 0) {
@@ -387,13 +458,25 @@ export async function resolveRunOptions(
   // Project scope applies to bare task names only. Anchored entries
   // (pkg#task) resolve directly to their own project regardless.
   const bareTasks = tasks.filter((t) => !t.includes('#'))
+  const anchoredTasks = tasks.filter((t) => t.includes('#'))
   let projects: string[] | undefined
   if (bareTasks.length === 0) {
     projects = undefined
   } else if (filterStrings.length > 0) {
     const resolved = await resolveFilters(cwd, filterStrings)
-    if (resolved.error) return { error: resolved.error }
-    projects = resolved.names
+    if ('error' in resolved) return { error: resolved.error }
+    if ('empty' in resolved) {
+      // "Nothing changed" is a clean exit for the BARE tasks the filter
+      // scopes — but it must never cancel an explicitly anchored
+      // `pkg#task`, which resolves to its own project regardless of
+      // scope. An empty project list keeps the bare tasks unselected
+      // while the anchored ones still run.
+      if (anchoredTasks.length === 0) return { nothingSelected: resolved.empty }
+      process.stderr.write(`vx: ${resolved.empty} — running ${anchoredTasks.join(', ')} only\n`)
+      projects = []
+    } else {
+      projects = resolved.names
+    }
   } else if (parsed.all) {
     projects = undefined
   } else {
@@ -414,6 +497,7 @@ export async function resolveRunOptions(
     flow: detectFlow(parsed),
     ...(parsed.frozen ? { frozen: true } : {}),
     ...(parsed.outputLogs !== undefined ? { outputLogs: parsed.outputLogs } : {}),
+    ...(parsed.download !== undefined ? { download: parsed.download } : {}),
     ...(parsed.continueMode !== undefined ? { continueMode: parsed.continueMode } : {}),
     forwardArgs: parsed.forwardArgs,
   }
@@ -471,6 +555,10 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx run: ${resolved.error}\n`)
     return 1
   }
+  if ('nothingSelected' in resolved) {
+    process.stderr.write(`vx run: ${resolved.nothingSelected}\n`)
+    return 0
+  }
   const opts = resolved
   // The raw invocation, recorded on the `invocations` row so dashboards
   // show what was actually run. `args` is everything after `run`.
@@ -480,6 +568,12 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // graph + probe the cache; the difference is just the formatter.
   if (parsed.dry !== undefined || parsed.graph !== undefined) {
     const plan = await planRun(opts)
+    if (plan.unresolvedTasks !== undefined && plan.unresolvedTasks.length > 0) {
+      process.stderr.write(
+        `vx run: no projects declare task(s): ${plan.unresolvedTasks.join(', ')}.\n`,
+      )
+      return 1
+    }
     if (plan.tasks.length === 0) {
       process.stderr.write(`vx run: no projects declare task(s): ${tasks.join(', ')}.\n`)
       return 1
@@ -499,35 +593,93 @@ export async function runCmd(args: readonly string[]): Promise<number> {
     return 0
   }
 
-  // Resolve where this run executes. A plugin's `backend` capability wins
-  // first (e.g. a backend plugin routes to a local-or-hosted service);
-  // otherwise core's default is pure in-process. Core names no service —
-  // delegation is entirely a plugin concern.
-  const request = optionsToRequest(opts)
-  const root = await findWorkspaceRoot(cwd)
-  const workspaceConfig = await loadWorkspaceConfig(root)
-  const plugins = (workspaceConfig?.plugins ?? []) as readonly VxPlugin[]
-  const backend = await resolvePluginBackend(
-    plugins,
-    {
-      workspaceRoot: root,
-      cacheDir: resolveCacheDir(root, workspaceConfig),
-      warn: (m) => process.stderr.write(`${m}\n`),
-      request,
-    },
-    () => Promise.resolve(localBackend()),
-  )
-  const result = await backend.run(request)
+  // A run executes in THIS process, always. Where an individual task's
+  // command runs is the `executor` capability's business (per task, with
+  // the scheduler, cache, retries and telemetry unchanged above it); there
+  // is no whole-run delegation seam to consult.
+  const summary = await runOrchestrator(opts)
+  const result: RunResult = { ok: summary.ok, outcomes: summary.outcomes.map(projectOutcome) }
   if (parsed.verbosity > 0) printSummary(result)
-  // Report generation is post-run, gated on the flag — zero cost when
-  // absent. Goes to stdout (NOT the status logger) so it stays
-  // machine-clean for `vx run ci --report=markdown >> $GITHUB_STEP_SUMMARY`.
-  if (parsed.report === 'markdown') {
-    process.stdout.write(formatRunReportMarkdown(result))
+  // Report generation is post-run, gated on the flags — zero cost when
+  // both are absent. Rendered once, however many sinks asked for it.
+  if (parsed.report === 'markdown' || parsed.reportFile !== undefined) {
+    const md = formatRunReportMarkdown(result)
+    // `--report` writes stdout. The report ITSELF is machine-clean, but
+    // stdout is not vx's alone — the status logger writes there too, so
+    // `--report=markdown >> "$GITHUB_STEP_SUMMARY"` captures every frame,
+    // meter bar and `::group::` command above the table. `--report-file`
+    // is the redirect-free form.
+    if (parsed.report === 'markdown') process.stdout.write(md)
+    if (parsed.reportFile !== undefined) {
+      const target = path.resolve(cwd, parsed.reportFile)
+      try {
+        // APPEND, not overwrite: the flag exists for `$GITHUB_STEP_SUMMARY`,
+        // which GitHub documents as append-only and which other steps in the
+        // same job also write to. Truncating it would silently destroy their
+        // content, and would make replacing the documented `>>` recipe a
+        // behaviour change rather than a drop-in.
+        await appendFile(target, md)
+      } catch (err) {
+        // Same contract as --summarize / --profile: the run already
+        // happened, so a write failure is reported, not fatal.
+        const message = err instanceof Error ? err.message : String(err)
+        process.stderr.write(`vx: failed to write report to ${target}: ${message}\n`)
+      }
+    }
   }
   return result.ok ? 0 : 1
 }
 
+/**
+ * Which projects declare a `cache.inputs.workspaceFiles` glob matching one of
+ * `orphans` (workspace-relative paths belonging to no project).
+ *
+ * Reached ONLY when a changed path belongs to no project, so a run whose every
+ * change is inside a project never gets here — the scoped-config-loading win
+ * is untouched for the common case.
+ *
+ * `vx-lock.json` FIRST when present: it holds the resolved configs, so CI —
+ * where `--affected` matters most and the lock is committed — answers with
+ * zero evaluation. Without a lock this evaluates configs, which is the honest
+ * cost of the question: nothing cheaper can know which globs a program
+ * declares. A config that fails to load is skipped rather than failing the
+ * run, matching the deliberate Turbo-like rule that a broken out-of-scope
+ * config does not fail a scoped run.
+ */
+async function workspaceGlobOwners(
+  root: string,
+  projects: readonly ProjectMeta[],
+  orphans: readonly string[],
+): Promise<string[]> {
+  const lock = await readLockfile(root)
+  const owners: string[] = []
+  const declaresMatch = (config: ProjectConfig): boolean => {
+    for (const task of Object.values(config.tasks ?? {})) {
+      const globs = task.cache?.inputs?.workspaceFiles
+      if (globs === undefined) continue
+      if (orphans.some((rel) => workspaceGlobsMatch(globs, rel))) return true
+    }
+    return false
+  }
+  await Promise.all(
+    projects.map(async (meta) => {
+      const locked = lock?.projects[meta.name]
+      if (locked !== undefined) {
+        if (declaresMatch(locked.config)) owners.push(meta.name)
+        return
+      }
+      if (meta.configPath === null || meta.configPath === '') return
+      try {
+        if (declaresMatch(await loadProjectConfig(meta.configPath))) owners.push(meta.name)
+      } catch {
+        // A config that will not load cannot be shown to declare a matching
+        // glob; surfacing it here would fail a run the loader itself tolerates.
+      }
+    }),
+  )
+  return owners
+}
+
 async function loadWorkspaceProjects(cwd: string): Promise<ProjectMeta[]> {
   const root = await findWorkspaceRoot(cwd)
   const ws = await loadWorkspace(root)
@@ -546,10 +698,9 @@ async function findCwdProject(cwd: string): Promise<string | null> {
   return best?.name ?? null
 }
 
-async function resolveFilters(
-  cwd: string,
-  raw: string[],
-): Promise<{ names?: string[]; error?: string }> {
+type FilterResolution = { names: string[] } | { error: string } | { empty: string }
+
+async function resolveFilters(cwd: string, raw: string[]): Promise<FilterResolution> {
   const root = await findWorkspaceRoot(cwd)
   const projects = await loadWorkspaceProjects(cwd)
   const graph = buildPackageGraph(projects)
@@ -562,7 +713,12 @@ async function resolveFilters(
   for (const f of parsed) {
     if (f.gitSince === undefined) continue
     try {
-      const names = await affectedProjects({ workspaceRoot: root, since: f.gitSince, projects })
+      const names = await affectedProjects({
+        workspaceRoot: root,
+        since: f.gitSince,
+        projects,
+        workspaceGlobOwners: (orphans) => workspaceGlobOwners(root, projects, orphans),
+      })
       affectedByFilter.set(f, names)
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
@@ -570,8 +726,29 @@ async function resolveFilters(
     }
   }
 
-  const selected = applyFilters({ filters: parsed, projects, graph, affectedByFilter })
+  const selected = applyFilters({
+    filters: parsed,
+    projects,
+    graph,
+    affectedByFilter,
+    // A `[<since>]` selector matching nothing is the ordinary "nothing
+    // changed" outcome, reported below; only a name/path pattern that
+    // matched nothing is worth flagging as a probable typo.
+    onNoMatch: (f) => {
+      if (f.gitSince === undefined) {
+        process.stderr.write(`vx: filter "${f.raw}" matched no projects\n`)
+      }
+    },
+  })
   if (selected.size === 0) {
+    // "Nothing changed" is a legitimate outcome, not a typo — a docs-only
+    // commit must not red `vx run … --affected=origin/main`. Only report an
+    // error when the user named something concrete that failed to resolve.
+    const includes = parsed.filter((f) => !f.negate)
+    if (includes.length > 0 && includes.every((f) => f.gitSince !== undefined)) {
+      const refs = includes.map((f) => f.gitSince).join(', ')
+      return { empty: `nothing affected since ${refs}` }
+    }
     return { error: `no projects matched filter(s): ${raw.join(', ')}` }
   }
   return { names: [...selected].sort() }
@@ -681,3 +858,18 @@ function formatRow(o: OutcomeView): { task: string; status: string; duration: st
     duration: `${o.durationMs}ms`,
   }
 }
+
+/** `(did you mean --concurrency?)` for a flag within two edits of a documented one. */
+function didYouMeanFlag(flag: string): string {
+  const name = flag.replace(/=.*$/, '')
+  let best: string | undefined
+  let bestD = 3
+  for (const f of documentedFlags('run')) {
+    const d = editDistance(name, f)
+    if (d < bestD) {
+      bestD = d
+      best = f
+    }
+  }
+  return best === undefined || best === name ? '' : ` (did you mean ${best}?)`
+}

package/src/cli/upgrade.ts

@@ -1,6 +1,6 @@
 // `vx upgrade [tag]` — self-update the compiled binary in place.
-// Mirrors install.sh: download the release asset for this os/arch,
-// write next to the current executable, atomic rename over it.
+// Downloads the GitHub release asset for this os/arch, writes next to
+// the current executable, atomic rename over it.
 // Named `upgrade` (not `update`) per CLI convention: bun upgrade,
 // deno upgrade — "update" is what package managers do to indexes.
 
@@ -24,7 +24,7 @@ export function isBunfsPath(p: string): boolean {
  * `Bun.main` (and argv[1]) rather than `import.meta.path`: with
  * `--minify --bytecode` — vx's release build flags — `import.meta.path`
  * reports the ORIGINAL SOURCE path, not the bunfs path, so the old
- * check silently failed for every curl-installed binary and `vx
+ * check silently failed for every installed binary and `vx
  * upgrade` refused with "running from source". `Bun.main` stays the
  * bunfs path under every compile-flag combination.
  */
@@ -68,7 +68,7 @@ export async function replaceBinary(dest: string, url: string): Promise<void> {
     const msg = err instanceof Error ? err.message : String(err)
     throw new UserError(
       `vx upgrade: could not replace ${dest} (${msg}) — ` +
-        `check permissions, or reinstall via install.sh with VX_INSTALL_DIR set`,
+        `check permissions, or reinstall with npm install -g @vzn/vx`,
     )
   }
 }
@@ -82,8 +82,9 @@ export async function upgradeCmd(args: readonly string[]): Promise<number> {
   }
   if (!isCompiledBinary()) {
     throw new UserError(
-      'vx upgrade only works for the compiled binary (install.sh). ' +
-        'You are running from source — use git pull instead.',
+      'vx upgrade only works for the compiled binary. ' +
+        'You are running from source — use git pull instead. ' +
+        '(npm installs update with: npm install -g @vzn/vx@latest)',
     )
   }
   const asset = assetName()