@vzn/vx 0.0.652 → 0.0.653

package/src/cli/lock.ts

@@ -3,21 +3,29 @@
 // `vx lock --check` — audit the lock against a fresh evaluation in the
 // current environment. Design: docs/design/config-lock-2026-06.md.
 
+import { readdirSync } from 'node:fs'
 import { open } from 'node:fs/promises'
 import path from 'node:path'
 import type { ProjectConfig } from '../config.js'
 import { flagHint, formatValue, refuse, refusedWord, seeHelp } from './help.js'
-import { buildTaskGraph, expandRequested, isDefaultBuild } from '../graph/index.js'
+import {
+  buildTaskGraph,
+  expandRequested,
+  isDefaultBuild,
+  refuseFiltersThroughGroups,
+} from '../graph/index.js'
 import {
   applyGraphStage,
   claimedDigests,
   discoverProjects,
   fingerprintClaims,
   hasHook,
+  ignoredConfigRefusal,
   loadProjects,
 } from '../orchestrator/index.js'
 import { resolveSetting, runRules } from '../settings.js'
 import {
+  configErrorFrame,
   DOT_VX_GITATTRIBUTES,
   fsRefusalHint,
   isFsRefusal,
@@ -26,10 +34,12 @@ import {
   maskedLine,
   relPosix,
   type RefusalParts,
-  type UserError,
+  UserError,
   secretMask,
+  secretNamed,
   type SecretMask,
   refuseSymlink,
+  writeAllOrNone,
   writeNoFollow,
 } from '../util/index.js'
 import * as ui from '../ui/index.js'
@@ -39,6 +49,7 @@ import {
   findProjectConfigs,
   findWorkspaceRoot,
   REVIEW_FILE,
+  PROJECT_CONFIG_FILENAMES,
   loadProjectConfigs,
   LOCKFILE_NAME,
   LOCKFILE_VERSION,
@@ -48,11 +59,11 @@ import {
   checkBracketLiterals,
   checkDependencyRules,
   computeNestedProjectDirs,
-  writeLockfile,
+  lockfileWrite,
   DEPENDENCIES_LOCK_NAME,
   dependenciesLock,
   parseDependenciesLock,
-  writeDependenciesLock,
+  dependenciesLockWrite,
   type DependenciesLock,
   type Lockfile,
   type ProjectMeta,
@@ -86,6 +97,29 @@ export function parseLockArgs(args: readonly string[]): LockArgs {
 
 type ConfiguredMeta = ProjectMeta & { configPath: string }
 
+/**
+ * A `dependsOn` the graph refused (`a#dep: dependsOn a#nope …`), said as
+ * a schema refusal of that field, so it prints at the config's line with
+ * its frame as every other config error does. Undefined when the task's
+ * `dependsOn` is not in its file (a plugin's task, the default build).
+ */
+function placedDependsOn(
+  err: UserError,
+  all: readonly ProjectMeta[],
+  root: string,
+): string | undefined {
+  if (err.code !== 'VX_E_DEPENDS_ON') return undefined
+  const m = /^(.+)#([^#\s]+): dependsOn (.+)$/s.exec(err.message)
+  if (m === null) return undefined
+  const configPath = all.find((p) => p.name === m[1])?.configPath
+  if (configPath === undefined || configPath === null) return undefined
+  // `does not accept …` reads on from the field; a named dep takes `names`.
+  // The frame turns a trailing ` — did you mean X?` into its fix line.
+  const said = /^(?:does not|patterns are)\b/.test(m[3]!) ? m[3] : `names ${m[3]}`
+  const placed = `${configPath}: tasks.${m[2]}.dependsOn ${said!.replace(/\. Did you mean (.+)\?$/s, ' — did you mean $1?')}`
+  return configErrorFrame(placed, root) === undefined ? undefined : placed
+}
+
 export async function lockCmd(args: readonly string[]): Promise<number> {
   const parsed = parseLockArgs(args)
   if (parsed.error) return refuse('lock', args, parsed.error, 'VX_E_USAGE')
@@ -156,11 +190,19 @@ async function audit(root: string, warn: (message: string) => void): Promise<Gra
   try {
     const { workspaceConfig, plugins, cacheDir } = await loadCliWorkspace(root)
     out.reviewFiles = resolveSetting('lock.reviewFiles', workspaceConfig).value !== false
-    const { configs: found, strayReviews, shadowed } = await findProjectConfigs(root)
+    const {
+      configs: found,
+      strayReviews,
+      shadowed,
+      nestedWorkspaces,
+    } = await findProjectConfigs(root)
     out.strayReviews = strayReviews
     out.shadowed = shadowed
     // The one load that evaluates: every reader reads the lock this writes.
-    const configs = await loadProjectConfigs(found.map((f) => f.configPath))
+    const configs = await loadProjectConfigs(
+      found.map((f) => f.configPath),
+      root,
+    )
     // In the lock's form: a field left `undefined` is a key the stored JSON
     // never has. Entries, not assignment: a directory named `__proto__` is
     // a key of its own (D-152).
@@ -173,10 +215,16 @@ async function audit(root: string, warn: (message: string) => void): Promise<Gra
         },
       ]),
     )
+    if (nestedWorkspaces.length > 0)
+      out.fresh.nestedWorkspaces = nestedWorkspaces.map((dir) => lockKey(root, dir))
     // The stages edit what they are handed; the lock keeps what the configs say.
     const view = structuredClone(out.fresh)
     const lock = async (): Promise<Lockfile> => view
     out.all = await discoverProjects(root, lock, plugins, cacheDir, warn)
+    for (const m of out.all) {
+      const why = m.configPath === null ? ignoredConfigRefusal(root, m) : undefined
+      if (why !== undefined) throw new UserError(why, 'VX_E_LOCK')
+    }
     const { projects } = await loadProjects({
       workspaceRoot: root,
       cacheDir,
@@ -216,11 +264,19 @@ async function audit(root: string, warn: (message: string) => void): Promise<Gra
       workspaceRoot: root,
       rules,
       nestedProjects: new Map(
-        [...computeNestedProjectDirs(out.all)].map(([name, dirs]) => [
+        [...computeNestedProjectDirs(out.all, nestedWorkspaces)].map(([name, dirs]) => [
           name,
-          dirs.map((dir) => ({ name: nameOf.get(dir)!, dir })),
+          dirs.map((dir) => {
+            const project = nameOf.get(dir)
+            return project === undefined
+              ? { name: relPosix(root, dir), dir, workspace: true }
+              : { name: project, dir }
+          }),
         ]),
       ),
+      projectConfigs: out.all.flatMap((m) =>
+        m.configPath === null ? [] : [{ name: m.name, configPath: m.configPath }],
+      ),
     })
     if (hasHook(plugins, 'graph'))
       await applyGraphStage(plugins, nodes, {
@@ -230,11 +286,14 @@ async function audit(root: string, warn: (message: string) => void): Promise<Gra
         warn,
         rules,
       })
+    // A run refuses it after its `graph` stage; the lock, which holds the
+    // graph every run trusts, refuses it too.
+    refuseFiltersThroughGroups(nodes)
   } catch (err) {
     if (isUserError(err))
       return {
         ...out,
-        broken: err.message,
+        broken: placedDependsOn(err, out.all, root) ?? err.message,
         ...(err.parts ? { brokenParts: err.parts } : {}),
         ...(err instanceof ConfigsRefused ? { alsoBroken: err.all.slice(1) } : {}),
       }
@@ -424,11 +483,11 @@ async function writeLock(
   }
   // The copies first: one that cannot be written leaves the lock as it was,
   // not a new lock beside stale copies and a stack.
-  for (const r of reviews) refuseSymlink(r.file)
+  for (const r of reviews) refuseSymlink(r.file, root)
   const blocked = (
     await Promise.all(
       reviews.map((r) =>
-        writeNoFollow(r.file, r.text).then(
+        writeNoFollow(r.file, r.text, root).then(
           () => null,
           (err: unknown): { file: string; err: NodeJS.ErrnoException } => {
             if (typeof (err as NodeJS.ErrnoException).code !== 'string' || isOutOfFds(err))
@@ -451,8 +510,13 @@ async function writeLock(
     })
     return 1
   }
-  await writeLockfile(root, check.fresh)
-  if (check.dependencies !== null) await writeDependenciesLock(root, check.dependencies)
+  await writeAllOrNone(
+    [
+      lockfileWrite(root, check.fresh),
+      ...(check.dependencies === null ? [] : [dependenciesLockWrite(root, check.dependencies)]),
+    ],
+    root,
+  )
   await writeIfMissing(path.join(root, '.vx', '.gitattributes'), DOT_VX_GITATTRIBUTES)
   const n = metas.length
   say(`${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}`)
@@ -464,6 +528,27 @@ async function writeLock(
   return 0
 }
 
+/** The first places (three at most) two evaluated configs differ: `path: locked → now`. */
+function configDiff(locked: unknown, now: unknown, at = '', out: string[] = []): string[] {
+  if (out.length >= 3 || Bun.deepEquals(locked, now, true)) return out
+  const isObj = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object'
+  if (isObj(locked) && isObj(now) && Array.isArray(locked) === Array.isArray(now)) {
+    for (const k of new Set([...Object.keys(locked), ...Object.keys(now)])) {
+      const next = Array.isArray(now) ? `${at}[${k}]` : at === '' ? k : `${at}.${k}`
+      configDiff(locked[k], now[k], next, out)
+    }
+    return out
+  }
+  out.push(`${at}: ${diffValue(locked)} → ${diffValue(now)}`)
+  return out
+}
+
+function diffValue(v: unknown): string {
+  if (v === undefined) return '(none)'
+  const s = JSON.stringify(v)
+  return s.length > 60 ? `${s.slice(0, 59)}…` : s
+}
+
 /**
  * Review copies with no config beside them, sorted. One left beside a
  * config since deleted shows reviewers tasks nothing runs, and keys the
@@ -483,21 +568,45 @@ async function strayCopies(check: GraphCheck): Promise<string[]> {
   return [...new Set([...kept.filter((f) => f !== null), ...check.strayReviews])].sort()
 }
 
-const strayLine = (root: string, file: string): string =>
-  `${relPosix(root, file)} has no vx.config beside it — delete it`
+/**
+ * A copy's config renamed to a name vx does not read (`.json`, `.tsx`)
+ * is still there: "delete it" was the wrong advice. Looked for only here,
+ * once a copy is already stray.
+ */
+function strayLine(root: string, file: string): string {
+  const copy = `${relPosix(root, file)} has no vx.config beside it`
+  let names: string[] = []
+  try {
+    names = readdirSync(path.dirname(file))
+  } catch {
+    // gone or unreadable: nothing beside it to name
+  }
+  const unread = names
+    .filter((n) => n.startsWith('vx.config.') && !PROJECT_CONFIG_FILENAMES.includes(n))
+    .sort()[0]
+  if (unread === undefined) return `${copy} — delete it`
+  const exts = PROJECT_CONFIG_FILENAMES.map((n) => n.slice('vx.config.'.length)).join(', ')
+  return `${copy}: ${unread} is not a config vx reads (${exts})`
+}
 
 /**
  * Each place an evaluated config holds the value of a secret in this
  * environment, by the rule output masking uses (a secret-named variable,
- * or one a task lists in `exec.env.secret`). The lock is committed, so
- * such a value would be published, and masking it would freeze a `***`
- * that every run runs (L-42).
+ * one a task lists in `exec.env.secret`, or a define of such a name whose
+ * value this environment holds). The lock is committed, so such a value
+ * would be published, and masking it would freeze a `***` that every run
+ * runs (L-42).
  */
 function secretsIn(projects: Record<string, ProjectConfig>): Array<{ at: string; name: string }> {
   const named = new Set<string>()
+  const defines: Array<[name: string, value: string]> = []
   for (const config of Object.values(projects)) {
-    for (const task of Object.values(config.tasks ?? {}))
-      for (const n of task?.exec?.env?.secret ?? []) named.add(n)
+    for (const task of Object.values(config.tasks ?? {})) {
+      const secret = task?.exec?.env?.secret ?? []
+      for (const n of secret) named.add(n)
+      for (const [n, v] of Object.entries(task?.exec?.env?.define ?? {}))
+        if (secretNamed(n) || secret.includes(n)) defines.push([n, v])
+    }
   }
   // Each variable's own mask: what the output masks of it, a URL's
   // password and a key's lines too, not only the whole value.
@@ -507,12 +616,26 @@ function secretsIn(projects: Record<string, ProjectConfig>): Array<{ at: string;
       value === undefined ? null : secretMask([{ [name]: value }], named.has(name) ? [name] : [])
     if (mask !== null) secrets.push([mask, name])
   }
+  // The output masks a secret define's value by the define's name, so
+  // `API_TOKEN: process.env.MY_CREDS` printed masked and locked in clear.
+  // Only a value this environment holds counts: a literal define is the
+  // config's own committed text, and npm's `'${NPM_TOKEN}'` is no secret.
+  for (const [n, v] of defines) {
+    const mask = secretMask([{ [n]: v }], [n])
+    if (mask === null) continue
+    for (const [name, value] of Object.entries(process.env))
+      if (value !== undefined && mask.spans(value).length > 0) secrets.push([mask, name])
+  }
   if (secrets.length === 0) return []
   const found: Array<{ at: string; name: string }> = []
   const walk = (project: string, at: string, v: unknown): void => {
     if (typeof v === 'string') {
-      for (const [mask, name] of secrets)
-        if (mask.spans(v).length > 0) found.push({ at: `${project}: ${at} holds $${name}`, name })
+      for (const [mask, name] of secrets) {
+        const place = `${project}: ${at} holds $${name}`
+        // A define's mask and its variable's own both find one value.
+        if (mask.spans(v).length > 0 && !found.some((f) => f.at === place))
+          found.push({ at: place, name })
+      }
     } else if (Array.isArray(v)) {
       v.forEach((x, i) => walk(project, `${at}[${i}]`, x))
     } else if (v !== null && typeof v === 'object') {
@@ -533,6 +656,29 @@ function warnShadowed(root: string, check: GraphCheck, verb: string): void {
     )
 }
 
+/**
+ * `read` with each file's record taken from `fresh` where only the files
+ * its digests read moved (same bytes, same extra files, an extra's hash
+ * changed): a run digests anew on such an edit (`lockfileClaim`'s
+ * `lockedOnce`), and cli.md says it needs no `vx lock`, yet `--check`
+ * failed every edit in a `file:` directory or a patch. With every hash
+ * unchanged a run keys from the record, so its digests are compared.
+ */
+function liveExtras(read: DependenciesLock, fresh: DependenciesLock): DependenciesLock {
+  const files = { ...read.files }
+  for (const [name, now] of Object.entries(fresh.files)) {
+    const was = files[name]
+    if (
+      was !== undefined &&
+      was.hash === now.hash &&
+      Bun.deepEquals(Object.keys(was.extras ?? {}), Object.keys(now.extras ?? {})) &&
+      !Bun.deepEquals(was.extras ?? {}, now.extras ?? {})
+    )
+      files[name] = now
+  }
+  return { ...read, files }
+}
+
 /**
  * Audit the lock: find and re-evaluate every config in the CURRENT
  * environment and deep-compare it with the locked object. That sees an
@@ -586,12 +732,26 @@ async function checkLock(root: string, json: boolean): Promise<number> {
           ? `${rel} is not the ${locked.file} the lock holds for ${dir === '.' ? 'the workspace root project' : dir} — run 'vx lock'`
           : !Bun.deepEquals(fresh.config, locked.config, true)
             ? `${rel} evaluates differently from the lock here — its config, a file ` +
-              `it imports, or the environment it reads changed; run 'vx lock'`
+              `it imports, or the environment it reads changed; run 'vx lock'` +
+              // What changed: a config that reads the environment shows no file diff.
+              configDiff(locked.config, fresh.config)
+                .map((d) => `\n  ${maskedLine(d)}`)
+                .join('')
             : null
     if (problem === null) continue
     failures.push(problem)
     drifted.add(dir)
   }
+  const lockedWalls = lock.nestedWorkspaces ?? []
+  const walls = check.fresh.nestedWorkspaces ?? []
+  for (const dir of walls)
+    if (!lockedWalls.includes(dir))
+      failures.push(`${dir} is a nested workspace the lock does not hold — run 'vx lock'`)
+  for (const dir of lockedWalls)
+    if (!walls.includes(dir))
+      failures.push(
+        `the lock holds ${dir} as a nested workspace, which it is not now — run 'vx lock'`,
+      )
   if (broken !== null && check.loaded) failures.push(broken)
   // Each config that does not load, as `vx lock` names them: a CI fixing
   // one at a time re-ran the gate once per broken config.
@@ -645,7 +805,10 @@ async function checkLock(root: string, json: boolean): Promise<number> {
       .catch(() => null)
     // Compared as JSON: a formatter may lay the file out its own way.
     const read = parseDependenciesLock(text)
-    if (read === null || !Bun.deepEquals(read, check.dependencies, true))
+    if (
+      read === null ||
+      !Bun.deepEquals(liveExtras(read, check.dependencies), check.dependencies, true)
+    )
       failures.push(
         `${DEPENDENCIES_LOCK_NAME} ${text === null ? 'is missing' : 'is not what the dependencies resolve to here'} — run 'vx lock'`,
       )

package/src/cli/plan-format.ts

@@ -3,7 +3,7 @@
 import type { AffectedReason, CacheStatus, RunPlan } from '../orchestrator/index.js'
 import { computeReverseDepCount } from '../graph/index.js'
 import { planList, type PlannedRow, skippedReason } from '../report/index.js'
-import { formatBytes, formatElapsed, maskedCommand } from '../util/index.js'
+import { formatBytes, formatElapsed, maskedCommand, printable } from '../util/index.js'
 import * as ui from '../ui/index.js'
 import type { ColorSupport } from '../ui/index.js'
 
@@ -12,11 +12,10 @@ import type { ColorSupport } from '../ui/index.js'
  * list's grid (what the run would do with it, its usual time, where it
  * would run), then the counts and the predicted time.
  *
- *   ─ Plan 3 ─────────────────────────────────────────────────────
- *         time   usual status  cache      cpu    mem outputs  blocks worker       task
- *    ⇢                 cached  local                                 local        @vzn/vx#lint
- *    ⇣                 cached  remote                     12MB       local        @vzn/vx#test
- *    ⏺︎               ~1.2s run     miss                                  local        @vzn/vx#build
+ *     Plan 3    status  cache     usual    time   cpu    mem outputs  blocks worker       task
+ *              cached  local          —       —     —      —       —       — local        @vzn/vx#lint
+ *              cached  remote         —       —     —      —    12MB       — local        @vzn/vx#test
+ *              run     miss       ~1.2s       —     —      —       —       — local        @vzn/vx#build
  *
  *     tasks      3 planned · 2 cache hits (1 local, 1 remote, 12MB) · 1 would run
  *     predicted  ~1.20s wall · ~1.20s total execution
@@ -46,12 +45,12 @@ export function planReport(plan: RunPlan): ui.Block {
     if (t.cacheStatus === 'skipped') notes.push(skippedReason(t))
     const desc = shownDescription(t)
     if (desc !== undefined && desc !== '') notes.push(desc)
-    if (t.affected !== undefined) notes.push(`affected: ${describeReason(t.affected)}`)
+    if (t.affected !== undefined) notes.push(`affected: ${printable(describeReason(t.affected))}`)
     const executes = !skipped && (t.cacheStatus === 'miss' || t.cacheStatus === 'no-cache')
     rows.push({
       node: t.node,
       ...(skipped ? NOOP : LOOK[t.cacheStatus]),
-      ...(executes && t.p50Ms !== undefined ? { usualMs: t.p50Ms } : {}),
+      ...(executes ? { usualMs: t.p50Ms ?? null } : {}),
       ...(t.cacheStatus === 'hit-remote' && t.remoteBytes !== undefined
         ? { outputBytes: t.remoteBytes }
         : {}),
@@ -114,7 +113,7 @@ export function planReport(plan: RunPlan): ui.Block {
     const parts = [`~${formatElapsed(p.wallMs)} wall`]
     parts.push(`~${formatElapsed(p.workMs)} total execution`)
     if (p.unknownCount > 0) {
-      parts.push(`${p.unknownCount} task${p.unknownCount === 1 ? '' : 's'} without history (+?)`)
+      parts.push(`${p.unknownCount} task${p.unknownCount === 1 ? '' : 's'} never timed (+?)`)
     }
     facts.push(['predicted', parts.join(' · ')])
   }
@@ -137,37 +136,34 @@ export function formatPlanText(plan: RunPlan, c: ColorSupport = { enabled: false
   return ui.render([planReport(plan)], c)
 }
 
-type Look = Pick<PlannedRow, 'glyph' | 'status' | 'tone' | 'cache' | 'cacheTone'>
+type Look = Pick<PlannedRow, 'status' | 'tone' | 'cache' | 'cacheTone'>
 
-/** Each outcome on the run's grid: its glyph and words, as the run would print them. */
+/** Each outcome on the run's grid: its words, as the run would print them. */
 const LOOK: Record<CacheStatus, Look> = {
   'hit-local': {
-    glyph: '\u21e2',
     status: 'cached',
     tone: 'ok',
     cache: 'local',
     cacheTone: 'local',
   },
   'hit-remote': {
-    glyph: '\u21e3',
     status: 'cached',
     tone: 'ok',
     cache: 'remote',
     cacheTone: 'remote',
   },
-  miss: { glyph: '\u23fa\ufe0e', status: 'run', tone: 'info', cache: 'miss', cacheTone: 'muted' },
+  miss: { status: 'run', tone: 'info', cache: 'miss', cacheTone: 'muted' },
   'no-cache': {
-    glyph: '\u23fa\ufe0e',
     status: 'run',
     tone: 'info',
     cache: 'no-cache',
     cacheTone: 'muted',
   },
-  group: { glyph: '\u25cb', status: 'group', tone: 'muted', cache: '', cacheTone: '' },
-  'not-started': { glyph: '\u25cc', status: 'not run', tone: 'muted', cache: '', cacheTone: '' },
-  skipped: { glyph: '\u2298', status: 'skipped', tone: 'warn', cache: '', cacheTone: '' },
+  group: { status: 'group', tone: 'muted', cache: '', cacheTone: '' },
+  'not-started': { status: 'not run', tone: 'muted', cache: '', cacheTone: '' },
+  skipped: { status: 'skipped', tone: 'warn', cache: '', cacheTone: '' },
 }
-const NOOP: Look = { glyph: '\u00b7', status: 'noop', tone: 'muted', cache: '', cacheTone: '' }
+const NOOP: Look = { status: 'noop', tone: 'muted', cache: '', cacheTone: '' }
 
 /** One `--affected --dry` reason line: the cause, then the edge chain that carried it. */
 function describeReason(r: AffectedReason): string {
@@ -181,13 +177,20 @@ function describeReason(r: AffectedReason): string {
           : r.kind === 'input'
             ? `${r.file} changed (an input)`
             : r.kind === 'workspace'
-              ? `${r.file} changed (workspace-wide)`
+              ? `${r.file} changed (${r.wide === true ? 'workspace-wide' : 'every task in its project'})`
               : r.file !== undefined
                 ? `${r.file} changed (in its project)`
                 : 'its project changed as a whole'
   return r.via === undefined ? cause : `${cause}, via ${r.via.join(' ← ')}`
 }
 
+function wireReason(r: AffectedReason): AffectedReason {
+  if (r.wide === undefined) return r
+  const wire = { ...r }
+  delete wire.wide
+  return wire
+}
+
 /** A TS config may build the description from `process.env` (L-11). */
 function shownDescription(t: RunPlan['tasks'][number]): string | undefined {
   const { description, exec } = t.node.config
@@ -232,7 +235,7 @@ export function formatPlanJson(
           ...(t.executor !== undefined ? { executor: t.executor } : {}),
           ...(t.download !== undefined ? { download: t.download } : {}),
           ...(description !== undefined ? { description } : {}),
-          ...(t.affected !== undefined ? { affected: t.affected } : {}),
+          ...(t.affected !== undefined ? { affected: wireReason(t.affected) } : {}),
           ...(t.otherPlatform !== undefined ? { otherPlatform: t.otherPlatform } : {}),
           ...(t.blockedBy !== undefined ? { blockedBy: t.blockedBy } : {}),
         }

package/src/cli/plugin-commands.ts

@@ -337,7 +337,12 @@ export async function pluginCommandHelp(cwd = process.cwd()): Promise<string[]>
       if (seen.has(verb)) continue
       seen.add(verb)
       lines.push(
-        ...helpLines(`  vx ${verb.padEnd(17)} `, `${command.description} (${plugin.name})`),
+        ...helpLines(
+          // Two spaces at least: one ran a long verb into its description,
+          // and the help painter reads a description after two.
+          `  vx ${verb.length < 17 ? `${verb.padEnd(17)} ` : `${verb}  `}`,
+          `${command.description} (${plugin.name})`,
+        ),
       )
     }
   }

package/src/cli/plugin-templates.ts

@@ -16,7 +16,7 @@ export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: s
     "test": "// A test for the example `commands` plugin beside it: the verb is called\n// the way vx calls it, with the context vx hands it. `bun test` runs it.\nimport { expect, it, spyOn } from 'bun:test'\nimport { cacheDirVerb } from './commands.ts'\n\nconst verb = cacheDirVerb().commands!['cache-dir']!\nconst ctx = {\n  workspaceRoot: '/ws',\n  cacheDir: '/ws/.vx/cache',\n  warn() {},\n  concurrency: 1,\n  vx: ['vx'],\n  cache: {\n    get: async () => null,\n    put: async () => {},\n    has: async () => null,\n    hasMany: async () => null,\n    getRun: async () => null,\n  },\n  artifacts: {\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  },\n  artifactsFor: () => ({\n    save: async () => {},\n    restore: async () => null,\n    output: async () => null,\n    share: async () => false,\n    resend: async () => false,\n  }),\n}\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(process.stdout, 'write').mockImplementation(() => true)\n  const err = spyOn(process.stderr, 'write').mockImplementation(() => true)\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache\\n']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    // On CI the line is coloured: the words are what this asserts.\n    expect(err.mock.calls.map(([l]) => Bun.stripANSI(String(l)))).toEqual([\n      'vx cache-dir: takes no arguments, got x\\n',\n    ])\n  } finally {\n    out.mockRestore()\n    err.mockRestore()\n  }\n})\n"
   },
   "executor": {
-    "plugin": "// `executor`: where a task's command runs. This one runs it here, in a\n// shell of its own, and stops the shell's whole process group when core\n// aborts the request (a stop, or `exec.timeout`): core cannot reach a\n// process an executor spawned.\nimport { definePlugin, withForwardArgs, type TaskExecutor, type VxPlugin } from '@vzn/vx'\n\nexport function shellExecutor(): VxPlugin {\n  const executor: TaskExecutor = {\n    name: 'shell',\n    async execute(req) {\n      const started = Date.now()\n      // A stop before the spawn is work not to start: an abort fires no\n      // listener added after it, so the command would run unstopped.\n      if (req.signal?.aborted === true) {\n        const exitCode = req.signal.reason === 'SIGINT' ? 130 : 143\n        return { exitCode, durationMs: 0, stdout: '', stderr: '', violations: [], where: 'shell' }\n      }\n      // vx's own `sh`: a bare name is looked up on `req.env`'s PATH, which\n      // leads with the project's node_modules/.bin, where a dependency's\n      // `sh` would run every command.\n      const sh = Bun.which('sh') ?? '/bin/sh'\n      // The args after `--`, quoted and placed as the local executor places\n      // them (before a trailing comment, never on a heredoc's terminator).\n      const command = withForwardArgs(req.command, req.forwardArgs)\n      const child = Bun.spawn([sh, '-c', command], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const kill = (signal: NodeJS.Signals): void => {\n        try {\n          process.kill(-child.pid, signal)\n        } catch {\n          // already gone\n        }\n      }\n      // Core abandons an executor 2 s after the abort: a group that ignores\n      // SIGTERM is killed before then, or it would run on unreached.\n      let killTimer: ReturnType<typeof setTimeout> | undefined\n      const stop = (): void => {\n        kill('SIGTERM')\n        killTimer = setTimeout(() => kill('SIGKILL'), 1_000)\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const readers: { cancel(): Promise<void> }[] = []\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const reader = stream.getReader()\n        readers.push(reader)\n        const decoder = new TextDecoder()\n        let all = ''\n        for (let r = await reader.read(); !r.done; r = await reader.read()) {\n          const text = decoder.decode(r.value, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const drained = Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n      ])\n      const exitCode = await child.exited\n      // A pipe ends only when every writer closes it: a process the command\n      // left running (`server &`) would hold the task open. What it writes\n      // after a short grace is not the task's.\n      const cut = setTimeout(() => readers.forEach((r) => void r.cancel()), 250)\n      const [stdout, stderr] = await drained\n      clearTimeout(cut)\n      req.signal?.removeEventListener('abort', stop)\n      clearTimeout(killTimer)\n      return {\n        exitCode,\n        durationMs: Date.now() - started,\n        stdout,\n        stderr,\n        violations: [],\n        where: 'shell',\n      }\n    },\n  }\n  return definePlugin(import.meta, { executor: () => executor })\n}\n",
+    "plugin": "// `executor`: where a task's command runs. This one runs it here, in a\n// shell of its own, and stops the shell's whole process group when core\n// aborts the request (a stop, or `exec.timeout`): core cannot reach a\n// process an executor spawned.\nimport { definePlugin, withForwardArgs, type TaskExecutor, type VxPlugin } from '@vzn/vx'\n\nexport function shellExecutor(): VxPlugin {\n  const executor: TaskExecutor = {\n    name: 'shell',\n    // No `sandbox: true`: it ignores `req.sandbox`, so vx runs a task that\n    // declares `exec.sandbox` itself, inside one.\n    async execute(req) {\n      const started = Date.now()\n      // A stop before the spawn is work not to start: an abort fires no\n      // listener added after it, so the command would run unstopped.\n      if (req.signal?.aborted === true) {\n        const exitCode = req.signal.reason === 'SIGINT' ? 130 : 143\n        return { exitCode, durationMs: 0, stdout: '', stderr: '', violations: [], where: 'shell' }\n      }\n      // vx's own `sh`: a bare name is looked up on `req.env`'s PATH, which\n      // leads with the project's node_modules/.bin, where a dependency's\n      // `sh` would run every command.\n      const sh = Bun.which('sh') ?? '/bin/sh'\n      // The args after `--`, quoted and placed as the local executor places\n      // them (before a trailing comment, never on a heredoc's terminator).\n      const command = withForwardArgs(req.command, req.forwardArgs)\n      const child = Bun.spawn([sh, '-c', command], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const kill = (signal: NodeJS.Signals): void => {\n        try {\n          process.kill(-child.pid, signal)\n        } catch {\n          // already gone\n        }\n      }\n      // Core abandons an executor 2 s after the abort: a group that ignores\n      // SIGTERM is killed before then, or it would run on unreached.\n      let killTimer: ReturnType<typeof setTimeout> | undefined\n      const stop = (): void => {\n        kill('SIGTERM')\n        killTimer = setTimeout(() => kill('SIGKILL'), 1_000)\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const readers: { cancel(): Promise<void> }[] = []\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const reader = stream.getReader()\n        readers.push(reader)\n        const decoder = new TextDecoder()\n        let all = ''\n        for (let r = await reader.read(); !r.done; r = await reader.read()) {\n          const text = decoder.decode(r.value, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const drained = Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n      ])\n      const exitCode = await child.exited\n      // A pipe ends only when every writer closes it: a process the command\n      // left running (`server &`) would hold the task open. What it writes\n      // after a short grace is not the task's.\n      const cut = setTimeout(() => readers.forEach((r) => void r.cancel()), 250)\n      const [stdout, stderr] = await drained\n      clearTimeout(cut)\n      req.signal?.removeEventListener('abort', stop)\n      clearTimeout(killTimer)\n      return {\n        exitCode,\n        durationMs: Date.now() - started,\n        stdout,\n        stderr,\n        violations: [],\n        where: 'shell',\n      }\n    },\n  }\n  return definePlugin(import.meta, { executor: () => executor })\n}\n",
     "test": "// A test for the example `executor` plugin beside it: a throwaway workspace\n// declares the plugin and vx's own run() drives it. `bun test` runs it.\nimport { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'\nimport os from 'node:os'\nimport path from 'node:path'\nimport { afterEach, beforeEach, expect, it } from 'bun:test'\nimport { run, type Logger } from '@vzn/vx'\nimport { shellExecutor } from './executor.ts'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-executor-'))\n  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name: 'ws', private: true }))\n  await writeFile(path.join(root, 'pnpm-workspace.yaml'), 'packages:\\n  - \"packages/*\"\\n')\n  Bun.spawnSync({ cmd: ['git', 'init', '-q'], cwd: root })\n})\nafterEach(async () => {\n  await rm(root, { recursive: true, force: true })\n})\n\n/** A package `name` whose `vx.config.mjs` is `config`. */\nasync function pkg(\n  name: string,\n  config: string,\n  scripts?: Record<string, string>,\n): Promise<string> {\n  const dir = path.join(root, 'packages', name)\n  await mkdir(dir, { recursive: true })\n  await writeFile(\n    path.join(dir, 'package.json'),\n    JSON.stringify({ name, version: '1.0.0', ...(scripts ? { scripts } : {}) }),\n  )\n  // Core reads no package.json: the config names the project.\n  await writeFile(\n    path.join(dir, 'vx.config.mjs'),\n    config.replace('export default {', `export default { name: ${JSON.stringify(name)},`),\n  )\n  return dir\n}\n\n/**\n * A `.vx/workspace.mjs` declaring `call`, e.g. `shellExecutor()`, from the plugin file\n * beside this test, then `vx lock`: a run reads project configs only from the lock.\n */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'executor.ts'))\n  await Bun.write(\n    path.join(root, '.vx/workspace.mjs'),\n    `import { shellExecutor } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\n  const vx = path.join(path.dirname(new URL(import.meta.resolve('@vzn/vx')).pathname), 'bin.ts')\n  const lock = Bun.spawnSync({ cmd: [process.execPath, vx, 'lock'], cwd: root })\n  expect([lock.exitCode, lock.stderr.toString()]).toEqual([0, ''])\n}\n\nfunction log(order: string[] = []): Logger {\n  return {\n    status() {},\n    taskStart(node) {\n      order.push(`start ${node.id}`)\n    },\n    taskStdout() {},\n    taskStderr() {},\n    taskComplete(node) {\n      order.push(`end ${node.id}`)\n    },\n  }\n}\n\nit('runs the command and says where; stops it on exec.timeout', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: {\n      hello: { exec: { command: 'echo hi > out.txt' } },\n      slow: { exec: { command: 'exec sleep 30', timeout: '300ms' } },\n    } }`,\n  )\n  await workspace('shellExecutor()')\n  const ok = await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(ok.outcomes.map((o) => [o.node.id, o.status, o.where])).toEqual([\n    ['a#hello', 'success', 'shell'],\n  ])\n  expect(await Bun.file(path.join(dir, 'out.txt')).text()).toBe('hi\\n')\n  const started = Date.now()\n  const slow = await run({ cwd: root, tasks: ['slow'], log: log(), handleSignals: false })\n  expect(slow.outcomes.map((o) => [o.node.id, o.status, o.timedOut === true])).toEqual([\n    ['a#slow', 'failed', true],\n  ])\n  expect(Date.now() - started).toBeLessThan(10_000)\n}, 20_000)\n\nit(\"runs the command through this machine's sh, not a project's node_modules/.bin sh\", async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { hello: { exec: { command: 'echo real' } } } }`,\n  )\n  await mkdir(path.join(dir, 'node_modules', '.bin'), { recursive: true })\n  await writeFile(path.join(dir, 'node_modules', '.bin', 'sh'), '#!/bin/sh\\necho planted\\n', {\n    mode: 0o755,\n  })\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['hello'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], 'real\\n'])\n}, 20_000)\n\nit('puts the args after -- on the command as the local executor does', async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { say: { exec: { command: \"printf '<%s>' # each arg\" } } } }`,\n  )\n  await workspace('shellExecutor()')\n  const out: string[] = []\n  const r = await run({\n    cwd: root,\n    tasks: ['say'],\n    forwardArgs: [\"it's\", 'a b'],\n    log: { ...log(), taskStdout: (_n, chunk) => void out.push(chunk) },\n    handleSignals: false,\n  })\n  expect([r.outcomes.map((o) => o.status), out.join('')]).toEqual([['success'], \"<it's><a b>\"])\n}, 20_000)\n\n// An abort fires no listener added after it: a request stopped before\n// `execute` ran its command anyway, in a group nothing would stop.\nit('starts nothing for a request already aborted', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const stop = new AbortController()\n  stop.abort('SIGTERM')\n  const r = await executor.execute({\n    command: 'sleep 0.3; echo ran > ran.txt',\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n    signal: stop.signal,\n  } as never)\n  await Bun.sleep(600)\n  expect([r.exitCode, await Bun.file(path.join(root, 'ran.txt')).exists()]).toEqual([143, false])\n})\n\n// Core abandons an executor 2 s after its abort: a group that ignored\n// SIGTERM ran on, unreached, after the run had ended.\nit('kills a group that ignores SIGTERM after a grace', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const stop = new AbortController()\n  const started = Date.now()\n  setTimeout(() => stop.abort('SIGTERM'), 200)\n  const r = await executor.execute({\n    command: \"trap '' TERM; sleep 30\",\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n    signal: stop.signal,\n  } as never)\n  expect([r.exitCode, Date.now() - started < 10_000]).toEqual([137, true])\n}, 40_000)\n\n// A pipe ends only when every writer closes it: a process the command\n// left running (`server &`) held the task open until it exited.\nit('ends when the shell exits, though a process it left holds the pipes', async () => {\n  const executor = (await shellExecutor().executor!({} as never))!\n  const started = Date.now()\n  const r = await executor.execute({\n    command: 'sleep 5 & echo up',\n    cwd: root,\n    env: { PATH: process.env['PATH'] ?? '' },\n    forwardArgs: [],\n    onStdout() {},\n    onStderr() {},\n  } as never)\n  expect([r.exitCode, r.stdout, Date.now() - started < 3_000]).toEqual([0, 'up\\n', true])\n}, 20_000)\n"
   },
   "graph": {