@vzn/vx 0.0.643 → 0.0.645

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vx contributors
+Copyright (c) 2026 VZN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -12,7 +12,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@vzn/vx"><img src="https://img.shields.io/npm/v/@vzn/vx?color=7cb518" alt="npm"></a>
-  <a href="https://github.com/vznjs/vx/actions/workflows/ci.yml"><img src="https://github.com/vznjs/vx/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/vznjs/vx/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush"><img src="https://github.com/vznjs/vx/actions/workflows/ci.yml/badge.svg?branch=main&event=push" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
   <a href="https://vznjs.github.io/vx/"><img src="https://img.shields.io/badge/docs-vznjs.github.io%2Fvx-c6f84e" alt="Documentation"></a>
 </p>
@@ -35,13 +35,12 @@ Windows: run vx inside WSL2.
 
 ## Quick start
 
-In a git repo with a `package.json` workspace:
+In a git repo:
 
 ```sh
-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
+npx @vzn/vx init       # installs vx globally and in the repo; beside turbo.json or nx.json: migrates them; else a root vx.config.ts
+vx run build --all     # builds in dependency order and stores the results
+vx run build --all     # nothing changed: every task up-to-date
 ```
 
 Bun workspaces: `bun add -d @vzn/vx` and `bunx @vzn/vx` (npm refuses to run in
@@ -166,17 +165,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                                            | **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 added over the ideal run, 1,601 projects, 9,603 tasks | vx         | Turborepo | Nx         | Vite Task |
+| ---------------------------------------------------------- | ---------- | --------- | ---------- | --------- |
+| Nothing changed                                            | **757 ms** | 761 ms    | 22.63 s    | 12.26 s   |
+| Nothing changed, outputs restored                          | **1.27 s** | 1.76 s    | 22.16 s    | 11.66 s   |
+| Cold build                                                 | **6.13 s** | 8.87 s    | 3 min 20 s | 7.94 s    |
+| Cold build: CPU the runner burns                           | 30.06 s    | 1 min 8 s | 5 min 45 s | 23.91 s   |
 
 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-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.
+Run 2026-10-20 on linux x64, 4 cores: vx at commit a88652b0b, Turborepo 2.11.9, Nx 23.3.0, Vite Task (vite-plus) 1.3.0.
 
 Same graph, commands and concurrency: [how it is measured](https://vznjs.github.io/vx/benchmarks/).
 
@@ -188,17 +187,10 @@ Same graph, commands and concurrency: [how it is measured](https://vznjs.github.
 vx. The schema may still change; 1.0's promise:
 [versioning-1.0.md](packages/vx/docs/design/versioning-1.0.md).
 
-## Contributing
+## Issues
 
-```sh
-git clone https://github.com/vznjs/vx && cd vx
-bun install
-bun packages/vx/src/bin.ts run ci --all     # lint, test, docs build: every package
-```
-
-Needs Bun ≥ 1.4. Every dev task is a vx task; no `package.json`
-scripts. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and
-[STATUS.md](packages/vx/docs/STATUS.md).
+vx is maintained by VZN and takes issues, not pull requests: report a
+bug or ask for a feature in [issues](https://github.com/vznjs/vx/issues).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.643",
+  "version": "0.0.645",
   "description": "Task orchestration you own: correct, sandboxed, extensible, with a content-addressed build cache.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.643",
-    "@vzn/vx-linux-arm64": "0.0.643",
-    "@vzn/vx-darwin-x64": "0.0.643",
-    "@vzn/vx-darwin-arm64": "0.0.643"
+    "@vzn/vx-linux-x64": "0.0.645",
+    "@vzn/vx-linux-arm64": "0.0.645",
+    "@vzn/vx-darwin-x64": "0.0.645",
+    "@vzn/vx-darwin-arm64": "0.0.645"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/schemas/info.json

@@ -26,7 +26,6 @@
     "cacheEntries",
     "cacheBytes",
     "settings",
-    "cacheRetention",
     "orphans",
     "runs24h",
     "hits24h",
@@ -105,16 +104,6 @@
         }
       }
     },
-    "cacheRetention": {
-      "type": ["object", "null"],
-      "description": "cache.retention from its variables, else the workspace, 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,

package/schemas/init.json

@@ -52,6 +52,11 @@
     "next": {
       "type": ["string", "null"],
       "description": "the command to type after the real run; null where the plan names none"
+    },
+    "installs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "core's plan only: the install commands the real run runs (global, then the root devDependency)"
     }
   }
 }

package/skills/vx/SKILL.md

@@ -110,4 +110,4 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 has installed, copy it from there instead:
 `cp node_modules/@vzn/vx/skills/vx/SKILL.md .claude/skills/vx/`.
 `vx upgrade` inside a workspace moves the project's `@vzn/vx` and the
-global vx that ran it to the same version.
+global vx that ran it to the same version, then runs `vx lock`.

package/src/cache/archive.ts

@@ -70,6 +70,7 @@ import {
   stat,
   symlink,
   unlink,
+  utimes,
   writeFile,
 } from 'node:fs/promises'
 import path from 'node:path'
@@ -471,6 +472,84 @@ function streamOf(gen: AsyncGenerator<Uint8Array>): ReadableStream<Uint8Array> {
   })
 }
 
+/**
+ * The tree form (`cache.store.decompress`, v47): an artifact's members
+ * as plain files under one directory, `outputs/<rel>` and
+ * `workspace-outputs/<rel>` as named in the tar, beside its sidecar.
+ * stdout lives in the index. A restore copies (or clones) each file out,
+ * so a hit decodes nothing; an upload packs the tree back into the
+ * artifact a remote expects.
+ *
+ * Write `plan`'s outputs into the empty `dir` as the tree form, each copied
+ * by the kernel (`copy_file_range`, or a clone where the filesystem has one)
+ * and given its sidecar mtime, and return what a scan of the plan's tar
+ * would: the save indexes from it without packing a tar.
+ */
+export async function writeTree(plan: ArtifactPlan, dir: string): Promise<ArtifactScan> {
+  const fold = new ScanFold()
+  const meta = plan.inputs.find((i) => i.name === META_ENTRY)!.body as Uint8Array
+  const metaText = utf8.decode(meta)
+  fold.sidecar(metaText)
+  const times = (JSON.parse(metaText) as MetaFile).files
+  for (const i of plan.inputs) {
+    if (i.name === META_ENTRY) continue
+    assertSafeName(i.name)
+    if (i.name === STDOUT_ENTRY) fold.stdout = utf8.decode(i.body as Uint8Array)
+    fold.entry(i.name, i.size, times[i.name]?.[1] ?? 0)
+  }
+  // A stdout-only entry writes no file to make the directory.
+  await mkdir(dir, { recursive: true })
+  await Promise.all(
+    plan.inputs.map(async (i) => {
+      if (!(i.body instanceof Blob)) return
+      const to = path.join(dir, i.name)
+      await Bun.write(to, i.body)
+      const at = new Date(times[i.name]![1])
+      await utimes(to, at, at)
+    }),
+  )
+  await writeFile(path.join(dir, META_ENTRY), meta)
+  return fold.result()
+}
+
+/**
+ * Write a scanned artifact's sidecar into `dir`, whose outputs an extract
+ * just wrote: an ingested remote hit kept as a tree.
+ */
+export async function sealTree(dir: string, scan: ArtifactScan): Promise<void> {
+  // An artifact with no outputs extracts nothing, so nothing made `dir`.
+  await mkdir(dir, { recursive: true })
+  const meta: MetaFile = { version: 1, files: {} }
+  if (scan.key !== undefined) meta.key = scan.key
+  for (const e of scan.entries) {
+    if (e.name !== STDOUT_ENTRY) meta.files[e.name] = [e.mode, e.mtimeMs]
+  }
+  if (scan.dirs.length > 0) meta.dirs = scan.dirs
+  if (scan.links.length > 0) meta.links = Object.fromEntries(scan.links)
+  if (scan.exec !== undefined) meta.exec = scan.exec
+  await writeFile(path.join(dir, META_ENTRY), JSON.stringify(meta))
+}
+
+/** The plan that packs the tree in `dir` back into the artifact it holds. */
+export function planOfTree(dir: string, stdout: string): ArtifactPlan {
+  const metaBytes = readFileSync(path.join(dir, META_ENTRY))
+  const meta = JSON.parse(utf8.decode(metaBytes)) as MetaFile
+  const out = new TextEncoder().encode(stdout)
+  const inputs: TarInput[] = [{ name: STDOUT_ENTRY, size: out.byteLength, body: out }]
+  for (const [name, [mode, mtimeMs]] of Object.entries(meta.files)) {
+    const file = Bun.file(path.join(dir, name))
+    inputs.push({
+      name,
+      size: statSync(path.join(dir, name)).size,
+      mode,
+      mtime: Math.min(USTAR_MTIME_MAX, Math.max(0, Math.floor(mtimeMs / 1000))),
+      body: file,
+    })
+  }
+  inputs.push({ name: META_ENTRY, size: metaBytes.byteLength, body: new Uint8Array(metaBytes) })
+  return { inputs, size: tarSize([...inputs, sumInput('0'.repeat(SUM_SIZE))]) }
+}
+
 /** What a scan of an artifact reads out of it. */
 interface ArtifactScan {
   entries: ArchiveEntry[]
@@ -664,6 +743,8 @@ export async function extractArtifactStream(
   accept?: (name: string) => boolean,
   /** The workspace root whose `.vx/tmp/` stages the entries; absent, each stages beside its target. */
   stageRoot?: string,
+  /** Handed what `scanArtifact` would read of the same bytes, once their sum has checked. */
+  onScan?: (scan: ArtifactScan) => void,
 ): Promise<Set<string>> {
   // No `mkdir -p` of the destination here: `stage` creates each entry's
   // directory chain, the destination included, and the cache restores
@@ -676,6 +757,7 @@ export async function extractArtifactStream(
   let meta: MetaFile['files'] = {}
   let dirs: string[] = []
   let links: Array<[string, string]> = []
+  const fold = onScan === undefined ? undefined : new ScanFold()
   try {
     const check = new SumCheck()
     for await (const e of tarEntries(tar)) {
@@ -683,7 +765,9 @@ export async function extractArtifactStream(
       const body = await check.body(e.name, e.body)
       if (body === null) continue
       if (e.name === META_ENTRY) {
-        const parsed = JSON.parse(await textOf(body)) as MetaFile
+        const text = await textOf(body)
+        fold?.sidecar(text)
+        const parsed = JSON.parse(text) as MetaFile
         meta = parsed.files ?? {}
         dirs = dirsOf(parsed)
         links = linksOf(parsed)
@@ -697,9 +781,11 @@ export async function extractArtifactStream(
           `archive entry is not one of the task's declared outputs: ${e.name}`,
         )
       }
+      fold?.entry(e.name, e.size, e.mtimeMs)
       const dest = x.destFor(e.name)
       if (dest === null || dest.rel.length === 0) {
-        await drain(body)
+        if (fold !== undefined && e.name === STDOUT_ENTRY) fold.stdout = await textOf(body)
+        else await drain(body)
         continue
       }
       const target = path.join(dest.base, dest.rel)
@@ -709,6 +795,7 @@ export async function extractArtifactStream(
       await x.stage(e.name, dest.base, target, e.size <= SMALL_ENTRY ? await bytesOf(body) : body)
     }
     check.done()
+    if (fold !== undefined) onScan!(fold.result())
     for (const name of dirs) {
       if (accept !== undefined && !accept(name)) {
         throw new ArchiveSecurityError(