@vzn/vx 0.0.18 → 0.0.21

package/src/cli/run.ts

@@ -1,34 +1,21 @@
-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,
-  buildPackageGraph,
-  defaultAffectedBase,
-  findWorkspaceRoot,
-  listProjects,
-  loadProjectConfig,
-  loadWorkspace,
-  parseFilter,
-  readLockfile,
-  workspaceGlobsMatch,
-  type ProjectMeta,
-} from '../workspace/index.js'
+import { documentedFlags, seeHelp } from './help.js'
+import { defaultAffectedBase, findWorkspaceRoot } from '../workspace/index.js'
 import {
   planRun,
   formatRunReportMarkdown,
+  outcomeLabel,
   projectOutcome,
   run as runOrchestrator,
   type OutcomeView,
   type RunOptions,
   type RunResult,
 } 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 { MAX_TIMEOUT_MS, parseDecimalInt, parseSize, editDistance } from '../util/index.js'
+import { findCwdProject, pickTask, resolveFilters } from './select.js'
+import { MAX_TIMEOUT_MS, parseDecimalInt, nearest, machineParallelism } from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
 
 export interface RunArgs {
@@ -55,6 +42,8 @@ export interface RunArgs {
    * / `--force` in precedence order. Defaults to all-on.
    */
   cache: CachePolicy
+  /** `--cache` named a remote axis (`remote:r`, `:w`, `:rw`): the run says so when no plugin serves one. */
+  remoteRequested?: boolean
   /** `--cache-dir <path>`: override the cache directory (cwd-relative). */
   cacheDir: string | undefined
   frozen: boolean
@@ -69,23 +58,6 @@ export interface RunArgs {
    * env and workspace `timeout` defaults. Undefined when not passed.
    */
   timeout: number | undefined
-  /**
-   * `--memory <size>` / `--memory=<size>`: memory budget (resolved to
-   * bytes) for `exec.resources.memory` reservations. Defaults to
-   * os.totalmem() when not passed — pass it in cgroup-limited containers.
-   */
-  memory: number | undefined
-  /**
-   * `--verify[=determinism|inputs|fingerprint|all]`: cache-correctness
-   * verification. Undefined when not passed. `determinism` re-runs and
-   * content-compares outputs; `inputs` sandboxes with the declared-input
-   * baseline and flags undeclared reads; `fingerprint` ships output-tree
-   * fingerprints for the cross-machine diff (no re-run; the determinism
-   * modes set it too, for free). `allow` (from `--verify-allow=<pkg#task>,…`)
-   * exempts tasks from failing the run on a divergence.
-   */
-  verify: { determinism: boolean; inputs: boolean; fingerprint: boolean } | undefined
-  verifyAllow: string[]
   outputLogs?: 'full' | 'errors-only' | 'none' | 'hash-only'
   download?: 'all' | 'toplevel' | 'none'
   forwardArgs: string[]
@@ -113,6 +85,30 @@ export interface RunArgs {
   error?: string
 }
 
+// The camelCase spelling the flag shipped with (retired 2026-09-10): two
+// edits past the suggester's reach, so it is named outright. A regex, not a
+// quoted literal, so the doc-drift test does not count it as an accepted flag.
+const RETIRED_EXCLUDE_DEPENDENCIES = /^--excludeDependencies(=|$)/
+
+/**
+ * `--concurrency <n>` is a positive decimal integer, or `<n>%` of the
+ * cores this process may use (`50%` on eight cores is 4, never below 1;
+ * over 100% is allowed for I/O-bound work; a container's CPU quota caps
+ * the count the way it caps the default). The percent form resolves
+ * here, at parse time, so the run sees one number and the summary says
+ * what it ran with.
+ */
+export function parseConcurrency(v: string, cpus = machineParallelism()): number | null {
+  const pct = /^(\d+)%$/.exec(v)
+  if (pct) {
+    const n = parseDecimalInt(pct[1]!)
+    if (n === null || n < 1) return null
+    return Math.max(1, Math.round((Math.max(1, cpus) * n) / 100))
+  }
+  const n = parseDecimalInt(v)
+  return n === null || n < 1 ? null : n
+}
+
 export function parseRunArgs(args: readonly string[]): RunArgs {
   const out: RunArgs = {
     tasks: [],
@@ -125,9 +121,6 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     frozen: false,
     retries: undefined,
     timeout: undefined,
-    memory: undefined,
-    verify: undefined,
-    verifyAllow: [],
     forwardArgs: [],
     verbosity: 0,
     dry: undefined,
@@ -162,25 +155,30 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     } 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}` }
+      const n = parseConcurrency(v)
+      if (n === null) return { ...out, error: `invalid concurrency: ${v}` }
       out.concurrency = n
     } else if (a === '--all') {
       out.all = true
-    } else if (a === '--excludeDependencies') {
+    } else if (RETIRED_EXCLUDE_DEPENDENCIES.test(a ?? '')) {
+      return {
+        ...out,
+        error: `unknown flag: ${a} (the flag is --exclude-dependencies)${seeHelp('run')}`,
+      }
+    } else if (a === '--exclude-dependencies') {
       out.excludeDependencies = 'all'
-    } else if (a?.startsWith('--excludeDependencies=')) {
-      const raw = a.slice('--excludeDependencies='.length)
+    } else if (a?.startsWith('--exclude-dependencies=')) {
+      const raw = a.slice('--exclude-dependencies='.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=)
+      // sibling value flags (--retry=, --timeout=, --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`,
+          error: `--exclude-dependencies= needs a value — pass bare --exclude-dependencies to drop every dependsOn edge, or omit the flag to keep them`,
         }
       }
       out.excludeDependencies = raw
@@ -215,42 +213,6 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
         return { ...out, error: `--timeout must be a positive integer (ms), got: ${v}` }
       }
       out.timeout = n
-    } else if (a === '--memory' || a?.startsWith('--memory=')) {
-      const v = a === '--memory' ? before[++i] : a.slice('--memory='.length)
-      if (v === undefined || v === '') return { ...out, error: `--memory requires a value` }
-      const bytes = parseSize(v)
-      if (bytes === null || bytes <= 0) {
-        return { ...out, error: `--memory must be a size like 8GB or 512MB, got: ${v}` }
-      }
-      out.memory = bytes
-    } else if (a === '--verify' || a?.startsWith('--verify=')) {
-      const what = a === '--verify' ? 'determinism' : a.slice('--verify='.length)
-      if (what === 'determinism') {
-        out.verify = { determinism: true, inputs: false, fingerprint: true }
-      } else if (what === 'inputs') {
-        out.verify = { determinism: false, inputs: true, fingerprint: false }
-      } else if (what === 'fingerprint') {
-        out.verify = { determinism: false, inputs: false, fingerprint: true }
-      } else if (what === 'all') {
-        out.verify = { determinism: true, inputs: true, fingerprint: true }
-      } else {
-        return {
-          ...out,
-          error: `--verify must be determinism | inputs | fingerprint | all (or bare --verify), got: ${what}`,
-        }
-      }
-    } 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' || 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') {
@@ -291,6 +253,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       }
       try {
         cachePolicy = parseCachePolicy(v, cachePolicy)
+        if (/remote:[rw]/.test(v)) out.remoteRequested = true
       } catch (err) {
         cacheSpecError = err instanceof Error ? err.message : String(err)
       }
@@ -299,7 +262,14 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     } else if (a === '--force') {
       forceFlag = true
     } else if (a === '--continue') {
-      // Bare --continue = 'always' (the Turbo convention).
+      // Bare --continue = 'always' (the Turbo convention). Its mode comes
+      // with '=' only: `--continue never` would read `never` as a TASK, and
+      // the run would then say "No projects declare task(s): never" — true,
+      // and no help at all.
+      const next = before[i + 1]
+      if (next === 'never' || next === 'deps-ok' || next === 'always') {
+        return { ...out, error: `--continue takes its mode with '=': --continue=${next}` }
+      }
       out.continueMode = 'always'
     } else if (a?.startsWith('--continue=')) {
       const v = a.slice('--continue='.length)
@@ -367,7 +337,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       }
       out.report = fmt
     } else if (a !== undefined && a.startsWith('-')) {
-      return { ...out, error: `unknown flag: ${a}${didYouMeanFlag(a)}` }
+      return { ...out, error: `unknown flag: ${a}${didYouMeanFlag(a)}${seeHelp('run')}` }
     } else if (a !== undefined) {
       out.tasks.push(a)
     }
@@ -460,10 +430,14 @@ export async function resolveRunOptions(
   const bareTasks = tasks.filter((t) => !t.includes('#'))
   const anchoredTasks = tasks.filter((t) => t.includes('#'))
   let projects: string[] | undefined
+  let staged: RunOptions['staged']
   if (bareTasks.length === 0) {
     projects = undefined
   } else if (filterStrings.length > 0) {
-    const resolved = await resolveFilters(cwd, filterStrings)
+    const resolved = await resolveFilters(cwd, filterStrings, {
+      ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+      ...(parsed.frozen ? { frozen: true } : {}),
+    })
     if ('error' in resolved) return { error: resolved.error }
     if ('empty' in resolved) {
       // "Nothing changed" is a clean exit for the BARE tasks the filter
@@ -476,6 +450,9 @@ export async function resolveRunOptions(
       projects = []
     } else {
       projects = resolved.names
+      // The graph walk staged every config; the run reuses those entries
+      // instead of evaluating and staging them a second time.
+      staged = resolved.staged
     }
   } else if (parsed.all) {
     projects = undefined
@@ -494,6 +471,7 @@ export async function resolveRunOptions(
     cwd,
     tasks: [...tasks],
     cache: parsed.cache,
+    ...(parsed.remoteRequested ? { remoteRequested: true } : {}),
     flow: detectFlow(parsed),
     ...(parsed.frozen ? { frozen: true } : {}),
     ...(parsed.outputLogs !== undefined ? { outputLogs: parsed.outputLogs } : {}),
@@ -507,18 +485,10 @@ export async function resolveRunOptions(
     opts.excludeDependencies = parsed.excludeDependencies
   }
   if (projects !== undefined) opts.projects = projects
+  if (staged !== undefined) opts.staged = staged
   if (parsed.retries !== undefined) opts.retries = parsed.retries
   if (parsed.timeout !== undefined) opts.timeout = parsed.timeout
-  if (parsed.memory !== undefined) opts.memory = parsed.memory
   if (parsed.cacheDir !== undefined) opts.cacheDir = parsed.cacheDir
-  if (parsed.verify !== undefined) {
-    opts.verify = {
-      determinism: parsed.verify.determinism,
-      inputs: parsed.verify.inputs,
-      fingerprint: parsed.verify.fingerprint,
-      allow: new Set(parsed.verifyAllow),
-    }
-  }
   if (parsed.concurrency !== undefined) opts.concurrency = parsed.concurrency
   if (parsed.summarize !== undefined) opts.summarize = parsed.summarize
   if (parsed.profile !== undefined) opts.profile = parsed.profile
@@ -545,7 +515,14 @@ export async function runCmd(args: readonly string[]): Promise<number> {
       process.stderr.write(`vx run: missing task name (stdin is not a TTY)\n`)
       return 1
     }
-    const picked = await pickTask(cwd)
+    const picked = await pickTask(
+      cwd,
+      {},
+      {
+        ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+        ...(parsed.frozen ? { frozen: true } : {}),
+      },
+    )
     if (!picked) return 1
     tasks = [`${picked.project}#${picked.task}`]
   }
@@ -630,182 +607,6 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   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)
-  return await listProjects(ws)
-}
-
-async function findCwdProject(cwd: string): Promise<string | null> {
-  const projects = await loadWorkspaceProjects(cwd)
-  const abs = path.resolve(cwd)
-  let best: ProjectMeta | null = null
-  for (const p of projects) {
-    if (abs === p.dir || abs.startsWith(p.dir + path.sep)) {
-      if (!best || p.dir.length > best.dir.length) best = p
-    }
-  }
-  return best?.name ?? null
-}
-
-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)
-  const parsed = raw.map((r) => parseFilter(r, root))
-
-  // Resolve every `[<since>]` filter against git before the pure
-  // applyFilters pass runs. One spawn per distinct ref — usually
-  // there's only one anyway.
-  const affectedByFilter = new Map<(typeof parsed)[number], Set<string>>()
-  for (const f of parsed) {
-    if (f.gitSince === undefined) continue
-    try {
-      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)
-      return { error: msg }
-    }
-  }
-
-  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() }
-}
-
-interface PickedTask {
-  project: string
-  task: string
-  description?: string
-}
-
-export async function pickTask(
-  cwd: string,
-  io: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream } = {},
-): Promise<PickedTask | null> {
-  const projects = await loadWorkspaceProjects(cwd)
-  const entries: PickedTask[] = []
-  for (const meta of projects) {
-    if (!meta.configPath) continue
-    const config = await loadProjectConfig(meta.configPath)
-    const taskNames = Object.keys(config.tasks ?? {}).sort()
-    for (const t of taskNames) {
-      const desc = config.tasks?.[t]?.description
-      entries.push({ project: meta.name, task: t, ...(desc ? { description: desc } : {}) })
-    }
-  }
-  if (entries.length === 0) {
-    process.stderr.write(`vx run: no tasks declared in any project\n`)
-    return null
-  }
-  const out = io.output ?? process.stdout
-  const numW = String(entries.length).length
-  const idW = Math.max(...entries.map((e) => `${e.project}#${e.task}`.length))
-  out.write('Tasks:\n')
-  entries.forEach((e, i) => {
-    const n = String(i + 1).padStart(numW, ' ')
-    const id = `${e.project}#${e.task}`.padEnd(idW)
-    const desc = e.description ? `  ${e.description}` : ''
-    out.write(`  ${n}. ${id}${desc}\n`)
-  })
-  const rl = readline.createInterface({
-    input: io.input ?? process.stdin,
-    output: io.output ?? process.stdout,
-  })
-  try {
-    const answer = (await rl.question(`Pick a task [1-${entries.length}]: `)).trim()
-    const n = Number(answer)
-    if (!Number.isInteger(n) || n < 1 || n > entries.length) {
-      process.stderr.write(`vx run: invalid selection: ${answer}\n`)
-      return null
-    }
-    return entries[n - 1] ?? null
-  } finally {
-    rl.close()
-  }
-}
-
 function printSummary(summary: RunResult): void {
   const rows = summary.outcomes.map((o) => formatRow(o))
   if (rows.length === 0) return
@@ -835,41 +636,22 @@ function printSummary(summary: RunResult): void {
 }
 
 function formatRow(o: OutcomeView): { task: string; status: string; duration: string } {
-  // Same outcome vocabulary as the framed blocks + summary:
-  // executed / restored-local / restored-remote / up-to-date /
-  // failed / skipped.
-  const status =
-    o.status === 'cache-hit'
-      ? o.restored === false
-        ? 'up-to-date'
-        : 'restored-local'
-      : o.status === 'cache-hit-remote'
-        ? o.restored === false
-          ? 'up-to-date'
-          : 'restored-remote'
-        : o.status === 'success'
-          ? 'executed'
-          : o.status === 'failed'
-            ? `failed (exit ${o.exitCode})`
-            : o.status
-  return {
-    task: o.taskId,
-    status,
-    duration: `${o.durationMs}ms`,
-  }
+  return { task: o.taskId, status: outcomeLabel(o), 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}?)`
+  const flags = documentedFlags('run')
+  // The usual two edits; a third only between flags that share their
+  // first five characters, so `--retries` reaches `--retry` (the i/y)
+  // while `--zzz` does not reach `--all` — a plain three-edit budget did.
+  const best =
+    nearest(name, flags) ??
+    nearest(
+      name,
+      flags.filter((f) => f.slice(0, 5) === name.slice(0, 5)),
+      3,
+    )
+  return best === undefined ? '' : ` (did you mean ${best}?)`
 }