@vzn/vx 0.0.631 → 0.0.632

package/schemas/summary.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx run --summarize",
+  "description": "Every task's outcome in one run: <cacheDir>/runs/<runId>.json, or the --summarize=<path> file.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "runId",
+    "ok",
+    "exitCode",
+    "startedAt",
+    "endedAt",
+    "totalMs",
+    "savedMs",
+    "tasks",
+    "aborted",
+    "summary"
+  ],
+  "properties": {
+    "runId": { "type": "string" },
+    "ok": { "type": "boolean", "description": "the run's verdict: exitCode is 0" },
+    "exitCode": { "type": "integer" },
+    "startedAt": { "type": "string", "description": "ISO 8601" },
+    "endedAt": { "type": "string", "description": "ISO 8601" },
+    "totalMs": { "type": "number" },
+    "savedMs": {
+      "type": "number",
+      "description": "what the cache hits skipped: the sum of their storedDurationMs"
+    },
+    "tasks": {
+      "type": "array",
+      "description": "every counted task: not a group, not aborted",
+      "items": { "$ref": "#/$defs/task" }
+    },
+    "aborted": {
+      "type": "array",
+      "description": "tasks a shutdown signal killed; in no bucket and no total",
+      "items": { "$ref": "#/$defs/task" }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "successful",
+        "failed",
+        "skipped",
+        "cachedLocal",
+        "restoredLocal",
+        "restoredRemote",
+        "upToDate",
+        "cachedRemote",
+        "aborted",
+        "total"
+      ],
+      "properties": {
+        "successful": { "type": "integer" },
+        "failed": { "type": "integer" },
+        "skipped": { "type": "integer" },
+        "cachedLocal": { "type": "integer" },
+        "restoredLocal": { "type": "integer" },
+        "restoredRemote": { "type": "integer" },
+        "upToDate": { "type": "integer" },
+        "cachedRemote": { "type": "integer" },
+        "aborted": { "type": "integer" },
+        "total": { "type": "integer" }
+      }
+    }
+  },
+  "$defs": {
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "project", "task", "status", "exitCode", "durationMs", "hash"],
+      "properties": {
+        "id": { "type": "string" },
+        "project": { "type": "string" },
+        "task": { "type": "string" },
+        "status": {
+          "enum": ["success", "cache-hit", "cache-hit-remote", "failed", "skipped", "aborted"]
+        },
+        "exitCode": { "type": "integer" },
+        "durationMs": { "type": "number" },
+        "hash": { "type": ["string", "null"] },
+        "restored": {
+          "type": "boolean",
+          "description": "on a hit only: true when outputs were restored, false when they were already up to date"
+        },
+        "noCache": {
+          "const": true,
+          "description": "the task declares no cache block: it could never hit"
+        },
+        "flaky": {
+          "type": "object",
+          "description": "this key both passed and failed on record, or the task needed a retry",
+          "additionalProperties": false,
+          "required": ["passes", "failures", "attempts"],
+          "properties": {
+            "passes": { "type": "integer" },
+            "failures": { "type": "integer" },
+            "attempts": { "type": "integer" }
+          }
+        },
+        "cpuMs": { "type": "number" },
+        "peakRssBytes": { "type": "integer" },
+        "storedDurationMs": {
+          "type": "number",
+          "description": "a hit: how long the producing execution ran, what the hit skipped"
+        },
+        "storedCpuMs": {
+          "type": "number",
+          "description": "a hit: what the producing execution used"
+        },
+        "storedPeakRssBytes": { "type": "integer" },
+        "admissionHeldMs": {
+          "type": "number",
+          "description": "an admit policy held it with a worker free"
+        },
+        "blockedBy": {
+          "type": "string",
+          "description": "a skipped task: the failed task at the root of what blocked it"
+        },
+        "timedOut": { "const": true },
+        "sandboxViolations": { "type": "integer" },
+        "notReady": { "enum": ["timeout", "exited", "spawn"] },
+        "wallclockStartNs": {
+          "type": "string",
+          "description": "decimal nanoseconds from the run's start"
+        },
+        "wallclockEndNs": { "type": "string" }
+      }
+    }
+  }
+}

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,85 @@
+---
+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`,
+`getWorkspaceInfo`, `runTasks`, `planTasks`. `runTasks` answers what
+`vx run <tasks> --format json` prints, `planTasks` what
+`vx run <tasks> --dry=json` prints; 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/`.
+- 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.