@vzn/vx 0.0.635 → 0.0.637

package/README.md

@@ -38,10 +38,23 @@ Windows: run vx inside WSL2.
 In a git repo with a `package.json` workspace:
 
 ```sh
-npx vx init               # a vx.config.ts per package, from its scripts
+npm install -D @vzn/vx         # the scope matters: npm's `vx` is an unrelated package
+npx @vzn/vx init               # beside turbo.json or nx.json: migrates them; else a vx.config.ts per package
+npx @vzn/vx run build --all    # builds in dependency order and stores the results
+npx @vzn/vx run build --all    # nothing changed: every task up-to-date
 ```
 
-Give a task a cache block, what it reads and writes:
+Bun workspaces: `bun add -d @vzn/vx` and `bunx @vzn/vx` (npm refuses to run in
+a repo whose `devEngines` names Bun).
+
+Without Turbo or Nx, tasks run uncached until you declare what they read (below).
+
+`init` prints what it wrote and anything left to decide (a `TODO`). A miss you did not expect?
+`npx @vzn/vx why <task>` names the input that moved.
+
+### Without Turbo or Nx
+
+`init` writes one task per package script, uncached. Cache one by saying what it reads and writes:
 
 ```ts
 // packages/app/vx.config.ts
@@ -62,15 +75,31 @@ export default defineProject({
 ```
 
 ```sh
-npx vx run build --all    # builds, in dependency order; stores the results
-npx vx run build --all    # nothing changed: up-to-date, in milliseconds
+npx @vzn/vx run build --all    # builds, in dependency order; stores the results
+npx @vzn/vx run build --all    # nothing changed: up-to-date, in milliseconds
 rm -rf packages/*/dist
-npx vx run build --all    # restored from the cache, not rebuilt
+npx @vzn/vx run build --all    # restored from the cache, not rebuilt
 ```
 
 <img src="https://vznjs.github.io/vx/demo.svg" width="760" alt="vx run ci --all on examples/basic: cold, three tasks run; again, three up-to-date.">
 
-Starter: [`examples/basic`](examples/basic), run by CI on every commit.
+### When to run `vx lock`
+
+`init` also writes `.vx/projects.lock.json`, every project's config as it evaluated.
+Commit it. Every run reads its configs from the lock, so run
+`npx @vzn/vx lock` and commit the lock again after you:
+
+- edit any `vx.config.ts` or `.vx/workspace.ts`,
+- update dependencies or plugins,
+- change a file a config imports.
+
+Otherwise runs keep the old configs. On CI, `vx lock --check` fails a
+stale lock before any task runs.
+
+Starters: [`examples/basic`](examples/basic), and
+[`examples/ci`](examples/ci) with a GitHub Actions workflow; CI runs both
+on every commit. The [CI guide](https://vznjs.github.io/vx/guides/ci/)
+explains the workflow.
 More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 [Configure](https://vznjs.github.io/vx/guides/configure/) ·
 [CLI](packages/vx/docs/cli.md) · [every config field](packages/vx/docs/schema.md) ·
@@ -84,13 +113,13 @@ More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
 - **Sandboxed tasks:** opt in per task; a workspace file the task did
   not declare is out of its reach, so it cannot poison the cache.
 - **Clean exits:** Ctrl-C reaps each task's process group.
-- **Plugins at every stage** (14 hooks, `commands` included): remote cache, remote execution, telemetry,
+- **Plugins at every stage** (15 hooks, `commands` included): remote cache, remote execution, telemetry,
   CLI verbs. Core ships none and needs none.
 - **Free:** MIT. No paywall, no cloud, no account.
 
 ## Plugins
 
-What vx can do, not what it is limited to. Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
+What vx can do, not what it is limited to. Declared in `.vx/workspace.ts`; without any, vx runs and caches locally.
 
 | Package                                                    | What it adds                                                                  |
 | ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
@@ -99,7 +128,6 @@ What vx can do, not what it is limited to. Declared in `vx.workspace.ts`; withou
 | [`@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`: 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/) ·
@@ -107,10 +135,10 @@ Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
 
 ## Coming from Turbo or Nx
 
-Beside `turbo.json` or `nx.json`, `npx vx init` runs `@vzn/vx-migrate`:
+Beside `turbo.json` or `nx.json`, `npx @vzn/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,
+a `.vx/workspace.ts` that maps the old config instead, and its lock: a temporary start,
 not a way to run the repo. The benchmark below uses native vx config.
 [Migration guide](https://vznjs.github.io/vx/guides/migrate/).
 
@@ -138,17 +166,17 @@ Every gap, and when another tool is the better pick:
 
 <!-- bench:start — generated by packages/vx-bench/update-site.ts from results.json; do not hand-edit -->
 
-| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx          | Turborepo                 | Nx                         | Vite Task                |
-| ---------------------------------------------------------- | ----------- | ------------------------- | -------------------------- | ------------------------ |
-| Nothing changed                                            | **1.07 s**  | 898 ms (vx 19% slower)    | 25.45 s (vx 24× faster)    | 11.75 s (vx 11× faster)  |
-| Nothing changed, outputs restored                          | **1.27 s**  | 844 ms (vx 51% slower)    | 23.82 s (vx 19× faster)    | 11.83 s (vx 9.3× faster) |
-| Cold build                                                 | **7.07 s**  | 9.15 s (vx 29% faster)    | 3 min 48 s (vx 32× faster) | 8.16 s (vx 15% faster)   |
-| Cold build: CPU the runner burns                           | **32.28 s** | 1 min 3 s (vx 94% faster) | 6 min 6 s (vx 11× faster)  | 24.82 s (vx 30% slower)  |
+| Time added over the ideal run, 1,601 projects, 9,603 tasks | vx          | Turborepo | Nx         | Vite Task |
+| ---------------------------------------------------------- | ----------- | --------- | ---------- | --------- |
+| Nothing changed                                            | **856 ms**  | 855 ms    | 23.22 s    | 11.24 s   |
+| Nothing changed, outputs restored                          | **1.45 s**  | 1.50 s    | 21.64 s    | 11.21 s   |
+| Cold build                                                 | **7.73 s**  | 10.32 s   | 3 min 23 s | 9.44 s    |
+| Cold build: CPU the runner burns                           | **36.42 s** | 1 min 3 s | 5 min 35 s | 25.64 s   |
 
-Time each tool adds over the ideal run; vx N% or N× faster means that tool adds N% more or N times as much as vx.
+Time each tool adds over the ideal run; lower is better.
 
 Benchmark workload: a synthetic monorepo of 1,601 projects and 9,603 tasks in 30 dependency levels, five core libraries a quarter of the projects use; build 300 ms, test and typecheck 150 ms, lint 75 ms, publish 30 ms; real repos with uneven task times will differ.
-Run 2026-10-09 on linux x64, 4 cores: vx at commit 3d48a981d, Turborepo 2.11.7, Nx 23.3.0, Vite Task (vite-plus) 1.1.0.
+Run 2026-10-12 on linux x64, 4 cores: vx at commit 126d60a93, Turborepo 2.11.7, Nx 23.3.0, Vite Task (vite-plus) 1.1.0.
 
 Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).