@vzn/vx 0.0.100 → 0.0.101

package/README.md

@@ -96,15 +96,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 +112,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
@@ -170,15 +170,15 @@ when another tool is the better pick:
 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.101",
   "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.101",
+    "@vzn/vx-linux-arm64": "0.0.101",
+    "@vzn/vx-darwin-x64": "0.0.101",
+    "@vzn/vx-darwin-arm64": "0.0.101"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

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/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

@@ -65,7 +65,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.

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.ts

@@ -150,11 +150,19 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
     const a = before[i]
     if (a === '--filter' || a?.startsWith('--filter=')) {
       const v = a === '--filter' ? before[++i] : a.slice('--filter='.length)
-      if (v === undefined || v === '') return { ...out, error: `--filter requires a value` }
+      if (v === undefined || v === '')
+        return {
+          ...out,
+          error: `--filter requires a value (a project name, glob or path, e.g. --filter app)`,
+        }
       out.filters.push(v)
     } else if (a === '--concurrency' || a?.startsWith('--concurrency=')) {
       const v = a === '--concurrency' ? before[++i] : a.slice('--concurrency='.length)
-      if (v === undefined) return { ...out, error: `--concurrency requires a value` }
+      if (v === undefined)
+        return {
+          ...out,
+          error: `--concurrency requires a value (a positive integer, or a share of the cores such as 50%)`,
+        }
       const n = parseConcurrency(v)
       if (n === null)
         return {
@@ -193,7 +201,8 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.frozen = true
     } else if (a === '--retry' || a?.startsWith('--retry=')) {
       const v = a === '--retry' ? before[++i] : a.slice('--retry='.length)
-      if (v === undefined) return { ...out, error: `--retry requires a value` }
+      if (v === undefined)
+        return { ...out, error: `--retry requires a value (a non-negative integer)` }
       const n = parseDecimalInt(v)
       if (n === null) {
         return { ...out, error: `--retry must be a non-negative integer, got: ${v}` }
@@ -201,7 +210,8 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.retries = n
     } else if (a === '--timeout' || a?.startsWith('--timeout=')) {
       const v = a === '--timeout' ? before[++i] : a.slice('--timeout='.length)
-      if (v === undefined) return { ...out, error: `--timeout requires a value` }
+      if (v === undefined)
+        return { ...out, error: `--timeout requires a value (a positive integer, in ms)` }
       const n = parseDecimalInt(v)
       if (n !== null && n > MAX_TIMEOUT_MS) {
         // Not "effectively no limit" — setTimeout reduces a delay past 2^31-1
@@ -243,7 +253,11 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.cacheDir = v
     } else if (a === '--cache' || a?.startsWith('--cache=')) {
       const v = a === '--cache' ? before[++i] : a.slice('--cache='.length)
-      if (v === undefined) return { ...out, error: `--cache requires a value` }
+      if (v === undefined)
+        return {
+          ...out,
+          error: `--cache requires a value (a spec like local:r, local:rw, remote:, or local:,remote:rw)`,
+        }
       // A spec with no segment at all applies NOTHING, so `--cache=`
       // (an empty shell var, or someone reaching for "no cache") left
       // all four axes ON — the opposite of the intent. Reject it; an
@@ -283,7 +297,8 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.continueMode = v
     } else if (a === '--verbosity' || a?.startsWith('--verbosity=')) {
       const v = a === '--verbosity' ? before[++i] : a.slice('--verbosity='.length)
-      if (v === undefined) return { ...out, error: `--verbosity requires a value` }
+      if (v === undefined)
+        return { ...out, error: `--verbosity requires a value (a non-negative integer)` }
       const n = parseDecimalInt(v)
       if (n === null) return { ...out, error: `invalid verbosity: ${v} (a non-negative integer)` }
       out.verbosity = n
@@ -317,7 +332,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       out.affected = a.slice('--affected='.length)
     } else if (a === '--tag' || a?.startsWith('--tag=')) {
       const raw = a === '--tag' ? before[++i] : a.slice('--tag='.length)
-      if (raw === undefined) return { ...out, error: `${a} requires a value` }
+      if (raw === undefined) return { ...out, error: `${a} requires a value (k=v)` }
       // Split on the FIRST `=` so values may contain `=` (e.g. a URL).
       const eq = raw.indexOf('=')
       if (eq <= 0) return { ...out, error: `invalid --tag (expected k=v): ${raw}` }

package/src/cli/show.ts

@@ -35,7 +35,8 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
     else if (a.startsWith('--format=')) format = a.slice('--format='.length)
     else if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('show', a)}${seeHelp('show')}` }
-    else if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    else if (out.target !== undefined)
+      return { ...out, error: `unexpected argument: ${a}${seeHelp('show')}` }
     // An empty name is a part of every name: its "did you mean" listed the
     // whole workspace.
     else if (a === '') return { ...out, error: 'empty target (omit it to list every project)' }

package/src/cli/watch-set.ts

@@ -0,0 +1,182 @@
+// What `vx watch` watches: the projects a cycle can run, what their configs
+// declare (outputs to ignore, inputs, workspace-wide globs) and the member
+// directories a package glob can grow. Read at start and again whenever an
+// edit reshapes the set; the loop in watch.ts decides when.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import type { ProjectConfig } from '../config.js'
+import {
+  buildPackageGraph,
+  configImports,
+  loadProjectConfig,
+  WORKSPACE_CONFIG_FILENAMES,
+  type ProjectEntry,
+  type ProjectMeta,
+} from '../workspace/index.js'
+import { taskEdges, taskEdgesFrom } from './select.js'
+import { type CliLoadOptions, loadCliProjects } from './workspace-config.js'
+
+/**
+ * The projects a cycle can run, so both watcher arms cover the same dirs:
+ * the scope plus its transitive dependencies through the package graph
+ * and the cross-project `dependsOn` edges the task graph adds
+ * (`e2e` → `app` from `dependsOn: ['app#build']`). Before this, the
+ * per-project arm watched the filter's answer only, so
+ * `vx watch build --filter app` never re-ran on a `lib` edit that
+ * `vx run build --filter app` would have rebuilt. A whole-workspace
+ * scope is every project already and walks nothing. A config the loader
+ * rejects contributes no edges here; the run that just happened said so.
+ */
+export async function watchedProjects(
+  workspaceRoot: string,
+  allProjects: readonly ProjectMeta[],
+  scope: readonly ProjectMeta[],
+  load: CliLoadOptions = {},
+  staged: ReadonlyMap<string, ProjectEntry> | null = null,
+): Promise<ProjectMeta[]> {
+  if (scope.length === allProjects.length) return [...allProjects]
+  let edges: Map<string, string[]> | undefined
+  try {
+    edges =
+      staged !== null
+        ? taskEdgesFrom(staged)
+        : (await taskEdges(workspaceRoot, allProjects, load)).edges
+  } catch {
+    edges = undefined
+  }
+  const graph = buildPackageGraph([...allProjects], edges)
+  const names = new Set(scope.map((p) => p.name))
+  for (const p of scope) for (const d of graph.transitiveDeps(p.name)) names.add(d)
+  return allProjects.filter((p) => names.has(p.name))
+}
+
+/** What one sweep over every config tells the loop. */
+export interface ConfigSweep {
+  workspaceWide: boolean
+  workspaceInputs: string[]
+  outputs: Map<string, string[]>
+  /** Declared input globs per directory they are relative to, the counterweight to `outputs`. */
+  inputs: Map<string, string[]>
+  /** Projects with a task that has a command and no cache: it reads what it likes, git-ignored files included. */
+  uncached: Set<string>
+  /** Files the project configs import by relative path (item 949). */
+  configImports: string[]
+  /** Files the workspace config imports by relative path: loaded once per process (item 949). */
+  workspaceConfigImports: string[]
+  /** The staged load the sweep read, when the run path's load succeeded; `watchedProjects` reads the same one. */
+  staged: Map<string, ProjectEntry> | null
+}
+
+/**
+ * One sweep over every config for the two things the loop needs: whether
+ * any task declares `inputs.workspaceFiles` — globs with no project
+ * prefix, so the whole tree has to be watched — and every project's
+ * declared outputs, so their writes are not taken for edits. The run
+ * path's load (`loadProjects`): the plugin `project` stage applies, so an
+ * output a plugin gave a config-less package is ignored like a declared
+ * one, and a pure config is served from its cached evaluation rather than
+ * re-evaluated in a worker. A config that fails to load is out of this
+ * concern's scope — the run that just happened already said so, or will —
+ * and the sweep falls back to the files that do load, one by one.
+ */
+export async function sweepConfigs(
+  projects: readonly ProjectMeta[],
+  workspaceRoot: string,
+  load: CliLoadOptions = {},
+): Promise<ConfigSweep> {
+  const outputs = new Map<string, string[]>()
+  const inputs = new Map<string, string[]>()
+  const addTo = (
+    into: Map<string, string[]>,
+    dir: string,
+    globs: readonly string[] | undefined,
+  ): void => {
+    if (globs === undefined || globs.length === 0) return
+    into.set(dir, [...(into.get(dir) ?? []), ...globs])
+  }
+  const add = (dir: string, globs: readonly string[] | undefined): void =>
+    addTo(outputs, dir, globs)
+  const workspaceInputs = new Set<string>()
+  const uncached = new Set<string>()
+  const fold = (dir: string, config: ProjectConfig): void => {
+    for (const task of Object.values(config.tasks ?? {})) {
+      if (task.cache === undefined && task.exec !== undefined && task.exec.persistent === undefined)
+        uncached.add(dir)
+      for (const g of task.cache?.inputs?.workspaceFiles ?? []) workspaceInputs.add(g)
+      addTo(inputs, dir, task.cache?.inputs?.files)
+      addTo(inputs, workspaceRoot, task.cache?.inputs?.workspaceFiles)
+      add(dir, task.cache?.outputs?.files)
+      add(workspaceRoot, task.cache?.outputs?.workspaceFiles)
+    }
+  }
+  const result = (staged: Map<string, ProjectEntry> | null): ConfigSweep => ({
+    workspaceWide: workspaceInputs.size > 0,
+    workspaceInputs: [...workspaceInputs],
+    outputs,
+    inputs,
+    uncached,
+    configImports: [...projectImports],
+    workspaceConfigImports: [...wsImports],
+    staged,
+  })
+  const projectImports = new Set<string>()
+  const wsImports = new Set<string>()
+  await Promise.all([
+    ...projects.map(async (p) => {
+      if (p.configPath === null) return
+      for (const f of await configImports(p.configPath)) projectImports.add(f)
+    }),
+    ...WORKSPACE_CONFIG_FILENAMES.map(async (name) => {
+      for (const f of await configImports(path.join(workspaceRoot, name))) wsImports.add(f)
+    }),
+  ])
+  let staged: Map<string, ProjectEntry> | null = null
+  try {
+    staged = await loadCliProjects(workspaceRoot, projects, 'all', load)
+  } catch {
+    staged = null
+  }
+  if (staged !== null) {
+    for (const p of staged.values()) fold(p.dir, p.config)
+    return result(staged)
+  }
+  await Promise.all(
+    projects.map(async (p) => {
+      if (p.configPath === null) return
+      try {
+        fold(p.dir, await loadProjectConfig(p.configPath))
+      } catch {
+        // broken config — out of this concern's scope
+      }
+    }),
+  )
+  return result(null)
+}
+
+/**
+ * The directory entries under a package glob's directory that can be
+ * members: directories (or links) whose name is not dotted and not
+ * `node_modules`, the same rule discovery applies. A watcher on that
+ * directory reacts only when this set changes.
+ */
+export function memberEntries(base: string): ReadonlySet<string> {
+  const out = new Set<string>()
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(base, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || e.name === 'node_modules') continue
+    if (e.isDirectory() || e.isSymbolicLink()) out.add(e.name)
+  }
+  return out
+}
+
+export function sameMembers(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+  if (a.size !== b.size) return false
+  for (const name of a) if (!b.has(name)) return false
+  return true
+}

package/src/cli/watch.ts

@@ -25,22 +25,15 @@ import {
   type RunOptions,
 } from '../orchestrator/index.js'
 import {
-  buildPackageGraph,
   findWorkspaceRoot,
   type LoadReads,
   listProjects,
-  loadProjectConfig,
   loadWorkspace,
   LOCKFILE_NAME,
   memberBaseDirs,
-  WORKSPACE_CONFIG_FILENAMES,
-  configImports,
-  type ProjectEntry,
   type ProjectMeta,
 } from '../workspace/index.js'
-import type { ProjectConfig } from '../config.js'
-import { type CliLoadOptions, loadCliProjects, loadCliWorkspace } from './workspace-config.js'
-import { taskEdges, taskEdgesFrom } from './select.js'
+import { type CliLoadOptions, loadCliWorkspace } from './workspace-config.js'
 import {
   gitIgnored,
   isIgnoredWatchPath,
@@ -59,6 +52,7 @@ import {
   WATCH_PROBE_TIMEOUT_MS,
   type WatchHandle,
 } from './watch-fs.js'
+import { memberEntries, sameMembers, sweepConfigs, watchedProjects } from './watch-set.js'
 
 /** Wait this long after the last filesystem event before re-running. */
 const DEBOUNCE_MS = 150
@@ -264,151 +258,6 @@ export async function watchCmd(args: readonly string[]): Promise<number> {
   })
 }
 
-/**
- * The projects a cycle can run, so both watcher arms cover the same dirs:
- * the scope plus its transitive dependencies through the package graph
- * and the cross-project `dependsOn` edges the task graph adds
- * (`e2e` → `app` from `dependsOn: ['app#build']`). Before this, the
- * per-project arm watched the filter's answer only, so
- * `vx watch build --filter app` never re-ran on a `lib` edit that
- * `vx run build --filter app` would have rebuilt. A whole-workspace
- * scope is every project already and walks nothing. A config the loader
- * rejects contributes no edges here; the run that just happened said so.
- */
-export async function watchedProjects(
-  workspaceRoot: string,
-  allProjects: readonly ProjectMeta[],
-  scope: readonly ProjectMeta[],
-  load: CliLoadOptions = {},
-  staged: ReadonlyMap<string, ProjectEntry> | null = null,
-): Promise<ProjectMeta[]> {
-  if (scope.length === allProjects.length) return [...allProjects]
-  let edges: Map<string, string[]> | undefined
-  try {
-    edges =
-      staged !== null
-        ? taskEdgesFrom(staged)
-        : (await taskEdges(workspaceRoot, allProjects, load)).edges
-  } catch {
-    edges = undefined
-  }
-  const graph = buildPackageGraph([...allProjects], edges)
-  const names = new Set(scope.map((p) => p.name))
-  for (const p of scope) for (const d of graph.transitiveDeps(p.name)) names.add(d)
-  return allProjects.filter((p) => names.has(p.name))
-}
-
-/**
- * One sweep over every config for the two things the loop needs: whether
- * any task declares `inputs.workspaceFiles` — globs with no project
- * prefix, so the whole tree has to be watched — and every project's
- * declared outputs, so their writes are not taken for edits. The run
- * path's load (`loadProjects`): the plugin `project` stage applies, so an
- * output a plugin gave a config-less package is ignored like a declared
- * one, and a pure config is served from its cached evaluation rather than
- * re-evaluated in a worker. A config that fails to load is out of this
- * concern's scope — the run that just happened already said so, or will —
- * and the sweep falls back to the files that do load, one by one.
- */
-export async function sweepConfigs(
-  projects: readonly ProjectMeta[],
-  workspaceRoot: string,
-  load: CliLoadOptions = {},
-): Promise<{
-  workspaceWide: boolean
-  workspaceInputs: string[]
-  outputs: Map<string, string[]>
-  /** Declared input globs per directory they are relative to, the counterweight to `outputs`. */
-  inputs: Map<string, string[]>
-  /** Projects with a task that has a command and no cache: it reads what it likes, git-ignored files included. */
-  uncached: Set<string>
-  /** Files the project configs import by relative path (item 949). */
-  configImports: string[]
-  /** Files the workspace config imports by relative path: loaded once per process (item 949). */
-  workspaceConfigImports: string[]
-  /** The staged load the sweep read, when the run path's load succeeded; `watchedProjects` reads the same one. */
-  staged: Map<string, ProjectEntry> | null
-}> {
-  const outputs = new Map<string, string[]>()
-  const inputs = new Map<string, string[]>()
-  const addTo = (
-    into: Map<string, string[]>,
-    dir: string,
-    globs: readonly string[] | undefined,
-  ): void => {
-    if (globs === undefined || globs.length === 0) return
-    into.set(dir, [...(into.get(dir) ?? []), ...globs])
-  }
-  const add = (dir: string, globs: readonly string[] | undefined): void =>
-    addTo(outputs, dir, globs)
-  const workspaceInputs = new Set<string>()
-  const uncached = new Set<string>()
-  const fold = (dir: string, config: ProjectConfig): void => {
-    for (const task of Object.values(config.tasks ?? {})) {
-      if (task.cache === undefined && task.exec !== undefined && task.exec.persistent === undefined)
-        uncached.add(dir)
-      for (const g of task.cache?.inputs?.workspaceFiles ?? []) workspaceInputs.add(g)
-      addTo(inputs, dir, task.cache?.inputs?.files)
-      addTo(inputs, workspaceRoot, task.cache?.inputs?.workspaceFiles)
-      add(dir, task.cache?.outputs?.files)
-      add(workspaceRoot, task.cache?.outputs?.workspaceFiles)
-    }
-  }
-  const result = (
-    staged: Map<string, ProjectEntry> | null,
-  ): {
-    workspaceWide: boolean
-    workspaceInputs: string[]
-    outputs: Map<string, string[]>
-    inputs: Map<string, string[]>
-    uncached: Set<string>
-    configImports: string[]
-    workspaceConfigImports: string[]
-    staged: Map<string, ProjectEntry> | null
-  } => ({
-    workspaceWide: workspaceInputs.size > 0,
-    workspaceInputs: [...workspaceInputs],
-    outputs,
-    inputs,
-    uncached,
-    configImports: [...projectImports],
-    workspaceConfigImports: [...wsImports],
-    staged,
-  })
-  const projectImports = new Set<string>()
-  const wsImports = new Set<string>()
-  await Promise.all([
-    ...projects.map(async (p) => {
-      if (p.configPath === null) return
-      for (const f of await configImports(p.configPath)) projectImports.add(f)
-    }),
-    ...WORKSPACE_CONFIG_FILENAMES.map(async (name) => {
-      for (const f of await configImports(path.join(workspaceRoot, name))) wsImports.add(f)
-    }),
-  ])
-  let staged: Map<string, ProjectEntry> | null = null
-  try {
-    staged = await loadCliProjects(workspaceRoot, projects, 'all', load)
-  } catch {
-    staged = null
-  }
-  if (staged !== null) {
-    for (const p of staged.values()) fold(p.dir, p.config)
-    return result(staged)
-  }
-  await Promise.all(
-    projects.map(async (p) => {
-      if (p.configPath === null) return
-      try {
-        fold(p.dir, await loadProjectConfig(p.configPath))
-      } catch {
-        // broken config — out of this concern's scope
-      }
-    }),
-  )
-  return result(null)
-}
-
 interface WatchLoopArgs {
   opts: RunOptions
   /** The persistent tasks the initial run left running; the next cycle stops them before it starts. */
@@ -1099,30 +948,3 @@ export function pendingAfterCycle(
   const [abs, label] = [...pending][0]!
   return [abs, label]
 }
-
-/**
- * The directory entries under a package glob's directory that can be
- * members: directories (or links) whose name is not dotted and not
- * `node_modules`, the same rule discovery applies. A watcher on that
- * directory reacts only when this set changes.
- */
-export function memberEntries(base: string): ReadonlySet<string> {
-  const out = new Set<string>()
-  let entries: fs.Dirent[]
-  try {
-    entries = fs.readdirSync(base, { withFileTypes: true })
-  } catch {
-    return out
-  }
-  for (const e of entries) {
-    if (e.name.startsWith('.') || e.name === 'node_modules') continue
-    if (e.isDirectory() || e.isSymbolicLink()) out.add(e.name)
-  }
-  return out
-}
-
-function sameMembers(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
-  if (a.size !== b.size) return false
-  for (const name of a) if (!b.has(name)) return false
-  return true
-}

package/src/cli/why.ts

@@ -86,7 +86,8 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
     }
     if (a.startsWith('-'))
       return { ...out, error: `unknown flag: ${a}${flagHint('why', a)}${seeHelp('why')}` }
-    if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    if (out.target !== undefined)
+      return { ...out, error: `unexpected argument: ${a}${seeHelp('why')}` }
     // Empty is no task: read as a query it matched every recorded one.
     if (a !== '') out.target = a
   }

package/src/orchestrator/admission.ts

@@ -64,8 +64,9 @@ export function taintTracker(
     u !== undefined && (failed(u) || taintOf(u.node.id))
   // Post-order over the settled deps with an explicit stack: a chain of
   // restore-tier hits is judged in one ask, and a recursion would take a
-  // frame per hop. Memoized once every dep has settled; until then the
-  // answer may still grow.
+  // frame per hop. Taint is final at once; a clean answer only once every
+  // dep has settled and its own answer is kept, since a dep below a settled
+  // one may still fail (C-23).
   const taintOf = (root: string): boolean => {
     const known = memo.get(root)
     if (known !== undefined) return known
@@ -95,7 +96,7 @@ export function taintTracker(
           return u !== undefined && (failed(u) || valueOf(d) === true)
         })
       local.set(id, taint)
-      if (taint || deps.every((d) => outcomes.has(d))) memo.set(id, taint)
+      if (taint || deps.every((d) => outcomes.has(d) && memo.has(d))) memo.set(id, taint)
     }
     return valueOf(root)!
   }

package/src/workspace/config-imports.ts

@@ -135,6 +135,14 @@ export function unprovidedBareImports(
   return out
 }
 
+/**
+ * A textual pass before the scan: a relative specifier opens with a quoted
+ * `./` or `../`, or spells one with an escape, and most configs hold
+ * neither, so the scan is skipped for them (D-23). A candidate in a comment
+ * or string still goes to the scan, which decides.
+ */
+const RELATIVE_CANDIDATE = /["'`](?:\.\.?\/|[^"'`\n]*\\)/
+
 /**
  * Absolute resolved targets of the RELATIVE specifiers in `source`; one that
  * does not resolve contributes the paths it names.
@@ -145,6 +153,7 @@ export function unprovidedBareImports(
  * which is correct: an erased import cannot move a resolved value.
  */
 function scanLocalImports(source: string, fromDir: string, loader: 'ts' | 'js'): string[] {
+  if (!RELATIVE_CANDIDATE.test(source)) return []
   let specifiers: string[]
   try {
     specifiers = scanner(loader)
@@ -246,26 +255,35 @@ export async function configImportOwners(a: ConfigImportOwnersArgs): Promise<Set
   // changed set answers every root at once, instead of a walk per root.
   const importedBy = new Map<string, string[]>()
   const visited = new Set<string>()
-  const queue = [...roots.keys()]
-  while (queue.length > 0) {
-    const file = queue.pop()!
-    if (visited.has(file)) continue
-    visited.add(file)
-    let source: string
-    try {
-      source = await Bun.file(file).text()
-    } catch {
-      continue // unreadable: no edges, and not this pass's problem to report
-    }
-    const loader = TS_EXT.has(path.extname(file)) ? 'ts' : 'js'
-    for (const target of scanLocalImports(source, path.dirname(file), loader)) {
-      if (!target.startsWith(workspaceRoot + path.sep)) continue
-      if (target.split(path.sep).includes('node_modules')) continue
-      const list = importedBy.get(target)
-      if (list) list.push(file)
-      else importedBy.set(target, [file])
-      // Descend ONLY through unowned files — see the header.
-      if (ownerOf(target, dirToName) === undefined) queue.push(target)
+  // A level at a time, its files read together: one awaited read per
+  // config put 5,000 of them 200 ms behind (D-23).
+  let frontier = [...roots.keys()]
+  while (frontier.length > 0) {
+    const read = await Promise.all(
+      frontier.map(async (file) => {
+        if (visited.has(file)) return null
+        visited.add(file)
+        try {
+          return { file, source: await Bun.file(file).text() }
+        } catch {
+          return null // unreadable: no edges, and not this pass's problem to report
+        }
+      }),
+    )
+    frontier = []
+    for (const entry of read) {
+      if (entry === null) continue
+      const { file, source } = entry
+      const loader = TS_EXT.has(path.extname(file)) ? 'ts' : 'js'
+      for (const target of scanLocalImports(source, path.dirname(file), loader)) {
+        if (!target.startsWith(workspaceRoot + path.sep)) continue
+        if (target.split(path.sep).includes('node_modules')) continue
+        const list = importedBy.get(target)
+        if (list) list.push(file)
+        else importedBy.set(target, [file])
+        // Descend ONLY through unowned files — see the header.
+        if (ownerOf(target, dirToName) === undefined) frontier.push(target)
+      }
     }
   }