@vzn/vx 0.0.631 → 0.0.633

package/schemas/why.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx why --format json",
+  "description": "A task's run against its previous run. On history older than run ids, `why` and `diff` are null and `explanation` carries the latest cache entry.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["taskId", "runId", "why", "diff", "roots"],
+      "properties": {
+        "taskId": { "type": "string" },
+        "runId": { "type": "string" },
+        "why": { "$ref": "#/$defs/why" },
+        "diff": { "$ref": "#/$defs/diff" },
+        "roots": {
+          "type": "array",
+          "description": "The tasks under moved upstreams whose own key components moved in this run, each with the chain from the asked task down to it.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["chain", "entries"],
+            "properties": {
+              "chain": { "type": "array", "items": { "type": "string" } },
+              "entries": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "name", "change", "before", "after"],
+                  "properties": {
+                    "kind": { "type": "string" },
+                    "name": { "type": "string" },
+                    "change": { "enum": ["added", "removed", "changed"] },
+                    "before": { "type": ["string", "null"] },
+                    "after": { "type": ["string", "null"] }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["taskId", "why", "diff", "explanation"],
+      "properties": {
+        "taskId": { "type": "string" },
+        "why": { "type": "null" },
+        "diff": { "type": "null" },
+        "explanation": { "$ref": "#/$defs/explanation" }
+      }
+    }
+  ],
+  "$defs": {
+    "why": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runId", "taskId", "found", "thisRun", "previousRun", "hashChanged", "note"],
+      "properties": {
+        "runId": { "type": "string" },
+        "taskId": { "type": "string" },
+        "found": { "const": true },
+        "thisRun": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["hash", "status", "cacheHit", "restored", "cached", "startedAt"],
+          "properties": {
+            "hash": {
+              "type": "string",
+              "description": "empty for a task that never ran (skipped)"
+            },
+            "status": { "type": "string" },
+            "cacheHit": { "type": ["boolean", "null"] },
+            "restored": {
+              "type": ["boolean", "null"],
+              "description": "on a hit: true when outputs were restored, false when up-to-date"
+            },
+            "cached": { "type": ["boolean", "null"] },
+            "startedAt": { "type": "integer", "description": "epoch ms" }
+          }
+        },
+        "previousRun": {
+          "type": ["object", "null"],
+          "description": "null on the task's first recorded run",
+          "additionalProperties": false,
+          "required": ["hash", "status", "cacheHit", "restored", "startedAt"],
+          "properties": {
+            "hash": { "type": "string" },
+            "status": { "type": "string" },
+            "cacheHit": { "type": ["boolean", "null"] },
+            "restored": {
+              "type": ["boolean", "null"],
+              "description": "on a hit: true when outputs were restored, false when up-to-date"
+            },
+            "startedAt": { "type": "integer" }
+          }
+        },
+        "hashChanged": {
+          "type": ["boolean", "null"],
+          "description": "null when either run has no key"
+        },
+        "note": { "type": "string" }
+      }
+    },
+    "diff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "taskId",
+        "found",
+        "previousRunId",
+        "entries",
+        "unchangedCount",
+        "note"
+      ],
+      "properties": {
+        "runId": { "type": "string" },
+        "taskId": { "type": "string" },
+        "found": { "type": "boolean" },
+        "previousRunId": { "type": ["string", "null"] },
+        "entries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "name", "change", "before", "after"],
+            "properties": {
+              "kind": { "type": "string", "description": "files, env, runtime, upstream, …" },
+              "name": { "type": "string" },
+              "change": { "enum": ["added", "removed", "changed"] },
+              "before": { "type": ["string", "null"] },
+              "after": { "type": ["string", "null"] }
+            }
+          }
+        },
+        "unchangedCount": { "type": "integer" },
+        "note": { "type": "string" }
+      }
+    },
+    "explanation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["taskId", "project", "task", "latestEntry", "note"],
+      "properties": {
+        "taskId": { "type": "string" },
+        "project": { "type": "string" },
+        "task": { "type": "string" },
+        "latestEntry": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "required": ["hash", "command", "exitCode", "durationMs", "sizeBytes", "createdAt"],
+          "properties": {
+            "hash": { "type": "string" },
+            "command": { "type": "string" },
+            "exitCode": { "type": "integer" },
+            "durationMs": { "type": "number" },
+            "sizeBytes": { "type": "integer" },
+            "createdAt": { "type": "integer" }
+          }
+        },
+        "note": { "type": "string" }
+      }
+    }
+  }
+}

package/skills/vx/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: vx
+description: Run, inspect and debug tasks in a vx monorepo (vx.config.ts, vx.workspace.ts). Use to build or test projects, find what a change affects, read why a task failed or re-ran, and query the cache as JSON.
+---
+
+# vx
+
+vx is the workspace's task runner and build cache. Run tasks through it, not
+through package scripts, so results are cached and ordered by their
+dependencies.
+
+## Run
+
+```sh
+vx run build --all                  # a task in every project that declares it
+vx run test --affected=origin/main  # only what the diff since origin/main reaches
+vx run app#build                    # one project's task (and what it depends on)
+vx run build --all --format json    # the result as JSON on stdout; logs go to stderr
+```
+
+The exit code is the verdict: `0` every task passed or hit the cache, `1` a
+task failed or was skipped, or the command was refused. `--format json`
+prints `schemas/summary.json` (`runId`, `ok`, `exitCode`, a row per task).
+Without a TTY a missing task name never prompts: vx exits 1 and lists the
+tasks it found.
+
+## Look before running
+
+```sh
+vx show --format json                          # projects, their tasks and dependencies
+vx run test --affected=origin/main --dry=json  # what would run, cache hit or miss, and why
+```
+
+Under `--affected`, each kept task in `--dry=json` carries `affected`:
+`{ kind, file?, project?, via? }`, where `kind` is `input` (a changed file
+is one of its inputs), `project`, `package`, `named` or `selected`, and
+`via` is the `dependsOn` chain that carried the change.
+
+## When a task fails
+
+```sh
+vx last --failed --format json   # the last failed run; a failed row has output and locations
+vx last --log app#build          # one task's output: a failure's, or its cached log
+```
+
+A failed row's `output` is the task's output as plain text (secrets masked)
+and `locations` the files it names as `{ file, line?, col? }`. Read those
+files, fix, and re-run the same command: cached tasks that passed replay from the cache.
+
+## When a task re-ran unexpectedly
+
+```sh
+vx why app#build --format json   # which input changed, down to the root cause
+```
+
+## Workspace health
+
+```sh
+vx info --format json   # vx and Bun versions, projects, config errors, plugins, cache
+```
+
+## MCP
+
+When `@vzn/vx-mcp` is a plugin in `vx.workspace.ts`, `vx mcp` serves the
+same facts and runs tasks. Adoption does not add it: install
+`@vzn/vx-mcp` and put `mcp()` (from `'@vzn/vx-mcp'`) in `plugins`. Its tools: `listTasks`, `getCacheStats`,
+`getRunHistory`, `explainCacheKey`, `whyDidThisRerun`, `getFailures`, `getTaskLog`, `getConfig`, `checkLock`, `pruneCache`, `planInit`, `searchDocs`,
+`getWorkspaceInfo`, `runTasks`, `planTasks`. `runTasks` answers what
+`vx run <tasks> --format json` prints, `planTasks` what
+`vx run <tasks> --dry=json` prints, `pruneCache` evicts only with
+`dryRun: false`; the others only read.
+
+## Rules
+
+- Never delete or edit the cache by hand; vx repairs it itself.
+- A sandboxed task that fails on a denied path: grant that one path in
+  `exec.sandbox.allow`. Never remove `sandbox` or widen it further.
+- A cached task declares its inputs (`cache.inputs.files`); if a change
+  does not re-run a task, the file is not one of its inputs. Fix the
+  config, do not force.
+- Every JSON shape is a JSON Schema in `node_modules/@vzn/vx/schemas/`.
+- Offline reference: `vx docs <words> --format json` searches the CLI, config
+  and cache pages that ship with vx; the sections holding every word print
+  whole.
+- Docs as markdown: https://vznjs.github.io/vx/llms.txt (its index).
+  When that host is unreachable, the same pages are
+  `https://raw.githubusercontent.com/vznjs/vx/main/packages/vx-docs/src/content/docs/<page>.md`:
+  `quickstart`, `guides/migrate`, `guides/configure`, `guides/agents`,
+  `guides/troubleshooting`, `guides/ci`, `guides/plugins`.

package/src/bin.ts

@@ -32,12 +32,15 @@ async function main(): Promise<void> {
   } catch (err) {
     const {
       configErrorFrame,
+      errorCode,
+      errorDocument,
       fsRefusalHint,
       isFsRefusal,
       isOutOfFds,
       isUserError,
       maskedLine,
       OUT_OF_FDS_HINT,
+      wantsJson,
     } = await import('./util/index.js')
     // A plugin's failure quotes what it was told (a remote's reply, a
     // header), and a config's own throw is its author's text: a secret in
@@ -64,6 +67,12 @@ async function main(): Promise<void> {
       const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
       say(`vx: ${message}\n`)
     }
+    // A verb asked for JSON answers JSON on a refusal too: an agent reading
+    // stdout got nothing to parse, and only prose on stderr to branch on.
+    if (wantsJson(argv)) {
+      const message = err instanceof Error ? err.message : String(err)
+      process.stdout.write(errorDocument(errorCode(err), maskedLine(message)))
+    }
     // Same reason as the success path above: a large stderr is truncated by
     // `process.exit` too, and an error message cut in half is the one a
     // reader most needs whole.

package/src/cache/archive.ts

@@ -50,7 +50,15 @@ import { lstat, mkdir, readlink, realpath, rmdir, stat, unlink, writeFile } from
 import path from 'node:path'
 import { UserError } from '../util/index.js'
 import { WORKSPACE_OUTPUT_PREFIX } from './layer.js'
-import { TarFormatError, type TarInput, tarEntries, tarPack, tarSize } from './tar-stream.js'
+import {
+  TarFormatError,
+  type TarInput,
+  tarEntries,
+  tarEntriesSync,
+  tarPack,
+  tarPackInto,
+  tarSize,
+} from './tar-stream.js'
 import { ON_THREAD_MAX } from './zstd.js'
 
 /** Archive entry name carrying the per-output mode/mtime sidecar. */
@@ -59,6 +67,10 @@ const META_ENTRY = '.vx-meta.json'
 /** Archive entry name of the always-present stdout record. */
 const STDOUT_ENTRY = 'stdout'
 
+// One decoder, its defaults (a leading BOM dropped), for both scanners.
+// `ignoreBOM`: a leading U+FEFF in a task's stdout is the task's.
+const utf8 = new TextDecoder('utf-8', { ignoreBOM: true })
+
 /**
  * The last entry: a CRC-32 over every entry before it, each its name, a
  * NUL, then its body, as 8 lowercase hex digits (v36, L-19). Nothing else
@@ -107,19 +119,30 @@ class SumCheck {
     name: string,
     body: AsyncIterable<Uint8Array>,
   ): Promise<AsyncIterable<Uint8Array> | null> {
+    if (!this.enter(name)) return this.sum.through(body)
+    this.verify(await textOf(body))
+    return null
+  }
+  /**
+   * The next regular entry: true when it is the sum entry, whose text the
+   * caller hands to `verify`; otherwise the caller hands its bytes to `add`.
+   */
+  enter(name: string): boolean {
     if (this.seen) throw new TarFormatError(`entry ${name} follows the artifact's checksum`)
-    if (name === SUM_ENTRY) {
-      const got = await textOf(body)
-      if (got !== this.sum.hex()) {
-        throw new TarFormatError(
-          `artifact content does not match its checksum (${got}, read ${this.sum.hex()})`,
-        )
-      }
-      this.seen = true
-      return null
-    }
+    if (name === SUM_ENTRY) return true
     this.sum.entry(name)
-    return this.sum.through(body)
+    return false
+  }
+  add(bytes: Uint8Array): void {
+    this.sum.add(bytes)
+  }
+  verify(got: string): void {
+    if (got !== this.sum.hex()) {
+      throw new TarFormatError(
+        `artifact content does not match its checksum (${got}, read ${this.sum.hex()})`,
+      )
+    }
+    this.seen = true
   }
   done(): void {
     if (!this.seen) throw new TarFormatError('artifact carries no checksum')
@@ -373,16 +396,12 @@ async function* summed(inputs: readonly TarInput[]): AsyncGenerator<TarInput> {
  * otherwise (measured 2026-09-03: 238 → 293 ms per 1 000 saves).
  */
 export async function packArtifactBytes(plan: ArtifactPlan): Promise<Uint8Array> {
-  // A small artifact's files are read on this thread (`ON_THREAD_MAX`).
-  const onThread = plan.size <= ON_THREAD_MAX
+  // A small artifact is read and packed on this thread (`ON_THREAD_MAX`):
+  // no promise or generator hop per file or block.
+  if (plan.size <= ON_THREAD_MAX) return packSmall(plan)
   const inputs = await Promise.all(
     plan.inputs.map(async (i) =>
-      i.body instanceof Blob
-        ? {
-            ...i,
-            body: onThread ? readFileSync((i.body as Bun.BunFile).name!) : await i.body.bytes(),
-          }
-        : i,
+      i.body instanceof Blob ? { ...i, body: await i.body.bytes() } : i,
     ),
   )
   const out = new Uint8Array(plan.size)
@@ -395,6 +414,28 @@ export async function packArtifactBytes(plan: ArtifactPlan): Promise<Uint8Array>
   return out
 }
 
+/** `summed` + `tarPack` for a plan whose bodies fit in memory, synchronously. */
+function packSmall(plan: ArtifactPlan): Uint8Array {
+  const sum = new EntrySum()
+  const inputs: (TarInput & { body: Uint8Array | string })[] = []
+  for (const i of plan.inputs) {
+    const body =
+      i.body instanceof Blob
+        ? readFileSync((i.body as Bun.BunFile).name!)
+        : typeof i.body === 'string'
+          ? new TextEncoder().encode(i.body)
+          : (i.body as Uint8Array)
+    sum.entry(i.name)
+    sum.add(body)
+    inputs.push({ ...i, body })
+  }
+  inputs.push({ name: SUM_ENTRY, size: SUM_SIZE, body: sum.hex() })
+  const out = new Uint8Array(plan.size)
+  const n = tarPackInto(inputs, out)
+  if (n !== plan.size) throw new TarFormatError(`packed ${n} bytes, planned ${plan.size}`)
+  return out
+}
+
 /** Plan and pack in one go, in memory. */
 export async function packArtifact(args: PackArgs): Promise<Uint8Array> {
   return await packArtifactBytes(await planArtifact(args))
@@ -413,6 +454,51 @@ function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
   })
 }
 
+/** What a scan of an artifact reads out of it. */
+interface ArtifactScan {
+  entries: ArchiveEntry[]
+  stdout: string | null
+  exec: ExecUsage | undefined
+  key: string | undefined
+}
+
+/** A scan's result, built entry by entry in tar order: the one fold both scanners share. */
+class ScanFold {
+  private readonly seen: Array<{ name: string; size: number; mtimeMs: number }> = []
+  private files: MetaFile['files'] = {}
+  private exec: ExecUsage | undefined
+  private key: string | undefined
+  stdout: string | null = null
+
+  sidecar(text: string): void {
+    const parsed = JSON.parse(text) as MetaFile
+    this.files = parsed.files ?? {}
+    // The ingest side is the untrusted boundary: a foreign sidecar's
+    // usage is taken only when it is a plain non-negative number.
+    this.exec = usageOf(parsed.exec)
+    if (typeof parsed.key === 'string') this.key = parsed.key
+  }
+
+  entry(name: string, size: number, mtimeMs: number): void {
+    this.seen.push({ name, size, mtimeMs })
+  }
+
+  result(): ArtifactScan {
+    return {
+      entries: this.seen.map((s) => {
+        const m = this.files[s.name]
+        // A foreign artifact (or one whose sidecar lost an entry) restores
+        // readable-but-not-executable rather than failing the hit: the
+        // sidecar is metadata, never the authority on whether bytes exist.
+        return { name: s.name, size: s.size, mode: m?.[0] ?? 0o644, mtimeMs: m?.[1] ?? s.mtimeMs }
+      }),
+      stdout: this.stdout,
+      exec: this.exec,
+      key: this.key,
+    }
+  }
+}
+
 /**
  * List an artifact's regular entries with their restore metadata, and
  * its stdout text (`null` when the entry is absent — not a vx artifact),
@@ -420,49 +506,55 @@ function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
  * name is unsafe — a partial reading of a poisoned artifact is the
  * outcome the traversal defense exists to prevent.
  */
-export async function scanArtifact(tar: ReadableStream<Uint8Array>): Promise<{
-  entries: ArchiveEntry[]
-  stdout: string | null
-  exec: ExecUsage | undefined
-  key: string | undefined
-}> {
-  const seen: Array<{ name: string; size: number; mtimeMs: number }> = []
-  let meta: MetaFile['files'] = {}
-  let exec: ExecUsage | undefined
-  let key: string | undefined
-  let stdout: string | null = null
+export async function scanArtifact(tar: ReadableStream<Uint8Array>): Promise<ArtifactScan> {
+  const fold = new ScanFold()
   const check = new SumCheck()
   for await (const e of tarEntries(tar)) {
     if (e.type !== '0') continue
     const body = await check.body(e.name, e.body)
     if (body === null) continue
     if (e.name === META_ENTRY) {
-      const parsed = JSON.parse(await textOf(body)) as MetaFile
-      meta = parsed.files ?? {}
-      // The ingest side is the untrusted boundary: a foreign sidecar's
-      // usage is taken only when it is a plain non-negative number.
-      exec = usageOf(parsed.exec)
-      if (typeof parsed.key === 'string') key = parsed.key
+      fold.sidecar(await textOf(body))
       continue
     }
     assertSafeName(e.name)
-    if (e.name === STDOUT_ENTRY) stdout = await textOf(body)
+    if (e.name === STDOUT_ENTRY) fold.stdout = await textOf(body)
     else await drain(body)
-    seen.push({ name: e.name, size: e.size, mtimeMs: e.mtimeMs })
+    fold.entry(e.name, e.size, e.mtimeMs)
   }
   check.done()
-  return {
-    entries: seen.map((s) => {
-      const m = meta[s.name]
-      // A foreign artifact (or one whose sidecar lost an entry) restores
-      // readable-but-not-executable rather than failing the hit: the
-      // sidecar is metadata, never the authority on whether bytes exist.
-      return { name: s.name, size: s.size, mode: m?.[0] ?? 0o644, mtimeMs: m?.[1] ?? s.mtimeMs }
-    }),
-    stdout,
-    exec,
-    key,
+  return fold.result()
+}
+
+/**
+ * `scanArtifact` over a tar in memory, synchronously: a save scans the
+ * tar it just packed. Same decoder, same checks in the same order, same
+ * result. The async generators, per-chunk promises and drain were most
+ * of a small save's scan: one 400 B output, 49 → 14 µs (X-191).
+ */
+export function scanTarBytes(tar: Uint8Array): ArtifactScan {
+  const fold = new ScanFold()
+  const check = new SumCheck()
+  for (const e of tarEntriesSync(tar)) {
+    if (e.type !== '0') continue
+    if (check.enter(e.name)) {
+      check.verify(utf8.decode(e.body()))
+      continue
+    }
+    if (e.name === META_ENTRY) {
+      const body = e.body()
+      check.add(body)
+      fold.sidecar(utf8.decode(body))
+      continue
+    }
+    assertSafeName(e.name)
+    const body = e.body()
+    check.add(body)
+    if (e.name === STDOUT_ENTRY) fold.stdout = utf8.decode(body)
+    fold.entry(e.name, e.size, e.mtimeMs)
   }
+  check.done()
+  return fold.result()
 }
 
 /** The usage worth carrying: each axis a finite non-negative number, or absent; nothing → undefined. */
@@ -569,7 +661,7 @@ async function bytesOf(body: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
 }
 
 const textOf = async (body: AsyncIterable<Uint8Array>): Promise<string> =>
-  new TextDecoder().decode(await bytesOf(body))
+  utf8.decode(await bytesOf(body))
 
 /** One staged entry: written at `tmp`, renamed to `target` on commit. */
 interface Staged {
@@ -1012,6 +1104,12 @@ function assertSafeName(name: string): void {
   if (name.includes('//')) {
     throw new ArchiveSecurityError(`archive entry name has empty path component (unsafe): ${name}`)
   }
+  // vx never packs a `.` segment, and `outputs/.` names the anchor itself:
+  // ingest kept it, and every hit then failed renaming a file over the
+  // project directory, blamed on the user's tree.
+  if (hasDotSegment(name)) {
+    throw new ArchiveSecurityError(`archive entry name has a '.' segment (unsafe): ${name}`)
+  }
   // No backslash refusal: vx runs on Linux and macOS (Windows through WSL),
   // where it is a name character, and the save scans its own artifact with
   // these checks, so refusing one made `dist/back\slash` uncacheable.
@@ -1049,6 +1147,10 @@ const NAME_MAX = 255
 /** Bytes a path may hold, its terminating NUL included (limits.h). */
 const PATH_MAX = process.platform === 'darwin' ? 1024 : 4096
 
+function hasDotSegment(p: string): boolean {
+  return p === '.' || p.startsWith('./') || p.endsWith('/.') || p.includes('/./')
+}
+
 function hasParentSegment(p: string): boolean {
   if (p === '..' || p.startsWith('../') || p.endsWith('/..')) return true
   return p.includes('/../')