@vzn/vx 0.0.18 → 0.0.22

package/src/cli/init.ts

@@ -0,0 +1,87 @@
+// `vx init [--dry] [--force] [--mjs]` — a workspace from nowhere: one vx.config.ts
+// 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.
+
+import path from 'node:path'
+import { seeHelp } from './help.js'
+import {
+  applyMigration,
+  findWorkspaceRoot,
+  type LoadReads,
+  listProjects,
+  loadWorkspace,
+  migrateScripts,
+} from '../workspace/index.js'
+
+export interface InitArgs {
+  dry: boolean
+  force: boolean
+  /** `vx.config.mjs` instead of `.ts` — see `ApplyMigrationArgs.format`. */
+  mjs: boolean
+  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
+    else if (a === '--force') out.force = true
+    else if (a === '--mjs') out.mjs = true
+    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('init')}` }
+    else return { ...out, error: `unexpected argument: ${a}` }
+  }
+  return out
+}
+
+export async function initCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseInitArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx init: ${parsed.error}\n`)
+    return 1
+  }
+  const reads: LoadReads = new Map()
+  const root = await findWorkspaceRoot(process.cwd(), reads)
+  const metas = await listProjects(await loadWorkspace(root, reads))
+  // `init` reads scripts only; a runner's own config beside them is the
+  // richer source (dependsOn, inputs, outputs) and was ignored without a
+  // word — the walkthrough on a Turbo repo (2026-09-09) got the scripts'
+  // TODOs and none of the edges turbo.json already declared.
+  const notes: string[] = []
+  // Turbo 2.5+ reads `turbo.jsonc` as well (item 938).
+  let turbo: string | undefined
+  for (const name of ['turbo.json', 'turbo.jsonc']) {
+    if (await Bun.file(path.join(root, name)).exists()) {
+      turbo = name
+      break
+    }
+  }
+  if (turbo !== undefined) {
+    notes.push(
+      `${turbo} found and not read — ` +
+        '`bunx @vzn/vx-migrate` maps it (dependsOn, inputs, ' +
+        'outputs), or `plugins: [turbo()]` from @vzn/vx-migrate runs it with nothing written',
+    )
+  } else if (
+    (await Bun.file(path.join(root, 'nx.json')).exists()) ||
+    (await Bun.file(path.join(root, '.nx', 'workspace-data', 'project-graph.json')).exists())
+  ) {
+    notes.push(
+      'an Nx workspace found and not read — `bunx @vzn/vx-migrate --from nx` maps its ' +
+        'exported project graph, or `plugins: [nx()]` from @vzn/vx-migrate runs it with ' +
+        'nothing written',
+    )
+  }
+  return applyMigration({
+    root,
+    metas,
+    plan: migrateScripts(metas),
+    source: 'package.json scripts',
+    verb: 'vx init',
+    dry: parsed.dry,
+    force: parsed.force,
+    init: true,
+    notes,
+    format: parsed.mjs ? 'mjs' : 'ts',
+  })
+}

package/src/cli/last.ts

@@ -4,15 +4,26 @@
 // history in cache.db is the only replay surface, and this verb reads it.
 // Read-only — no config evaluation, no re-hash, no cache probe.
 
-import { Cache } from '../cache/index.js'
-import { getInvocation, getRun, listInvocations } from '../orchestrator/index.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { formatBytes } from './format.js'
+import { seeHelp } from './help.js'
+import {
+  exitSignal,
+  getInvocation,
+  getRun,
+  listInvocations,
+  type RunSummaryRow,
+} from '../orchestrator/index.js'
 import { UserError } from '../util/index.js'
-import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
+import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 
 interface LastArgs {
   runId?: string
   list?: number
   format: 'pretty' | 'json'
+  /** `--cache-dir`: read the history a run with the same flag wrote. */
+  cacheDir?: string
   error?: string
 }
 
@@ -21,7 +32,14 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
   for (let i = 0; i < args.length; i++) {
     const a = args[i]!
     if (a === '--list' || a.startsWith('--list=')) {
-      const lv = a === '--list' ? '10' : a.slice(7)
+      // `--list 5` is the count, like every other value flag's space form:
+      // it read as a run id, which `--list` then ignored, and ten runs came
+      // back (item 899). A run id is never a bare integer, so the next
+      // argument is taken only when it is one.
+      const next = args[i + 1]
+      const spaced = a === '--list' && next !== undefined && /^\d+$/.test(next)
+      const lv = a === '--list' ? (spaced ? next : '10') : a.slice(7)
+      if (spaced) i++
       const n = Number(lv)
       if (!Number.isInteger(n) || n < 1 || n > 500) {
         return { ...out, error: `invalid --list: ${lv} (expected 1..500)` }
@@ -37,10 +55,24 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       out.format = fv
       continue
     }
-    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
+    const cd = parseCacheDirFlag(args, i)
+    if (cd !== null) {
+      if ('error' in cd) return { ...out, error: cd.error }
+      out.cacheDir = cd.cacheDir
+      i = cd.next
+      continue
+    }
+    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('last')}` }
     if (out.runId !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     out.runId = a
   }
+  // One run's replay or a list of runs, not both: the id was dropped.
+  if (out.runId !== undefined && out.list !== undefined) {
+    return {
+      ...out,
+      error: `a run id and --list do not combine: replay ${out.runId}, or list runs`,
+    }
+  }
   return out
 }
 
@@ -53,13 +85,103 @@ function fmtMs(ms: number): string {
   return `${m}m ${Math.round((ms - m * 60_000) / 1000)}s`
 }
 
+/**
+ * What an executed task used — its peak RSS and its CPU parallelism (CPU
+ * time over wall time) — as the runner recorded them. This is the number
+ * `@vzn/vx-schedule-history` reserves from, so the replay shows it where
+ * a developer can read it; a hit spent nothing and shows nothing.
+ */
+function fmtUsage(t: {
+  cpuMs: number | null
+  peakRssBytes: number | null
+  durationMs: number
+}): string {
+  const parts: string[] = []
+  if (t.peakRssBytes !== null) parts.push(formatBytes(t.peakRssBytes))
+  if (t.cpuMs !== null && t.durationMs > 0)
+    parts.push(`${(t.cpuMs / t.durationMs).toFixed(1)}× cpu`)
+  return parts.length > 0 ? `  ${parts.join(' · ')}` : ''
+}
+
+/**
+ * Why a row failed or was skipped, as the run's own footer said it (the
+ * v27 columns): a timeout or a never-ready server instead of the signal
+ * their exit stands for, the sandbox's violation count, a skip's blocker.
+ * Older rows carry none and read as before.
+ */
+function reasonParts(t: RunSummaryRow): string {
+  const parts: string[] = []
+  if (t.status === 'failed') {
+    if (t.notReady !== null) {
+      parts.push(
+        `never ready: ${t.notReady === 'timeout' ? 'timed out' : t.notReady === 'exited' ? 'exited' : 'spawn failed'}`,
+      )
+    } else if (t.timedOut === true) {
+      parts.push('timed out')
+    } else {
+      const signal = exitSignal(t.exitCode)
+      if (signal !== undefined) parts.push(`128 + ${signal}`)
+    }
+    if (t.sandboxViolations !== null && t.sandboxViolations > 0) {
+      parts.push(`${t.sandboxViolations} sandbox violation${t.sandboxViolations === 1 ? '' : 's'}`)
+    }
+  } else if (t.status === 'skipped' && t.blockedBy !== null) {
+    parts.push(`after ${t.blockedBy} failed`)
+  }
+  return parts.map((p) => `  ${p}`).join('')
+}
+
+/** Hit rows shown before the rest fold — the slowest restores. */
+const HITS_SHOWN = 16
+
+/**
+ * The per-task rows: failures first, then what executed or was skipped,
+ * then cache hits. Hits are the noise of a warm run — 996 of a thousand
+ * rows on a red run put the failure a screen's height above the prompt
+ * (item 280) — so past `HITS_SHOWN` they fold into one line with their
+ * count; the ones shown are the slowest restores, the one thing a hit's
+ * row tells. `--format json` lists every row.
+ */
+export function formatTaskRows(tasks: readonly RunSummaryRow[]): string[] {
+  if (tasks.length === 0) return []
+  const failed = tasks.filter((t) => t.status === 'failed')
+  const hits = tasks.filter((t) => t.status !== 'failed' && t.cacheHit === true)
+  const rest = tasks.filter((t) => t.status !== 'failed' && t.cacheHit !== true)
+  const folded = hits.length > HITS_SHOWN
+  const shownHits = folded
+    ? [...hits].sort((a, b) => b.durationMs - a.durationMs).slice(0, HITS_SHOWN)
+    : hits
+  const ordered = [...failed, ...rest, ...shownHits]
+  const idW = Math.max(...ordered.map((t) => `${t.project}#${t.task}`.length), 4)
+  const lines = ['']
+  for (const t of ordered) {
+    const id = `${t.project}#${t.task}`
+    // The terminal summary's own word for a task that runs every time
+    // by design; a reader must not take its row for a miss.
+    // A failure's row reads as the frame did — `failed (exit 137)` —
+    // and above 128 names the signal the number stands for (260).
+    const status = t.status === 'failed' ? `failed (exit ${t.exitCode})` : t.status
+    lines.push(
+      `  ${status.padEnd(17)} ${id.padEnd(idW)}  ${fmtMs(t.durationMs).padStart(8)}` +
+        `${t.hash !== '' ? `  ${t.hash}` : ''}${t.cached === false ? '  no-cache' : ''}${fmtUsage(t)}` +
+        reasonParts(t),
+    )
+  }
+  if (folded) {
+    lines.push(
+      `  … +${hits.length - HITS_SHOWN} more cache hits (the ${HITS_SHOWN} slowest restores shown) — vx last --format json lists every row`,
+    )
+  }
+  return lines
+}
+
 export async function lastCmd(args: readonly string[]): Promise<number> {
   const parsed = parseLastArgs(args)
   if (parsed.error !== undefined) throw new UserError(`vx last: ${parsed.error}`)
 
   const root = await findWorkspaceRoot(process.cwd())
-  const cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
-  const cache = new Cache(cacheDir)
+  const cache = Cache.inspect(await cliCacheDir(root, parsed.cacheDir))
+  noteSchemaReset(cache, warnToStderr)
   try {
     const db = cache.dbHandle()
 
@@ -116,22 +238,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
         ` (${inv.hitLocalCount} local, ${inv.hitRemoteCount} remote)` +
         `${inv.failedCount > 0 ? ` · ${inv.failedCount} failed` : ''}`,
     )
-    const tasks = detail?.tasks ?? []
-    if (tasks.length > 0) {
-      lines.push('')
-      const failedFirst = [
-        ...tasks.filter((t) => t.status === 'failed'),
-        ...tasks.filter((t) => t.status !== 'failed'),
-      ]
-      const idW = Math.max(...tasks.map((t) => `${t.project}#${t.task}`.length), 4)
-      for (const t of failedFirst) {
-        const id = `${t.project}#${t.task}`
-        lines.push(
-          `  ${t.status.padEnd(17)} ${id.padEnd(idW)}  ${fmtMs(t.durationMs).padStart(8)}` +
-            `${t.hash !== '' ? `  ${t.hash}` : ''}`,
-        )
-      }
-    }
+    lines.push(...formatTaskRows(detail?.tasks ?? []))
     process.stdout.write(`${lines.join('\n')}\n`)
     return 0
   } finally {

package/src/cli/lock.ts

@@ -3,9 +3,11 @@
 // current environment. Design: docs/design/config-lock-2026-06.md.
 
 import type { ProjectConfig } from '../config.js'
+import { seeHelp } from './help.js'
 import { relPosix, xxh3hex } from '../util/index.js'
 import {
   findWorkspaceRoot,
+  type LoadReads,
   listProjects,
   loadProjectConfig,
   loadWorkspace,
@@ -27,7 +29,7 @@ export function parseLockArgs(args: readonly string[]): LockArgs {
   const out: LockArgs = { check: false }
   for (const a of args) {
     if (a === '--check') out.check = true
-    else return { check: false, error: `unknown argument: ${a}` }
+    else return { check: false, error: `unknown argument: ${a}${seeHelp('lock')}` }
   }
   return out
 }
@@ -40,32 +42,42 @@ export async function lockCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx lock: ${parsed.error}\n`)
     return 1
   }
-  const root = await findWorkspaceRoot(process.cwd())
-  const workspace = await loadWorkspace(root)
-  const metas = (await listProjects(workspace)).filter(
-    (m): m is ConfiguredMeta => m.configPath !== null,
-  )
-  if (parsed.check) return await checkLock(root, metas)
-  return await writeLock(root, metas)
+  const reads: LoadReads = new Map()
+  const root = await findWorkspaceRoot(process.cwd(), reads)
+  const workspace = await loadWorkspace(root, reads)
+  const all = await listProjects(workspace)
+  const metas = all.filter((m): m is ConfiguredMeta => m.configPath !== null)
+  // A project with no vx.config has nothing to freeze: its tasks (a plugin's,
+  // or none) load live under --frozen too, so both verbs say how many the
+  // count above leaves out — `locked 0 project configs` on a turbo() repo
+  // read like an audit of something (2026-09-16).
+  const bare = all.length - metas.length
+  if (parsed.check) return await checkLock(root, metas, bare)
+  return await writeLock(root, metas, bare)
 }
 
 /** Evaluate one config in the current env, returning its lock entry. */
 async function evaluateEntry(root: string, meta: ConfiguredMeta): Promise<LockfileEntry> {
   const bytes = await Bun.file(meta.configPath).bytes()
-  // `fresh: true` — locking must observe the current environment, not
-  // a module-cache replay from earlier in this process.
+  // `fresh: true` — the lock freezes this environment's evaluation, never
+  // a stored one, whatever options a later edit passes beside it.
   const config = await loadProjectConfig(meta.configPath, { fresh: true })
   return {
     configPath: relPosix(root, meta.configPath),
     configHash: xxh3hex(bytes),
-    // JSON round-trip drops `undefined` fields so the stored object is
-    // byte-identical to what a later read of the lock will produce —
-    // the exact form `--check` compares against.
-    config: JSON.parse(JSON.stringify(config)) as ProjectConfig,
+    // Stored through `writeLockfile`'s JSON.stringify, which drops a field
+    // left `undefined` — the form `--check` compares a fresh evaluation in.
+    config,
   }
 }
 
-async function writeLock(root: string, metas: ConfiguredMeta[]): Promise<number> {
+function bareNote(bare: number): string {
+  return bare === 0
+    ? ''
+    : ` (${bare} project${bare === 1 ? ' has' : 's have'} no vx.config; their tasks are never frozen)`
+}
+
+async function writeLock(root: string, metas: ConfiguredMeta[], bare: number): Promise<number> {
   const entries = await Promise.all(metas.map((m) => evaluateEntry(root, m)))
   const projects: Record<string, LockfileEntry> = {}
   // `listProjects` sorts by name — stable lockfile diffs for free.
@@ -73,7 +85,9 @@ async function writeLock(root: string, metas: ConfiguredMeta[]): Promise<number>
   const lock: Lockfile = { version: LOCKFILE_VERSION, projects }
   await writeLockfile(root, lock)
   const n = metas.length
-  process.stdout.write(`vx: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}\n`)
+  process.stdout.write(
+    `vx: locked ${n} project config${n === 1 ? '' : 's'} → ${LOCKFILE_NAME}${bareNote(bare)}\n`,
+  )
   return 0
 }
 
@@ -85,7 +99,7 @@ async function writeLock(root: string, metas: ConfiguredMeta[]): Promise<number>
  *      catches eval-time env-var drift that file hashes cannot see —
  *      file bytes unchanged, resolved value changed.
  */
-async function checkLock(root: string, metas: ConfiguredMeta[]): Promise<number> {
+async function checkLock(root: string, metas: ConfiguredMeta[], bare: number): Promise<number> {
   const lock = await readLockfile(root)
   if (!lock) {
     process.stderr.write(
@@ -104,6 +118,8 @@ async function checkLock(root: string, metas: ConfiguredMeta[]): Promise<number>
       if (hash !== entry.configHash) {
         return `config file changed since lock (${m.name}: ${rel}) — run 'vx lock'`
       }
+      // The lock's form: a first load is the module's live export, where a
+      // field left `undefined` is a key the stored JSON never has.
       const fresh = JSON.parse(
         JSON.stringify(await loadProjectConfig(m.configPath, { fresh: true })),
       ) as ProjectConfig
@@ -130,6 +146,8 @@ async function checkLock(root: string, metas: ConfiguredMeta[]): Promise<number>
     return 1
   }
   const n = metas.length
-  process.stdout.write(`vx: lock is up to date (${n} project${n === 1 ? '' : 's'})\n`)
+  const audited = `${n} project${n === 1 ? '' : 's'}`
+  const skipped = bare === 0 ? '' : `; ${bare} without a vx.config not audited`
+  process.stdout.write(`vx: lock is up to date (${audited}${skipped})\n`)
   return 0
 }

package/src/cli/plan-format.ts

@@ -9,12 +9,12 @@ import { formatDuration } from '../orchestrator/index.js'
  * task with recorded history also shows its typical duration (~p50).
  *
  *   would run:
- *     ✓  @vzn/vx#lint       cache hit (local)        abc12345
+ *     ◉  @vzn/vx#lint       cache hit (local)        abc12345
  *     ↓  @vzn/vx#test       cache hit (remote)       def67890
- *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98  ~1.2s
+ *     ▶  @vzn/vx#build      cache miss — would exec  fedcba98  ~1.20s
  *
- *   3 task(s) planned: 2 cache hits (1 local, 1 remote), 1 would run.
- *   predicted: ~1.2s wall · ~1.2s total execution
+ *   3 task(s) planned, 2 cache hits (1 local, 1 remote), 1 would run.
+ *   predicted: ~1.20s wall · ~1.20s total execution
  */
 export function formatPlanText(plan: RunPlan): string {
   const real = plan.tasks.filter((t) => t.cacheStatus !== 'group')
@@ -144,19 +144,30 @@ export function formatPlanJson(plan: RunPlan): string {
 export function formatGraphDot(plan: RunPlan): string {
   const lines: string[] = ['digraph TaskGraph {', '  rankdir=LR;', '  node [shape=box];']
   for (const t of plan.tasks) {
-    const label = `${t.node.id}\\n${t.hash.slice(0, 8)}`
     const color = dotColor(t.cacheStatus)
-    lines.push(`  "${t.node.id}" [label="${label}", style="filled", fillcolor="${color}"];`)
+    lines.push(
+      `  ${dotString(t.node.id)} [label=${dotString(`${t.node.id}\n${t.hash.slice(0, 8)}`)}, style="filled", fillcolor="${color}"];`,
+    )
   }
   for (const t of plan.tasks) {
     for (const dep of t.deps) {
-      lines.push(`  "${dep}" -> "${t.node.id}";`)
+      lines.push(`  ${dotString(dep)} -> ${dotString(t.node.id)};`)
     }
   }
   lines.push('}')
   return lines.join('\n') + '\n'
 }
 
+/**
+ * A DOT double-quoted ID. A task name is any object key in a config, so
+ * `"`, `\` and a newline are all reachable; unescaped they end the
+ * string early and the document stops parsing. `\n` is DOT's own line
+ * break inside a label.
+ */
+function dotString(s: string): string {
+  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n')}"`
+}
+
 function symbolFor(s: CacheStatus): string {
   switch (s) {
     case 'hit-local':

package/src/cli/plugin-commands.ts

@@ -8,7 +8,8 @@
 // before this is asked, so a plugin cannot shadow `run`.
 
 import type { VxPlugin, PluginCommand, CommandContext } from '../orchestrator/index.js'
-import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
+import { loadCliWorkspace } from './workspace-config.js'
 
 export interface ResolvedPluginCommand {
   plugin: VxPlugin
@@ -16,6 +17,17 @@ export interface ResolvedPluginCommand {
   ctx: CommandContext
 }
 
+/**
+ * No plugin here declares the verb, and these are the verbs they DO declare
+ * — the same load that failed to find the verb already knows them, so the
+ * "did you mean" and the "where verbs come from" line cost nothing extra.
+ * An empty list is a workspace whose plugins declare no verb at all; `null`
+ * from the lookup is no workspace.
+ */
+interface NoPluginCommand {
+  declaredVerbs: readonly string[]
+}
+
 /**
  * Why a verb could not be looked up: the workspace file failed to load.
  * Surfaced next to "unknown command" rather than as the whole answer — a
@@ -39,31 +51,31 @@ async function workspacePlugins(
   } catch {
     return null
   }
-  let config
+  let ws
   try {
-    config = await loadWorkspaceConfig(workspaceRoot)
+    ws = await loadCliWorkspace(workspaceRoot)
   } catch (err) {
     return { loadError: err instanceof Error ? err.message : String(err) }
   }
-  return {
-    workspaceRoot,
-    cacheDir: resolveCacheDir(workspaceRoot, config),
-    plugins: (config?.plugins ?? []) as readonly VxPlugin[],
-  }
+  return { workspaceRoot, cacheDir: ws.cacheDir, plugins: ws.plugins }
 }
 
 /**
- * The plugin verb named `verb` for the workspace around `cwd`; null when
- * there is none; the load error when the workspace file could not say.
+ * The plugin verb named `verb` for the workspace around `cwd`; the verbs
+ * this workspace's plugins do declare when none of them is it; null when
+ * there is no workspace; the load error when the workspace file could not
+ * say.
  */
 export async function resolvePluginCommand(
   verb: string,
   cwd = process.cwd(),
-): Promise<ResolvedPluginCommand | UnresolvedPluginCommand | null> {
+): Promise<ResolvedPluginCommand | NoPluginCommand | UnresolvedPluginCommand | null> {
   const ws = await workspacePlugins(cwd)
   if (ws === null) return null
   if ('loadError' in ws) return ws
+  const declaredVerbs = new Set<string>()
   for (const plugin of ws.plugins) {
+    for (const declared of Object.keys(plugin.commands ?? {})) declaredVerbs.add(declared)
     const command = plugin.commands?.[verb]
     if (command === undefined) continue
     return {
@@ -76,7 +88,17 @@ export async function resolvePluginCommand(
       },
     }
   }
-  return null
+  return { declaredVerbs: [...declaredVerbs] }
+}
+
+/** The plugin verbs the workspace around `cwd` declares, in declaration order; none when it does not load. */
+export async function pluginVerbs(cwd = process.cwd()): Promise<string[]> {
+  const ws = await workspacePlugins(cwd).catch(() => null)
+  if (ws === null || 'loadError' in ws) return []
+  const verbs = new Set<string>()
+  for (const plugin of ws.plugins)
+    for (const verb of Object.keys(plugin.commands ?? {})) verbs.add(verb)
+  return [...verbs]
 }
 
 /** `vx help` lines for every plugin verb in the workspace around `cwd`. */