@vzn/vx 0.0.18 → 0.0.21

package/src/cli/select.ts

@@ -0,0 +1,332 @@
+// What a run is asked to run: the projects a `--filter` selects, the
+// ones `--affected` touches (with the orphan-path owners), the project the
+// cwd sits in, and the interactive picker. Every read of the workspace
+// here goes through the staged load, so the answer is the run's.
+
+import readline from 'node:readline/promises'
+import path from 'node:path'
+import {
+  affectedProjects,
+  applyFilters,
+  buildPackageGraph,
+  findWorkspaceRoot,
+  type FingerprintClaims,
+  FROZEN_WITHOUT_LOCK,
+  listProjects,
+  loadProjectConfig,
+  loadWorkspace,
+  parseFilter,
+  type ProjectMeta,
+  readLockfile,
+  workspaceGlobsMatch,
+} from '../workspace/index.js'
+import type { ProjectConfig } from '../config.js'
+import type { ProjectEntry } from '../workspace/index.js'
+import { parseDependencySpec } from '../graph/index.js'
+import { nearest, UserError } from '../util/index.js'
+import { claimedAffected, fingerprintClaims } from '../orchestrator/index.js'
+import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './workspace-config.js'
+
+/**
+ * The projects whose tasks declare a `cache.inputs.workspaceFiles` glob
+ * matching an ORPHAN changed path (one no project owns): `--affected`
+ * selects them, since the glob is that task's input. Through the run
+ * path's staged load, so a glob a `project` plugin gave a config-less
+ * package counts; evaluated live as a default run does, or read from the
+ * lock as a `--frozen` run does. A load that fails drops to the config files that
+ * do load, one by one — a broken out-of-scope config does not fail a
+ * scoped run, and must not fail its selection either.
+ */
+export async function workspaceGlobOwners(
+  root: string,
+  projects: readonly ProjectMeta[],
+  orphans: readonly string[],
+  load: CliLoadOptions = {},
+  stagedLoad: () => Promise<ReadonlyMap<string, ProjectEntry>> = () =>
+    loadCliProjects(root, projects, 'all', load),
+): Promise<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
+  }
+  // A frozen run with no lock is refused here, before the tolerant sweep
+  // below could answer "nothing affected" and exit 0 without ever reaching
+  // the run's own refusal.
+  if (load.frozen === true && (await readLockfile(root)) === null) {
+    throw new UserError(FROZEN_WITHOUT_LOCK)
+  }
+  try {
+    const staged = await stagedLoad()
+    return [...staged.values()].filter((p) => declaresMatch(p.config)).map((p) => p.name)
+  } catch {
+    // Fall through to the per-file sweep.
+  }
+  const owners: string[] = []
+  await Promise.all(
+    projects.map(async (meta) => {
+      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
+}
+
+/**
+ * The fingerprint files the workspace's plugins claim, with each claimant
+ * asked through the same host the run uses — so a bad answer is refused by
+ * the plugin's name here exactly as it would be at key time.
+ */
+async function workspaceFingerprintClaims(
+  root: string,
+  projects: readonly ProjectMeta[],
+  load: CliLoadOptions,
+): Promise<FingerprintClaims> {
+  const ws = await loadCliWorkspace(root)
+  const claims = fingerprintClaims(ws.plugins)
+  const ctx = {
+    workspaceRoot: root,
+    cacheDir: load.cacheDir ?? ws.cacheDir,
+    warn: (m: string) => process.stderr.write(`${m}\n`),
+    projects: projects.map((p) => ({ name: p.name, dir: p.dir })),
+  }
+  return {
+    files: new Set(claims.keys()),
+    affected: (change) => claimedAffected(claims.get(change.file)!, change, ctx),
+  }
+}
+
+export async function loadWorkspaceProjects(cwd: string): Promise<ProjectMeta[]> {
+  const root = await findWorkspaceRoot(cwd)
+  const ws = await loadWorkspace(root)
+  return await listProjects(ws)
+}
+
+export 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
+}
+
+export type FilterResolution =
+  | {
+      names: string[]
+      /** The staged load the graph walk needed, for the run to reuse (`RunOptions.staged`). */
+      staged?: ReadonlyMap<string, ProjectEntry>
+    }
+  | { error: string }
+  | { empty: string }
+
+/**
+ * The cross-project `dependsOn` edges the configs declare, project → the
+ * projects it names (`dependsOn: ['app#build']` makes `app` a dependency
+ * of the declaring project). Read from the staged load — the same configs
+ * the run will use — only when a filter walks the graph (`...`, `^...`).
+ * A spec the loader will reject is skipped here; the run reports it.
+ */
+export async function taskEdges(
+  root: string,
+  projects: readonly ProjectMeta[],
+  load: CliLoadOptions,
+): Promise<{ edges: Map<string, string[]>; staged: Map<string, ProjectEntry> }> {
+  const staged = await loadCliProjects(root, projects, 'all', load)
+  return { edges: taskEdgesFrom(staged), staged }
+}
+
+/** The same edges, read from a load the caller already has. */
+export function taskEdgesFrom(staged: ReadonlyMap<string, ProjectEntry>): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  for (const p of staged.values()) {
+    const targets = new Set<string>()
+    for (const task of Object.values(p.config.tasks ?? {})) {
+      for (const raw of task.dependsOn ?? []) {
+        let spec
+        try {
+          spec = parseDependencySpec(raw)
+        } catch {
+          continue
+        }
+        if (spec.kind === 'cross' && !spec.negated && spec.project !== p.name) {
+          targets.add(spec.project)
+        }
+      }
+    }
+    if (targets.size > 0) out.set(p.name, [...targets].sort())
+  }
+  return out
+}
+
+export async function resolveFilters(
+  cwd: string,
+  raw: string[],
+  load: CliLoadOptions = {},
+): Promise<FilterResolution> {
+  const root = await findWorkspaceRoot(cwd)
+  const projects = await loadWorkspaceProjects(cwd)
+  const parsed = raw.map((r) => parseFilter(r, root))
+  const walksGraph = parsed.some((f) => f.withDeps || f.withDependents || f.onlyDeps)
+  // Every reader of the staged configs in this pass — the `pkg#task`
+  // edge walk, the `workspaceFiles` owners of an orphan path — shares
+  // ONE load, and the run reuses it (`RunOptions.staged`): the `project`
+  // stage runs once per project per run.
+  let stagedPromise: Promise<Map<string, ProjectEntry>> | undefined
+  const stagedOnce = (): Promise<Map<string, ProjectEntry>> =>
+    (stagedPromise ??= loadCliProjects(root, projects, 'all', load))
+  let edges: Map<string, string[]> | undefined
+  if (walksGraph) {
+    try {
+      edges = taskEdgesFrom(await stagedOnce())
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(err) }
+    }
+  }
+  const graph = buildPackageGraph(projects, edges)
+
+  // 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, load, stagedOnce),
+        fingerprintClaims: () => workspaceFingerprintClaims(root, projects, load),
+      })
+      affectedByFilter.set(f, names)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      return { error: msg }
+    }
+  }
+
+  const unmatched: string[] = []
+  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) unmatched.push(f.raw)
+    },
+  })
+  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}` }
+    }
+    // One line, not a warning per pattern and then an error saying the same:
+    // the patterns are in the error, and the nearest project name is the
+    // hint a typo needs.
+    return {
+      error: `no projects matched filter(s): ${raw.join(', ')}${didYouMeanProject(unmatched, projects)}`,
+    }
+  }
+  // Something matched, so the run proceeds; a pattern that matched nothing
+  // alongside it is still worth a line — it is probably a typo.
+  for (const f of unmatched) process.stderr.write(`vx: filter "${f}" matched no projects\n`)
+  let staged: Map<string, ProjectEntry> | undefined
+  if (stagedPromise !== undefined) {
+    try {
+      staged = await stagedPromise
+    } catch {
+      // The owners walk fell through to its per-file sweep; the run loads for itself.
+      staged = undefined
+    }
+  }
+  return { names: [...selected].sort(), ...(staged !== undefined ? { staged } : {}) }
+}
+
+export interface PickedTask {
+  project: string
+  task: string
+  description?: string
+}
+
+export async function pickTask(
+  cwd: string,
+  io: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream } = {},
+  load: CliLoadOptions = {},
+): Promise<PickedTask | null> {
+  const projects = await loadWorkspaceProjects(cwd)
+  // The staged load: a task a `project` plugin gave a config-less package
+  // is on the menu, as it is in a run.
+  const staged = await loadCliProjects(await findWorkspaceRoot(cwd), projects, 'all', load)
+  const entries: PickedTask[] = []
+  for (const meta of projects) {
+    const config = staged.get(meta.name)?.config
+    if (config === undefined) continue
+    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()
+  }
+}
+
+/** `. Did you mean @acme/app?` for the first unmatched pattern within two edits of a project name. */
+function didYouMeanProject(
+  unmatched: readonly string[],
+  projects: Iterable<{ name: string }>,
+): string {
+  const names = [...projects].map((p) => p.name)
+  for (const pattern of unmatched) {
+    const best = nearest(pattern.replace(/^!|\.\.\.$|^\.\.\.|\^/g, ''), names)
+    if (best !== undefined) return `. Did you mean ${best}?`
+  }
+  return ''
+}

package/src/cli/show.ts

@@ -1,17 +1,20 @@
-// `vx show [target]` — introspect the workspace's LIVE resolved configs.
-// No target: one line per project. `<project>`: every task's resolved
-// config, evaluated with the same loader the run path uses (scoped to
-// that single project). `<pkg>#<task>`: one task. This is deliberately
-// NOT the lock — vx-lock.json is already the frozen JSON; `show` answers
-// "what would a live run see here, now".
+// `vx show [target]` — introspect the workspace's LIVE resolved configs:
+// what a run would see here, now. Configs load through the same path a
+// run uses (`loadProjects`): the plugin `config` and `project` stages
+// apply, so a package a plugin gives tasks to shows them. No target: one
+// line per project. `<project>`: every task's resolved config. `<pkg>#
+// <task>`: one task. `<task>`: that task in every project declaring it.
+// Deliberately NOT the lock — vx-lock.json is already the frozen JSON.
 
 import type { ProjectConfig, TaskConfig } from '../config.js'
-import { relPosix, UserError } from '../util/index.js'
+import { seeHelp } from './help.js'
+import { nearMatches, relPosix, UserError } from '../util/index.js'
+import { loadCliProjects } from './workspace-config.js'
 import {
   findWorkspaceRoot,
   listProjects,
-  loadProjectConfig,
   loadWorkspace,
+  type ProjectEntry,
   type ProjectMeta,
 } from '../workspace/index.js'
 
@@ -28,7 +31,7 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
     let format: string | undefined
     if (a === '--format') format = args[++i] ?? ''
     else if (a.startsWith('--format=')) format = a.slice('--format='.length)
-    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
+    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('show')}` }
     else if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     else out.target = a
 
@@ -50,55 +53,81 @@ export async function showCmd(args: readonly string[]): Promise<number> {
   }
   const root = await findWorkspaceRoot(process.cwd())
   const metas = await listProjects(await loadWorkspace(root))
+  const byName = new Map(metas.map((m) => [m.name, m]))
+
+  const hashAt = parsed.target?.indexOf('#') ?? -1
+  const projectName =
+    parsed.target === undefined
+      ? undefined
+      : hashAt === -1
+        ? parsed.target
+        : parsed.target.slice(0, hashAt)
+  const taskName = hashAt === -1 ? undefined : parsed.target!.slice(hashAt + 1)
+  if (taskName === '') throw new UserError(`missing task name after '#' in "${parsed.target}"`)
+  if (projectName !== undefined && (taskName !== undefined || byName.has(projectName))) {
+    if (!byName.has(projectName)) {
+      throw new UserError(
+        `unknown project: "${projectName}"${suggest(projectName, [...byName.keys()])}`,
+      )
+    }
+  }
+  // A bare name that is no project is a TASK: shown in every project that
+  // declares it, so the whole workspace loads.
+  const bareTask = projectName !== undefined && taskName === undefined && !byName.has(projectName)
+  const scope = projectName === undefined || bareTask ? 'all' : [projectName]
+
+  const projects = await loadCliProjects(root, metas, scope)
 
   if (parsed.target === undefined) {
-    process.stdout.write(await renderList(root, metas, parsed.format))
+    process.stdout.write(renderList(root, metas, projects, parsed.format))
     return 0
   }
 
-  const hashAt = parsed.target.indexOf('#')
-  const projectName = hashAt === -1 ? parsed.target : parsed.target.slice(0, hashAt)
-  const taskName = hashAt === -1 ? undefined : parsed.target.slice(hashAt + 1)
-  if (taskName === '') throw new UserError(`missing task name after '#' in "${parsed.target}"`)
-
-  const meta = metas.find((m) => m.name === projectName)
-  if (!meta) {
-    throw new UserError(
-      `unknown project: "${projectName}"${suggest(
-        projectName,
-        metas.map((m) => m.name),
-      )}`,
-    )
+  if (bareTask) {
+    const declaring = [...projects.values()].filter((p) => p.config.tasks?.[projectName!])
+    if (declaring.length === 0) {
+      const names = new Set<string>()
+      for (const p of projects.values())
+        for (const t of Object.keys(p.config.tasks ?? {})) names.add(t)
+      throw new UserError(
+        `unknown project or task: "${projectName}"${suggest(projectName!, [...byName.keys(), ...names])}`,
+      )
+    }
+    process.stdout.write(renderTaskAcross(root, declaring, projectName!, parsed.format))
+    return 0
   }
-  const config = meta.configPath === null ? null : await loadProjectConfig(meta.configPath)
+
+  const meta = byName.get(projectName!)!
+  const entry = projects.get(meta.name)
+  const config = entry?.config ?? null
   const dir = projectDir(root, meta)
 
   if (taskName === undefined) {
-    process.stdout.write(renderProject(meta.name, dir, config, parsed.format))
+    process.stdout.write(
+      renderProject(meta.name, dir, config, meta.configPath !== null, parsed.format),
+    )
     return 0
   }
 
   const task = config?.tasks?.[taskName]
   if (task === undefined) {
     throw new UserError(
-      `unknown task: "${meta.name}#${taskName}"${suggest(
-        taskName,
-        Object.keys(config?.tasks ?? {}),
-      )}`,
+      `unknown task: "${meta.name}#${taskName}"${suggest(taskName, Object.keys(config?.tasks ?? {}))}`,
     )
   }
   process.stdout.write(renderTask(meta.name, dir, taskName, task, parsed.format))
   return 0
 }
 
-/** Simple includes-match in both directions, case-insensitive. */
+/** Near misses by edit distance, plus partial names in either direction. */
 function suggest(query: string, candidates: readonly string[]): string {
   const q = query.toLowerCase()
-  const near = candidates.filter((c) => {
+  const near = new Set(nearMatches(query, candidates))
+  for (const c of candidates) {
     const n = c.toLowerCase()
-    return n.includes(q) || q.includes(n)
-  })
-  return near.length > 0 ? ` — did you mean ${near.join(', ')}?` : ''
+    if (n.includes(q) || q.includes(n)) near.add(c)
+  }
+  return near.size > 0 ? ` — did you mean ${[...near].join(', ')}?` : ''
 }
 
 function projectDir(root: string, meta: ProjectMeta): string {
@@ -106,22 +135,18 @@ function projectDir(root: string, meta: ProjectMeta): string {
   return rel === '' ? '.' : rel
 }
 
-async function renderList(
+function renderList(
   root: string,
   metas: readonly ProjectMeta[],
+  projects: ReadonlyMap<string, ProjectEntry>,
   format: 'pretty' | 'json',
-): Promise<string> {
-  const rows = await Promise.all(
-    metas.map(async (meta) => {
-      const config = meta.configPath === null ? null : await loadProjectConfig(meta.configPath)
-      return {
-        name: meta.name,
-        dir: projectDir(root, meta),
-        tasks: Object.keys(config?.tasks ?? {}),
-        configured: meta.configPath !== null,
-      }
-    }),
-  )
+): string {
+  const rows = metas.map((meta) => ({
+    name: meta.name,
+    dir: projectDir(root, meta),
+    tasks: Object.keys(projects.get(meta.name)?.config.tasks ?? {}),
+    configured: meta.configPath !== null,
+  }))
   if (format === 'json') {
     return `${JSON.stringify(
       rows.map(({ name, dir, tasks }) => ({ name, dir, tasks })),
@@ -132,9 +157,14 @@ async function renderList(
   const nameW = Math.max(...rows.map((r) => r.name.length))
   const dirW = Math.max(...rows.map((r) => r.dir.length))
   const lines = rows.map((r) => {
+    const n = r.tasks.length
+    const count = `${n} task${n === 1 ? '' : 's'}`
+    // A package with no config file only has tasks a plugin gave it.
     const tasks = r.configured
-      ? `${r.tasks.length} task${r.tasks.length === 1 ? '' : 's'}`
-      : '(no vx config)'
+      ? count
+      : n > 0
+        ? `${count} (no vx config; from plugins)`
+        : '(no vx config)'
     return `${r.name.padEnd(nameW)}  ${r.dir.padEnd(dirW)}  ${tasks}`
   })
   return `${lines.join('\n')}\n`
@@ -144,6 +174,7 @@ function renderProject(
   name: string,
   dir: string,
   config: ProjectConfig | null,
+  hasConfigFile: boolean,
   format: 'pretty' | 'json',
 ): string {
   if (format === 'json') {
@@ -152,9 +183,9 @@ function renderProject(
     return `${JSON.stringify(JSON.parse(JSON.stringify({ name, dir, config })), null, 2)}\n`
   }
   const head = `${name} — ${dir}`
-  if (config === null) return `${head}\n  (no vx config)\n`
-  const tasks = Object.entries(config.tasks ?? {})
-  if (tasks.length === 0) return `${head}\n  (no tasks declared)\n`
+  const tasks = Object.entries(config?.tasks ?? {})
+  if (tasks.length === 0)
+    return `${head}\n  ${hasConfigFile ? '(no tasks declared)' : '(no vx config)'}\n`
   const blocks = tasks.map(([taskName, task]) => taskBlock(taskName, task))
   return `${head}\n\n${blocks.join('\n')}`
 }
@@ -173,27 +204,71 @@ function renderTask(
   return `${name} — ${dir}\n\n${taskBlock(taskName, task)}`
 }
 
+function renderTaskAcross(
+  root: string,
+  declaring: readonly ProjectEntry[],
+  taskName: string,
+  format: 'pretty' | 'json',
+): string {
+  if (format === 'json') {
+    const list = declaring.map((p) => ({
+      name: p.name,
+      dir: relPosix(root, p.dir) || '.',
+      task: taskName,
+      config: p.config.tasks![taskName],
+    }))
+    return `${JSON.stringify(JSON.parse(JSON.stringify(list)), null, 2)}\n`
+  }
+  return declaring
+    .map(
+      (p) =>
+        `${p.name} — ${relPosix(root, p.dir) || '.'}\n\n${taskBlock(taskName, p.config.tasks![taskName]!)}`,
+    )
+    .join('\n')
+}
+
+/** Every field the run reads, in the order the schema declares them. */
 function taskBlock(taskName: string, task: TaskConfig): string {
   const rows: [string, string][] = []
-  if (task.description !== undefined) rows.push(['description', task.description])
-  rows.push(['command', task.exec?.command ?? '(group)'])
-  if (task.dependsOn !== undefined) rows.push(['dependsOn', task.dependsOn.join(', ')])
-  if (task.cache !== undefined) {
-    rows.push(['inputs.files', task.cache.inputs.files.join(', ')])
-    if (task.cache.inputs.env !== undefined) {
-      rows.push(['inputs.env', task.cache.inputs.env.join(', ')])
-    }
-    if (task.cache.inputs.tasks !== undefined) {
-      rows.push(['inputs.tasks', task.cache.inputs.tasks.join(', ')])
-    }
-    rows.push(['outputs.files', task.cache.outputs.files.join(', ')])
+  const list = (xs: readonly string[] | undefined): string | undefined =>
+    xs === undefined ? undefined : xs.join(', ')
+  const add = (label: string, value: string | number | boolean | undefined): void => {
+    if (value !== undefined) rows.push([label, String(value)])
   }
-  if (task.exec?.timeout !== undefined) rows.push(['timeout', `${task.exec.timeout}ms`])
-  const persistent = task.exec?.persistent
+  add('description', task.description)
+  const exec = task.exec
+  rows.push(['command', exec?.command ?? '(group)'])
+  add('dependsOn', list(task.dependsOn))
+  add('timeout', exec?.timeout === undefined ? undefined : `${exec.timeout}ms`)
+  add('retries', exec?.retries)
+  add('env.passThrough', list(exec?.env?.passThrough))
+  add(
+    'env.define',
+    exec?.env?.define === undefined
+      ? undefined
+      : Object.entries(exec.env.define)
+          .map(([k, v]) => `${k}=${v}`)
+          .join(', '),
+  )
+  add('remote', exec?.remote === undefined ? undefined : String(exec.remote))
+  add('sandbox', exec?.sandbox === undefined ? undefined : JSON.stringify(exec.sandbox))
+  const persistent = exec?.persistent
   if (persistent !== undefined) {
-    const fields: string[] = []
-    if (persistent.readyWhen !== undefined) fields.push(`readyWhen: ${persistent.readyWhen}`)
-    rows.push(['persistent', fields.length > 0 ? fields.join(', ') : 'yes'])
+    add(
+      'persistent',
+      persistent.readyWhen === undefined ? 'yes' : `readyWhen: ${persistent.readyWhen}`,
+    )
+  }
+  const cache = task.cache
+  if (cache !== undefined) {
+    add('inputs.files', list(cache.inputs.files))
+    add('inputs.workspaceFiles', list(cache.inputs.workspaceFiles))
+    add('inputs.env', list(cache.inputs.env))
+    add('inputs.tasks', list(cache.inputs.tasks))
+    add('inputs.runtime', list(cache.inputs.runtime))
+    add('inputs.workspaceRuntime', list(cache.inputs.workspaceRuntime))
+    add('outputs.files', list(cache.outputs.files))
+    add('outputs.workspaceFiles', list(cache.outputs.workspaceFiles))
   }
   const labelW = Math.max(...rows.map(([label]) => label.length))
   const body = rows.map(([label, value]) => `  ${`${label}:`.padEnd(labelW + 1)} ${value}`)

package/src/cli/upgrade.ts

@@ -5,6 +5,7 @@
 // deno upgrade — "update" is what package managers do to indexes.
 
 import { chmod, rename, rm } from 'node:fs/promises'
+import { seeHelp } from './help.js'
 import { UserError } from '../util/index.js'
 import { VERSION } from '../version.js'
 
@@ -77,7 +78,7 @@ export async function upgradeCmd(args: readonly string[]): Promise<number> {
   const tag = args.find((a) => !a.startsWith('-'))
   const unknown = args.find((a) => a.startsWith('-'))
   if (unknown !== undefined) {
-    process.stderr.write(`vx upgrade: unknown flag: ${unknown}\n`)
+    process.stderr.write(`vx upgrade: unknown flag: ${unknown}${seeHelp('upgrade')}\n`)
     return 1
   }
   if (!isCompiledBinary()) {