@vzn/vx 0.0.100 → 0.0.102

package/README.md

@@ -38,10 +38,7 @@ burns 35 s of CPU in vx, 73 s in Turborepo and 114 minutes in Nx; a
 fully cached run replays the graph in 510 ms.
 <!-- bench:end -->
 
-On a real Turbo repo (`solidjs/solid`, its own `turbo.json`, nothing
-rewritten) vx replays a cached build in 51 ms where Turbo takes 95,
-restores every output in 66 ms against 127, and builds cold in 40.6 s
-against 45.5 s ([benchmarks](packages/vx/docs/benchmarks.md)).
+Measured on eleven real Turborepo and Nx repos too: [tried on real repos](#tried-on-real-repos).
 
 ## Install
 
@@ -96,15 +93,15 @@ runs on every commit. More: [Quickstart](https://vznjs.github.io/vx/quickstart/)
 [CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md) ·
 [playground](https://vznjs.github.io/vx/playground/) (the planner, in your browser).
 
-## Already on Turborepo or Nx?
+## Already on Turborepo, Nx or moon?
 
-Keep your `turbo.json` or Nx project graph. Two lines run it under vx,
-with nothing rewritten:
+Keep your `turbo.json`, Nx project graph or `.moon/`. Two lines run it
+under vx, with nothing rewritten:
 
 ```ts
 // vx.workspace.ts
 import { defineWorkspace } from '@vzn/vx'
-import { turbo } from '@vzn/vx-migrate' // or: nx
+import { turbo } from '@vzn/vx-migrate' // or: nx, moon
 
 export default defineWorkspace({ plugins: [turbo()] })
 ```
@@ -112,7 +109,7 @@ export default defineWorkspace({ plugins: [turbo()] })
 When you want configs of your own, one command writes them:
 
 ```sh
-bunx @vzn/vx-migrate      # vx.config.ts per package, from turbo.json or an Nx graph
+bunx @vzn/vx-migrate      # vx.config.ts per package, from turbo.json, an Nx graph or .moon/
 ```
 
 The written configs derive the same cache keys, so what `turbo()` cached
@@ -146,39 +143,73 @@ Turbo and Nx feature is in vx, pinned by a test:
   Vite does it. Core ships none and needs none.
 - **Free.** MIT. No paywall, no cloud, no account.
 
+## Tried on real repos
+
+Eleven public monorepos, each run with its own `turbo.json` or Nx graph
+and nothing rewritten, against the tool it ships with. Both tools on the same machine and
+tasks per row, medians; vx first, theirs second. Where the other tool
+wins, the row says so.
+
+| Repo                                                        | Against | Cold build            | Restore outputs | Nothing to do       |
+| ----------------------------------------------------------- | ------- | --------------------- | --------------- | ------------------- |
+| [solidjs/solid](https://github.com/solidjs/solid)           | Turbo   | 40.6 s / 45.5 s       | 66 ms / 127 ms  | 51 ms / 95 ms       |
+| [withastro/astro](https://github.com/withastro/astro)       | Turbo   | 48.0 s / 57.9 s       | 478 ms / 1.43 s | 249 ms / 1.38 s     |
+| [payloadcms/payload](https://github.com/payloadcms/payload) | Turbo   | 126.9 s / 127.5 s     | 3.44 s / 3.46 s | 256 ms / **237 ms** |
+| [medusajs/medusa](https://github.com/medusajs/medusa)       | Turbo   | 308 s / 315 s         | 3.86 s / 7.16 s | 947 ms / 3.29 s     |
+| [n8n-io/n8n](https://github.com/n8n-io/n8n)                 | Turbo   | 137.2 s / **133.7 s** | 8.27 s / 12.5 s | 842 ms / 1.36 s     |
+| [calcom/cal.com](https://github.com/calcom/cal.com)         | Turbo   | 245.7 s / 250.7 s     | 17.4 s / 19.9 s | 14.7 s / 18.5 s     |
+| [TanStack/query](https://github.com/TanStack/query)         | Nx      | 47.4 s / 55.1 s       | 656 ms / 1.98 s | 174 ms / 1.88 s     |
+| [strapi/strapi](https://github.com/strapi/strapi)           | Nx      | 238.2 s / 245.7 s     | 1.61 s / 3.94 s | 341 ms / 4.02 s     |
+| [novuhq/novu](https://github.com/novuhq/novu)               | Nx      | 291.2 s / 299.4 s     | 3.10 s / 9.05 s | 655 ms / 8.55 s     |
+| [TanStack/router](https://github.com/TanStack/router)       | Nx      | 199.9 s / 226.7 s     | 1.00 s / 3.33 s | 505 ms / 3.21 s     |
+| [refinedev/refine](https://github.com/refinedev/refine)     | Nx      | 96.2 s / 105.9 s      | 1.06 s / 1.19 s | 303 ms / 1.16 s     |
+
+**Bold** marks the other tool winning. Versions, revisions, scopes and
+harness per repo: [benchmarks](packages/vx/docs/benchmarks.md) (astro
+and refine as re-measured on 2026-09-27, the rest 2026-09-10 and -11).
+
 ## How it compares
 
-|                           | vx                                        | Turborepo                      | Nx               |
-| ------------------------- | ----------------------------------------- | ------------------------------ | ---------------- |
-| Fully cached, 1,090 pkgs¹ | **510 ms**                                | 760 ms                         | 3.59 s           |
-| Config                    | TypeScript, evaluated into the cache key  | JSON (static)                  | JSON (static)    |
-| Output ownership          | **Strict**: wiped before exec and restore | Additive (stale files survive) | Additive         |
-| Clean-tree hashing        | **Zero reads** (git index OIDs)           | git OIDs                       | re-hash / daemon |
-| Daemon required for speed | **No**                                    | Optional                       | Yes              |
-| Per-task sandbox          | **Yes**: kernel-level, opt-in             | No                             | No               |
-| Plugin API                | **Yes**: every pipeline stage             | No                             | Yes (TS-tied)    |
-| OTel CI/CD spans          | **Yes**: `otel()` plugin, no OTel SDK     | No                             | Paid             |
-| Install                   | **Single binary**; no Bun, Node optional  | npm + Node                     | npm + Node       |
+|                           | vx                                        | Turborepo                      | Nx               | moon²                          |
+| ------------------------- | ----------------------------------------- | ------------------------------ | ---------------- | ------------------------------ |
+| Fully cached, 1,090 pkgs¹ | **510 ms**                                | 760 ms                         | 3.59 s           | not measured                   |
+| Config                    | TypeScript, evaluated into the cache key  | JSON (static)                  | JSON (static)    | YAML, Pkl and others (static)  |
+| Output ownership          | **Strict**: wiped before exec and restore | Additive (stale files survive) | Additive         | Glob outputs pruned on restore |
+| Clean-tree hashing        | **Zero reads** (git index OIDs)           | git OIDs                       | re-hash / daemon | `git hash-object`              |
+| Daemon required for speed | **No**                                    | Optional                       | Yes              | Optional (experimental)        |
+| Per-task sandbox          | **Yes**: kernel-level, opt-in             | No                             | No               | No                             |
+| Plugin API                | **Yes**: every pipeline stage             | No                             | Yes (TS-tied)    | WASM toolchains, extensions    |
+| OTel CI/CD spans          | **Yes**: `otel()` plugin, no OTel SDK     | No                             | Paid             | No                             |
+| Install                   | **Single binary**; no Bun, Node optional  | npm + Node                     | npm + Node       | Single binary                  |
 
 ¹ Warm, nothing to rebuild, the graph charted above. Every gap, and
 when another tool is the better pick:
 [comparison](packages/vx/docs/comparison.md) ·
 [vx, Turborepo, Nx, Bazel](https://vznjs.github.io/vx/compare/).
 
+² From moon's own docs (2026-09-28): [config](https://github.com/moonrepo/moon/blob/master/website/docs/config/overview.mdx),
+[outputs](https://github.com/moonrepo/moon/blob/master/website/docs/config/project.mdx),
+[hashing](https://github.com/moonrepo/moon/blob/master/website/docs/guides/debug-task.mdx),
+[daemon](https://github.com/moonrepo/moon/blob/master/website/docs/guides/daemon.mdx),
+[plugins](https://github.com/moonrepo/moon/blob/master/website/docs/guides/wasm-plugins.mdx),
+[install](https://github.com/moonrepo/moon/blob/master/website/docs/install.mdx);
+they describe no per-task sandbox and no OpenTelemetry export. Already on
+moon: `moon()` runs it unchanged.
+
 ## Plugins
 
 Declared in `vx.workspace.ts`. Without one, vx runs and caches on this
 machine.
 
-| Package                                                    | What it adds                                                                  |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Run a Turbo or Nx repo unchanged; write configs; keep a Turbo or Nx cache     |
-| [`@vzn/vx-reapi`](packages/vx-reapi)                       | Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy) |
-| [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn              |
-| [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                |
-| [`@vzn/vx-github`](packages/vx-github)                     | GitHub Actions job summary and Checks API                                     |
-| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: a read-only MCP server for AI coding agents                         |
-| [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
+| Package                                                    | What it adds                                                                    |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [`@vzn/vx-migrate`](packages/vx-migrate)                   | Run a Turbo, Nx or moon repo unchanged; write configs; keep a Turbo or Nx cache |
+| [`@vzn/vx-reapi`](packages/vx-reapi)                       | Remote cache and remote execution over Bazel's REAPI (NativeLink, BuildBuddy)   |
+| [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn                |
+| [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                  |
+| [`@vzn/vx-github`](packages/vx-github)                     | GitHub Actions job summary and Checks API                                       |
+| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: a read-only MCP server for AI coding agents                           |
+| [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                            |
 
 Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
 [architecture](packages/vx/docs/architecture.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.100",
+  "version": "0.0.102",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.100",
-    "@vzn/vx-linux-arm64": "0.0.100",
-    "@vzn/vx-darwin-x64": "0.0.100",
-    "@vzn/vx-darwin-arm64": "0.0.100"
+    "@vzn/vx-linux-x64": "0.0.102",
+    "@vzn/vx-linux-arm64": "0.0.102",
+    "@vzn/vx-darwin-x64": "0.0.102",
+    "@vzn/vx-darwin-arm64": "0.0.102"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/bin.ts

@@ -1,6 +1,12 @@
 #!/usr/bin/env -S bun --no-env-file
 import { registerCoreAlias, run } from './cli/index.js'
-import { fsRefusalHint, isFsRefusal, isUserError } from './util/index.js'
+import {
+  fsRefusalHint,
+  isFsRefusal,
+  isOutOfFds,
+  isUserError,
+  OUT_OF_FDS_HINT,
+} from './util/index.js'
 
 // Every `import … from '@vzn/vx'` this process evaluates — a plugin
 // package, a workspace or project config — resolves to THIS core, not to
@@ -38,6 +44,8 @@ async function main(): Promise<void> {
       // it produced `vx: vx why: …` (walkthrough, 2026-09-04).
       const m = err.message
       process.stderr.write(m.startsWith('vx ') ? `${m}\n` : `vx: ${m}\n`)
+    } else if (isOutOfFds(err)) {
+      process.stderr.write(`vx: ${err.message} — ${OUT_OF_FDS_HINT}\n`)
     } else if (isFsRefusal(err)) {
       // The file system's refusal names the path; the stack would name
       // the verb's write, which the reader cannot act on either.

package/src/cache/inputs.ts

@@ -25,6 +25,7 @@ import {
   isExecutableMissing,
   isLiteralPattern,
   normalizeGlob,
+  shellArgv,
   slashBraceExpansions,
   taskGlob,
   UserError,
@@ -382,15 +383,16 @@ async function runRuntimeCommand(
   const prefix = binDirs.join(path.delimiter)
   let proc
   try {
-    proc = Bun.spawn(['sh', '-c', command], {
+    const argv = process.platform === 'win32' ? shellArgv(command) : ['sh', '-c', command]
+    proc = Bun.spawn(argv, {
       cwd,
       env: { ...process.env, PATH: ambient ? `${prefix}${path.delimiter}${ambient}` : prefix },
       stdin: 'ignore',
       stdout: 'pipe',
       stderr: 'pipe',
       // Its own group, so the probe's whole tree can be taken down with vx
-      // (`killProbesOnExit`).
-      detached: true,
+      // (`killProbesOnExit`). Windows has no groups.
+      detached: process.platform !== 'win32',
     })
   } catch (err) {
     // The probe runs through `sh -c` like a task: a box without sh names

package/src/cli/cache.ts

@@ -74,7 +74,7 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
         return { error: `--older-than requires a value (e.g. 30d, 24h, 60m)` }
       }
       const ms = parseDuration(v)
-      if (ms === null) return { error: `invalid duration: ${v}` }
+      if (ms === null) return { error: `invalid duration: ${v} (e.g. 30d, 24h, 60m)` }
       // `0d` evicts everything ever cached. That is far more often a
       // computed-to-zero retention than an intent, and no other flag
       // combination expresses "wipe the cache" — so refuse it and name
@@ -91,7 +91,7 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
         return { error: `--max-size requires a value (e.g. 500M, 1G)` }
       }
       const bytes = parseSize(v)
-      if (bytes === null) return { error: `invalid size: ${v}` }
+      if (bytes === null) return { error: `invalid size: ${v} (e.g. 500M, 1G)` }
       if (bytes === 0) {
         return {
           error: `--max-size 0 would evict every entry — delete the cache directory instead`,

package/src/cli/help.ts

@@ -44,7 +44,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx watch [OPTIONS] TASK [-- forwarded-args...]',
     '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--cache-dir <path>]',
     '  vx lock [--check]',
-    '  vx init [--dry] [--force] [--mjs]',
+    '  vx init [--dry] [--force] [--mjs] [--plugin <seam>]',
     '  vx upgrade [tag]',
     '  vx show [PROJECT[#TASK] | TASK] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
@@ -158,6 +158,9 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       TODO(vx-migrate) comments.',
     '      --dry            Print the generated files instead of writing them.',
     '      --force          Overwrite existing vx.config.* files.',
+    '      --plugin <seam>  Instead: write plugins/<seam>.ts, a runnable plugin, and its',
+    '                       test (executor, cache, telemetry, schedule, admit, commands,',
+    '                       project, graph, key).',
     '  From turbo.json or an Nx project graph: `bunx @vzn/vx-migrate` (its own package).',
     '',
     'Shell completions:',

package/src/cli/index.ts

@@ -40,6 +40,23 @@ export async function run(argv: readonly string[]): Promise<number> {
       // reference, which lists the plugin verbs.
       const verb = rest[0]
       const core = verb !== undefined && (CORE_VERBS as readonly string[]).includes(verb)
+      if (verb !== undefined && !core) {
+        // A name that is no verb here is the typo `vx rnu` is, not a request
+        // for the whole reference: it printed 145 lines and no hint.
+        const resolved = await resolvePluginCommand(verb)
+        const unknown = resolved === null || 'declaredVerbs' in resolved
+        if (unknown && MOVED_VERBS[verb] !== undefined) {
+          process.stderr.write(`${MOVED_VERBS[verb]}\n`)
+          return 1
+        }
+        if (unknown) {
+          const declared = resolved === null ? [] : resolved.declaredVerbs
+          process.stderr.write(
+            `vx help: unknown command: ${verb}${didYouMeanVerb(verb, declared)} (see \`vx help\`)\n`,
+          )
+          return 1
+        }
+      }
       printHelp(await pluginCommandHelp(), core ? verb : undefined)
       return 0
     }

package/src/cli/init.ts

@@ -2,9 +2,13 @@
 // per package from its package.json scripts, and the workspace file every
 // run needs. Turbo and Nx are not read here; a runner's own config beside
 // the scripts is the richer source, and `@vzn/vx-migrate` maps it.
+// `vx init --plugin <seam>` writes a runnable plugin for one seam and its
+// test instead (plugin-templates.ts, the examples the gate runs).
 
+import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 import { flagHint, seeHelp } from './help.js'
+import { PLUGIN_TEMPLATES } from './plugin-templates.js'
 import { isUserError, UserError } from '../util/index.js'
 import {
   applyMigration,
@@ -20,18 +24,31 @@ export interface InitArgs {
   force: boolean
   /** `vx.config.mjs` instead of `.ts` — see `ApplyMigrationArgs.format`. */
   mjs: boolean
+  /** `--plugin <seam>`: scaffold that seam's plugin instead of the workspace. */
+  plugin?: string
   error?: string
 }
 
 export function parseInitArgs(args: readonly string[]): InitArgs {
   const out: InitArgs = { dry: false, force: false, mjs: false }
-  for (const a of args) {
-    if (a === '--dry') out.dry = true
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    if (a === '--plugin' || a.startsWith('--plugin=')) {
+      const seam = a === '--plugin' ? args[++i] : a.slice('--plugin='.length)
+      const seams = Object.keys(PLUGIN_TEMPLATES).join(', ')
+      if (seam === undefined || !Object.hasOwn(PLUGIN_TEMPLATES, seam)) {
+        return {
+          ...out,
+          error: `--plugin takes a seam: one of ${seams}${seam === undefined ? '' : ` (got '${seam}')`}`,
+        }
+      }
+      out.plugin = seam
+    } else if (a === '--dry') out.dry = true
     else if (a === '--force') out.force = true
     else if (a === '--mjs') out.mjs = true
     else if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('init', a)}${seeHelp('init')}` }
-    else return { ...out, error: `unexpected argument: ${a}` }
+    else return { ...out, error: `unexpected argument: ${a}${seeHelp('init')}` }
   }
   return out
 }
@@ -42,6 +59,7 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx init: ${parsed.error}\n`)
     return 1
   }
+  if (parsed.plugin !== undefined) return scaffoldPlugin(parsed.plugin, parsed)
   const reads: LoadReads = new Map()
   // "a workspace from nowhere" still needs a package.json to start from,
   // and the lookup's own refusal named no next step.
@@ -96,3 +114,32 @@ export async function initCmd(args: readonly string[]): Promise<number> {
     format: parsed.mjs ? 'mjs' : 'ts',
   })
 }
+
+/** Write `plugins/<seam>.ts` and its test under the workspace root (the cwd when there is none). */
+async function scaffoldPlugin(seam: string, args: InitArgs): Promise<number> {
+  const root = await findWorkspaceRoot(process.cwd(), new Map()).catch(() => process.cwd())
+  const template = PLUGIN_TEMPLATES[seam]!
+  const files = [
+    [path.join('plugins', `${seam}.ts`), template.plugin],
+    [path.join('plugins', `${seam}.test.ts`), template.test],
+  ] as const
+  if (!args.force) {
+    for (const [rel] of files) {
+      if (await Bun.file(path.join(root, rel)).exists()) {
+        process.stderr.write(`vx init: ${rel} exists; --force overwrites it\n`)
+        return 1
+      }
+    }
+  }
+  if (!args.dry) {
+    await mkdir(path.join(root, 'plugins'), { recursive: true })
+    for (const [rel, text] of files) await Bun.write(path.join(root, rel), text)
+  }
+  const factory = /^export function (\w+)/m.exec(template.plugin)![1]!
+  process.stdout.write(
+    `${args.dry ? 'would write' : 'wrote'} ${files.map(([rel]) => rel).join(' and ')}\n` +
+      `Declare it in vx.workspace.ts: import { ${factory} } from './plugins/${seam}.ts', then plugins: [${factory}(…)]\n` +
+      `Test it: bun test plugins/${seam}.test.ts (needs @vzn/vx installed)\n`,
+  )
+  return 0
+}

package/src/cli/last.ts

@@ -17,7 +17,7 @@ import {
 import { formatElapsed, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
-import { resolveRunId } from './run-id.js'
+import { resolveRunId, shortRunId } from './run-id.js'
 
 interface LastArgs {
   runId?: string
@@ -51,7 +51,13 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
     if (a === '--format' || a.startsWith('--format=')) {
       const fv = a === '--format' ? args[++i] : a.slice(9)
       if (fv !== 'pretty' && fv !== 'json') {
-        return { ...out, error: `invalid --format: ${fv ?? ''} (expected pretty | json)` }
+        return {
+          ...out,
+          error:
+            fv === undefined || fv === ''
+              ? '--format requires a value (pretty | json)'
+              : `invalid --format: ${fv} (expected pretty | json)`,
+        }
       }
       out.format = fv
       continue
@@ -65,7 +71,8 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
     }
     if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('last', a)}${seeHelp('last')}` }
-    if (out.runId !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    if (out.runId !== undefined)
+      return { ...out, error: `unexpected argument: ${a}${seeHelp('last')}` }
     out.runId = a
   }
   // One run's replay or a list of runs, not both: the id was dropped.
@@ -195,7 +202,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
       for (const inv of invocations) {
         const verdict = inv.exitOk ? 'ok    ' : 'FAILED'
         process.stdout.write(
-          `${verdict} ${fmtWhen(inv.startedAt)}  ${inv.runId}  ` +
+          `${verdict} ${fmtWhen(inv.startedAt)}  ${shortRunId(db, inv.runId)}  ` +
             `${inv.taskCount} task${inv.taskCount === 1 ? '' : 's'} · ${inv.hitCount} hit${inv.hitCount === 1 ? '' : 's'}` +
             `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''} · ${fmtMs(inv.totalDurationMs)}  $ ${inv.command}\n`,
         )
@@ -236,6 +243,15 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''}`,
     )
     lines.push(...formatTaskRows(detail?.tasks ?? []))
+    // The next command after reading a failed run, with the arguments the
+    // run forwarded (a failure under `-- --shard 2` is that shard's).
+    const failed = (detail?.tasks ?? []).filter((t) => t.status === 'failed')
+    if (failed.length > 0) {
+      const at = inv.command.indexOf(' -- ')
+      const forwarded = at === -1 ? '' : inv.command.slice(at)
+      const ids = failed.map((t) => `${t.project}#${t.task}`).join(' ')
+      lines.push('', `  re-run what failed: vx run ${ids}${forwarded}`)
+    }
     process.stdout.write(`${lines.join('\n')}\n`)
     return 0
   } finally {

package/src/cli/plugin-templates.ts

@@ -0,0 +1,51 @@
+// Generated from packages/vx-plugin-examples/plugins by
+// tests/plugin-templates.unsafe.test.ts; edit the examples, then
+// VX_UPDATE_CONTRACT=1 that test. `vx init --plugin <seam>` writes these.
+
+export const PLUGIN_TEMPLATES: Readonly<Record<string, { plugin: string; test: string }>> = {
+  admit: {
+    plugin:
+      "// `admit`: whether a ready task starts now, beside what runs here. At most\n// one task of the named `task` runs at a time (say, one that holds a port).\n// Synchronous and cheap: it is asked at every dispatch.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function oneAtATime(task: string): VxPlugin {\n  const named = (id: string): boolean => id.endsWith(`#${task}`)\n  return definePlugin(import.meta, {\n    admit(node, ctx) {\n      return !named(node.id) || !ctx.running.some((r) => named(r.id))\n    },\n  })\n}\n",
+    test: "// A test for the example `admit` 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'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-admit-'))\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  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `oneAtATime()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'admit.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { oneAtATime } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\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('two tasks of the named task never overlap, even with two workers', async () => {\n  for (const name of ['a', 'b']) {\n    await pkg(name, `export default { tasks: { serve: { exec: { command: 'sleep 0.2' } } } }`)\n  }\n  await workspace(`oneAtATime('serve')`)\n  const order: string[] = []\n  await run({ cwd: root, tasks: ['serve'], log: log(order), handleSignals: false, concurrency: 2 })\n  // Each start is followed by its own end: no second start in between.\n  expect(order).toHaveLength(4)\n  expect(order[1]!.replace('end', 'start')).toBe(order[0]!)\n  expect(order[3]!.replace('end', 'start')).toBe(order[2]!)\n}, 20_000)\n",
+  },
+  cache: {
+    plugin:
+      "// `cache`: where artifacts live. A directory stands in for a remote store;\n// `LayeredCache` puts it behind the local cache, so a remote error is a\n// miss and a warning, never a failed run.\nimport { mkdir, rename } from 'node:fs/promises'\nimport path from 'node:path'\nimport { definePlugin, LayeredCache, type RemoteCacheLayer, type VxPlugin } from '@vzn/vx'\n\nclass DirRemote implements RemoteCacheLayer {\n  constructor(readonly endpoint: string) {}\n  async has(hash: string): Promise<boolean> {\n    return Bun.file(path.join(this.endpoint, hash)).exists()\n  }\n  async get(hash: string) {\n    const file = Bun.file(path.join(this.endpoint, hash))\n    return (await file.exists()) ? { body: file, durationMs: undefined } : null\n  }\n  async put(hash: string, body: Blob): Promise<void> {\n    await mkdir(this.endpoint, { recursive: true })\n    // Written aside, then renamed: a reader never sees half an artifact.\n    const tmp = path.join(this.endpoint, `.${hash}.${process.pid}`)\n    await Bun.write(tmp, body)\n    await rename(tmp, path.join(this.endpoint, hash))\n  }\n}\n\nexport function dirCache(dir: string): VxPlugin {\n  return definePlugin(import.meta, {\n    cache(ctx) {\n      return new LayeredCache(ctx.localCache, new DirRemote(dir), {\n        policy: ctx.policy,\n        onRemoteError: (err) => ctx.warn(`dir-cache: ${err.message}`),\n      })\n    },\n  })\n}\n",
+    test: "// A test for the example `cache` 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'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-cache-'))\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  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `dirCache()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'cache.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { dirCache } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\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('a run on an empty local cache restores from the directory', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'mkdir -p dist && echo built > dist/out.txt' },\n      cache: { inputs: { files: ['package.json'] }, outputs: { files: ['dist/**'] } },\n    } } }`,\n  )\n  await workspace(`dirCache(${JSON.stringify(path.join(root, 'remote'))})`)\n  const first = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(first.outcomes.map((o) => o.status)).toEqual(['success'])\n  await rm(path.join(root, '.vx'), { recursive: true, force: true })\n  await rm(path.join(dir, 'dist'), { recursive: true, force: true })\n  const second = await run({ cwd: root, tasks: ['build'], log: log(), handleSignals: false })\n  expect(second.outcomes.map((o) => o.status)).toEqual(['cache-hit-remote'])\n  expect(await Bun.file(path.join(dir, 'dist', 'out.txt')).text()).toBe('built\\n')\n}, 20_000)\n",
+  },
+  commands: {
+    plugin:
+      "// `commands`: a CLI verb. `vx cache-dir` prints where this workspace's cache\n// lives. The verb's return value is the exit code.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function cacheDirVerb(): VxPlugin {\n  return definePlugin(import.meta, {\n    commands: {\n      'cache-dir': {\n        description: \"print this workspace's cache directory\",\n        run(argv, ctx) {\n          if (argv.length > 0) {\n            console.error(`vx cache-dir: takes no arguments, got ${argv.join(' ')}`)\n            return 2\n          }\n          console.log(ctx.cacheDir)\n          return 0\n        },\n      },\n    },\n  })\n}\n",
+    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 = { workspaceRoot: '/ws', cacheDir: '/ws/.vx/cache', warn() {}, concurrency: 1 }\n\nit('prints the cache directory; an argument is exit 2', async () => {\n  const out = spyOn(console, 'log').mockImplementation(() => {})\n  const err = spyOn(console, 'error').mockImplementation(() => {})\n  try {\n    expect(await verb.run([], ctx)).toBe(0)\n    expect(out.mock.calls).toEqual([['/ws/.vx/cache']])\n    expect(await verb.run(['x'], ctx)).toBe(2)\n    expect(err.mock.calls).toEqual([['vx cache-dir: takes no arguments, got x']])\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, 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      const child = Bun.spawn(['sh', '-c', [req.command, ...req.forwardArgs].join(' ')], {\n        cwd: req.cwd,\n        env: req.env,\n        stdout: 'pipe',\n        stderr: 'pipe',\n        detached: true,\n      })\n      const stop = (): void => {\n        try {\n          process.kill(-child.pid, 'SIGTERM')\n        } catch {\n          // already gone\n        }\n      }\n      req.signal?.addEventListener('abort', stop, { once: true })\n      const drain = async (stream: ReadableStream<Uint8Array>, on: (s: string) => void) => {\n        const decoder = new TextDecoder()\n        let all = ''\n        for await (const chunk of stream) {\n          const text = decoder.decode(chunk, { stream: true })\n          all += text\n          on(text)\n        }\n        return all\n      }\n      const [stdout, stderr, exitCode] = await Promise.all([\n        drain(child.stdout, req.onStdout),\n        drain(child.stderr, req.onStderr),\n        child.exited,\n      ])\n      req.signal?.removeEventListener('abort', stop)\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'\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  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `shellExecutor()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'executor.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { shellExecutor } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\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: 300 } },\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",
+  },
+  graph: {
+    plugin:
+      "// `graph`: the run's edges. Every task named `task` waits for the one\n// before it in id order, so they run one after another across projects.\n// Core checks the edited graph again (a missing dep, a cycle).\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function chain(task: string): VxPlugin {\n  return definePlugin(import.meta, {\n    graph(nodes) {\n      const ids = [...nodes.keys()].filter((id) => id.endsWith(`#${task}`)).sort()\n      for (const [i, id] of ids.entries()) {\n        const prev = ids[i - 1]\n        const node = nodes.get(id)!\n        if (prev !== undefined && !node.deps.includes(prev)) node.deps.push(prev)\n      }\n    },\n  })\n}\n",
+    test: "// A test for the example `graph` 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 { planRun, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-graph-'))\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  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `chain()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'graph.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { chain } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\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('each named task waits on the one before it in id order', async () => {\n  for (const name of ['a', 'b', 'c']) {\n    await pkg(name, `export default { tasks: { build: { exec: { command: 'true' } } } }`)\n  }\n  await workspace(`chain('build')`)\n  const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n  expect(plan.tasks.map((t) => `${t.node.id} <- ${t.deps.join(',')}`).sort()).toEqual([\n    'a#build <- ',\n    'b#build <- a#build',\n    'c#build <- b#build',\n  ])\n}, 20_000)\n",
+  },
+  key: {
+    plugin:
+      "// `key`: extra cache-key material. The value of each named environment\n// variable is folded into every cached task's key and named in `vx why`,\n// so a change to it is a miss. An unset variable folds as ''.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function envKey(names: readonly string[]): VxPlugin {\n  return definePlugin(import.meta, {\n    key() {\n      return Object.fromEntries(names.map((n) => [n, process.env[n] ?? '']))\n    },\n  })\n}\n",
+    test: "// A test for the example `key` 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 { planRun, type Logger } from '@vzn/vx'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-key-'))\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  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `envKey()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'key.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { envKey } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\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(\"the variable's value moves the key; the same value keeps it\", async () => {\n  await pkg(\n    'a',\n    `export default { tasks: { build: {\n      exec: { command: 'true' },\n      cache: { inputs: { files: ['package.json'] }, outputs: { files: [] } },\n    } } }`,\n  )\n  await workspace(`envKey(['EXAMPLE_FLAG'])`)\n  const hash = async (value: string): Promise<string | undefined> => {\n    process.env['EXAMPLE_FLAG'] = value\n    try {\n      const plan = await planRun({ cwd: root, tasks: ['build'], log: log() })\n      return plan.tasks[0]!.hash\n    } finally {\n      delete process.env['EXAMPLE_FLAG']\n    }\n  }\n  const one = await hash('1')\n  expect(one).toBeDefined()\n  expect(await hash('1')).toBe(one)\n  expect(await hash('2')).not.toBe(one)\n}, 20_000)\n",
+  },
+  project: {
+    plugin:
+      "// `project`: a project's tasks. Every package.json script becomes a task of\n// the same name that runs it, unless the project already declares one.\n// Core re-validates each edit as it would the user's own config.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function scriptTasks(): VxPlugin {\n  return definePlugin(import.meta, {\n    project(config, ctx) {\n      const scripts = ctx.packageJson['scripts']\n      if (scripts === null || typeof scripts !== 'object') return\n      config.tasks ??= {}\n      for (const [name, command] of Object.entries(scripts)) {\n        if (typeof command !== 'string' || config.tasks[name] !== undefined) continue\n        config.tasks[name] = { exec: { command } }\n      }\n    },\n  })\n}\n",
+    test: "// A test for the example `project` 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'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-project-'))\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  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `scriptTasks()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'project.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { scriptTasks } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\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('a package.json script runs as a task; a declared task wins', async () => {\n  const dir = await pkg(\n    'a',\n    `export default { tasks: { build: { exec: { command: 'echo declared > build.txt' } } } }`,\n    { hello: 'echo hi > hello.txt', build: 'echo script > build.txt' },\n  )\n  await workspace('scriptTasks()')\n  const r = await run({ cwd: root, tasks: ['hello', 'build'], log: log(), handleSignals: false })\n  expect(r.outcomes.map((o) => `${o.node.id} ${o.status}`).sort()).toEqual([\n    'a#build success',\n    'a#hello success',\n  ])\n  expect(await Bun.file(path.join(dir, 'hello.txt')).text()).toBe('hi\\n')\n  expect(await Bun.file(path.join(dir, 'build.txt')).text()).toBe('declared\\n')\n}, 20_000)\n",
+  },
+  schedule: {
+    plugin:
+      "// `schedule`: which ready task runs first. Tasks named here outrank the rest;\n// earlier in the list, higher.\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function prioritize(ids: readonly string[]): VxPlugin {\n  return definePlugin(import.meta, {\n    schedule(nodes) {\n      const weights = new Map<string, number>()\n      for (const [i, id] of ids.entries()) if (nodes.has(id)) weights.set(id, 1e6 - i)\n      return weights\n    },\n  })\n}\n",
+    test: "// A test for the example `schedule` 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'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-schedule-'))\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  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `prioritize()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'schedule.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { prioritize } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\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('the named task starts first on one worker, whichever it is', async () => {\n  for (const name of ['a', 'b']) {\n    await pkg(name, `export default { tasks: { build: { exec: { command: 'true' } } } }`)\n  }\n  const first = async (id: string): Promise<string | undefined> => {\n    await workspace(`prioritize([${JSON.stringify(id)}])`)\n    const order: string[] = []\n    await run({\n      cwd: root,\n      tasks: ['build'],\n      log: log(order),\n      handleSignals: false,\n      concurrency: 1,\n    })\n    return order[0]\n  }\n  expect(await first('b#build')).toBe('start b#build')\n  expect(await first('a#build')).toBe('start a#build')\n}, 20_000)\n",
+  },
+  telemetry: {
+    plugin:
+      "// `telemetry`: who observes. One JSON line per run, appended to a file.\n// Observability never breaks a run: a sink that throws is switched off,\n// and `flush` is where slow I/O goes (core bounds it).\nimport { appendFile } from 'node:fs/promises'\nimport { definePlugin, type VxPlugin } from '@vzn/vx'\n\nexport function jsonlTelemetry(file: string): VxPlugin {\n  return definePlugin(import.meta, {\n    telemetry() {\n      const lines: string[] = []\n      return {\n        onRunSummary(s) {\n          lines.push(\n            JSON.stringify({ tasks: s.taskCount, failed: s.failedCount, cached: s.hitCount }),\n          )\n        },\n        async flush() {\n          if (lines.length > 0) await appendFile(file, lines.splice(0).join('\\n') + '\\n')\n        },\n      }\n    },\n  })\n}\n",
+    test: "// A test for the example `telemetry` 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'\n\nlet root: string\nbeforeEach(async () => {\n  root = await mkdtemp(path.join(os.tmpdir(), 'vx-plugin-telemetry-'))\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  await writeFile(path.join(dir, 'vx.config.mjs'), config)\n  return dir\n}\n\n/** A `vx.workspace.mjs` declaring `call`, e.g. `jsonlTelemetry()`, from the plugin file beside this test. */\nasync function workspace(call: string): Promise<void> {\n  const from = JSON.stringify(path.join(import.meta.dir, 'telemetry.ts'))\n  await writeFile(\n    path.join(root, 'vx.workspace.mjs'),\n    `import { jsonlTelemetry } from ${from}\\nexport default { plugins: [${call}] }\\n`,\n  )\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('appends one line per run', async () => {\n  await pkg('a', `export default { tasks: { hello: { exec: { command: 'true' } } } }`)\n  const file = path.join(root, 'runs.jsonl')\n  await workspace(`jsonlTelemetry(${JSON.stringify(file)})`)\n  await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  await run({ cwd: root, tasks: ['hello'], log: log(), handleSignals: false })\n  expect(await Bun.file(file).text()).toBe(\n    '{\"tasks\":1,\"failed\":0,\"cached\":0}\\n{\"tasks\":1,\"failed\":0,\"cached\":0}\\n',\n  )\n}, 20_000)\n",
+  },
+}

package/src/cli/run-id.ts

@@ -1,6 +1,5 @@
 // A run id as a user types it: the whole id, or a prefix of one, as git
-// takes a short sha. `vx last --list` prints 36-character ids; nobody
-// retypes one whole.
+// takes a short sha, and as `vx last --list` prints it.
 
 import type { Database } from 'bun:sqlite'
 import { UserError } from '../util/index.js'
@@ -25,3 +24,25 @@ export function resolveRunId(db: Database, raw: string, verb: string): string |
     `${verb}: run id ${raw} is the start of ${rows.length > 5 ? 'more than 5' : rows.length} runs — type more of it:\n${shown.join('\n')}`,
   )
 }
+
+/**
+ * The shortest prefix of `id` no other recorded run shares, and never
+ * shorter than 13 characters: a UUIDv7's first 13 are its millisecond
+ * clock, so a shorter one is part of a timestamp. Two indexed lookups, the
+ * ids sorted either side of it, since the longest prefix any id shares
+ * with it is shared with one of those two.
+ */
+export function shortRunId(db: Database, id: string): string {
+  const next = db.query('SELECT run_id FROM invocations WHERE run_id > ? ORDER BY run_id LIMIT 1')
+  const prev = db.query(
+    'SELECT run_id FROM invocations WHERE run_id < ? ORDER BY run_id DESC LIMIT 1',
+  )
+  let shared = 0
+  for (const row of [next.get(id), prev.get(id)] as Array<{ run_id: string } | null>) {
+    if (row === null) continue
+    let n = 0
+    while (n < id.length && id[n] === row.run_id[n]) n++
+    shared = Math.max(shared, n)
+  }
+  return id.slice(0, Math.max(13, shared + 1))
+}