@vzn/vx 0.0.18 → 0.0.21

package/src/cli/info.ts

@@ -1,110 +1,139 @@
 // `vx info` — workspace doctor printout. One screen of environment +
 // workspace + cache facts for bug reports and quick sanity checks.
-// `vx stats` is a deprecated alias (info absorbed it).
+// `vx stats` is a deprecated alias (info absorbed it). The facts come
+// from the orchestrator's `collectInfo` (doctor.ts), which `vx mcp` reads
+// too; this file parses the flags and renders the rows.
 
-import { Cache } from '../cache/index.js'
-import { VERSION } from '../version.js'
-import {
-  findWorkspaceRoot,
-  listProjects,
-  loadProjectConfig,
-  loadWorkspace,
-  loadWorkspaceConfig,
-  lockfilePath,
-  resolveCacheDir,
-} from '../workspace/index.js'
+import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
+import { seeHelp } from './help.js'
+import { parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 
-export async function infoCmd(args: readonly string[]): Promise<number> {
-  if (args.length > 0) {
-    process.stderr.write(`vx info: unknown argument: ${args[0]}\n`)
-    return 1
-  }
-  const root = await findWorkspaceRoot(process.cwd())
-  const metas = await listProjects(await loadWorkspace(root))
+export interface InfoArgs {
+  format: 'pretty' | 'json'
+  /** `--cache-dir`: report on the cache a run with the same flag uses. */
+  cacheDir?: string
+  error?: string
+}
 
-  let taskCount = 0
-  await Promise.all(
-    metas.map(async (meta) => {
-      if (meta.configPath === null) return
-      // A broken config must not take the doctor down with it — it
-      // just contributes zero tasks to the count.
-      try {
-        const config = await loadProjectConfig(meta.configPath)
-        taskCount += Object.keys(config.tasks ?? {}).length
-      } catch {
-        // counted as zero
+export function parseInfoArgs(args: readonly string[]): InfoArgs {
+  const out: InfoArgs = { format: 'pretty' }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--format' || a?.startsWith('--format=')) {
+      const v = a === '--format' ? args[++i] : a.slice('--format='.length)
+      if (v !== 'pretty' && v !== 'json') {
+        return { ...out, error: `--format must be pretty or json${seeHelp('info')}` }
       }
-    }),
-  )
-
-  const cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
-  const cache = new Cache(cacheDir)
-  let stats
-  try {
-    stats = cache.stats()
-  } finally {
-    cache.close()
+      out.format = v
+      continue
+    }
+    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
+    }
+    return { ...out, error: `unknown argument: ${a}${seeHelp('info')}` }
   }
+  return out
+}
 
-  const lockPresent = await Bun.file(lockfilePath(root)).exists()
+export async function infoCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseInfoArgs(args)
+  if (parsed.error) {
+    process.stderr.write(`vx info: ${parsed.error}\n`)
+    return 1
+  }
+  const facts = await collectInfo(process.cwd(), {
+    ...(parsed.cacheDir !== undefined ? { cacheDir: parsed.cacheDir } : {}),
+    warn: warnToStderr,
+  })
+  process.stdout.write(
+    parsed.format === 'json' ? `${JSON.stringify(facts, null, 2)}\n` : `${renderInfo(facts)}\n`,
+  )
+  return 0
+}
 
+export function renderInfo(f: InfoFacts): string {
   const rows: [string, string][] = [
-    ['vx', VERSION],
-    ['bun', Bun.version],
-    ['git', gitVersion()],
-    // The one `git status` walk per run is the warm path's critical path on
-    // a large tree (~55 ms at 1000 projects, measured 2026-09-02). git's
-    // own caches make it near-free after the first run, and they are OFF by
-    // default — say so, since nothing else in a run would.
-    ['git status cache', gitStatusCache(root)],
-    ['workspace root', root],
-    ['projects', `${metas.length} (${taskCount} task${taskCount === 1 ? '' : 's'})`],
-    ['cache dir', cacheDir],
-    ['cache entries', `${stats.entryCount} (${formatBytes(stats.totalBytes)})`],
-    ['runs (24h)', `${stats.runCountLast24h} (${stats.hitCountLast24h} cache hits)`],
-    ['vx-lock.json', lockPresent ? 'yes' : 'no'],
+    ['vx', f.vx],
+    ['bun', f.bun],
+    ['git', f.git ?? '(not found)'],
+    ['git status cache', renderGitStatusCache(f.gitStatusCache)],
+    ['workspace root', f.workspaceRoot],
+    ['projects', `${f.projects} (${f.tasks} task${f.tasks === 1 ? '' : 's'})`],
+    ['plugins', describePlugins(f.plugins)],
+    ['workers', describeWorkers(f.workers)],
+    ['memory', describeMemory(f.memory)],
+    ['cache dir', f.cacheDir],
+    ['cache versions', `keys ${f.cacheVersion} · index schema ${f.schemaVersion}`],
+    ['cache entries', `${f.cacheEntries} (${formatBytes(f.cacheBytes)})`],
+    // Only when there is something to say.
+    ...(f.orphans.artifacts > 0
+      ? ([
+          [
+            'orphans',
+            `${f.orphans.artifacts} artifact${f.orphans.artifacts === 1 ? '' : 's'} (${formatBytes(f.orphans.bytes)}) the index does not know — \`vx cache prune\` reaps them`,
+          ],
+        ] as [string, string][])
+      : []),
+    ['runs (24h)', `${f.runs24h} (${f.hits24h} cache hits)`],
+    ['flaky tasks', describeFlakyTasks(f.flakyTasks)],
+    ['vx-lock.json', f.lockfile ? 'yes' : 'no'],
   ]
   const labelW = Math.max(...rows.map(([label]) => label.length))
-  const lines = rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`)
-  process.stdout.write(`${lines.join('\n')}\n`)
-  return 0
+  return rows.map(([label, value]) => `${`${label}:`.padEnd(labelW + 1)} ${value}`).join('\n')
 }
 
-/** Whether git's fsmonitor / untracked cache are on, with the remedy when not. */
-function gitStatusCache(root: string): string {
-  try {
-    const p = Bun.spawnSync({
-      cmd: ['git', 'config', '--get-regexp', '^core\\.(fsmonitor|untrackedcache)$'],
-      cwd: root,
-      stdout: 'pipe',
-      stderr: 'pipe',
-    })
-    const out = p.exitCode === 0 ? new TextDecoder().decode(p.stdout) : ''
-    const on = (key: string): boolean =>
-      new RegExp(`^core\\.${key} (true|1|yes|on)$`, 'im').test(out)
-    const fsmonitor = on('fsmonitor')
-    const untracked = on('untrackedcache')
-    if (fsmonitor && untracked) return 'fsmonitor + untrackedCache on'
-    const missing = [
-      ...(fsmonitor ? [] : ['core.fsmonitor']),
-      ...(untracked ? [] : ['core.untrackedCache']),
-    ]
-    return `${missing.join(', ')} off — \`git config ${missing[0]} true\` makes every run's status walk near-free on a large tree`
-  } catch {
-    return '(unknown)'
-  }
+/** `4 — the CPU count`, `2 — cgroup CPU quota 2 of 8 cores`, `8 — vx.workspace.ts (4 cores)`. */
+export function describeWorkers(w: InfoFacts['workers']): string {
+  const quota = w.cpuQuota === null ? '' : `, cgroup CPU quota ${trimCores(w.cpuQuota)}`
+  if (w.source === 'workspace') return `${w.count} — vx.workspace.ts (${w.cores} cores${quota})`
+  if (w.source === 'cgroup')
+    return `${w.count} — cgroup CPU quota ${trimCores(w.cpuQuota ?? w.count)} of ${w.cores} cores`
+  return `${w.count} — the CPU count${quota}`
 }
 
-function gitVersion(): string {
-  try {
-    const p = Bun.spawnSync({ cmd: ['git', '--version'], stdout: 'pipe', stderr: 'pipe' })
-    if (p.exitCode !== 0) return '(not found)'
-    return new TextDecoder()
-      .decode(p.stdout)
-      .trim()
-      .replace(/^git version /, '')
-  } catch {
-    return '(not found)'
+/** `13 GB usable — cgroup limit; the machine has 16 GB`, or `16 GB`. */
+export function describeMemory(m: InfoFacts['memory']): string {
+  if (m.cgroupLimitBytes !== null && m.usableBytes < m.totalBytes) {
+    return `${formatBytes(m.usableBytes)} usable — cgroup limit; the machine has ${formatBytes(m.totalBytes)}`
   }
+  return formatBytes(m.totalBytes)
+}
+
+function trimCores(n: number): string {
+  return Number.isInteger(n) ? String(n) : n.toFixed(2).replace(/0+$/, '')
+}
+
+/** `2 — app#test (3 of 7 runs failed on unchanged inputs); api#e2e (1 of 4)`, or `none`. */
+export function describeFlakyTasks(tasks: readonly FlakyTask[]): string {
+  if (tasks.length === 0) return 'none'
+  const parts = tasks.map(
+    (t, i) =>
+      `${t.taskId} (${t.failures} of ${t.passes + t.failures} runs failed${i === 0 ? ' on unchanged inputs' : ''})`,
+  )
+  return `${tasks.length} — ${parts.join('; ')}`
+}
+
+export function describePlugins(
+  plugins: ReadonlyArray<{ name: string; seams: readonly string[] }>,
+): string {
+  if (plugins.length === 0) return 'none'
+  const parts = plugins.map(
+    (p) => `${p.name} (${p.seams.length === 0 ? 'no seams' : p.seams.join(', ')})`,
+  )
+  return `${plugins.length} — ${parts.join('; ')}`
+}
+
+function renderGitStatusCache(c: InfoFacts['gitStatusCache']): string {
+  if (c === null) return '(unknown)'
+  if (c.fsmonitor && c.untrackedCache) return 'fsmonitor + untrackedCache on'
+  const missing = [
+    ...(c.fsmonitor ? [] : ['core.fsmonitor']),
+    ...(c.untrackedCache ? [] : ['core.untrackedCache']),
+  ]
+  return `${missing.join(', ')} off`
 }

package/src/cli/init.ts

@@ -0,0 +1,75 @@
+// `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,
+  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 root = await findWorkspaceRoot(process.cwd())
+  const metas = await listProjects(await loadWorkspace(root))
+  // `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[] = []
+  if (await Bun.file(path.join(root, 'turbo.json')).exists()) {
+    notes.push(
+      'turbo.json 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',
+    )
+  }
+  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,20 @@
 // 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 { Cache, noteSchemaReset } from '../cache/index.js'
+import { formatBytes } from './format.js'
+import { seeHelp } from './help.js'
 import { getInvocation, getRun, listInvocations } 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
 }
 
@@ -37,7 +42,14 @@ 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
   }
@@ -53,13 +65,31 @@ 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(' · ')}` : ''
+}
+
 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 = new Cache(await cliCacheDir(root, parsed.cacheDir))
+  noteSchemaReset(cache, warnToStderr)
   try {
     const db = cache.dbHandle()
 
@@ -126,9 +156,11 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
       const idW = Math.max(...tasks.map((t) => `${t.project}#${t.task}`.length), 4)
       for (const t of failedFirst) {
         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.
         lines.push(
           `  ${t.status.padEnd(17)} ${id.padEnd(idW)}  ${fmtMs(t.durationMs).padStart(8)}` +
-            `${t.hash !== '' ? `  ${t.hash}` : ''}`,
+            `${t.hash !== '' ? `  ${t.hash}` : ''}${t.cached === false ? '  no-cache' : ''}${fmtUsage(t)}`,
         )
       }
     }

package/src/cli/lock.ts

@@ -3,6 +3,7 @@
 // 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,
@@ -27,7 +28,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
 }

package/src/cli/plan-format.ts

@@ -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
@@ -39,17 +40,13 @@ 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 }
 }
 
 /**
@@ -80,6 +77,16 @@ export async function resolvePluginCommand(
 }
 
 /** `vx help` lines for every plugin verb in the workspace around `cwd`. */
+/** 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]
+}
+
 export async function pluginCommandHelp(cwd = process.cwd()): Promise<string[]> {
   const ws = await workspacePlugins(cwd).catch(() => null)
   if (ws === null || 'loadError' in ws) return []