@vzn/vx 0.0.97 → 0.0.99

package/README.md

@@ -93,7 +93,8 @@ npx vx run build --all    # restored from the cache, not rebuilt
 Or copy [`examples/basic`](examples/basic), a two-package starter CI
 runs on every commit. More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 [Configure](https://vznjs.github.io/vx/guides/configure/) ·
-[CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md).
+[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?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.97",
+  "version": "0.0.99",
   "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.97",
-    "@vzn/vx-linux-arm64": "0.0.97",
-    "@vzn/vx-darwin-x64": "0.0.97",
-    "@vzn/vx-darwin-arm64": "0.0.97"
+    "@vzn/vx-linux-x64": "0.0.99",
+    "@vzn/vx-linux-arm64": "0.0.99",
+    "@vzn/vx-darwin-x64": "0.0.99",
+    "@vzn/vx-darwin-arm64": "0.0.99"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cli/help.ts

@@ -141,7 +141,6 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       task counts, cache dir/entries/size, recent runs,',
     '                       lock status.',
     '      --format <fmt>   pretty (default) | json.',
-    '  vx stats             Deprecated: alias of vx info.',
     "  vx why <task>        Why did this task re-run? Compares the task's latest",
     '                       run (or --run <id>) against its previous run: names the',
     '                       exact changed cache-key components (files / env / runtime',

package/src/cli/index.ts

@@ -61,9 +61,6 @@ export async function run(argv: readonly string[]): Promise<number> {
       return await (await import('./upgrade.js')).upgradeCmd(rest)
     case 'show':
       return await (await import('./show.js')).showCmd(rest)
-    case 'stats': // deprecated alias — `vx info` absorbed `vx stats`
-      process.stderr.write('vx stats is deprecated; use vx info\n')
-      return await (await import('./info.js')).infoCmd(rest)
     case 'info':
       return await (await import('./info.js')).infoCmd(rest)
     case 'why':

package/src/cli/info.ts

@@ -1,6 +1,6 @@
 // `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). The facts come
+// The facts come
 // from the orchestrator's `collectInfo` (doctor.ts), which `vx mcp` reads
 // too; this file parses the flags and renders the rows.
 

package/src/cli/last.ts

@@ -17,6 +17,7 @@ import {
 import { formatElapsed, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
+import { resolveRunId } from './run-id.js'
 
 interface LastArgs {
   runId?: string
@@ -204,7 +205,7 @@ export async function lastCmd(args: readonly string[]): Promise<number> {
 
     const inv =
       parsed.runId !== undefined
-        ? getInvocation(db, parsed.runId)
+        ? getInvocation(db, resolveRunId(db, parsed.runId, 'vx last') ?? parsed.runId)
         : (listInvocations(db, { limit: 1 })[0] ?? null)
     if (inv === null || inv === undefined) {
       throw new UserError(

package/src/cli/run-id.ts

@@ -0,0 +1,27 @@
+// A run id as a user types it: the whole id, or a prefix of one, as git
+// takes a short sha. `vx last --list` prints 36-character ids; nobody
+// retypes one whole.
+
+import type { Database } from 'bun:sqlite'
+import { UserError } from '../util/index.js'
+
+/**
+ * The recorded run `raw` names: itself when recorded, else the one run
+ * whose id starts with it. Null when none does; a prefix several runs share
+ * is refused with those runs, since picking one would replay the wrong run.
+ */
+export function resolveRunId(db: Database, raw: string, verb: string): string | null {
+  const exact = db.query('SELECT 1 FROM invocations WHERE run_id = ?').get(raw)
+  if (exact !== null) return raw
+  const rows = db
+    .query(
+      'SELECT run_id FROM invocations WHERE substr(run_id, 1, ?) = ? ORDER BY run_id DESC LIMIT 6',
+    )
+    .all(raw.length, raw) as Array<{ run_id: string }>
+  if (rows.length === 0) return null
+  if (rows.length === 1) return rows[0]!.run_id
+  const shown = rows.slice(0, 5).map((r) => `  ${r.run_id}`)
+  throw new UserError(
+    `${verb}: run id ${raw} is the start of ${rows.length > 5 ? 'more than 5' : rows.length} runs — type more of it:\n${shown.join('\n')}`,
+  )
+}

package/src/cli/run.ts

@@ -547,7 +547,9 @@ export async function runCmd(args: readonly string[]): Promise<number> {
   // explicit anchored positional.
   if (tasks.length === 0) {
     if (!process.stdin.isTTY) {
-      process.stderr.write(`vx run: missing task name (stdin is not a TTY)\n`)
+      process.stderr.write(
+        `vx run: missing task name (stdin is not a TTY, so no picker; vx run <task>, e.g. vx run build)${seeHelp('run')}\n`,
+      )
       return 1
     }
     const picked = await pickTask(

package/src/cli/select.ts

@@ -305,7 +305,10 @@ export async function resolveFilters(
   }
   // Something matched, so the run proceeds; a pattern that matched nothing
   // alongside it is still worth a line — it is probably a typo.
-  for (const f of unmatched) process.stderr.write(`vx: filter "${f}" matched no projects\n`)
+  for (const f of unmatched)
+    process.stderr.write(
+      `vx: filter "${f}" matched no projects${didYouMeanProject([f], projects)}\n`,
+    )
   let staged: Map<string, ProjectEntry> | undefined
   if (stagedPromise !== undefined) {
     try {
@@ -398,7 +401,9 @@ export async function pickTask(
     }
     const n = Number(answer)
     if (!Number.isInteger(n) || n < 1 || n > entries.length) {
-      process.stderr.write(`vx run: invalid selection: ${answer}\n`)
+      process.stderr.write(
+        `vx run: invalid selection: ${answer} (type a number from 1 to ${entries.length})\n`,
+      )
       return null
     }
     return entries[n - 1] ?? null

package/src/cli/show.ts

@@ -70,7 +70,12 @@ export async function showCmd(args: readonly string[]): Promise<number> {
         ? parsed.target
         : parsed.target.slice(0, hashAt)
   const taskName = hashAt === -1 ? undefined : parsed.target!.slice(hashAt + 1)
-  if (taskName === '') throw new UserError(`missing task name after '#' in "${parsed.target}"`)
+  if (taskName === '') {
+    const list = projectName === '' ? 'vx show' : `vx show ${projectName}`
+    throw new UserError(
+      `vx show: missing task name after '#' in "${parsed.target}" (${list} lists the tasks)`,
+    )
+  }
   if (projectName !== undefined && (taskName !== undefined || byName.has(projectName))) {
     if (!byName.has(projectName)) {
       throw new UserError(

package/src/cli/upgrade.ts

@@ -105,11 +105,15 @@ export function releaseAsset(release: unknown, name: string): ReleaseAsset {
       typeof a === 'object' && a !== null && (a as { name?: unknown }).name === name,
   )
   if (asset === undefined) {
-    throw new UserError(`vx upgrade: release ${tag} has no asset ${name} for this platform`)
+    throw new UserError(
+      `vx upgrade: release ${tag} has no asset ${name} for this platform — nothing replaced; npm install -g @vzn/vx@latest installs it instead`,
+    )
   }
   const url = asset.browser_download_url
   if (typeof url !== 'string' || url.length === 0) {
-    throw new UserError(`vx upgrade: release ${tag} names no download for ${name}`)
+    throw new UserError(
+      `vx upgrade: release ${tag} names no download for ${name} — nothing replaced; npm install -g @vzn/vx@latest installs it instead`,
+    )
   }
   const digest = asset.digest
   const m = typeof digest === 'string' ? /^sha256:([0-9a-f]{64})$/i.exec(digest) : null
@@ -217,13 +221,15 @@ export async function replaceBinary(
 ): Promise<void> {
   const res = await fetchOrRefuse(url, { redirect: 'follow' }, 'download the release asset')
   if (!res.ok) {
-    throw new UserError(`vx upgrade: download failed (${res.status}) — ${url}`)
+    throw new UserError(
+      `vx upgrade: download failed (${res.status}) — ${url} — nothing replaced; re-run`,
+    )
   }
   const bytes = new Uint8Array(
     await readOrRefuse(() => res.arrayBuffer(), url, 'download the release asset'),
   )
   if (bytes.byteLength === 0) {
-    throw new UserError(`vx upgrade: empty download — ${url}`)
+    throw new UserError(`vx upgrade: empty download — ${url} — nothing replaced; re-run`)
   }
   const got = new Bun.CryptoHasher('sha256').update(bytes).digest('hex')
   if (got !== sha256.toLowerCase()) {

package/src/cli/why.ts

@@ -17,6 +17,7 @@ import {
 import { nearMatches, UserError } from '../util/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
 import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
+import { resolveRunId } from './run-id.js'
 
 interface WhyArgs {
   target?: string
@@ -166,7 +167,10 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
   try {
     const db = cache.dbHandle()
     const taskId = resolveTarget(cache, parsed.target)
-    const runId = parsed.runId ?? latestRunId(cache.dbHandle(), taskId)
+    const runId =
+      parsed.runId !== undefined
+        ? (resolveRunId(db, parsed.runId, 'vx why') ?? parsed.runId)
+        : latestRunId(db, taskId)
 
     if (runId === null) {
       // Runs exist (resolveTarget passed) but predate run ids — fall back to

package/src/orchestrator/doctor.ts

@@ -243,7 +243,7 @@ async function sandboxFact(declared: number): Promise<InfoFacts['sandbox']> {
 
 /**
  * The doctor's output is pasted into bug reports and compared between
- * invocations (`vx stats` is pinned byte-identical to `vx info`), so a
+ * invocations, so a
  * reason must not carry this process's id. The Linux runtime names its
  * mux socket after the pid (`srt-mux-<pid>-<n>.sock`), and a listen that
  * fails — a nested sandbox, a read-only tmpdir — quotes that path.

package/src/orchestrator/index.ts

@@ -154,7 +154,6 @@ export type {
   CacheKeyExplanation,
   InputDiffEntry,
   InvocationDetail,
-  InvocationRow,
   ListInvocationsArgs,
   ListRunsArgs,
   RunDetail,

package/src/orchestrator/metrics.ts

@@ -114,7 +114,7 @@ export function listRuns(db: Database, args: ListRunsArgs = {}): RunSummaryRow[]
 /**
  * One `vx run` invocation header — every `invocations` column, camelCased,
  * `tags` parsed to a `Record<string,string>` and `dirty`/`ci`/`exitOk`
- * surfaced as booleans. Superset of the old `InvocationRow`: the SPA's
+ * surfaced as booleans. The SPA's
  * existing fields (runId / startedAt / endedAt / taskCount / failedCount /
  * hitCount / totalDurationMs) are all present, so existing views keep working.
  */
@@ -147,9 +147,6 @@ export interface InvocationDetail {
   tags: Record<string, string>
 }
 
-/** @deprecated kept as an alias of `InvocationDetail` for older callers. */
-export type InvocationRow = InvocationDetail
-
 interface InvocationRawRow {
   runId: string
   command: string

package/src/util/index.ts

@@ -45,7 +45,7 @@ export { appendTail, createTail, resetTail, tailText, type Tail } from './tail.j
 export { ulid } from './ulid.js'
 export { splitTaskId } from './task-id.js'
 export { editDistance, nearMatches, nearest } from './edit-distance.js'
-export { CORE_VERBS, DISPATCHED_VERBS, MOVED_VERBS } from './verbs.js'
+export { CORE_VERBS, MOVED_VERBS } from './verbs.js'
 export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.js'
 export { executablePath } from './which.js'
 export { procfsIsOwn } from './procfs.js'

package/src/util/verbs.ts

@@ -1,7 +1,5 @@
 /**
- * The verbs the CLI dispatcher (`cli/index.ts`) owns; `stats` is a
- * deprecated alias of `info` and stays out of hints but is still matched
- * first. Lives in util rather than cli because the workspace VALIDATOR
+ * The verbs the CLI dispatcher (`cli/index.ts`) owns. Lives in util rather than cli because the workspace VALIDATOR
  * refuses a plugin verb that names one of these — a verb core matches
  * first could never run — and the workspace module cannot import cli.
  */
@@ -21,9 +19,6 @@ export const CORE_VERBS = [
   'version',
 ] as const
 
-/** Every word the dispatcher matches before consulting plugins. */
-export const DISPATCHED_VERBS: readonly string[] = [...CORE_VERBS, 'stats']
-
 /**
  * Verbs core owned once and a package owns now. Not core verbs: a plugin
  * may declare them, and the dispatcher prints the
@@ -36,4 +31,5 @@ export const MOVED_VERBS: Readonly<Record<string, string>> = {
   prune:
     'vx prune was removed (2026-09-11): the Docker-subset verb is not shipped; copy the ' +
     'workspace and `--filter` the build instead',
+  stats: 'vx stats was removed (H-19): run `vx info`, which prints the same report',
 }

package/src/workspace/config-schema.ts

@@ -15,7 +15,7 @@ import {
   type WorkspaceConfig,
 } from '../config.js'
 import {
-  DISPATCHED_VERBS,
+  CORE_VERBS,
   MAX_TIMEOUT_MS,
   nearest,
   normalizeGlob,
@@ -174,7 +174,7 @@ export function validateWorkspace(config: WorkspaceConfig, configPath: string):
           // would run the first declared and hide the second. Here, in the
           // schema, so every loader of the file — a run, a reading verb, the
           // plugin-verb lookup — refuses it the same way.
-          if (DISPATCHED_VERBS.includes(verb)) {
+          if ((CORE_VERBS as readonly string[]).includes(verb)) {
             throw new UserError(
               `${configPath}: plugin '${plug.name}' declares command '${verb}', a core verb — core verbs cannot be shadowed`,
             )

package/src/workspace/migration.ts

@@ -357,7 +357,13 @@ function renderConfigFile(
   if (p.importLines.length > 0) lines.push(...p.importLines)
   lines.push('', 'export default {', '  tasks: {')
   for (const t of p.tasks) {
-    for (const todo of t.todos) lines.push(`    // TODO(vx-migrate): ${todo}`)
+    // A reason can quote a manifest's own text (an Nx `env` key), and a
+    // line break there ended the comment: the rest was code in the file
+    // the next run evaluates (D-21). Each line stays inside the comment.
+    for (const todo of t.todos) {
+      const [first, ...rest] = todo.split(/\r\n|[\n\r\u2028\u2029]/)
+      lines.push(`    // TODO(vx-migrate): ${first}`, ...rest.map((l) => `    //   ${l}`))
+    }
     if (t.task === null) continue // skipped target — the TODO above explains
     // `__proto__: {…}` in a literal SETS the prototype, quoted or not, and
     // the run refused the config (item 1033); a computed key is a property.