@vzn/vx 0.0.16 → 0.0.18

package/README.md

@@ -3,9 +3,13 @@
 **The fastest way to build a monorepo.**
 
 vx runs your task graph, remembers every result, and never does the
-same work twice. Fully cached runs finish in milliseconds — 144 ms
-across 100 packages, 0.62 s across a 1090-package graph of 3,270
-tasks. Measured, reproducible, on hardware you own.
+same work twice. Fully cached runs finish in milliseconds — 76 ms
+across 46 packages, 559 ms across a 1,090-package graph of 3,270 tasks,
+where Turborepo takes 760 ms and Nx 3.59 s on the identical workspace —
+and a cold build of that graph burns 34 s of CPU in vx, 73 s in Turborepo
+and 114 minutes in Nx.
+Measured, reproducible, on hardware you own
+([benchmarks](docs/benchmarks.md)).
 
 One binary. No daemon. No Node. Nothing to babysit.
 
@@ -42,6 +46,7 @@ export default defineProject({
 ```
 
 ```sh
+vx init                   # scaffold vx.workspace.ts + a vx.config.ts per package from scripts
 vx run build              # cwd project + its workspace deps
 vx run test --all         # every project that declares `test`
 vx run ci --affected      # only what changed since origin/HEAD
@@ -125,23 +130,43 @@ resolution that bridges packages without the task · multi-task runs
 with one shared graph · pnpm-style filters and `--affected` ·
 watch mode · `--dry` / `--graph` plans · persistent dev servers ·
 retries, timeouts, `--continue` modes · per-layer cache control
-(`--cache=local:r,remote:`) · `vx info`, `--summarize`, `--profile`
-Chrome traces, `--report` · `vx cache prune` with TTL and size caps ·
-`vx migrate` from turbo.json or an Nx graph.
-
-## Extensible by design — the core is provider-neutral
-
-`vx` runs tasks and nothing else. A dashboard, a remote cache,
-distributed execution, and telemetry export all arrive through
-**plugins** declared in `vx.workspace.ts`, filling three seams the
-core exposes — **backend** (where a task runs), **cache** (a remote
-layer behind the local one), and **telemetry** (a read-only stream of
-the versioned `TelemetryRecord` / `RunSummaryRecord` contract). Core
-depends on none of them; the arrow only ever points plugin → core.
-First-party plugins ship the OpenTelemetry exporter
-([`@vzn/vx-otel`](https://www.npmjs.com/package/@vzn/vx-otel), OTLP
-traces + metrics with zero OTel-SDK deps) and **vx Cloud** (below) —
-and the same seams are open to anyone.
+(`--cache=local:r,remote:`) · `vx why` explains a re-run from the
+persisted input fingerprints · `vx last` replays a recorded run ·
+`vx prune` cuts a Docker-ready workspace subset · `vx info`,
+`--summarize`, `--profile` Chrome traces, `--report` · `vx cache prune`
+with TTL and size caps · `vx migrate` from turbo.json or an Nx graph.
+
+## A pipeline with seams — plugins decide what happens
+
+Core is the pipeline: discover projects, evaluate configs, build the
+task graph, derive keys, schedule, execute, cache, observe. Plugins
+declared in `vx.workspace.ts` hook each stage, Vite-style, on one
+`VxPlugin` object:
+
+| Stage     | Hook                       | A plugin can…                                               |
+| --------- | -------------------------- | ----------------------------------------------------------- |
+| workspace | `config(ws, ctx)`          | edit the workspace config before it is used                 |
+| project   | `project(config, ctx)`     | add, remove or rewrite a project's tasks (keyed like yours) |
+| graph     | `graph(nodes, ctx)`        | add or drop edges, mark tasks requested                     |
+| key       | `key(task, ctx)`           | fold extra material into the cache key (named in `vx why`)  |
+| schedule  | `schedule(nodes, ctx)`     | decide which ready task runs first                          |
+| execute   | `executor(ctx)`            | decide WHERE a task's command runs (local, a REAPI worker)  |
+| store     | `cache(ctx)`               | decide where artifacts live (local, a shared remote)        |
+| observe   | `telemetry(ctx)` / `setup` | receive every run record, or the raw event bus              |
+| cli       | `commands`                 | add verbs to `vx`                                           |
+
+Core applies **no plugin by default** — even its own local executor and
+cache are plugins your workspace declares, which is what makes "replace
+any part" real rather than promised. First-party plugins:
+[`@vzn/vx-reapi`](packages/vx-reapi) (Bazel Remote Execution API —
+remote cache and remote execution against NativeLink, BuildBuddy,
+Buildbarn or bazel-remote), [`@vzn/vx-otel`](packages/vx-otel)
+(OpenTelemetry traces + metrics + logs, zero SDK deps),
+[`@vzn/vx-github`](packages/vx-github) (Actions job summary + Checks
+API), [`@vzn/vx-mcp`](packages/vx-mcp) (`vx mcp` — a read-only Model
+Context Protocol server for AI coding agents, no SDK), and
+`@vzn/vx/plugins/schedule-history` (order by learned critical path). Nothing distributed ships in this repo; the seams are how you
+build it.
 
 ## How it compares
 
@@ -154,17 +179,13 @@ and the same seams are open to anyone.
 | Daemon required for speed | **No**                                                                | Optional                       | Yes              |
 | Per-task sandbox          | **Yes** — kernel-level, opt-in                                        | No                             | No               |
 | Provable cache safety     | **Yes** — `--verify` (determinism) + `--verify=inputs` (completeness) | No                             | No               |
-| MCP server for AI agents  | **Yes** — `vx mcp` (stdio, reads your local cache)                    | No                             | No               |
-| Plugin API                | **Yes** — backend / cache / telemetry seams                           | No                             | Yes (TS-tied)    |
-| Predictive scheduling     | **Yes** (opt-in: `predictive: true`)                                  | No                             | No               |
+| Plugin API                | **Yes** — executor / cache / telemetry seams                          | No                             | Yes (TS-tied)    |
 | OTel CI/CD spans          | **Yes** — `otel()` plugin, zero OTel-SDK deps                         | No                             | Paid             |
-| Self-hosted platform²     | **Yes** — dashboard, distributed CI, remote cache; Docker compose     | Vercel-only cache              | Paid (Nx Cloud)  |
 | Install                   | **Single binary** — npm or 1 curl line, no Node/Bun needed            | npm + Node                     | npm + Node       |
 
 ¹ Wall-clock, direct binaries, same machine and workspace — full
 methodology and more scenarios in
-[`docs/benchmarks.md`](docs/benchmarks.md). ² Optional, self-hosted,
-OSS — see [vx Cloud](#vx-cloud).
+[`docs/benchmarks.md`](docs/benchmarks.md).
 
 ## Switching from another runner
 
@@ -214,50 +235,6 @@ Differences to know:
 
 Side-by-side feature matrix + every known gap: [`docs/comparison.md`](./docs/comparison.md).
 
-## vx Cloud
-
-An **optional, self-hosted CI platform** — the first-party service you
-run yourself. It is a fully independent app (accounts, roles,
-organizations, teams, multiple workspaces), with **Postgres** as the
-system of record and an **S3-compatible bucket** for artifacts; the
-controller keeps zero artifact bytes at rest. Core `vx` never depends
-on it — it connects to a deployment through the plugin seams above.
-
-What a connected platform adds:
-
-- **Dashboard.** Runs, flamegraphs, a live run cockpit with the task
-  DAG, per-task logs + artifacts, cache-key diffs ("why did this
-  re-run?"), and flaky-task detection with the concrete fix.
-- **Remote cache.** The vx-native `/v1/cache` wire, tenant-partitioned
-  per org/workspace, with **trusted / untrusted tiers derived from the
-  token** — a fork-PR artifact can never feed a trusted build — and an
-  always-on integrity digest the client verifies.
-- **Distributed CI (DTE).** Agents form a session-keyed pool; a
-  `vx run` fans tasks out across same-commit agents, outputs propagate
-  through the shared artifact store, and a standing pool multiplexes
-  concurrent runs with fair scheduling.
-- **MCP over the platform.** `POST /mcp` (Postgres-backed, behind the
-  token) exposes the analytics as typed tools for AI agents — alongside
-  the core `vx mcp` stdio server that reads your local cache.
-
-Deploy the stack (app + Postgres + object storage) with Docker
-Compose, then connect any workspace with one URL and a minted token:
-
-```sh
-# Deploy — open the URL, register the first admin, mint a CI token under Admin → Tokens:
-VX_CLOUD_SECRET=$(openssl rand -hex 32) \
-  docker compose -f packages/cloud/deploy/docker-compose.yml up
-
-# Connect a workspace (remote cache + analytics + distribution):
-vx-cloud connect https://ci.acme.dev --token vxc_…
-# …or set VX_CLOUD_URL + VX_CLOUD_TOKEN in the environment.
-```
-
-Install the platform CLI with `npm i -g @vzn/vx-cloud` (a standalone
-binary, or the `ghcr.io/vznjs/vx-cloud` image). Full setup, RBAC,
-distributed CI, and the wire protocol live in the **vx Cloud** section
-of the [documentation site](https://vznjs.github.io/vx/).
-
 ## Architecture (one paragraph)
 
 `bin.ts → cli/index.ts` dispatches subcommands.
@@ -290,43 +267,43 @@ Full technical docs live under [`docs/`](./docs/) and on the
 - [`docs/cli.md`](./docs/cli.md) — every flag
 - [`docs/comparison.md`](./docs/comparison.md) — Turbo / Nx / vite-task feature matrix
 - [`docs/modules/`](./docs/modules/) — one reference page per source module
-- The **vx Cloud** section of the [docs site](https://vznjs.github.io/vx/) — deploy, RBAC, dashboard, distributed CI, wire protocol
 
-The full design record (including the platform-pivot notes) lives
-under [`docs/design/`](./docs/design/).
+The design record lives under [`docs/design/`](./docs/design/); the
+maintainers' handoff is [`docs/STATUS.md`](./docs/STATUS.md).
 
 ## Status
 
 **Pre-alpha.** The schema is settling; we bump `CACHE_VERSION` rather
-than maintain back-compat. **1,600+ tests (core + packages); CI green
-on every commit**; the project dogfoods itself (`vx run ci`).
-Published on npm: [`@vzn/vx`](https://www.npmjs.com/package/@vzn/vx)
-(a prebuilt standalone binary) and `@vzn/vx-cloud`.
+than maintain back-compat. **~2,500 core tests plus the package suites; CI green on every commit**;
+the project dogfoods itself (`vx run ci`). Published on npm:
+[`@vzn/vx`](https://www.npmjs.com/package/@vzn/vx) (a prebuilt standalone
+binary).
 
 Production readiness for the **core task runner**: the semantics are
 solid; it is dogfooded continuously. The main operational rough edge
 is Windows (unsupported).
 
-| Surface                                        | Maturity                       | Notes                                                             |
-| ---------------------------------------------- | ------------------------------ | ----------------------------------------------------------------- |
-| Core task runner + caching                     | **production-ready**           | dogfooded continuously; 1,200+ core tests, all green              |
-| `vx run --verify` (provable cache correctness) | **shippable**                  | determinism + input-completeness proofs; CI-gate recipe in docs   |
-| `vx mcp`                                       | **shippable**                  | live cache.db tools over stdio                                    |
-| Plugin API (backend / cache / telemetry)       | **shippable**                  | crash-isolated; the cloud + OTel plugins are ordinary plugins     |
-| Predictive scheduling                          | **shippable as opt-in**        | gated on `predictive: true` + observed data                       |
-| OTel export (`@vzn/vx-otel`)                   | **shippable**                  | declare `otel()` in `vx.workspace.ts`; OTLP traces + metrics      |
-| vx Cloud platform (self-hosted)                | **shippable for self-hosting** | accounts/RBAC/orgs on Postgres, S3 artifacts, dashboard, DTE, MCP |
+| Surface                                          | Maturity             | Notes                                                                        |
+| ------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------- |
+| Core task runner + caching                       | **production-ready** | dogfooded continuously; ~2,500 core tests + the package suites, green        |
+| `vx run --verify` (provable cache correctness)   | **shippable**        | determinism + input-completeness proofs; CI-gate recipe in docs              |
+| Plugin pipeline (9 hooks, `commands` included)   | **shippable**        | crash-isolated, re-validated; core's own executor + cache are plugins        |
+| `vx init` / `vx migrate` (scripts, Turbo, Nx)    | **shippable**        | one config per package, TODOs where a source cannot say                      |
+| REAPI remote cache + execution (`@vzn/vx-reapi`) | **shippable**        | Bazel AC + CAS + Execute; NativeLink / BuildBuddy / Buildbarn / bazel-remote |
+| OTel export (`@vzn/vx-otel`)                     | **shippable**        | OTLP traces + metrics + logs, zero SDK deps                                  |
+| GitHub Actions (`@vzn/vx-github`)                | **shippable**        | job summary + Checks API run                                                 |
+| MCP server (`@vzn/vx-mcp`)                       | **shippable**        | `vx mcp` — read-only tools for AI agents, no SDK                             |
 
 ## Development
 
 ```sh
 git clone https://github.com/vznjs/vx && cd vx
 bun install
-bun src/bin.ts run ci          # format-check + lint + test
-bun src/bin.ts run build       # cross-target binaries → dist/
+bun packages/vx/src/bin.ts run ci --all     # lint + test + docs build, every package
+bun packages/vx/src/bin.ts run build --filter @vzn/vx   # cross-target binaries → packages/vx/dist/
 ```
 
-vx is self-hosted: every dev task routes through `bun src/bin.ts run <task>` per the repo's own `vx.config.ts`. No `package.json` scripts; CI invokes vx directly.
+vx is self-hosted: every dev task routes through `bun packages/vx/src/bin.ts run <task>` per each package's own `vx.config.ts`. No `package.json` scripts; CI invokes vx directly. Start with [`docs/STATUS.md`](docs/STATUS.md) — the living handoff — and `CLAUDE.md`.
 
 ## License
 

package/index.ts

@@ -0,0 +1,10 @@
+// Root entry shim. Bun 1.4.0's `--compile` binaries resolve an on-disk
+// package by directory convention (`<pkg>/index.ts`, `<pkg>/<subpath>/index.ts`)
+// and ignore package.json `exports` / `main` (measured 2026-09-03: an
+// entry of `./src/index.ts` resolved to the root `index.ts` regardless of the
+// manifest, and a package with no root file was "not found"). Without this
+// file every `import … from '@vzn/vx'` in a workspace config fails under the
+// standalone binary. The exports map still wins everywhere else and points
+// at the same module, so this is one extra hop for the binary and nothing
+// for anyone else.
+export * from './src/index.js'

package/launcher.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 // npm launcher for a vx command — the entry a published package's `bin` points
 // at. It execs the prebuilt standalone binary shipped as a per-platform
-// optionalDependency, so end users get the command WITHOUT installing Bun. ONE
-// launcher serves both `@vzn/vx` and `@vzn/vx-cloud`: everything is derived from
-// this package's OWN name, read from the package.json sitting beside this file.
+// optionalDependency, so end users get the command WITHOUT installing Bun.
+// Everything is derived from this package's OWN name, read from the
+// package.json sitting beside this file, so any package built by
+// scripts/build-npm.ts can carry it:
 //
-//   @vzn/vx        → platform pkg @vzn/vx-<key>,        binary `vx`
-//   @vzn/vx-cloud  → platform pkg @vzn/vx-cloud-<key>,  binary `vx-cloud`
+//   @vzn/vx → platform pkg @vzn/vx-<key>, binary `vx`
 //
 // Resolution order:
 //   1. the matching <name>-<platform> optionalDependency's binary (the normal
@@ -26,11 +26,10 @@ const require = createRequire(import.meta.url)
 const here = dirname(fileURLToPath(import.meta.url))
 const pkg = require('./package.json')
 
-// Derive the platform-package prefix + binary basename from this package's name
-// so the same launcher works for @vzn/vx and @vzn/vx-cloud. `base` is the
-// unscoped name (vx / vx-cloud) — the command AND the binary filename inside the
-// platform package. `vxSourceEntry` (a package.json field) is the source-mode
-// entry: `src/bin.ts` for vx, `src/cli/bin.ts` for vx-cloud.
+// Derive the platform-package prefix + binary basename from this package's
+// name. `base` is the unscoped name — the command AND the binary filename
+// inside the platform package. `vxSourceEntry` (a package.json field) is the
+// source-mode entry, `src/bin.ts` by default.
 const name = pkg.name
 const base = name.replace(/^@[^/]+\//, '')
 const sourceEntry = pkg.vxSourceEntry ?? 'src/bin.ts'
@@ -86,7 +85,7 @@ process.stderr.write(
   `${base}: no prebuilt binary for ${key}.\n` +
     `  Supported platforms: ${supported}.\n` +
     `  If your platform should be supported, reinstall so npm fetches the\n` +
-    `  matching ${name}-${key} optionalDependency, or install Bun (>=1.3) to\n` +
+    `  matching ${name}-${key} optionalDependency, or install Bun (>=1.4) to\n` +
     `  run ${base} from source.\n`,
 )
 process.exit(1)

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "An open, extensible monorepo task runner.",
   "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "import": "./src/index.ts"
+    },
+    "./plugins/local-executor": {
+      "types": "./src/plugins/local-executor/index.ts",
+      "import": "./src/plugins/local-executor/index.ts"
+    },
+    "./plugins/local-cache": {
+      "types": "./src/plugins/local-cache/index.ts",
+      "import": "./src/plugins/local-cache/index.ts"
+    },
+    "./plugins/schedule-history": {
+      "types": "./src/plugins/schedule-history/index.ts",
+      "import": "./src/plugins/schedule-history/index.ts"
     }
   },
   "types": "./src/index.ts",
@@ -17,15 +29,17 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.16",
-    "@vzn/vx-linux-arm64": "0.0.16",
-    "@vzn/vx-darwin-x64": "0.0.16",
-    "@vzn/vx-darwin-arm64": "0.0.16"
+    "@vzn/vx-linux-x64": "0.0.18",
+    "@vzn/vx-linux-arm64": "0.0.18",
+    "@vzn/vx-darwin-x64": "0.0.18",
+    "@vzn/vx-darwin-arm64": "0.0.18"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.56"
   },
   "files": [
+    "index.ts",
+    "plugins",
     "src",
     "launcher.mjs",
     "README.md",

package/plugins/local-cache/index.ts

@@ -0,0 +1,2 @@
+// Subpath shim for Bun's compiled binaries — see ../../index.ts.
+export * from '../../src/plugins/local-cache/index.js'

package/plugins/local-executor/index.ts

@@ -0,0 +1,2 @@
+// Subpath shim for Bun's compiled binaries — see ../../index.ts.
+export * from '../../src/plugins/local-executor/index.js'

package/plugins/schedule-history/index.ts

@@ -0,0 +1,2 @@
+// Subpath shim for Bun's compiled binaries — see ../../index.ts.
+export * from '../../src/plugins/schedule-history/index.js'

package/src/bin.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { run } from './cli/index.js'
-import { UserError } from './util/index.js'
+import { isUserError } from './util/index.js'
 
 // Wrapped in an explicit async main so `bun build --compile` accepts
 // the file. The compile target doesn't allow top-level await.
@@ -12,7 +12,7 @@ async function main(): Promise<void> {
     // print the message only; the stack is noise the user can't act
     // on. Everything else gets the full stack so internal bugs are
     // debuggable.
-    if (err instanceof UserError) {
+    if (isUserError(err)) {
       process.stderr.write(`vx: ${err.message}\n`)
     } else {
       const message = err instanceof Error ? (err.stack ?? err.message) : String(err)