@vzn/vx 0.0.0 → 0.0.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nxt contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,332 @@
-Reserved by the vx project. Real release to follow.
+# vx
+
+**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.
+
+One binary. No daemon. No Node. Nothing to babysit.
+
+📖 **[Documentation site →](https://vznjs.github.io/vx/)** — guides,
+architecture, caching, and the full CLI / config reference.
+
+```sh
+# From npm — ships the prebuilt standalone binary (no Bun required):
+npm install -g @vzn/vx      # or: pnpm add -g @vzn/vx · bun add -g @vzn/vx
+
+# Or the zero-dependency install script (no Node/npm needed):
+curl -fsSL https://raw.githubusercontent.com/vznjs/vx/main/install.sh | sh
+```
+
+```ts
+// vx.config.ts
+import { defineProject } from '@vzn/vx'
+
+export default defineProject({
+  tasks: {
+    build: {
+      exec: { command: 'tsc -b' },
+      dependsOn: ['^build'],
+      cache: {
+        inputs: { files: ['src/**'] },
+        outputs: { files: ['dist/**'] },
+      },
+    },
+    test: {
+      exec: { command: 'bun test' },
+      dependsOn: ['build'],
+      cache: { inputs: { files: ['src/**', 'tests/**'] }, outputs: { files: [] } },
+    },
+    ci: { dependsOn: ['lint', 'test'] }, // umbrella; runs both
+  },
+})
+```
+
+```sh
+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
+vx watch lint             # re-run on file changes
+vx run build --dry        # show the plan, don't execute
+```
+
+## Beyond a task runner — what shipped in the 2026-06 platform arc
+
+vx now ships an **open platform**, not just a CLI. Every surface
+below is built into the binary; no external services required.
+
+```sh
+vx mcp                                    # Model Context Protocol server (stdio)
+                                          # — Claude Code / Cursor / Continue.dev talk to vx as a typed tool
+
+vx coordinator build test --workers 4     # start a distributed-CI coordinator
+vx run --worker ws://coord:5180           # pull tasks from a coordinator and execute them
+
+vx serve --ui --open                      # unified backend + embedded dashboard + open browser
+                                          # /v1/* JSON, SSE events, WS run protocol, CORS *
+```
+
+### Open platform highlights
+
+- **Wire protocol = JSON-RPC 2.0 + OTel LogRecord payload.** Any
+  JSON-RPC client works against `vx serve`. Three transports — WS,
+  SSE, NDJSON — off the same bus.
+- **MCP server with live tools** (`getCacheStats`, `getRunHistory`,
+  `explainCacheKey`, `whyDidThisRerun`) that read your real
+  `cache.db`. Drop into any agent's stdio MCP slot.
+- **Plugin API.** Declare `plugins: [...]` in `vx.workspace.ts`;
+  each plugin subscribes to bus lifecycle events with crash
+  isolation per hook.
+- **Predictive scheduling.** Opt in with `predictive: true` in
+  `vx.workspace.ts` — the scheduler reads run history and picks
+  the task on the longest expected remaining critical path.
+- **Distributed CI.** `vx coordinator` + `vx run --worker` over the
+  same protocol. Content-addressed: any worker producing
+  `<hash>` satisfies every consumer of `<hash>`.
+- **OTel CI/CD spans (native).** Set `OTEL_EXPORTER_OTLP_ENDPOINT`,
+  install the three `@opentelemetry/*` peer deps — core speaks OTel
+  natively; every event flows to Grafana / Honeycomb / Datadog /
+  Tempo with zero bridge package.
+- **Self-host vx serve.** Same backend everywhere — laptop, Docker,
+  any container runtime. JSON `/v1/*` metrics API + WebSocket run
+  protocol + SSE event stream + permissive CORS. One stack.
+- **Dashboard embedded in the binary.** `vx serve --ui` serves a Solid
+  SPA at `/` — task averages, p50/p99, cache savings, recent runs,
+  flamegraphs — compiled into `vx` itself, nothing to install.
+  Connection picker switches between local and hosted backends.
+
+Each lives behind a one-paragraph design doc under
+`docs/design/*-2026-06.md`. Phase-by-phase implementation log:
+`docs/progress/implementation-log-2026-06.md`.
+
+## A cache that actually understands your build
+
+Every task runner caches. vx caches _correctly_ — and stops work
+others would redo:
+
+- **Config is code, and the cache knows it.** `vx.config.ts` is
+  evaluated before hashing, so imports, presets, and computed values
+  all participate in cache identity. Change a shared preset, and
+  exactly the right tasks re-run.
+- **Outputs are owned.** Declared outputs are wiped before every
+  execution and every restore. Your tree ends each run bit-identical
+  to the cached snapshot — stale files cannot exist.
+- **Hashes come from git.** On a clean tree, deriving every cache key
+  costs zero file reads, zero stats, zero database lookups. At
+  15,000 files that's a 3.2× faster warm path.
+
+## Speed is a design discipline
+
+Exact bitset graph algorithms for scheduling. One bulk git
+enumeration per run, partitioned by binary search. Restores that
+skip extraction entirely when the tree already matches. In-process
+tar (no subprocess on the hot path). Atomic artifact publishes.
+Single-transaction metadata writes. Every optimization is recorded
+with the invariant that keeps it valid —
+[`docs/optimizations.md`](docs/optimizations.md) is the ledger, and
+[`bench/`](bench/) reproduces the numbers.
+
+## Built for trust
+
+- **Signed artifacts.** HMAC signing on the remote-cache wire; with a
+  key configured, unsigned or tampered artifacts are rejected and the
+  task simply re-runs. A poisoned cache can't reach your machines.
+- **Corruption can't go live.** Artifacts are validated before they
+  enter the store; bad bytes degrade to a cache miss, never a crash.
+- **Clean exits.** SIGINT/SIGTERM reap every child process — no
+  orphaned dev servers in CI.
+- **Readiness you can bound.** Persistent tasks gate downstream work
+  on a `readyWhen` signal with a `readyTimeoutMs` ceiling.
+- **Kernel-level sandboxing**, opt-in per task, that fails the build
+  on violation instead of hiding it.
+
+## Reproducible graphs, when you want them
+
+Configs are TypeScript — powerful, but a program's output can vary
+with its environment. `vx lock` freezes the fully-resolved task graph
+into a committed `vx-lock.json`, pnpm-style:
+
+```sh
+vx lock                      # evaluate everything once, write vx-lock.json
+vx lock --check && vx run ci --frozen     # CI: audit, then run EXACTLY that graph
+```
+
+| Command           | Evaluates configs | Uses lock                                                       |
+| ----------------- | ----------------- | --------------------------------------------------------------- |
+| `vx run`          | always, live      | never — local truth has no asterisks                            |
+| `vx run --frozen` | never             | yes; refuses if absent or a config file changed since locking   |
+| `vx lock --check` | full graph        | compares — catches env and import drift that byte hashes cannot |
+
+Env values read at lock time are frozen by design — cache keys become
+reproducible across machines. Bonus: `--frozen` runs skip config
+evaluation entirely (~120 ms back per 1,000 packages). No other
+runner has an equivalent.
+
+## Everything you need, nothing to configure twice
+
+TypeScript config with real imports · task graph with `^task`
+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 ·
+remote caching via two env vars, wire-compatible with existing
+artifact servers · `vx stats`, `--summarize`, `--profile` Chrome
+traces · `vx cache prune` with TTL and size caps.
+
+## How it compares
+
+|                           | vx                                                                   | Turborepo                      | Nx                  |
+| ------------------------- | -------------------------------------------------------------------- | ------------------------------ | ------------------- |
+| Fully cached, 100 pkgs¹   | **144 ms**                                                           | 279 ms                         | 583+ ms             |
+| Config                    | TypeScript, evaluated into the cache key                             | JSON (static)                  | JSON (static)       |
+| Output ownership          | **Strict** — wiped before exec AND restore                           | Additive (stale files survive) | Additive            |
+| Clean-tree hashing        | **Zero reads** (git index OIDs)                                      | git OIDs                       | re-hash / daemon    |
+| Daemon required for speed | **No**                                                               | Optional                       | Yes                 |
+| Artifact signing          | **Hard-fail** on unsigned                                            | Soft                           | No                  |
+| Per-task sandbox          | **Yes** — kernel-level, opt-in                                       | No                             | No                  |
+| MCP server for AI agents  | **Yes** (`vx mcp`, stdio)                                            | No                             | No                  |
+| Distributed CI execution  | **Yes** — OSS, self-hostable (`vx coordinator` + `vx run --worker`)  | No                             | Paid (Nx Cloud DTE) |
+| Dashboard SPA             | **Yes** — bundled into `vx serve --ui`, Solid + p50/p99 + sparklines | No                             | Paid                |
+| Self-hosted cloud         | **Yes** — same `vx serve` in Docker; one stack                       | Vercel-only                    | No (proprietary)    |
+| Plugin API                | **Yes** — Vite-style lifecycle hooks                                 | No                             | Yes (TS-tied)       |
+| Predictive scheduling     | **Yes** (opt-in: `predictive: true`)                                 | No                             | No                  |
+| OTel CI/CD spans          | **Yes** (`OTEL_EXPORTER_OTLP_ENDPOINT`)                              | No                             | Paid                |
+| Install                   | **Single binary** — 1 curl line                                      | npm + Node                     | npm + Node          |
+
+¹ Wall-clock, direct binaries, same machine and workspace — full
+methodology and more scenarios in
+[`docs/benchmarks.md`](docs/benchmarks.md).
+
+## Switching from another runner
+
+Most projects can move in an afternoon. The mapping is mechanical:
+
+```jsonc
+// turbo.json (before)
+{
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["src/**"],
+      "outputs": ["dist/**"],
+      "env": ["NODE_ENV"],
+    },
+  },
+}
+```
+
+```ts
+// vx.config.ts (after)
+import { defineProject } from '@vzn/vx'
+export default defineProject({
+  tasks: {
+    build: {
+      // Name the command (Turbo reads package.json scripts). The child
+      // env is ISOLATED: a cache-input env var must also be passed
+      // through, or the key would vary while the task can't see it.
+      exec: { command: 'tsc -b', env: { passThrough: ['NODE_ENV'] } },
+      dependsOn: ['^build'],
+      cache: {
+        inputs: { files: ['src/**'], env: ['NODE_ENV'] },
+        outputs: { files: ['dist/**'] },
+      },
+    },
+  },
+})
+```
+
+Differences to know:
+
+- vx requires `exec.command` in the config — we don't read `package.json` scripts implicitly.
+- vx requires `cache.inputs.files` when caching is enabled (no default `$TURBO_DEFAULT$`).
+- vx defaults caching **off**; opt in per task by adding the `cache` block.
+- Persistent tasks: `persistent: { readyWhen: 'regex' }` (Turbo uses just `persistent: true`).
+- Remote cache: same wire format. Existing `VERCEL_*` / Turbo-cache-server tokens work via `VX_REMOTE_CACHE_TOKEN`.
+
+Side-by-side feature matrix + every known gap: [`docs/comparison.md`](./docs/comparison.md).
+
+## Architecture (one paragraph)
+
+`bin.ts → cli/index.ts` dispatches subcommands.
+`orchestrator/run.ts:run()` calls `prepareRun()` which discovers the
+workspace, loads configs, builds the package + task graph, opens the
+cache (local SQLite + optional remote layer), loads
+`HistoryProvider` (if `predictive: true`), and installs plugins from
+`vx.workspace.ts`. The scheduler runs the graph in topological order
+with bounded concurrency; each task hits the cache (hash → get →
+restore on hit; spawn → save on miss) or short-circuits as a group /
+persistent. Every observation flows through one event bus —
+terminal renderer, MCP server, OTel bridge, user plugins, and cloud
+uploader all subscribe to it. The on-wire form (JSON-RPC 2.0 +
+OTel-LogRecord-shaped payload) is the same across WS / SSE / NDJSON
+on `vx serve` and across the distributed-CI coordinator. Every
+module has a docs page; every interface is a swappable seam.
+
+Read [`docs/architecture.md`](./docs/architecture.md) for the module
+map. The 2026-06 platform arc is documented under
+[`docs/design/`](./docs/design/) and
+[`docs/progress/implementation-log-2026-06.md`](./docs/progress/implementation-log-2026-06.md).
+
+## Documentation
+
+Full technical docs live under [`docs/`](./docs/):
+
+**Core**
+
+- [`docs/architecture.md`](./docs/architecture.md) — module map + data flow
+- [`docs/schema.md`](./docs/schema.md) — every config field
+- [`docs/caching.md`](./docs/caching.md) — cache-key derivation + invalidation table
+- [`docs/execution.md`](./docs/execution.md) — `vx run` lifecycle
+- [`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
+
+**Design + 2026-06 platform arc** (`docs/design/`)
+
+- [`architecture-north-star-2026-06.md`](./docs/design/architecture-north-star-2026-06.md) — the unified vision
+- [`architecture-review-2026-06.md`](./docs/design/architecture-review-2026-06.md) — review + applied checklist
+- [`wire-protocol-2026-06.md`](./docs/design/wire-protocol-2026-06.md) — JSON-RPC 2.0 + OTel envelope (shipped)
+- [`distributed-ci-2026-06.md`](./docs/design/distributed-ci-2026-06.md) — coordinator + worker (Phase A-B shipped)
+- [`vx-cloud-2026-06.md`](./docs/design/vx-cloud-2026-06.md) — original CF cloud (superseded; vx serve now runs in Docker)
+- [`extension-protocol-2026-06.md`](./docs/design/extension-protocol-2026-06.md) — subscriber/inspector/driver/plugin (Phase 1 shipped)
+- [`predictive-execution-2026-06.md`](./docs/design/predictive-execution-2026-06.md) — history-aware scheduling (Phase A-B shipped)
+- [`docs/progress/implementation-log-2026-06.md`](./docs/progress/implementation-log-2026-06.md) — phase-by-phase narrative
+
+## Status
+
+**Pre-alpha.** The schema is settling; we bump `CACHE_VERSION` rather
+than maintain back-compat. **958+ tests across 70 files; CI green on
+every commit**; the project dogfoods itself (`bun run ci` → `vx run ci`).
+
+Production readiness for the **core task runner**: the semantics are
+solid. The rough edges are operational (Windows unsupported, no
+published versions on npm).
+
+Production readiness for the **2026-06 platform layer**:
+
+| Surface                                       | Maturity                         | Notes                                                                    |
+| --------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------ |
+| Core task runner + caching                    | **production-ready**             | dogfooded continuously; 836 tests pre-existing, all green                |
+| `vx mcp`                                      | **shippable**                    | live cache.db tools, stdio; agents work today                            |
+| `vx serve` (WS + SSE + NDJSON, JSON-RPC 2.0)  | **shippable**                    | accepts both legacy + new envelope; `curl` works                         |
+| `vx coordinator` + `vx run --worker`          | **shippable for self-hosted CI** | content-addressed assignment, disconnect recovery                        |
+| Plugin API                                    | **shippable**                    | crash-isolated, lifecycle hooks fire end-to-end                          |
+| Predictive scheduling                         | **shippable as opt-in**          | gated on `predictive: true` + observed data                              |
+| Dashboard SPA (`packages/cloud/ui`, embedded) | **scaffold**                     | served by `vx-cloud`; HTTP /v1/\* reads; pages need real-world iteration |
+| OTel export (`@vzn/vx-otel` telemetry plugin) | **shippable**                    | declare `otel()` in `vx.workspace.ts`; OTLP traces + metrics             |
+
+## 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/
+```
+
+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.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/launcher.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// npm launcher for the `vx` command — the entry the published `@vzn/vx`
+// package's `bin` points at. It execs the prebuilt standalone binary shipped
+// as a per-platform optionalDependency (@vzn/vx-<platform>), so end users get
+// vx WITHOUT installing Bun. This file is authored for the PUBLISHED layout:
+// at install time it sits at the package root, next to `src/`.
+//
+// Resolution order:
+//   1. the matching @vzn/vx-<platform> optionalDependency's binary (the
+//      normal path — esbuild/turborepo/biome model, no install-time download);
+//   2. a source fallback: `bun src/bin.ts` (works in a source checkout, or on a
+//      platform with no prebuilt binary if the user happens to have Bun).
+// Anything else is a clear, actionable error.
+
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const require = createRequire(import.meta.url)
+const here = dirname(fileURLToPath(import.meta.url))
+
+const PLATFORM_PACKAGES = {
+  'linux-x64': '@vzn/vx-linux-x64',
+  'linux-arm64': '@vzn/vx-linux-arm64',
+  'darwin-x64': '@vzn/vx-darwin-x64',
+  'darwin-arm64': '@vzn/vx-darwin-arm64',
+}
+
+const key = `${process.platform}-${process.arch}`
+const args = process.argv.slice(2)
+
+function platformBinary() {
+  const pkg = PLATFORM_PACKAGES[key]
+  if (pkg === undefined) return undefined
+  try {
+    // No `exports` restriction on the platform packages, so package.json
+    // resolves; the binary sits beside it. Works under npm hoisting + pnpm.
+    const manifest = require.resolve(`${pkg}/package.json`)
+    const bin = join(dirname(manifest), 'vx')
+    return existsSync(bin) ? bin : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function hasBun() {
+  const probe = spawnSync('bun', ['--version'], { stdio: 'ignore' })
+  return probe.status === 0
+}
+
+function run(cmd, cmdArgs) {
+  const res = spawnSync(cmd, cmdArgs, { stdio: 'inherit' })
+  if (res.error) {
+    process.stderr.write(`vx: failed to launch (${res.error.message})\n`)
+    process.exit(1)
+  }
+  // Mirror the child's exit; a signal death maps to the POSIX 128+signo code.
+  if (res.signal) process.exit(1)
+  process.exit(res.status ?? 0)
+}
+
+const bin = platformBinary()
+if (bin !== undefined) {
+  run(bin, args)
+}
+
+// No prebuilt binary for this platform — fall back to the shipped source if Bun
+// is available (a source checkout, or an unsupported platform + Bun installed).
+const sourceEntry = join(here, 'src', 'bin.ts')
+if (existsSync(sourceEntry) && hasBun()) {
+  run('bun', [sourceEntry, ...args])
+}
+
+const supported = Object.keys(PLATFORM_PACKAGES).join(', ')
+process.stderr.write(
+  `vx: no prebuilt binary for ${key}.\n` +
+    `  Supported platforms: ${supported}.\n` +
+    `  If your platform should be supported, reinstall so npm fetches the\n` +
+    `  matching @vzn/vx-${key} optionalDependency, or install Bun (>=1.3) to\n` +
+    `  run vx from source.\n`,
+)
+process.exit(1)

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.0",
-  "description": "Placeholder to reserve the name and enable npm trusted publishing. Real release to follow.",
-  "license": "MIT"
+  "version": "0.0.12",
+  "description": "An open, extensible monorepo task runner.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "types": "./src/index.ts",
+  "bin": {
+    "vx": "./launcher.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@vzn/vx-linux-x64": "0.0.12",
+    "@vzn/vx-linux-arm64": "0.0.12",
+    "@vzn/vx-darwin-x64": "0.0.12",
+    "@vzn/vx-darwin-arm64": "0.0.12"
+  },
+  "dependencies": {
+    "@anthropic-ai/sandbox-runtime": "^0.0.56"
+  },
+  "files": [
+    "src",
+    "launcher.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": "https://github.com/vznjs/vx",
+  "homepage": "https://github.com/vznjs/vx#readme",
+  "bugs": "https://github.com/vznjs/vx/issues",
+  "license": "MIT",
+  "keywords": [
+    "monorepo",
+    "task-runner",
+    "build",
+    "cache",
+    "bun",
+    "turborepo",
+    "nx"
+  ]
 }

package/src/bin.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env bun
+import { run } from './cli/index.js'
+import { UserError } 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.
+async function main(): Promise<void> {
+  try {
+    process.exit(await run(process.argv.slice(2)))
+  } catch (err) {
+    // UserError (workspace not found, cycle, config invalid, ...) —
+    // 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) {
+      process.stderr.write(`vx: ${err.message}\n`)
+    } else {
+      const message = err instanceof Error ? (err.stack ?? err.message) : String(err)
+      process.stderr.write(`vx: ${message}\n`)
+    }
+    process.exit(1)
+  }
+}
+
+void main()