@vzn/vx 0.0.18 → 0.0.22

package/src/cache/zstd.ts

@@ -0,0 +1,183 @@
+// zstd framing for artifacts: the declared-size gate that refuses a
+// decompression bomb before it can expand, and the bounded one-call /
+// streamed decoders the store and the ingest path share.
+
+import { CorruptArtifactError } from './layer.js'
+
+/**
+ * A decompressed artifact above this is refused as a zstd bomb rather than
+ * expanded into memory. 2 GiB comfortably exceeds any real build output while
+ * bounding a malicious/compromised remote's ability to OOM a victim who takes
+ * a cache hit. The default of `Cache`'s `artifactCeiling`, the one seam that
+ * lowers it (for a test: no test can produce 2 GiB of output).
+ */
+export const MAX_DECOMPRESSED_ARTIFACT_BYTES = 2 * 1024 * 1024 * 1024
+
+/**
+ * Read a zstd frame's declared Frame_Content_Size (RFC 8878 §3.1.1) WITHOUT
+ * decompressing. Returns null when the frame omits it (streaming frames) or
+ * the header is too short to parse. vx's own producer (single-shot
+ * `Bun.zstdCompress` of a known buffer) always writes it, so an artifact that
+ * declares an enormous size can be rejected before a byte is allocated.
+ *
+ * Exported for tests: pins the per-`fcsFlag` byte layouts (incl. the 2-byte
+ * `+256` adjustment and the `dictIdFlag` offset) that a bomb-refusal e2e can't
+ * discriminate (their max declarable sizes sit below the ceiling).
+ */
+export function zstdContentSize(b: Uint8Array): bigint | null {
+  if (b.length < 5) return null
+  // Magic_Number 0xFD2FB528, little-endian.
+  if (b[0] !== 0x28 || b[1] !== 0xb5 || b[2] !== 0x2f || b[3] !== 0xfd) return null
+  const desc = b[4]!
+  const fcsFlag = desc >> 6
+  const singleSegment = (desc >> 5) & 1
+  const dictIdFlag = desc & 3
+  let off = 5
+  if (singleSegment === 0) off += 1 // Window_Descriptor byte
+  off += dictIdFlag === 3 ? 4 : dictIdFlag // Dictionary_ID: 0,1,2,4 bytes
+  let fcsSize: number
+  if (fcsFlag === 0) fcsSize = singleSegment === 1 ? 1 : 0
+  else if (fcsFlag === 1) fcsSize = 2
+  else if (fcsFlag === 2) fcsSize = 4
+  else fcsSize = 8
+  if (fcsSize === 0 || b.length < off + fcsSize) return null
+  let v = 0n
+  for (let i = 0; i < fcsSize; i++) v |= BigInt(b[off + i]!) << BigInt(8 * i)
+  if (fcsSize === 2) v += 256n // per spec, the 2-byte field stores value − 256
+  return v
+}
+
+/**
+ * Decompress a zstd artifact that DECLARES its content size, with a hard
+ * output ceiling: refused before a byte is allocated when the declaration
+ * is over the cap. The re-check on the actual length below is a backstop
+ * against a decoder that stops validating the declaration, NOT a second
+ * live layer — see its comment. A frame with no
+ * declaration (a streamed producer's — vx's own, above 4 MiB) never comes
+ * here: `decodedTar` decodes it as a stream under the running count, so
+ * a sizeless bomb has nowhere to expand.
+ */
+async function zstdDecompressBounded(
+  compressed: Uint8Array,
+  hash: string,
+  cap: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
+): Promise<Uint8Array> {
+  assertDeclaredSize(compressed, hash, cap)
+  const out = await Bun.zstdDecompress(compressed)
+  // UNREACHABLE as written, and kept deliberately. `assertDeclaredSize`
+  // above refuses any frame DECLARING more than the cap, and Bun refuses a
+  // frame whose declaration disagrees with its body ("Decompression
+  // failed" on a forged Frame_Content_Size, measured item 487) — so a frame
+  // that gets here declared <= cap and produced exactly that. The only way
+  // this fires again is a decoder that stops validating the declaration.
+  // That is what it is for; it is not a second live layer, and no test can
+  // reach it.
+  if (out.length > cap) {
+    throw new CorruptArtifactError(hash, `decompressed to ${out.length} bytes (> ${cap} cap)`)
+  }
+  return out
+}
+
+/** The pre-decompress half of the ceiling: the frame header's own claim, when it makes one. */
+function assertDeclaredSize(
+  compressed: Uint8Array,
+  hash: string,
+  cap: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
+): bigint | null {
+  const declared = zstdContentSize(compressed)
+  if (declared !== null && declared > BigInt(cap)) {
+    throw new CorruptArtifactError(hash, `declares ${declared} decompressed bytes (> ${cap} cap)`)
+  }
+  return declared
+}
+
+/** Compressed artifacts above this size are decoded as a stream, on restore and on ingest. */
+export const STREAM_DECODE_FROM = 4 * 1024 * 1024
+
+/** Collect a byte stream; only ever used where the seam wants bytes. */
+export async function bytesOf(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+  return new Uint8Array(await new Response(stream).arrayBuffer())
+}
+
+/**
+ * Bun's `CompressionStream` types do not satisfy `pipeThrough`'s pair
+ * (its readable side is typed `NonSharedUint8Array`); the runtime object
+ * is a plain byte transform.
+ */
+export const zstdEncoder = (): TransformStream<Uint8Array, Uint8Array> =>
+  new CompressionStream('zstd') as unknown as TransformStream<Uint8Array, Uint8Array>
+
+const oneChunk = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
+  new ReadableStream({
+    start(c) {
+      c.enqueue(bytes)
+      c.close()
+    },
+  })
+
+/**
+ * The decoded tar as a stream: one call for a small artifact that
+ * declares its size, a streamed decode otherwise — the stream setup is
+ * ~35 µs, which matters at a thousand one-file artifacts and nowhere
+ * else. Bytes in memory are only ever the small case (a large source
+ * must be a FILE: a Blob copies its bytes and hands the decoder
+ * everything at once, measured +519 MiB on 150 MiB against +448 for the
+ * plain decode). The 2 GiB ceiling applies either way: the declaration
+ * and the result length in one call, a running count on the stream.
+ */
+export async function decodedTar(
+  source: Uint8Array | Bun.BunFile,
+  hash: string,
+  /**
+   * The decompression ceiling: `Cache` passes its `artifactCeiling`, whose
+   * default IS this module's. Reaching the real one needs an artifact that
+   * expands past 2 GiB, which no test can produce — so before item 487 the
+   * sizeless-bomb defense this module's comments promise had nothing
+   * asserting it, while the declared-size half was pinned by a forged
+   * header costing 20 bytes.
+   */
+  cap: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
+): Promise<ReadableStream<Uint8Array>> {
+  if (source instanceof Uint8Array) {
+    if (assertDeclaredSize(source, hash, cap) === null) {
+      return zstdDecodeStream(new Blob([source]), hash, cap)
+    }
+    return oneChunk(await zstdDecompressBounded(source, hash, cap))
+  }
+  if (source.size <= STREAM_DECODE_FROM) {
+    const bytes = await source.bytes()
+    if (assertDeclaredSize(bytes, hash, cap) === null) return zstdDecodeStream(source, hash, cap)
+    return oneChunk(await zstdDecompressBounded(bytes, hash, cap))
+  }
+  assertDeclaredSize(await source.slice(0, 32).bytes(), hash, cap)
+  return zstdDecodeStream(source, hash, cap)
+}
+
+/**
+ * The streaming twin of `zstdDecompressBounded`: the decoded bytes as a
+ * stream, refused past the same ceiling. A malicious frame cannot expand
+ * past the cap here either — the count runs as bytes are produced, before
+ * any of them reach the reader's next entry.
+ */
+function zstdDecodeStream(
+  source: Blob,
+  hash: string,
+  cap: number = MAX_DECOMPRESSED_ARTIFACT_BYTES,
+): ReadableStream<Uint8Array> {
+  let total = 0
+  return source
+    .stream()
+    .pipeThrough(new DecompressionStream('zstd'))
+    .pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          total += chunk.byteLength
+          if (total > cap) {
+            controller.error(new CorruptArtifactError(hash, `decompresses past ${cap} bytes (cap)`))
+            return
+          }
+          controller.enqueue(chunk)
+        },
+      }),
+    )
+}

package/src/cli/cache.ts

@@ -1,11 +1,42 @@
-import { Cache } from '../cache/index.js'
-import { parseDecimalInt, parseSize } from '../util/index.js'
-import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { seeHelp } from './help.js'
+import { nearest, parseDuration, parseSize } from '../util/index.js'
+import { acquireRunLock } from '../orchestrator/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
+import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
 import { formatBytes } from './format.js'
 
 // parseSize moved to `util` (the orchestrator's resource resolver needs it
 // and can't import cli); re-exported here so existing callers are unchanged.
-export { parseSize } from '../util/index.js'
+export { parseDuration, parseSize } from '../util/index.js'
+
+/**
+ * `vx cache stats` is a habit from the other runners, and vx's answer is a
+ * different VERB rather than a missing one — saying so where the user typed
+ * it beats sending them to a help screen that lists only `prune` (walked the
+ * first-run path, 2026-09-20). A typo of `prune` itself gets the same
+ * nearest-neighbour hint a task, flag or project name gets.
+ */
+const CACHE_ELSEWHERE: Record<string, string> = {
+  stats: '`vx info` reports the cache directory, its entry count and its size',
+  status: '`vx info` reports the cache directory, its entry count and its size',
+  size: '`vx info` reports the cache directory, its entry count and its size',
+  entries: '`vx info` reports the cache directory, its entry count and its size',
+  dir: '`vx info` prints the cache directory this workspace uses',
+  path: '`vx info` prints the cache directory this workspace uses',
+  clean: '`vx cache prune` is the eviction verb (`--older-than`, `--max-size`)',
+  clear: '`vx cache prune` is the eviction verb (`--older-than`, `--max-size`)',
+  rm: '`vx cache prune` is the eviction verb (`--older-than`, `--max-size`)',
+  delete: '`vx cache prune` is the eviction verb (`--older-than`, `--max-size`)',
+  evict: '`vx cache prune` is the eviction verb (`--older-than`, `--max-size`)',
+}
+
+function cacheSubHint(sub: string): string {
+  const elsewhere = CACHE_ELSEWHERE[sub]
+  if (elsewhere !== undefined) return ` — ${elsewhere}`
+  const best = nearest(sub, ['prune'])
+  return best === undefined ? '' : `. Did you mean ${best}?`
+}
 
 export async function cacheCmd(args: readonly string[]): Promise<number> {
   const [sub, ...rest] = args
@@ -16,7 +47,9 @@ export async function cacheCmd(args: readonly string[]): Promise<number> {
       process.stderr.write('vx cache: missing subcommand. Try `vx cache prune`.\n')
       return 1
     default:
-      process.stderr.write(`vx cache: unknown subcommand: ${sub}\n`)
+      process.stderr.write(
+        `vx cache: unknown subcommand: ${sub}${cacheSubHint(sub)}${seeHelp('cache')}\n`,
+      )
       return 1
   }
 }
@@ -24,6 +57,9 @@ export async function cacheCmd(args: readonly string[]): Promise<number> {
 interface PruneArgs {
   olderThanMs?: number
   maxBytes?: number
+  dryRun?: boolean
+  /** `--cache-dir`: prune the cache a run with the same flag uses. */
+  cacheDir?: string
   error?: string
 }
 
@@ -60,9 +96,25 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
           error: `--max-size 0 would evict every entry — delete the cache directory instead`,
         }
       }
+      // A bare number is bytes to `parseSize` (a computed size needs that),
+      // but nobody caps a cache at 10 bytes: `--max-size 10`
+      // meant 10G or 10M and would evict everything, the same class of
+      // destructive typo the zero bound above refuses. An explicit `10B`
+      // still passes.
+      if (/^\d+$/.test(v)) {
+        return {
+          error: `--max-size ${v} would read as ${v} bytes and evict nearly everything — give a unit (e.g. ${v}M, ${v}G)`,
+        }
+      }
       out.maxBytes = bytes
+    } else if (a === '--dry-run') {
+      out.dryRun = true
     } else {
-      return { error: `unknown argument: ${a}` }
+      const cd = parseCacheDirFlag(args, i)
+      if (cd === null) return { error: `unknown argument: ${a}${seeHelp('cache')}` }
+      if ('error' in cd) return { error: cd.error }
+      out.cacheDir = cd.cacheDir
+      i = cd.next
     }
   }
   if (out.olderThanMs === undefined && out.maxBytes === undefined) {
@@ -85,38 +137,44 @@ async function pruneCmd(args: readonly string[]): Promise<number> {
     process.stderr.write(`vx cache prune: ${(err as Error).message}\n`)
     return 1
   }
-  // Honor `defineWorkspace({ cacheDir: '...' })` — `vx run` and
-  // `vx cache prune` must operate on the same directory or prune
-  // silently no-ops against the wrong path.
-  const workspaceConfig = await loadWorkspaceConfig(root)
-  const cache = new Cache(resolveCacheDir(root, workspaceConfig))
+  // Honor `--cache-dir`, `defineWorkspace({ cacheDir: '...' })` and a
+  // `config` plugin's edit of it — `vx run` and `vx cache prune` must
+  // operate on the same directory or prune silently no-ops against the
+  // wrong path.
+  // A dry run only reads: it never resets the index (item 896).
+  const dir = await cliCacheDir(root, parsed.cacheDir)
+  const cache = parsed.dryRun === true ? Cache.inspect(dir) : new Cache(dir)
+  // A prune deletes rows and artifacts; a cache this user cannot write is
+  // refused up front with the directory named, as a run refuses it, rather
+  // than dying in the first DELETE with SQLite's "readonly database" and a
+  // stack (an unprivileged user on a root-owned `.vx`, 2026-09-16). A dry
+  // run only reads, and reads a read-only cache fine.
+  if (!parsed.dryRun) cache.assertWritable()
+  noteSchemaReset(cache, warnToStderr)
+  // A prune beside a run on this workspace evicts what the run has just
+  // probed as hits, whose `accessed_at` bumps it has not flushed yet; the
+  // run then re-runs those tasks (upstream survey, nx#36688). So a prune
+  // takes the run's lock and waits its turn. A dry run deletes nothing.
+  const releaseRunLock = parsed.dryRun
+    ? async (): Promise<void> => {}
+    : await acquireRunLock(root, { log: warnToStderr })
   try {
-    const opts: { olderThanMs?: number; maxBytes?: number } = {}
+    const opts: { olderThanMs?: number; maxBytes?: number; dryRun?: boolean } = {}
     if (parsed.olderThanMs !== undefined) opts.olderThanMs = parsed.olderThanMs
     if (parsed.maxBytes !== undefined) opts.maxBytes = parsed.maxBytes
+    if (parsed.dryRun) opts.dryRun = true
     const result = await cache.prune(opts)
+    const dry = parsed.dryRun === true
+    const orphans =
+      result.orphans > 0
+        ? `, ${dry ? 'would reap' : 'reaped'} ${result.orphans} orphaned artifact${result.orphans === 1 ? '' : 's'} (${formatBytes(result.orphanBytes)})`
+        : ''
     process.stdout.write(
-      `Pruned ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)} freed)\n`,
+      `${dry ? 'Would prune' : 'Pruned'} ${result.evicted} entr${result.evicted === 1 ? 'y' : 'ies'} (${formatBytes(result.bytesFreed)}${dry ? '' : ' freed'})${orphans}\n`,
     )
   } finally {
     cache.close()
+    await releaseRunLock()
   }
   return 0
 }
-
-/**
- * Parse `<n><unit>` where unit is s/m/h/d, case-insensitively (`parseSize`
- * has always been case-insensitive; this matched only lowercase, so `30D`
- * was rejected while `1GB` and `1gb` both worked).
- */
-export function parseDuration(input: string): number | null {
-  const m = input.match(/^(\d+)([smhd])$/i)
-  if (!m) return null
-  const n = parseDecimalInt(m[1]!)
-  if (n === null) return null
-  // Lowercase before the switch: with the /i flag an uppercase `M` would
-  // otherwise fall through to the days branch.
-  const unit = m[2]!.toLowerCase()
-  const mult = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000
-  return n * mult
-}

package/src/cli/completions.ts

@@ -0,0 +1,104 @@
+// `vx completions <shell>` — a bash / zsh / fish script over the verb table
+// and each verb's help cut, so the verbs and every flag of each complete
+// from the one text `vx <verb> --help` prints. Plugin verbs of the
+// workspace around the cwd are included at generation time; task and
+// project names are not (a completion that evaluates configs on every
+// Tab is the wrong price).
+
+import { CORE_VERBS, seeHelp, verbHelpText } from './help.js'
+
+export type CompletionShell = 'bash' | 'zsh' | 'fish'
+const SHELLS: readonly CompletionShell[] = ['bash', 'zsh', 'fish']
+
+/** Every `--flag` the verb's help cut names, plus `--help`; deduped, in order of appearance. */
+export function verbFlags(verb: string): string[] {
+  const flags = new Set<string>(['--help'])
+  for (const f of verbHelpText(verb).match(/--[a-zA-Z][a-zA-Z-]*/g) ?? []) flags.add(f)
+  return [...flags]
+}
+
+/** The words that follow `vx <verb>` besides flags: subcommands and fixed choices. */
+const VERB_WORDS: Readonly<Record<string, readonly string[]>> = {
+  cache: ['prune'],
+  completions: [...SHELLS],
+}
+
+export function completionScript(shell: CompletionShell, verbs: readonly string[]): string {
+  const table = verbs.map((v) => ({
+    verb: v,
+    // A plugin verb owns its own arguments; only `--help` is known here.
+    words: [
+      ...(VERB_WORDS[v] ?? []),
+      ...((CORE_VERBS as readonly string[]).includes(v) ? verbFlags(v) : ['--help']),
+    ],
+  }))
+  switch (shell) {
+    case 'bash':
+      return [
+        '# vx completions — generated by `vx completions bash`',
+        '_vx() {',
+        '  local cur="${COMP_WORDS[COMP_CWORD]}"',
+        '  local verb="${COMP_WORDS[1]}"',
+        '  if [ "$COMP_CWORD" -eq 1 ]; then',
+        `    COMPREPLY=($(compgen -W "${verbs.join(' ')}" -- "$cur"))`,
+        '    return',
+        '  fi',
+        '  case "$verb" in',
+        ...table.map(
+          (t) => `    ${t.verb}) COMPREPLY=($(compgen -W "${t.words.join(' ')}" -- "$cur")) ;;`,
+        ),
+        '    *) COMPREPLY=() ;;',
+        '  esac',
+        '}',
+        'complete -F _vx vx',
+        '',
+      ].join('\n')
+    case 'zsh':
+      return [
+        '#compdef vx',
+        '# vx completions — generated by `vx completions zsh`',
+        '_vx() {',
+        '  if (( CURRENT == 2 )); then',
+        `    compadd -- ${verbs.join(' ')}`,
+        '    return',
+        '  fi',
+        '  case "${words[2]}" in',
+        ...table.map((t) => `    ${t.verb}) compadd -- ${t.words.join(' ')} ;;`),
+        '  esac',
+        '}',
+        'compdef _vx vx',
+        '',
+      ].join('\n')
+    case 'fish':
+      return [
+        '# vx completions — generated by `vx completions fish`',
+        'complete -c vx -f',
+        ...verbs.map((v) => `complete -c vx -n __fish_use_subcommand -a ${v}`),
+        ...table.flatMap((t) =>
+          t.words.map((w) =>
+            w.startsWith('--')
+              ? `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}" -l ${w.slice(2)}`
+              : `complete -c vx -n "__fish_seen_subcommand_from ${t.verb}" -a ${w}`,
+          ),
+        ),
+        '',
+      ].join('\n')
+  }
+}
+
+export async function completionsCmd(
+  args: readonly string[],
+  pluginVerbs: readonly string[],
+): Promise<number> {
+  const shell = args[0]
+  if (args.length !== 1 || !(SHELLS as readonly string[]).includes(shell ?? '')) {
+    process.stderr.write(
+      `vx completions: expected one shell — bash, zsh or fish${shell !== undefined && args.length === 1 ? ` (got ${shell})` : ''}${seeHelp('completions')}\n`,
+    )
+    return 1
+  }
+  const verbs = [...CORE_VERBS.filter((v) => v !== 'help' && v !== 'version'), 'help', 'version']
+  for (const v of pluginVerbs) if (!verbs.includes(v)) verbs.push(v)
+  process.stdout.write(completionScript(shell as CompletionShell, verbs))
+  return 0
+}

package/src/cli/core-alias.ts

@@ -0,0 +1,25 @@
+/**
+ * One core per process. A plugin package, a `vx.workspace.ts`, a
+ * `vx.config.ts` all `import … from '@vzn/vx'`, and that specifier
+ * resolves through node_modules — to a SECOND copy of core when the host
+ * is the compiled binary (whose own copy lives under the bunfs root) or
+ * an install with its own nested `@vzn/vx`. The second copy is core's
+ * whole source transpiled again, per process: ~20 ms per plugin package
+ * in the binary (measured 2026-09-10, `@vzn/vx-otel`: 20–25 ms → 2–3 ms),
+ * and two module states — two `definePlugin` memos, two of everything
+ * keyed by identity rather than by registry symbol.
+ *
+ * The alias is a Bun virtual module for the exact specifier `@vzn/vx`,
+ * served from the host's own façade, loaded lazily on the first import
+ * so a verb that never loads a plugin never loads the façade. The
+ * source form (`bun src/bin.ts`) resolves the specifier to the same file
+ * anyway; the alias makes that a guarantee rather than a layout fact.
+ */
+export function registerCoreAlias(load: () => Promise<Record<string, unknown>>): void {
+  Bun.plugin({
+    name: 'vx-core-alias',
+    setup(build) {
+      build.module('@vzn/vx', async () => ({ exports: await load(), loader: 'object' }))
+    },
+  })
+}

package/src/cli/format.ts

@@ -1,15 +1,4 @@
-/**
- * Human-readable byte size with KB/MB/GB/TB/PB suffixes and one
- * decimal of precision below 10 of any unit. Used by `vx stats` and
- * `vx cache prune` output.
- */
-export function formatBytes(n: number): string {
-  if (n < 1024) return `${n} B`
-  const units = ['KB', 'MB', 'GB', 'TB']
-  let v = n / 1024
-  for (const u of units) {
-    if (v < 1024) return `${v.toFixed(v < 10 ? 1 : 0)} ${u}`
-    v /= 1024
-  }
-  return `${v.toFixed(0)} PB`
-}
+// `formatBytes` moved to util/size.ts beside the parsers (item 658): a run
+// names what the workspace's `cacheRetention` evicted, and the orchestrator
+// may not import the CLI.
+export { formatBytes } from '../util/index.js'