@vzn/vx 0.0.90 → 0.0.91

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.90",
-  "description": "An open, extensible monorepo task runner.",
+  "version": "0.0.91",
+  "description": "A fast, correct task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
     ".": {
@@ -17,10 +17,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.90",
-    "@vzn/vx-linux-arm64": "0.0.90",
-    "@vzn/vx-darwin-x64": "0.0.90",
-    "@vzn/vx-darwin-arm64": "0.0.90"
+    "@vzn/vx-linux-x64": "0.0.91",
+    "@vzn/vx-linux-arm64": "0.0.91",
+    "@vzn/vx-darwin-x64": "0.0.91",
+    "@vzn/vx-darwin-arm64": "0.0.91"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"
@@ -36,16 +36,20 @@
     "type": "git",
     "url": "git+https://github.com/vznjs/vx.git"
   },
-  "homepage": "https://github.com/vznjs/vx#readme",
+  "homepage": "https://vznjs.github.io/vx/",
   "bugs": "https://github.com/vznjs/vx/issues",
   "license": "MIT",
   "keywords": [
+    "vx",
     "monorepo",
     "task-runner",
-    "build",
+    "build-cache",
+    "build-system",
     "cache",
-    "bun",
     "turborepo",
-    "nx"
+    "nx",
+    "bun",
+    "workspaces",
+    "ci"
   ]
 }

package/src/cache/cache.ts

@@ -40,6 +40,7 @@ import {
   span,
   splitTaskId,
   taskGlob,
+  xxh3hex,
 } from '../util/index.js'
 import {
   ArchiveSecurityError,
@@ -655,7 +656,7 @@ export class Cache implements CacheLayer {
     this.files = new FileHashStore(this.db, cacheDir, this.write, repoDir)
     this.configEvals = new ConfigEvalTable(this.db, { read: this.read, write: this.write })
     this.outputs = new OutputIndex(this.db)
-    this.history = new RunHistory(this.db)
+    this.history = new RunHistory(this.db, (v) => this.digestValue(v))
 
     // A CACHE_VERSION bump keeps the index but moves every key, so the run
     // after an upgrade misses everything. Roadmap 3.3: that is announced,
@@ -753,9 +754,47 @@ export class Cache implements CacheLayer {
       input,
       (f) => this.hashFile(f),
       (f) => this.relFor(input.workspaceRoot, f),
+      (v) => this.digestValue(v),
     )
   }
 
+  private valueSalt: string | undefined
+
+  /**
+   * The digest a value-bearing row holds (an env value, a runtime output,
+   * args after `--`): xxh3 under a random salt this store keeps. `vx why`,
+   * its JSON and MCP's `whyDidThisRerun` print it, and an unkeyed xxh3 in
+   * a public CI log let anyone confirm or brute-force a short secret
+   * (L-4). Salted, a digest still says whether a value changed, and says
+   * nothing without this cache's `schema_meta`. Asked for on a miss only.
+   */
+  private digestValue(value: string): string {
+    this.valueSalt ??= this.loadValueSalt()
+    return xxh3hex(`${this.valueSalt}\0${value}`)
+  }
+
+  private loadValueSalt(): string {
+    const read = (): string | undefined =>
+      (
+        this.db.prepare("SELECT value FROM schema_meta WHERE key = 'value_salt'").get() as {
+          value: string
+        } | null
+      )?.value
+    const found = read()
+    if (found !== undefined) return found
+    const salt = Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString('hex')
+    // A store this process may not write keeps the salt for the process:
+    // nothing it digests is persisted.
+    if (this.writeBlocked !== null || this.inspecting) return salt
+    // Two processes opening one new store: the first salt stands.
+    this.db
+      .prepare(
+        "INSERT INTO schema_meta(key, value) VALUES ('value_salt', ?) ON CONFLICT(key) DO NOTHING",
+      )
+      .run(salt)
+    return read() ?? salt
+  }
+
   // ctx is accepted but ignored — the local layer reads metadata from
   // the entries row. It's part of the contract so LayeredCache can
   // route metadata to `ingest()` on remote-hit without a separate API.

package/src/cache/key-fold.ts

@@ -99,6 +99,12 @@ export async function foldKey(
   input: CacheKeyInput,
   hashFile: (file: string) => Promise<string>,
   relOf: (file: string) => string,
+  /**
+   * The digest a value-bearing capture row holds. `Cache` keys it with a
+   * salt of its own (L-4); the default is for a caller that persists and
+   * prints nothing.
+   */
+  digestValue: (value: string) => string = xxh3hex,
 ): Promise<string> {
   // Seed-chained xxHash3: each step folds one field into the
   // running digest via `xxh3(part, prevDigest)`. Equivalent to the
@@ -124,16 +130,18 @@ export async function foldKey(
   // DIGEST of each component, never the raw value. For value-bearing kinds
   // (env, runtime, ws-runtime, forward) the payload is a secret or
   // sensitive string (API keys via cache.inputs.env, runtime-command
-  // output, args after `--`), so we push `xxh3hex(v)` — the diff consumer
-  // only needs to know whether a component CHANGED, which a digest
-  // preserves losslessly. cache.db must never hold plaintext secrets at
-  // rest. The cache KEY (`h`) folds the plaintext separately below and is
+  // output, args after `--`), so we push `digestValue(v)` — the diff
+  // consumer only needs to know whether a component CHANGED, which a
+  // digest preserves losslessly. cache.db must never hold plaintext
+  // secrets at rest, and `vx why` prints the digest, so it is salted: an
+  // unkeyed 64-bit xxh3 in a public CI log gave a short secret away to a
+  // brute force (L-4). The cache KEY (`h`) folds the plaintext separately below and is
   // unaffected.
   const forwarded = input.forwardArgs ?? []
   h = xxh3(`forward-args:${forwarded.length}`, h)
   for (const a of forwarded) h = xxh3(a, h)
   if (cap && forwarded.length > 0) {
-    cap.push({ kind: 'forward', name: 'argv', hash: xxh3hex(JSON.stringify(forwarded)) })
+    cap.push({ kind: 'forward', name: 'argv', hash: digestValue(JSON.stringify(forwarded)) })
   }
 
   h = xxh3(`env-values:${input.envValues.length}`, h)
@@ -145,20 +153,20 @@ export async function foldKey(
   for (const [n, v] of input.envValues) h = xxh3(v === undefined ? n : `${n}\0${v}`, h)
   if (cap)
     for (const [n, v] of input.envValues)
-      cap.push({ kind: 'env', name: n, hash: v === undefined ? 'unset' : xxh3hex(v) })
+      cap.push({ kind: 'env', name: n, hash: v === undefined ? 'unset' : digestValue(v) })
 
   const runtimeValues = input.runtimeValues ?? []
   h = xxh3(`runtime-values:${runtimeValues.length}`, h)
   for (const [c, o] of runtimeValues) h = xxh3(`${c}\0${o}`, h)
   if (cap)
-    for (const [c, o] of runtimeValues) cap.push({ kind: 'runtime', name: c, hash: xxh3hex(o) })
+    for (const [c, o] of runtimeValues) cap.push({ kind: 'runtime', name: c, hash: digestValue(o) })
 
   const wsRuntimeValues = input.workspaceRuntimeValues ?? []
   h = xxh3(`ws-runtime-values:${wsRuntimeValues.length}`, h)
   for (const [c, o] of wsRuntimeValues) h = xxh3(`${c}\0${o}`, h)
   if (cap)
     for (const [c, o] of wsRuntimeValues)
-      cap.push({ kind: 'ws-runtime', name: c, hash: xxh3hex(o) })
+      cap.push({ kind: 'ws-runtime', name: c, hash: digestValue(o) })
 
   const upstream = [...input.upstreamHashes].sort()
   h = xxh3(`upstream:${upstream.length}`, h)
@@ -174,7 +182,7 @@ export async function foldKey(
     h = xxh3(`plugin:${pluginParts.length}`, h)
     for (const [n, v] of pluginParts) h = xxh3(`${n}\0${v}`, h)
     if (cap) {
-      for (const [n, v] of pluginParts) cap.push({ kind: 'plugin', name: n, hash: xxh3hex(v) })
+      for (const [n, v] of pluginParts) cap.push({ kind: 'plugin', name: n, hash: digestValue(v) })
     }
   }
 

package/src/cache/run-history.ts

@@ -4,14 +4,17 @@
 // its statements over the store's handle; `Cache` delegates.
 
 import type { Database, SQLQueryBindings } from 'bun:sqlite'
-import { xxh3hex } from '../util/index.js'
 import type { InvocationRecord, RunRecord } from './layer.js'
 
 export class RunHistory {
   private readonly insertRun: ReturnType<Database['prepare']>
   private readonly insertInvocation: ReturnType<Database['prepare']>
 
-  constructor(private readonly db: Database) {
+  constructor(
+    private readonly db: Database,
+    /** The store's salted value digest (L-4). */
+    private readonly digestValue: (value: string) => string,
+  ) {
     this.insertRun = this.db.prepare(`
       INSERT INTO runs(
         hash, project, task, status, exit_code, duration_ms, forward_args,
@@ -37,13 +40,13 @@ export class RunHistory {
   }
 
   recordRun(run: RunRecord): void {
-    this.insertRun.run(...bindRun(run))
+    this.insertRun.run(...bindRun(run, this.digestValue))
   }
 
   recordRuns(runs: readonly RunRecord[]): void {
     if (runs.length === 0) return
     if (runs.length === 1) {
-      this.insertRun.run(...bindRun(runs[0]!))
+      this.insertRun.run(...bindRun(runs[0]!, this.digestValue))
       return
     }
     // `bun:sqlite`'s `transaction()` returns a callable that wraps the
@@ -51,7 +54,7 @@ export class RunHistory {
     // run that's one fsync instead of 200.
     const insert = this.insertRun
     const tx = this.db.transaction((batch: readonly RunRecord[]) => {
-      for (const r of batch) insert.run(...bindRun(r))
+      for (const r of batch) insert.run(...bindRun(r, this.digestValue))
     })
     tx(runs)
   }
@@ -66,7 +69,7 @@ export class RunHistory {
     const insertRun = this.insertRun
     const insertInvocation = this.insertInvocation
     this.db.transaction(() => {
-      for (const r of bundle.runs) insertRun.run(...bindRun(r))
+      for (const r of bundle.runs) insertRun.run(...bindRun(r, this.digestValue))
       insertInvocation.run(...bindInvocation(bundle.invocation))
     })()
   }
@@ -89,7 +92,7 @@ export class RunHistory {
  * `insertRun` prepared statement (21 columns). Shared between the
  * single and batched record paths.
  */
-function bindRun(run: RunRecord): SQLQueryBindings[] {
+function bindRun(run: RunRecord, digestValue: (v: string) => string): SQLQueryBindings[] {
   return [
     // The ONE place the no-key sentinel is applied, so the column's
     // NOT NULL invariant can't be violated from a call site.
@@ -102,7 +105,7 @@ function bindRun(run: RunRecord): SQLQueryBindings[] {
     // A digest, as entry_inputs keeps: args after `--` carry tokens
     // (`--token=…`), and cache.db holds no plaintext secret at rest; nothing
     // reads the column but for whether the args changed (item 1091).
-    run.forwardArgs ? xxh3hex(JSON.stringify(run.forwardArgs)) : null,
+    run.forwardArgs ? digestValue(JSON.stringify(run.forwardArgs)) : null,
     run.startedAt,
     run.endedAt,
     run.runId ?? null,

package/src/cli/cache.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { Cache, noteSchemaReset } from '../cache/index.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { nearest, parseDuration, parseSize } from '../util/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
@@ -112,7 +112,10 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
       out.dryRun = true
     } else {
       const cd = parseCacheDirFlag(args, i)
-      if (cd === null) return { error: `unknown argument: ${a}${seeHelp('cache')}` }
+      if (cd === null)
+        return {
+          error: `unknown argument: ${a}${flagHint('cache prune', a ?? '')}${seeHelp('cache')}`,
+        }
       if ('error' in cd) return { error: cd.error }
       out.cacheDir = cd.cacheDir
       i = cd.next

package/src/cli/help.ts

@@ -1,3 +1,5 @@
+import { nearest } from '../util/index.js'
+
 export function printHelp(pluginCommands: readonly string[] = [], verb?: string): void {
   process.stdout.write(verb === undefined ? helpText(pluginCommands) : verbHelpText(verb))
 }
@@ -188,6 +190,26 @@ export function seeHelp(verb: string): string {
   return ` (see \`vx ${verb} --help\`)`
 }
 
+/**
+ * `(did you mean --concurrency?)` for a flag within two edits of one `verb`
+ * accepts; empty for anything else (a positional included). A third edit
+ * is allowed only between flags that share their first five characters,
+ * so `--retries` reaches `--retry` while `--zzz` does not reach `--all`.
+ */
+export function flagHint(verb: string, arg: string): string {
+  if (!arg.startsWith('-')) return ''
+  const name = arg.replace(/=.*$/, '')
+  const flags = acceptedFlags(verb)
+  const best =
+    nearest(name, flags) ??
+    nearest(
+      name,
+      flags.filter((f) => f.slice(0, 5) === name.slice(0, 5)),
+      3,
+    )
+  return best === undefined ? '' : ` (did you mean ${best}?)`
+}
+
 /**
  * The documented `--flags` of one verb, read from the help text's
  * sections headed `… (for <verb>):` so there is no second list to drift —

package/src/cli/info.ts

@@ -5,7 +5,7 @@
 // too; this file parses the flags and renders the rows.
 
 import { collectInfo, type FlakyTask, type InfoFacts } from '../orchestrator/index.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { namedCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 import { MIN_BUN } from '../util/index.js'
@@ -36,7 +36,7 @@ export function parseInfoArgs(args: readonly string[]): InfoArgs {
       i = cd.next
       continue
     }
-    return { ...out, error: `unknown argument: ${a}${seeHelp('info')}` }
+    return { ...out, error: `unknown argument: ${a}${flagHint('info', a ?? '')}${seeHelp('info')}` }
   }
   return out
 }

package/src/cli/init.ts

@@ -4,7 +4,7 @@
 // the scripts is the richer source, and `@vzn/vx-migrate` maps it.
 
 import path from 'node:path'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import {
   applyMigration,
   findWorkspaceRoot,
@@ -28,7 +28,8 @@ export function parseInitArgs(args: readonly string[]): InitArgs {
     if (a === '--dry') out.dry = true
     else if (a === '--force') out.force = true
     else if (a === '--mjs') out.mjs = true
-    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('init')}` }
+    else if (a.startsWith('-'))
+      return { ...out, error: `unknown flag: ${a}${flagHint('init', a)}${seeHelp('init')}` }
     else return { ...out, error: `unexpected argument: ${a}` }
   }
   return out

package/src/cli/last.ts

@@ -6,7 +6,7 @@
 
 import { Cache, noteSchemaReset } from '../cache/index.js'
 import { formatBytes } from './format.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import {
   exitSignal,
   getInvocation,
@@ -62,7 +62,8 @@ export function parseLastArgs(args: readonly string[]): LastArgs {
       i = cd.next
       continue
     }
-    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('last')}` }
+    if (a.startsWith('-'))
+      return { ...out, error: `unknown flag: ${a}${flagHint('last', a)}${seeHelp('last')}` }
     if (out.runId !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     out.runId = a
   }

package/src/cli/lock.ts

@@ -3,7 +3,7 @@
 // current environment. Design: docs/design/config-lock-2026-06.md.
 
 import type { ProjectConfig } from '../config.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { relPosix, xxh3hex } from '../util/index.js'
 import {
   findWorkspaceRoot,
@@ -29,7 +29,11 @@ export function parseLockArgs(args: readonly string[]): LockArgs {
   const out: LockArgs = { check: false }
   for (const a of args) {
     if (a === '--check') out.check = true
-    else return { check: false, error: `unknown argument: ${a}${seeHelp('lock')}` }
+    else
+      return {
+        check: false,
+        error: `unknown argument: ${a}${flagHint('lock', a)}${seeHelp('lock')}`,
+      }
   }
   return out
 }

package/src/cli/run.ts

@@ -1,6 +1,6 @@
 import { appendFileSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
-import { documentedFlags, seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { defaultAffectedBase, findWorkspaceRoot } from '../workspace/index.js'
 import {
   planRun,
@@ -15,13 +15,7 @@ import {
 import type { ContinueMode } from '../graph/index.js'
 import { type CachePolicy, FULL_CACHE_POLICY, parseCachePolicy } from '../cache/index.js'
 import { findCwdProject, pickTask, resolveFilters } from './select.js'
-import {
-  MAX_TIMEOUT_MS,
-  isUserError,
-  parseDecimalInt,
-  nearest,
-  machineParallelism,
-} from '../util/index.js'
+import { MAX_TIMEOUT_MS, isUserError, parseDecimalInt, machineParallelism } from '../util/index.js'
 import { formatGraphDot, formatPlanJson, formatPlanText } from './plan-format.js'
 
 export interface RunArgs {
@@ -343,7 +337,7 @@ export function parseRunArgs(args: readonly string[]): RunArgs {
       }
       out.report = fmt
     } else if (a !== undefined && a.startsWith('-')) {
-      return { ...out, error: `unknown flag: ${a}${didYouMeanFlag(a)}${seeHelp('run')}` }
+      return { ...out, error: `unknown flag: ${a}${flagHint('run', a)}${seeHelp('run')}` }
     } else if (a !== undefined) {
       out.tasks.push(a)
     }
@@ -695,20 +689,3 @@ function printSummary(summary: RunResult): void {
 function formatRow(o: OutcomeView): { task: string; status: string; duration: string } {
   return { task: o.taskId, status: outcomeLabel(o), duration: `${o.durationMs}ms` }
 }
-
-/** `(did you mean --concurrency?)` for a flag within two edits of a documented one. */
-function didYouMeanFlag(flag: string): string {
-  const name = flag.replace(/=.*$/, '')
-  const flags = documentedFlags('run')
-  // The usual two edits; a third only between flags that share their
-  // first five characters, so `--retries` reaches `--retry` (the i/y)
-  // while `--zzz` does not reach `--all` — a plain three-edit budget did.
-  const best =
-    nearest(name, flags) ??
-    nearest(
-      name,
-      flags.filter((f) => f.slice(0, 5) === name.slice(0, 5)),
-      3,
-    )
-  return best === undefined ? '' : ` (did you mean ${best}?)`
-}

package/src/cli/show.ts

@@ -8,7 +8,7 @@
 
 import type { ProjectConfig, TaskConfig } from '../config.js'
 import { declaredTask } from '../graph/index.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { nearMatches, relPosix, UserError } from '../util/index.js'
 import { loadCliProjects } from './workspace-config.js'
 import {
@@ -33,7 +33,8 @@ export function parseShowArgs(args: readonly string[]): ShowArgs {
     let format: string | undefined
     if (a === '--format') format = args[++i] ?? ''
     else if (a.startsWith('--format=')) format = a.slice('--format='.length)
-    else if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('show')}` }
+    else if (a.startsWith('-'))
+      return { ...out, error: `unknown flag: ${a}${flagHint('show', a)}${seeHelp('show')}` }
     else if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     else out.target = a
 

package/src/cli/why.ts

@@ -6,7 +6,7 @@
 // no config evaluation, no re-hash.
 
 import { Cache, noteSchemaReset } from '../cache/index.js'
-import { seeHelp } from './help.js'
+import { flagHint, seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
@@ -83,7 +83,8 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
       i = cd.next
       continue
     }
-    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('why')}` }
+    if (a.startsWith('-'))
+      return { ...out, error: `unknown flag: ${a}${flagHint('why', a)}${seeHelp('why')}` }
     if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
     out.target = a
   }

package/src/orchestrator/stable-keys.ts

@@ -340,6 +340,19 @@ export function dependsOnSiblingOutputs(
     const outputs = sameProject.outputsOf.get(node.projectName) ?? []
     if (inputs === undefined || outputs.length === 0) return true
     if (workspaceInputsReach(inputs, outputs.map(literalPrefix))) return true
+    // Nor where it WRITES inside another task's tree: restored ahead of
+    // that producer, its restore raced the producer's clean and extract
+    // (M-5; invariant 2 of docs/design/overlapping-outputs-2026-09.md).
+    // `outputsOf` holds this task's own globs too; set them aside once.
+    const own = cache.outputs.files
+    if (own.length > 0) {
+      const others = [...outputs]
+      for (const g of own) {
+        const i = others.indexOf(g)
+        if (i !== -1) others.splice(i, 1)
+      }
+      if (others.length > 0 && workspaceInputsReach(own, others.map(literalPrefix))) return true
+    }
   }
   // A root-anchored output is boundary-IGNORING by design, so it can land
   // inside THIS task's own project dir — where an ordinary project-relative