@vzn/vx 0.0.364 → 0.0.365

package/README.md

@@ -34,12 +34,9 @@ Same graph, commands and concurrency: [how it is measured](https://vznjs.github.
 
 ## Why it is faster
 
-- **Nothing boots per task.** No daemon, no Node process per task: vx
-  spawns your command directly.
-- **Hashing without reading.** On a clean tree, cache keys come from
-  git's index; no file is read.
-- **One pass over the repo.** One git walk per run; each stat and
-  lookup happens once.
+- **Nothing boots per task:** no daemon, no Node process; vx spawns your command.
+- **No file reads to hash:** on a clean tree, keys come from git's index.
+- **One pass:** one git walk per run; each stat and lookup happens once.
 
 ## Install
 
@@ -47,9 +44,8 @@ Same graph, commands and concurrency: [how it is measured](https://vznjs.github.
 npm install -D @vzn/vx     # or: pnpm add -D -w · yarn add -D (-W on Yarn 1) · bun add -d
 ```
 
-The package ships a prebuilt binary for Linux and macOS, x64 and arm64;
-no Bun needed. The binary alone, from a
-[release](https://github.com/vznjs/vx/releases), needs no Node either.
+A prebuilt binary for Linux and macOS (x64, arm64); no Bun needed. The
+[release](https://github.com/vznjs/vx/releases) binary needs no Node either.
 Windows: use WSL.
 
 ## Quick start
@@ -60,7 +56,7 @@ In a git repo with a `package.json` workspace:
 npx vx init               # a vx.config.ts per package, from its scripts
 ```
 
-Give a task a cache block (what it reads, what it writes):
+Give a task a cache block, what it reads and writes:
 
 ```ts
 // packages/app/vx.config.ts
@@ -89,8 +85,8 @@ npx 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.">
 
-Or copy [`examples/basic`](examples/basic), a two-package starter CI
-runs on every commit. More: [Quickstart](https://vznjs.github.io/vx/quickstart/) ·
+Starter: [`examples/basic`](examples/basic), run by CI on every commit.
+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) ·
 [playground](https://vznjs.github.io/vx/playground/) (the planner, in your browser).
@@ -98,24 +94,21 @@ runs on every commit. 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; `vx init` in such a repo writes a
-`vx.workspace.ts` that reads them in place. Either is a temporary start:
-move to native vx config, which is what the numbers above measure.
-[Migration guide](https://vznjs.github.io/vx/guides/migrate/).
+`turbo.json` or the Nx graph. `vx init` there writes a `vx.workspace.ts`
+that reads them in place: a temporary start. The numbers above are native
+vx config. [Migration guide](https://vznjs.github.io/vx/guides/migrate/).
 
 ## More than speed
 
-- **A cache you can trust.** Configs are TypeScript, evaluated before
-  hashing, so imports and computed values are part of the key. Declared
-  outputs are wiped before every run and every restore: no stale file
-  survives.
-- **Sandboxed tasks.** Opt in per task: a read the task did not
-  declare fails the build instead of poisoning the cache.
-- **Clean exits.** Ctrl-C reaps every child. No orphaned dev servers.
-- **Plugins at every stage.** Remote cache, remote execution,
-  telemetry and new CLI verbs are plugins on documented seams, the way
-  Vite does it. Core ships none and needs none.
-- **Free.** MIT. No paywall, no cloud, no account.
+- **A cache you can trust:** TypeScript configs are evaluated before
+  hashing, so imports and computed values are in the key. Outputs are
+  wiped before every run and restore: no stale file survives.
+- **Sandboxed tasks:** opt in per task; an undeclared read fails the
+  build instead of poisoning the cache.
+- **Clean exits:** Ctrl-C reaps every child.
+- **Plugins at every stage:** remote cache, remote execution, telemetry,
+  CLI verbs. Core ships none and needs none.
+- **Free:** MIT. No paywall, no cloud, no account.
 
 ## How it compares
 
@@ -136,8 +129,7 @@ Every gap, and when another tool is the better pick:
 
 ## Plugins
 
-Declared in `vx.workspace.ts`. Without one, vx runs and caches on this
-machine.
+Declared in `vx.workspace.ts`; without any, vx runs and caches locally.
 
 | Package                                                    | What it adds                                                                  |
 | ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
@@ -156,9 +148,8 @@ Write your own: [plugin guide](https://vznjs.github.io/vx/guides/plugins/) ·
 
 ## Status
 
-**Pre-alpha**, dogfooded: this repo lints, tests and builds itself
-with vx. Over 4,000 core tests plus the package suites, CI green on
-every commit. The schema may still change; what 1.0 will promise is in
+**Pre-alpha**, dogfooded: this repo lints, tests and builds itself with
+vx. The schema may still change; 1.0's promise:
 [versioning-1.0.md](packages/vx/docs/design/versioning-1.0.md).
 
 | Surface                                            | Maturity             |
@@ -176,9 +167,9 @@ 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; there are no
-`package.json` scripts. Start with [CONTRIBUTING.md](CONTRIBUTING.md)
-and [STATUS.md](packages/vx/docs/STATUS.md), the living handoff.
+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).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.364",
+  "version": "0.0.365",
   "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.364",
-    "@vzn/vx-linux-arm64": "0.0.364",
-    "@vzn/vx-darwin-x64": "0.0.364",
-    "@vzn/vx-darwin-arm64": "0.0.364"
+    "@vzn/vx-linux-x64": "0.0.365",
+    "@vzn/vx-linux-arm64": "0.0.365",
+    "@vzn/vx-darwin-x64": "0.0.365",
+    "@vzn/vx-darwin-arm64": "0.0.365"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cache/cache.ts

@@ -439,6 +439,7 @@ export class Cache implements CacheLayer {
   private readonly insertEntry: ReturnType<Database['prepare']>
   private readonly deleteEntryRow: ReturnType<Database['prepare']>
   private readonly selectEntry: ReturnType<Database['prepare']>
+  private readonly entryExists: ReturnType<Database['prepare']>
   private readonly bumpAccessed: ReturnType<Database['prepare']>
   private readonly touched = new Set<string>()
   private readonly insertEntryInput: ReturnType<Database['prepare']>
@@ -711,6 +712,12 @@ export class Cache implements CacheLayer {
         peak_rss_bytes = excluded.peak_rss_bytes
     `)
     this.selectEntry = this.db.prepare('SELECT * FROM entries WHERE hash = ?')
+    // `has` asks only whether the row is there: the whole row, stdout
+    // included, was built and dropped once per task of a `--dry` plan. A
+    // column off the index, so the table row is still read and a corrupt
+    // table refuses here as it does on `get` (`SELECT 1` answers from the
+    // index alone); stdout's overflow pages are not.
+    this.entryExists = this.db.prepare('SELECT exit_code FROM entries WHERE hash = ?')
     this.bumpAccessed = this.db.prepare('UPDATE entries SET accessed_at = ? WHERE hash = ?')
     // INSERT OR IGNORE: re-saving the same hash (idempotent ingest /
     // overlapping concurrent saves) leaves the existing rows untouched —
@@ -981,8 +988,7 @@ export class Cache implements CacheLayer {
 
   private async hasEntry(hash: string): Promise<'local' | 'remote' | null> {
     if (!this.read) return null
-    const row = this.selectEntry.get(hash) as EntryRow | undefined
-    if (!row) return null
+    if (this.entryExists.get(hash) === null) return null
     return existsSync(this.tarPath(hash)) ? 'local' : null
   }
 

package/src/orchestrator/run-lock.ts

@@ -12,8 +12,8 @@
 // holds it.
 //
 // Keyed by the workspace, not the cache directory (`--cache-dir` must not
-// make two runs strangers), and kept under the temp directory so a
-// read-only checkout can take it.
+// make two runs strangers), and kept in this user's own directory under
+// the temp directory (L-47), so a read-only checkout can take it.
 //
 // The lock is a directory, HELD exactly while it is not empty. It holds
 // one entry, `h-<pid>-<start>-<n>`, naming the holder and unique to this
@@ -60,7 +60,7 @@
 // serialize what it chose to overlap. The lock is taken by the first of
 // them and left by the last to release.
 
-import { readFileSync, realpathSync } from 'node:fs'
+import { chmodSync, lstatSync, mkdirSync, readFileSync, realpathSync } from 'node:fs'
 import { rmdirSync, unlinkSync } from 'node:fs'
 import { mkdir, readdir, readFile, rename, rm, rmdir, unlink, writeFile } from 'node:fs/promises'
 import os from 'node:os'
@@ -110,7 +110,7 @@ const SAY_AFTER_MS = 1_000
 const LEGACY_PID = 'pid'
 
 export interface RunLockOptions {
-  /** Where the lock directories live; `os.tmpdir()` unless a test says otherwise. */
+  /** Where the lock directories live; this user's own directory in `os.tmpdir()` unless a test says otherwise. */
   dir?: string
   /** A status line for the waiting notice and the unlocked warning. */
   log: (line: string) => void
@@ -119,12 +119,12 @@ export interface RunLockOptions {
 }
 
 /**
- * The lock directory for a workspace root: stable across runs and users,
+ * The lock directory for a workspace root: stable across this user's runs,
  * private to this machine. Keyed by the REAL path: a CLI's cwd comes back
  * canonical while a caller may hold a symlinked spelling (macOS's /var ->
  * /private/var), and two spellings of one workspace must meet.
  */
-export function runLockPath(workspaceRoot: string, dir = os.tmpdir()): string {
+export function runLockPath(workspaceRoot: string, dir = userLockRoot(os.tmpdir())): string {
   const resolved = path.resolve(workspaceRoot)
   let real = resolved
   try {
@@ -135,6 +135,46 @@ export function runLockPath(workspaceRoot: string, dir = os.tmpdir()): string {
   return path.join(dir, `vx-run-${xxh3hex(real)}`)
 }
 
+/**
+ * This user's own directory for locks under `dir`. A lock named in the
+ * shared temp dir itself was anyone's to plant: another local user put a
+ * held lock naming a live pid there and every run on the workspace waited
+ * on it (L-47). Two users on one checkout no longer exclude each other;
+ * the files of one are rarely the other's to write.
+ */
+function userLockRoot(dir: string): string {
+  const uid = process.getuid?.()
+  return uid === undefined ? dir : path.join(dir, `vx-runs-${uid}`)
+}
+
+/** The roots this process has made or checked. */
+const ownedRoots = new Set<string>()
+
+/**
+ * Make the lock's root, or refuse it when it is not this user's own
+ * directory (a link, another owner): a lock read there is anyone's.
+ */
+function ownLockRoot(lockDir: string): void {
+  const root = path.dirname(lockDir)
+  const uid = process.getuid?.()
+  if (uid === undefined || ownedRoots.has(root)) return
+  // Not recursive: a temp directory that is not there is the warning
+  // that names TMPDIR, never one vx makes.
+  try {
+    mkdirSync(root, { mode: 0o700 })
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
+  }
+  const st = lstatSync(root)
+  if (!st.isDirectory() || st.uid !== uid) {
+    throw new Error(
+      `${root} is not this user's own directory (a link or another owner's); remove it`,
+    )
+  }
+  if ((st.mode & 0o077) !== 0) chmodSync(root, 0o700)
+  ownedRoots.add(root)
+}
+
 interface Holder {
   pid: number
   /** The holder's start time as `startTime` read it; null where the lock names none. */
@@ -309,6 +349,8 @@ export async function acquireRunLock(
     }
     let h: Holder | 'free' | null
     try {
+      // A caller's own `dir` (a test's) is theirs to vouch for.
+      if (opts.dir === undefined) ownLockRoot(lockDir)
       const entry = await place(lockDir)
       if (entry !== null) {
         heldHere.set(lockDir, 1)

package/src/workspace/config-eval.ts

@@ -42,6 +42,24 @@ import { nonJsonMessage, nonJsonPaths, type NonJsonValue } from './json-data.js'
 /** Why a config's `process.exit` throws, on both load paths (D-65). */
 export const CONFIG_EXIT = 'a config exports its object; it cannot end the run'
 
+/**
+ * The built-ins a config must not change: vx reads every other config and
+ * makes every cache key through them (D-74, D-75). The loader watches them
+ * in this process; the worker, asked to blame, in its own.
+ */
+export const WATCHED_BUILTIN_NAMES = [
+  'Object.prototype',
+  'Array.prototype',
+  'Bun',
+  'Bun.hash',
+  'JSON',
+  'Math',
+  'String.prototype',
+  'Map.prototype',
+  'Set.prototype',
+  'Promise.prototype',
+] as const
+
 const WORKER_SRC = `
 const nonJsonPaths = ${nonJsonPaths.toString()}
 // The parent's stdout is a verb's JSON or vx mcp's JSON-RPC stream, and a
@@ -83,6 +101,29 @@ self.onmessage = async (e) => {
   const live = globalThis.process.env
   for (const k of Object.keys(live)) if (!(k in env)) delete live[k]
   Object.assign(live, env)
+  // A blame request reports the built-ins and env vars this one evaluation
+  // changed, for a round whose loads overlapped and saw a change (D-119).
+  const watched = e.data.blame
+    ? ${JSON.stringify(WATCHED_BUILTIN_NAMES)}.map((n) => [n, n.split('.').reduce((o, k) => o[k], globalThis)])
+    : null
+  const own = (o) => new Map(Reflect.ownKeys(o).map((k) => [k, Object.getOwnPropertyDescriptor(o, k)]))
+  const before = watched?.map(([, o]) => own(o))
+  const envBefore = watched ? { ...live } : null
+  const same = (a, b) =>
+    a !== undefined && b !== undefined && a.value === b.value && a.get === b.get && a.set === b.set &&
+    a.writable === b.writable && a.enumerable === b.enumerable && a.configurable === b.configurable
+  const changed = () => {
+    if (watched === null) return undefined
+    const out = []
+    watched.forEach(([n, o], i) => {
+      const now = own(o)
+      for (const k of new Set([...before[i].keys(), ...now.keys()]))
+        if (!same(before[i].get(k), now.get(k))) out.push(n + '.' + String(k))
+    })
+    for (const k of new Set([...Object.keys(envBefore), ...Object.keys(live)]))
+      if (envBefore[k] !== live[k]) out.push('process.env.' + k)
+    return out
+  }
   try {
     const ns = await import(path)
     // Awaited as the in-process load's async return flattens it: a Promise
@@ -96,6 +137,7 @@ self.onmessage = async (e) => {
       ok: true,
       nonJson,
       json: isObject && nonJson.length === 0 ? JSON.stringify(mod) : null,
+      changed: changed(),
     })
   } catch (err) {
     postMessage({
@@ -104,6 +146,7 @@ self.onmessage = async (e) => {
       name: err?.name ?? 'Error',
       message: err?.message ?? String(err),
       stack: err?.stack ?? null,
+      changed: changed(),
       position:
         err?.position && typeof err.position === 'object'
           ? { file: err.position.file, line: err.position.line, column: err.position.column }
@@ -295,3 +338,31 @@ export async function evaluateConfigFresh(configPath: string): Promise<unknown>
     retireIfIdle()
   }
 }
+
+/**
+ * What evaluating `configPath` alone changes among the watched built-ins
+ * and env vars, in a worker of its own that is then discarded: a round
+ * whose overlapping loads saw a change asks each config in turn, so the
+ * refusal names the one that made it (D-119). Empty when the evaluation
+ * changes nothing, fails before reporting, or outlives the budget.
+ */
+export async function builtinsChangedBy(configPath: string): Promise<string[]> {
+  const w = new Worker(WORKER_URL)
+  try {
+    return await new Promise<string[]>((resolve) => {
+      const timer = setTimeout(() => resolve([]), evalBudgetMs())
+      timer.unref?.()
+      w.onmessage = (event: MessageEvent): void => {
+        clearTimeout(timer)
+        resolve((event.data as { changed?: string[] }).changed ?? [])
+      }
+      w.onerror = (): void => {
+        clearTimeout(timer)
+        resolve([])
+      }
+      w.postMessage({ id: 0, path: path.resolve(configPath), env: { ...process.env }, blame: true })
+    })
+  } finally {
+    w.terminate()
+  }
+}

package/src/workspace/project-loader.ts

@@ -3,7 +3,14 @@ import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
 import { UserError, xxh3hex } from '../util/index.js'
 import { validateProjectConfig, validateWorkspace } from './config-schema.js'
-import { beginEvalRound, CONFIG_EXIT, evalBudgetMs, evaluateConfigFresh } from './config-eval.js'
+import {
+  beginEvalRound,
+  builtinsChangedBy,
+  CONFIG_EXIT,
+  evalBudgetMs,
+  evaluateConfigFresh,
+  WATCHED_BUILTIN_NAMES,
+} from './config-eval.js'
 import { hasEsmExport, unprovidedBareImports } from './config-imports.js'
 import {
   configEvalKey,
@@ -434,6 +441,9 @@ export async function loadProjectConfigs(
   // `node:stream`), ~7 ms of a two-config warm run where every load hit.
   let builtins: BuiltinSnapshot = []
   let env: Readonly<Record<string, string | undefined>> = {}
+  // More than one evaluation in flight: a change seen after one load may
+  // be another's.
+  let overlapping = false
   const loadOne = async (entry: (typeof prepared)[number]): Promise<Loaded> => {
     const { configPath, cacheKey } = entry
     // A fast key that missed: the closure is stale or the file changed.
@@ -475,7 +485,12 @@ export async function loadProjectConfigs(
     // Before anything reads through them: a replaced `Array.prototype.includes`
     // turned the JSON-data walk's own check into "a cyclic reference".
     const changed = repeat ? [] : [...restoreBuiltins(builtins), ...restoreEnv(env)]
-    if (changed.length > 0) throw builtinsChanged(changed, configPath)
+    // Loads overlap, so another config's change can surface after this
+    // one: named here, the refusal blamed the wrong file (D-119). The round
+    // finds the one that made it.
+    if (changed.length > 0) {
+      throw overlapping ? new ChangedInRound(changed) : builtinsChanged(changed, configPath)
+    }
     assertDefaultObject(mod, 'Project', configPath)
     // Validation runs HERE, on whichever object we ended up with, so a
     // malformed config reports the identical UserError whether it was
@@ -522,6 +537,7 @@ export async function loadProjectConfigs(
       builtins = builtinSnapshot()
       env = { ...process.env }
     }
+    overlapping = misses.length > 1
     let next = 0
     const lane = async (): Promise<void> => {
       while (next < misses.length) {
@@ -539,6 +555,14 @@ export async function loadProjectConfigs(
       }
     }
     const changed = misses.length > 0 ? [...restoreBuiltins(builtins), ...restoreEnv(env)] : []
+    if (first?.failed instanceof ChangedInRound) {
+      for (const i of misses) {
+        const configPath = prepared[i]!.configPath
+        const own = await builtinsChangedBy(configPath)
+        if (own.length > 0) throw builtinsChanged(own, configPath)
+      }
+      throw builtinsChanged(first.failed.changed)
+    }
     if (first !== undefined) throw first.failed
     if (changed.length > 0) throw builtinsChanged(changed)
     return results.map((r) => (r as Loaded).config)
@@ -565,20 +589,18 @@ export async function loadProjectConfigs(
  * load runs in this process, so the round compares them before and after,
  * puts back what changed (a failed load too) and refuses.
  */
-const WATCHED_BUILTINS: ReadonlyArray<readonly [string, object]> = [
-  ['Object.prototype', Object.prototype],
-  ['Array.prototype', Array.prototype],
-  // What vx itself runs on: `Bun.hash.xxHash3 = () => 7n` gave every task
-  // the key 00000000, and a changed command replayed the old output (D-75).
-  ['Bun', Bun],
-  ['Bun.hash', Bun.hash],
-  ['JSON', JSON],
-  ['Math', Math],
-  ['String.prototype', String.prototype],
-  ['Map.prototype', Map.prototype],
-  ['Set.prototype', Set.prototype],
-  ['Promise.prototype', Promise.prototype],
-]
+// `Bun` and `Bun.hash` are what vx itself runs on: `Bun.hash.xxHash3 = ()
+// => 7n` gave every task the key 00000000, and a changed command replayed
+// the old output (D-75).
+const WATCHED_BUILTINS: ReadonlyArray<readonly [string, object]> = WATCHED_BUILTIN_NAMES.map(
+  (name) =>
+    [
+      name,
+      name
+        .split('.')
+        .reduce<unknown>((o, k) => (o as Record<string, unknown>)[k], globalThis) as object,
+    ] as const,
+)
 
 interface OwnProperties {
   keys: PropertyKey[]
@@ -614,7 +636,12 @@ function unchanged(proto: object, keys: readonly PropertyKey[], was: OwnProperti
   return true
 }
 
-/** Loads run together, so the config named is the one whose load saw the change. */
+/** A change seen by one of several overlapping loads; the round names its config. */
+class ChangedInRound {
+  constructor(readonly changed: readonly string[]) {}
+}
+
+/** Without `configPath`, no config alone was found to make the change. */
 function builtinsChanged(changed: readonly string[], configPath?: string): UserError {
   const who = configPath === undefined ? 'a project config' : configPath
   const env = changed.some((c) => c.startsWith('process.env.'))