@vzn/vx 0.0.631 → 0.0.632

package/README.md

@@ -93,12 +93,11 @@ More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 
 ## Coming from Turbo or Nx
 
-`bunx @vzn/vx-migrate` writes a `vx.config.ts` per package from
-`turbo.json` or the Nx graph; you keep those and delete the old config.
-Beside `turbo.json` or `nx.json`, `vx init` writes only a
-`vx.workspace.ts` that maps the old config until then: a temporary
-start, not a way to run the repo. The numbers above are native vx
-config.
+Beside `turbo.json` or `nx.json`, `npx vx init` runs `@vzn/vx-migrate`:
+it writes a `vx.config.ts` per package from `turbo.json` or the Nx graph,
+and you keep those and delete the old config. `vx init --keep` writes only
+a `vx.workspace.ts` that maps the old config instead: a temporary start,
+not a way to run the repo. The numbers above are native vx config.
 [Migration guide](https://vznjs.github.io/vx/guides/migrate/).
 
 ## Why it is faster
@@ -127,7 +126,7 @@ config.
 | Output ownership   | **Strict**: wiped before exec and restore | Additive (stale files survive) | Additive         |
 | Clean-tree hashing | **No source reads** (git index OIDs)      | git OIDs                       | re-hash / daemon |
 | Daemon             | **None**                                  | None for `turbo run`           | On by default    |
-| Per-task sandbox   | **Yes**: kernel-level, opt-in             | No                             | No               |
+| Per-task sandbox   | **Yes**: kernel-level, opt-in, local      | No                             | On Nx Cloud only |
 | Plugin API         | **Yes**: every pipeline stage             | No                             | Yes (TS-tied)    |
 | Install            | **Single binary**; no Bun, Node optional  | npm + Node                     | npm + Node       |
 
@@ -146,7 +145,7 @@ Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
 | [`@vzn/vx-lockfile`](packages/vx-lockfile)                 | Key each project on its own lockfile slice: pnpm, bun, npm, yarn              |
 | [`@vzn/vx-otel`](packages/vx-otel)                         | OpenTelemetry traces, metrics and logs, no SDK                                |
 | [`@vzn/vx-ci`](packages/vx-ci)                             | GitHub Actions job summary and Checks API                                     |
-| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: a read-only MCP server for AI coding agents                         |
+| [`@vzn/vx-mcp`](packages/vx-mcp)                           | `vx mcp`: an MCP server for AI coding agents that also runs tasks             |
 | [`@vzn/vx-schedule-history`](packages/vx-schedule-history) | Schedule by the critical path learned from past runs                          |
 
 Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.631",
+  "version": "0.0.632",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.631",
-    "@vzn/vx-linux-arm64": "0.0.631",
-    "@vzn/vx-darwin-x64": "0.0.631",
-    "@vzn/vx-darwin-arm64": "0.0.631"
+    "@vzn/vx-linux-x64": "0.0.632",
+    "@vzn/vx-linux-arm64": "0.0.632",
+    "@vzn/vx-darwin-x64": "0.0.632",
+    "@vzn/vx-darwin-arm64": "0.0.632"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"
@@ -33,6 +33,8 @@
     "index.ts",
     "src",
     "config",
+    "schemas",
+    "skills",
     "launcher.cjs",
     "README.md",
     "LICENSE"

package/schemas/cache.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx cache prune --format json",
+  "description": "What the policy evicted and the orphan sweep reaped; with dryRun, what they would.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["dryRun", "evicted", "bytesFreed", "orphans", "orphanBytes"],
+  "properties": {
+    "dryRun": { "type": "boolean" },
+    "evicted": {
+      "type": "integer",
+      "description": "index entries evicted by the age / size policy"
+    },
+    "bytesFreed": {
+      "type": "integer",
+      "description": "bytes those entries occupied, per the index"
+    },
+    "orphans": {
+      "type": "integer",
+      "description": "artifacts and temp files with no index row, reaped"
+    },
+    "orphanBytes": { "type": "integer" }
+  }
+}

package/schemas/error.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "a refusal under --format json",
+  "description": "What a verb asked for JSON prints on stdout when it refuses (exit 1). stderr carries the same refusal in prose.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "error"],
+  "properties": {
+    "ok": { "const": false },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "Stable; branch on it. VX_E_USAGE, VX_E_UNKNOWN_COMMAND, VX_E_UNKNOWN_TASK, VX_E_UNKNOWN_PROJECT, VX_E_NO_HISTORY, VX_E_AMBIGUOUS, VX_E_CONFIG, VX_E_CYCLE, VX_E_NO_WORKSPACE, VX_E_CACHE_VERSION, VX_E_REFUSED, VX_E_FS, VX_E_FDS, VX_E_INTERNAL."
+        },
+        "message": { "type": "string", "description": "The refusal in prose; may change." }
+      }
+    }
+  }
+}

package/schemas/info.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx info --format json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "vx",
+    "bun",
+    "bunSupported",
+    "git",
+    "gitStatusCache",
+    "workspaceRoot",
+    "projects",
+    "tasks",
+    "configErrors",
+    "plugins",
+    "workers",
+    "memory",
+    "cacheDir",
+    "cacheStore",
+    "cacheVersion",
+    "schemaVersion",
+    "cacheEntries",
+    "cacheBytes",
+    "cacheRetention",
+    "orphans",
+    "runs24h",
+    "hits24h",
+    "restored24h",
+    "flakyTasks",
+    "lockfile",
+    "sandbox"
+  ],
+  "properties": {
+    "vx": { "type": "string" },
+    "bun": { "type": "string" },
+    "bunSupported": { "type": "boolean" },
+    "git": { "type": ["string", "null"] },
+    "gitStatusCache": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["fsmonitor", "untrackedCache"],
+      "properties": { "fsmonitor": { "type": "boolean" }, "untrackedCache": { "type": "boolean" } }
+    },
+    "workspaceRoot": { "type": "string" },
+    "projects": { "type": "integer" },
+    "tasks": { "type": "integer" },
+    "configErrors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "message"],
+        "properties": { "path": { "type": "string" }, "message": { "type": "string" } }
+      }
+    },
+    "plugins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "seams"],
+        "properties": {
+          "name": { "type": "string" },
+          "seams": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "workers": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["count", "source", "cores", "cpuQuota"],
+      "properties": {
+        "count": { "type": "integer" },
+        "source": { "enum": ["workspace", "cgroup", "cores"] },
+        "cores": { "type": "integer" },
+        "cpuQuota": { "type": ["number", "null"] }
+      }
+    },
+    "memory": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["usableBytes", "totalBytes", "cgroupLimitBytes"],
+      "properties": {
+        "usableBytes": { "type": "integer" },
+        "totalBytes": { "type": "integer" },
+        "cgroupLimitBytes": { "type": ["integer", "null"] }
+      }
+    },
+    "cacheDir": { "type": "string" },
+    "cacheStore": { "type": ["string", "null"] },
+    "cacheVersion": { "type": "string" },
+    "schemaVersion": { "type": "string" },
+    "cacheEntries": { "type": "integer" },
+    "cacheBytes": { "type": "integer" },
+    "cacheRetention": {
+      "type": ["object", "null"],
+      "description": "the workspace's cacheRetention, maxSize also in bytes; null when none is declared",
+      "additionalProperties": false,
+      "properties": {
+        "olderThan": { "type": "string" },
+        "maxSize": { "type": "string" },
+        "maxBytes": { "type": "integer" }
+      }
+    },
+    "orphans": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifacts", "bytes"],
+      "properties": { "artifacts": { "type": "integer" }, "bytes": { "type": "integer" } }
+    },
+    "runs24h": { "type": "integer" },
+    "hits24h": { "type": "integer" },
+    "restored24h": {
+      "type": "integer",
+      "description": "of hits24h, the hits that restored outputs; the rest were up to date"
+    },
+    "flakyTasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["taskId", "project", "task", "keys", "passes", "failures"],
+        "properties": {
+          "taskId": { "type": "string" },
+          "project": { "type": "string" },
+          "task": { "type": "string" },
+          "keys": { "type": "integer" },
+          "passes": { "type": "integer" },
+          "failures": { "type": "integer" }
+        }
+      }
+    },
+    "lockfile": { "type": "boolean" },
+    "sandbox": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["available", "reason", "declared", "untraced"],
+      "properties": {
+        "available": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "declared": { "type": "integer" },
+        "untraced": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/schemas/last.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx last --format json",
+  "description": "`vx last [RUNID] [--failed]` prints a run; `--list` prints an array of invocations, newest first; `--log <task>` prints that task's output.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["invocation", "tasks"],
+      "properties": {
+        "invocation": { "$ref": "#/$defs/invocation" },
+        "tasks": { "type": "array", "items": { "$ref": "#/$defs/task" } }
+      }
+    },
+    { "type": "array", "items": { "$ref": "#/$defs/invocation" } },
+    { "$ref": "#/$defs/log" }
+  ],
+  "$defs": {
+    "log": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runId", "taskId", "status", "source", "output"],
+      "properties": {
+        "runId": { "type": "string" },
+        "taskId": { "type": "string" },
+        "status": { "type": "string" },
+        "source": {
+          "enum": ["failure", "cache", null],
+          "description": "the kept failure output, the cache entry's log, or none kept"
+        },
+        "output": { "type": "string", "description": "plain text; '' when source is null" }
+      }
+    },
+    "invocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "command",
+        "requestedTasks",
+        "cachePolicy",
+        "concurrency",
+        "flow",
+        "startedAt",
+        "endedAt",
+        "totalDurationMs",
+        "taskCount",
+        "failedCount",
+        "hitCount",
+        "hitLocalCount",
+        "hitRemoteCount",
+        "upToDateCount",
+        "restoredLocalCount",
+        "restoredRemoteCount",
+        "exitOk",
+        "commitSha",
+        "branch",
+        "dirty",
+        "ci",
+        "ciProvider",
+        "host",
+        "os",
+        "arch",
+        "vxVersion",
+        "tags"
+      ],
+      "properties": {
+        "runId": { "type": "string" },
+        "command": { "type": "string" },
+        "requestedTasks": { "type": "array", "items": { "type": "string" } },
+        "cachePolicy": { "type": "string" },
+        "concurrency": { "type": "integer" },
+        "flow": { "enum": ["focused", "broad", null] },
+        "startedAt": { "type": "integer", "description": "epoch ms" },
+        "endedAt": { "type": "integer", "description": "epoch ms" },
+        "totalDurationMs": { "type": "number" },
+        "taskCount": { "type": "integer" },
+        "failedCount": { "type": "integer" },
+        "hitCount": { "type": "integer" },
+        "hitLocalCount": { "type": "integer" },
+        "hitRemoteCount": { "type": "integer" },
+        "upToDateCount": {
+          "type": "integer",
+          "description": "hits that restored nothing: the disk already matched"
+        },
+        "restoredLocalCount": {
+          "type": "integer",
+          "description": "hits that restored outputs from the local cache"
+        },
+        "restoredRemoteCount": {
+          "type": "integer",
+          "description": "hits that restored outputs from the remote cache"
+        },
+        "exitOk": { "type": "boolean" },
+        "commitSha": { "type": ["string", "null"] },
+        "branch": { "type": ["string", "null"] },
+        "dirty": { "type": ["boolean", "null"] },
+        "ci": { "type": "boolean" },
+        "ciProvider": { "type": ["string", "null"] },
+        "host": { "type": ["string", "null"] },
+        "os": { "type": ["string", "null"] },
+        "arch": { "type": ["string", "null"] },
+        "vxVersion": { "type": "string" },
+        "tags": { "type": "object", "additionalProperties": { "type": "string" } }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runId",
+        "project",
+        "task",
+        "status",
+        "exitCode",
+        "durationMs",
+        "startedAt",
+        "endedAt",
+        "cacheHit",
+        "restored",
+        "cached",
+        "hash",
+        "cpuMs",
+        "peakRssBytes",
+        "wallclockStartNs",
+        "wallclockEndNs",
+        "blockedBy",
+        "timedOut",
+        "sandboxViolations",
+        "notReady",
+        "forwarded"
+      ],
+      "properties": {
+        "runId": { "type": ["string", "null"] },
+        "project": { "type": "string" },
+        "task": { "type": "string" },
+        "status": { "type": "string" },
+        "exitCode": { "type": "integer" },
+        "durationMs": { "type": "number" },
+        "startedAt": { "type": "integer", "description": "epoch ms" },
+        "endedAt": { "type": "integer", "description": "epoch ms" },
+        "cacheHit": {
+          "type": ["boolean", "null"],
+          "description": "true when the task's outputs came from the cache instead of running"
+        },
+        "restored": {
+          "type": ["boolean", "null"],
+          "description": "on a hit: true when outputs were restored, false when up-to-date"
+        },
+        "cached": {
+          "type": ["boolean", "null"],
+          "description": "whether the task declares a cache (false prints no-cache); not whether this run hit it"
+        },
+        "hash": { "type": "string" },
+        "cpuMs": { "type": ["number", "null"] },
+        "peakRssBytes": { "type": ["integer", "null"] },
+        "wallclockStartNs": {
+          "type": ["string", "null"],
+          "description": "decimal nanoseconds from the run's start"
+        },
+        "wallclockEndNs": { "type": ["string", "null"] },
+        "blockedBy": { "type": ["string", "null"] },
+        "timedOut": { "type": ["boolean", "null"] },
+        "sandboxViolations": { "type": ["integer", "null"] },
+        "notReady": { "enum": ["timeout", "exited", "spawn", null] },
+        "forwarded": { "type": "boolean" },
+        "output": {
+          "type": "string",
+          "description": "on a failed row: its output, plain text, bounded (first 8 KiB, last 56 KiB), secrets masked; '' when none was recorded"
+        },
+        "locations": {
+          "type": "array",
+          "description": "on a failed row: the existing files its output names, in order of first appearance",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["file"],
+            "properties": {
+              "file": { "type": "string", "description": "absolute" },
+              "line": { "type": "integer" },
+              "col": { "type": "integer" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/plan.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx run --dry=json",
+  "description": "The task graph a run would execute and what the cache predicts for each task; nothing runs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["tasks"],
+  "properties": {
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "project", "task", "hash", "cacheStatus", "deps"],
+        "properties": {
+          "id": { "type": "string", "description": "project#task" },
+          "project": { "type": "string" },
+          "task": { "type": "string" },
+          "hash": { "type": "string", "description": "the cache key" },
+          "cacheStatus": {
+            "enum": ["hit-local", "hit-remote", "miss", "no-cache", "group", "not-started"]
+          },
+          "deps": { "type": "array", "items": { "type": "string" } },
+          "p50Ms": {
+            "type": "number",
+            "description": "typical executed duration, when history has one"
+          },
+          "executor": {
+            "type": "string",
+            "description": "where it would run; only when the workspace declares more than one executor"
+          },
+          "download": {
+            "const": "deferred",
+            "description": "outputs would stay remote (--download)"
+          },
+          "description": { "type": "string" },
+          "affected": {
+            "type": "object",
+            "description": "why --affected kept this requested task; absent on a dependency it pulled in",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+              "kind": {
+                "enum": ["input", "project", "package", "named", "selected"],
+                "description": "input: a changed file is a declared input; project: its project changed and the task reads it whole; package: a ^ edge passes a changed package; named: asked as pkg#task; selected: another filter selected its project"
+              },
+              "file": { "type": "string", "description": "the changed file, workspace-relative" },
+              "project": { "type": "string", "description": "the changed package (kind package)" },
+              "via": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "the dependsOn chain, nearest first, to the task the change reached"
+              }
+            }
+          }
+        }
+      }
+    },
+    "predicted": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["wallMs", "workMs", "unknownCount", "criticalPath"],
+      "properties": {
+        "wallMs": { "type": "number" },
+        "workMs": { "type": "number" },
+        "unknownCount": {
+          "type": "integer",
+          "description": "would-run tasks with no history; the times are lower bounds when above 0"
+        },
+        "criticalPath": {
+          "type": "array",
+          "description": "the would-run task ids with history along the chain wallMs measures, dependencies first",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "downloadDowngrades": {
+      "type": "array",
+      "description": "producers --download wanted to defer but could not, and why",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["taskId", "reason"],
+        "properties": { "taskId": { "type": "string" }, "reason": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/show.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx show --format json",
+  "description": "`vx show` lists projects; `vx show <project>` prints one project's resolved config; `vx show <project>#<task>` one task's; `vx show <task>` that task in every project declaring it. A secret value is masked.",
+  "oneOf": [
+    { "type": "array", "items": { "$ref": "#/$defs/listRow" } },
+    { "$ref": "#/$defs/project" },
+    { "$ref": "#/$defs/task" },
+    { "type": "array", "items": { "$ref": "#/$defs/task" } }
+  ],
+  "$defs": {
+    "listRow": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "dir", "tags", "tasks"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": {
+          "type": "string",
+          "description": "relative to the workspace root, POSIX separators"
+        },
+        "tags": { "$ref": "#/$defs/stringList" },
+        "tasks": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "dir", "config"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": { "type": "string" },
+        "config": {
+          "type": ["object", "null"],
+          "description": "null when the package has no vx config and no plugin gave it one",
+          "additionalProperties": false,
+          "properties": {
+            "tags": { "$ref": "#/$defs/stringList" },
+            "tasks": { "type": "object", "additionalProperties": { "$ref": "#/$defs/taskConfig" } }
+          }
+        }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "dir", "task", "config"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": { "type": "string" },
+        "task": { "type": "string" },
+        "config": { "$ref": "#/$defs/taskConfig" }
+      }
+    },
+    "stringList": { "type": "array", "items": { "type": "string" } },
+    "taskConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "description": { "type": "string" },
+        "dependsOn": { "$ref": "#/$defs/stringList" },
+        "exec": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["command"],
+          "properties": {
+            "command": { "type": "string" },
+            "remote": { "enum": [true, false, "only"] },
+            "timeout": { "type": "number", "description": "ms" },
+            "retries": { "type": "integer" },
+            "env": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "passThrough": { "$ref": "#/$defs/stringList" },
+                "define": { "type": "object", "additionalProperties": { "type": "string" } },
+                "secret": { "$ref": "#/$defs/stringList" }
+              }
+            },
+            "persistent": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": { "readyWhen": { "type": "string" } }
+            },
+            "interactive": { "type": "boolean" },
+            "sandbox": {
+              "type": "object",
+              "description": "as declared; its fields are the `exec.sandbox` section of the config schema"
+            }
+          }
+        },
+        "cache": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["inputs", "outputs"],
+          "properties": {
+            "inputs": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["files"],
+              "properties": {
+                "files": { "$ref": "#/$defs/stringList" },
+                "workspaceFiles": { "$ref": "#/$defs/stringList" },
+                "env": { "$ref": "#/$defs/stringList" },
+                "tasks": { "$ref": "#/$defs/stringList" },
+                "runtime": { "$ref": "#/$defs/stringList" },
+                "workspaceRuntime": { "$ref": "#/$defs/stringList" }
+              }
+            },
+            "outputs": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["files"],
+              "properties": {
+                "files": { "$ref": "#/$defs/stringList" },
+                "workspaceFiles": { "$ref": "#/$defs/stringList" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}