@vzn/vx 0.0.591 → 0.0.594

package/launcher.cjs

@@ -37,8 +37,15 @@ const SUPPORTED = ['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64']
 const key = `${process.platform}-${process.arch}`
 const args = process.argv.slice(2)
 
+// The prebuilt Linux binaries link glibc. On musl (Alpine) the loader they
+// name is absent, execve fails with ENOENT on a file that exists, and the
+// user read "failed to launch (spawn … ENOENT)". Treated as no binary here,
+// so Bun runs the source when present and the error names the cause.
+const GLIBC_LOADER = { x64: '/lib64/ld-linux-x86-64.so.2', arm64: '/lib/ld-linux-aarch64.so.1' }
+const noGlibc = process.platform === 'linux' && !existsSync(GLIBC_LOADER[process.arch] ?? '/')
+
 function platformBinary() {
-  if (!SUPPORTED.includes(key)) return undefined
+  if (!SUPPORTED.includes(key) || noGlibc) return undefined
   const platformPkg = `${name}-${key}`
   try {
     // No `exports` restriction on the platform packages, so package.json
@@ -119,7 +126,7 @@ if (bin !== undefined) {
 } else {
   const supported = SUPPORTED.join(', ')
   process.stderr.write(
-    `${base}: no prebuilt binary for ${key}.\n` +
+    `${base}: no prebuilt binary for ${key}${noGlibc ? ' without glibc (musl)' : ''}.\n` +
       `  Supported platforms: ${supported}.\n` +
       `  If your platform should be supported, reinstall so npm fetches the\n` +
       `  matching ${name}-${key} optionalDependency, or install Bun (>=1.4) to\n` +

package/package.json

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

package/src/cache/archive.ts

@@ -563,6 +563,8 @@ interface Staged {
   target: string
   /** The topmost directory `mkdir -p` created for it, pruned on abort. */
   created: string | undefined
+  /** Written by Bun's file writer, which creates with 0664 where `writeFile` uses 0666 (before the umask). */
+  streamed: boolean
 }
 
 /**
@@ -761,7 +763,8 @@ class Extractor {
       path.dirname(target),
       `.vx-tmp-${process.pid.toString(36)}-${(tmpSeq++).toString(36)}`,
     )
-    this.staged.push({ name, tmp, target, created })
+    const streamed = !(body instanceof Uint8Array)
+    this.staged.push({ name, tmp, target, created, streamed })
     if (body instanceof Uint8Array) {
       this.inflightBytes += body.byteLength
       // `writeFile`, not `Bun.write`: for a buffer this size `Bun.write`
@@ -803,17 +806,23 @@ class Extractor {
    * (measured 2026-09-11 on payload's ui, 4,069 files: 892 ms → see the
    * archive bench). A yield every `COMMIT_BATCH` files keeps the other
    * restores' round trips flowing. The chmod is skipped when the mode is
-   * the one the temp file was created with — the common case.
+   * the one the temp file was created with — the common case. The two
+   * writers create with different modes (under umask 000: 0666 and 0664),
+   * so each is stat'ed once.
    */
   async commit(
     metaFor: (name: string) => [mode: number, mtimeMs: number | undefined],
   ): Promise<void> {
     await this.drain()
-    const first = this.staged[0]
-    const createdMode = first === undefined ? -1 : statSync(first.tmp).mode & 0o777
+    const createdModes = new Map<boolean, number>()
     let n = 0
     for (const s of this.staged) {
       const [mode, mtimeMs] = metaFor(s.name)
+      let createdMode = createdModes.get(s.streamed)
+      if (createdMode === undefined) {
+        createdMode = statSync(s.tmp).mode & 0o777
+        createdModes.set(s.streamed, createdMode)
+      }
       if ((mode & 0o777) !== createdMode) chmodSync(s.tmp, mode & 0o777)
       if (mtimeMs !== undefined) {
         // A Date, not seconds: Bun reads a negative number of seconds as
@@ -837,7 +846,9 @@ class Extractor {
     await Promise.allSettled(this.inflight)
     this.inflight = []
     await Promise.all(this.staged.map((s) => unlink(s.tmp).catch(() => undefined)))
-    for (const s of this.staged) {
+    // Newest first: a later entry's chain can sit inside an earlier one's
+    // (`dist/` then `dist/sub/`), never the reverse.
+    for (const s of this.staged.toReversed()) {
       if (s.created === undefined) continue
       let dir = path.dirname(s.target)
       const top = path.resolve(s.created)

package/src/cache/cache.ts

@@ -42,6 +42,7 @@ import {
   lstatSync,
   mkdirSync,
   openSync,
+  readdirSync,
   renameSync,
   writeFileSync,
 } from 'node:fs'
@@ -373,7 +374,7 @@ function usageOfEntry(entry: { cpuMs?: number; peakRssBytes?: number }): ExecUsa
  * it there", and the ignore file is created exclusively instead of probed
  * first. An existing cache costs three calls; it cost six.
  */
-function openCacheDir(cacheDir: string): string | null {
+function openCacheDir(cacheDir: string, workspaceRoot?: string): string | null {
   const ignore = path.join(cacheDir, '.gitignore')
   try {
     accessSync(cacheDir, constants.W_OK)
@@ -390,7 +391,7 @@ function openCacheDir(cacheDir: string): string | null {
     // A FILE at `cacheDir` passed the `access` above; mkdir names it.
     if (code === 'ENOTDIR') makeCacheDir(cacheDir)
     if (code !== 'ENOENT') return errorText(err)
-    refuseManifestDir(cacheDir)
+    refuseManifestDir(cacheDir, workspaceRoot)
   }
   try {
     writeFileSync(ignore, IGNORE_ALL, { flag: 'wx' })
@@ -456,21 +457,50 @@ const IGNORE_ALL = '*\n'
  * the workspace or a project (`cacheDir: ''`, `'.'`, `'packages/a'`): the
  * `*` ignore file above hid every file in it from git, so its inputs
  * matched nothing and a changed source replayed the old output, and the
- * artifacts landed among the sources (item 997). Asked only when there is
- * no index yet, so an open cache pays nothing for it.
+ * artifacts landed among the sources (item 997). A directory that holds
+ * projects (`'packages'`) or the workspace (`'..'`, `'/'`) does the same
+ * one level up. Asked only when there is no index yet, so an open cache
+ * pays nothing for it.
  */
-function refuseManifestDir(cacheDir: string): void {
-  for (const manifest of ['package.json', 'pnpm-workspace.yaml']) {
-    if (!existsSync(path.join(cacheDir, manifest))) continue
+function refuseManifestDir(cacheDir: string, workspaceRoot: string | undefined): void {
+  const manifestIn = (dir: string): string | undefined =>
+    MANIFESTS.find((m) => existsSync(path.join(dir, m)))
+  const own = manifestIn(cacheDir)
+  if (own !== undefined) {
     throw new UserError(
-      `cache directory ${cacheDir} holds a ${manifest}: it is the workspace's or a project's own ` +
+      `cache directory ${cacheDir} holds a ${own}: it is the workspace's or a project's own ` +
         `directory, and vx would keep its index there under a \`*\` .gitignore that hides every file ` +
-        `in it from git and from the cache keys. Point \`cacheDir\` in vx.workspace.ts (or ` +
-        `--cache-dir) at a directory of its own, such as .vx/cache.`,
+        `in it from git and from the cache keys. ${OWN_DIR_HINT}`,
+    )
+  }
+  let held: string | undefined
+  if (workspaceRoot !== undefined) {
+    const rel = path.relative(cacheDir, workspaceRoot)
+    if (!rel.startsWith('..') && !path.isAbsolute(rel)) held = workspaceRoot
+  }
+  if (held === undefined) {
+    for (const entry of readdirSync(cacheDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const sub = path.join(cacheDir, entry.name)
+      if (manifestIn(sub) !== undefined) {
+        held = sub
+        break
+      }
+    }
+  }
+  if (held !== undefined) {
+    throw new UserError(
+      `cache directory ${cacheDir} holds ${held}, a project or workspace directory, and vx would keep ` +
+        `its index there under a \`*\` .gitignore that hides it from git and from the cache keys. ` +
+        OWN_DIR_HINT,
     )
   }
 }
 
+const MANIFESTS = ['package.json', 'pnpm-workspace.yaml']
+const OWN_DIR_HINT =
+  'Point `cacheDir` in vx.workspace.ts (or --cache-dir) at a directory of its own, such as .vx/cache.'
+
 function makeCacheDir(cacheDir: string): void {
   try {
     mkdirSync(cacheDir, { recursive: true })
@@ -658,7 +688,7 @@ export class Cache implements CacheLayer {
     const dbFile = path.join(cacheDir, 'cache.db')
     this.dbFile = dbFile
     const absent = mode === 'inspect' && !existsSync(dbFile)
-    this.writeBlocked = absent ? 'no index there yet' : openCacheDir(cacheDir)
+    this.writeBlocked = absent ? 'no index there yet' : openCacheDir(cacheDir, repoDir)
     this.write = localPolicy.write && this.writeBlocked === null
     try {
       this.db = new Database(absent ? ':memory:' : dbFile, { create: true })

package/src/cache/git-inputs.ts

@@ -8,11 +8,12 @@
 import path from 'node:path'
 import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
 import {
-  UserError,
   executablePath,
   gitSpawnRefusal,
   isInstalledPath,
   notAWorkTree,
+  relPosix,
+  UserError,
   xxh3hex,
 } from '../util/index.js'
 import { FILE_HASH_RACY_MS, racyWindowMs } from './layer.js'
@@ -70,7 +71,9 @@ export function repoFacts(dir: string): RepoFacts | null {
   // One line per flag, in order. A git that does not know
   // `--show-object-format` echoes it back, as it does any unknown flag,
   // which reads as sha1 — what the flag's own spawn answered there too.
-  const [prefix = '', commonDir = '', format = '', indexFile = ''] = new TextDecoder()
+  const [prefix = '', commonDir = '', format = '', indexFile = ''] = new TextDecoder('utf-8', {
+    ignoreBOM: true,
+  })
     .decode(proc.stdout)
     .split('\n')
     .map((l) => l.trim())
@@ -115,10 +118,10 @@ function repoFactsFromDisk(dir: string): RepoFacts | undefined {
         if (!st.isDirectory() || !existsSync(path.join(dotGit, 'HEAD'))) return undefined
         const objectFormat = configObjectFormat(readFileSync(path.join(dotGit, 'config'), 'utf8'))
         if (objectFormat === undefined) return undefined
-        const below = path.relative(at, real).split(path.sep).join('/')
+        const below = relPosix(at, real)
         return {
           prefix: below === '' ? '' : `${below}/`,
-          commonDir: path.relative(real, dotGit).split(path.sep).join('/'),
+          commonDir: relPosix(real, dotGit),
           objectFormat,
           indexFile: path.relative(real, path.join(dotGit, 'index')).split(path.sep).join('/'),
         }
@@ -270,7 +273,7 @@ export class GitFilesCache extends Map<string, readonly string[]> {
       for (const rel of relPaths) {
         const abs = path.resolve(workspaceRoot, rel)
         if (abs.startsWith(key + path.sep)) {
-          under.push(path.relative(key, abs).split(path.sep).join('/'))
+          under.push(relPosix(key, abs))
         }
       }
       if (under.length > 0) this.recordChanged(key, under)
@@ -427,8 +430,10 @@ function decodeGitZ(bytes: Uint8Array): { text: string; undecodable: Set<string>
   return { text, undecodable }
 }
 
-const LOSSY_UTF8 = new TextDecoder()
-const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true })
+// A default decoder strips a leading U+FEFF: the first path git lists
+// would lose it and name no file.
+const LOSSY_UTF8 = new TextDecoder('utf-8', { ignoreBOM: true })
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
 
 const LS_FILES_STAGE_RE = /^(?:([A-Za-z]) )?([0-7]{6}) ([0-9a-f]{40,64}) ([0-3])\t/
 
@@ -1193,7 +1198,7 @@ export function gitPathspecs(
   projectDirs: readonly string[],
   workspaceWide: boolean,
 ): string[] {
-  const rels = projectDirs.map((d) => path.relative(workspaceRoot, d).split(path.sep).join('/'))
+  const rels = projectDirs.map((d) => relPosix(workspaceRoot, d))
   const scoped =
     !workspaceWide &&
     rels.length > 0 &&
@@ -1555,7 +1560,7 @@ export async function applyGitEnumeration(
     const relPrefix =
       base !== undefined && projectDir.startsWith(base) && path.normalize(projectDir) === projectDir
         ? projectDir.slice(base.length).replace(/\/$/, '')
-        : path.relative(workspaceRoot, projectDir).split(path.sep).join('/')
+        : relPosix(workspaceRoot, projectDir)
     if (relPrefix === '' || relPrefix === '.') {
       cache.set(projectDir, all)
       const rootOids = new Map<string, string>()

package/src/cache/inputs.ts

@@ -28,9 +28,10 @@ import {
   isLiteralPattern,
   normalizeGlob,
   outputMatcher,
+  relPosix,
   shellArgv,
-  splitNegations,
   slashBraceExpansions,
+  splitNegations,
   staticPrefix,
   taskGlob,
   UserError,
@@ -417,7 +418,11 @@ async function runRuntimeCommand(
   owner: RuntimeMemo | undefined,
 ): Promise<string> {
   const ambient = process.env['PATH']
-  const prefix = binDirs.join(path.delimiter)
+  // As the task's PATH does (exec/env.ts): a dir holding the delimiter
+  // splits into an entry relative to the probe's cwd.
+  const PATH = [...binDirs.filter((dir) => !dir.includes(path.delimiter)), ambient]
+    .filter((entry) => entry)
+    .join(path.delimiter)
   let proc
   try {
     // vx's own `sh`, resolved on its PATH before the probe's: Bun.spawn looks
@@ -425,7 +430,7 @@ async function runRuntimeCommand(
     // `node_modules/.bin`, so a dependency's `sh` bin ran every probe (J-69).
     proc = Bun.spawn(shellArgv(command), {
       cwd,
-      env: { ...process.env, PATH: ambient ? `${prefix}${path.delimiter}${ambient}` : prefix },
+      env: { ...process.env, PATH },
       stdin: 'ignore',
       stdout: 'pipe',
       stderr: 'pipe',
@@ -454,22 +459,49 @@ async function runRuntimeCommand(
   let stdout, stderr, exitCode
   try {
     ;[stdout, stderr, exitCode] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
+      new Response(proc.stdout).bytes(),
+      new Response(proc.stderr).bytes(),
       proc.exited,
     ])
   } finally {
     liveProbes.delete(proc)
     mine?.delete(proc)
   }
-  const output = `${stdout}${stderr}`.trim()
   if (exitCode !== 0) {
+    const lossy = new TextDecoder()
+    const shown = `${lossy.decode(stdout)}${lossy.decode(stderr)}`.trim()
     throw new UserError(
       `cache.inputs runtime command exited ${exitCode}: ${command} (cwd: ${cwd})` +
-        (output ? `\n${output}` : ''),
+        (shown ? `\n${shown}` : ''),
+    )
+  }
+  let out: string
+  let err: string
+  try {
+    out = FATAL_UTF8.decode(stdout)
+    err = FATAL_UTF8.decode(stderr)
+  } catch {
+    // A lossy decode keys every invalid byte as U+FFFD: Latin-1 é and è
+    // folded the same output and replayed each other's build.
+    throw new UserError(
+      `cache.inputs runtime command printed bytes that are not UTF-8: ${command} (cwd: ${cwd}). ` +
+        `Pipe it through a hash or od.`,
     )
   }
-  return output
+  return probeOutput(out, err)
+}
+
+/**
+ * The probe's output as the key folds it. Plain concatenation keyed stdout
+ * `ab` and stdout `a` + stderr `b` alike. A probe with no stderr and no NUL
+ * folds its trimmed stdout, as before; any other is framed with a leading
+ * NUL and stdout's length, a form no unframed output takes.
+ */
+function probeOutput(stdout: string, stderr: string): string {
+  const out = stdout.trim()
+  const err = stderr.trim()
+  if (err === '' && !out.includes('\0')) return out
+  return `\0${out.length}\0${out}${err}`
 }
 
 /**
@@ -701,7 +733,7 @@ export async function cleanOutputs(args: {
   )
   // Project-relative posix paths of what was removed — the caller
   // feeds these to GitFilesCache.markOutputsChanged after a restore.
-  return files.map((f) => path.relative(args.projectDir, f).split(path.sep).join('/'))
+  return files.map((f) => relPosix(args.projectDir, f))
 }
 
 /**
@@ -839,7 +871,7 @@ const SYNC_CLEAN_MAX = 128
 async function removeAll(all: readonly string[], root: string): Promise<string[]> {
   const files = notThroughLink(all, root)
   const refused = (f: string, err: NodeJS.ErrnoException): UserError => {
-    const rel = path.relative(root, f).split(path.sep).join('/')
+    const rel = relPosix(root, f)
     return new UserError(
       `cannot remove declared output ${rel}: ${err.code ?? err.message} — vx clears a task's ` +
         `declared outputs before it runs and before a restore; make the path removable ` +
@@ -1002,7 +1034,7 @@ export async function cleanWorkspaceOutputs(args: {
 }): Promise<string[]> {
   const files = await resolveWorkspaceOutputs(args)
   await pruneEmptiedDirs(args.workspaceRoot, await removeAll(files, args.workspaceRoot))
-  return files.map((f) => path.relative(args.workspaceRoot, f).split(path.sep).join('/'))
+  return files.map((f) => relPosix(args.workspaceRoot, f))
 }
 
 function stripTrailingSlash(p: string): string {
@@ -1136,7 +1168,7 @@ function refuseUndecodable(
   if (undecodable === undefined || undecodable.size === 0) return
   const bad = candidates.filter((abs) => undecodable.has(abs) && undecodableOnDisk(abs))
   if (bad.length === 0) return
-  const names = bad.map((abs) => JSON.stringify(path.relative(root, abs).split(path.sep).join('/')))
+  const names = bad.map((abs) => JSON.stringify(relPosix(root, abs)))
   throw new UserError(
     `cache.inputs.${field} matched ${names.join(', ')} in ${root}: the name is not valid UTF-8 ` +
       `(shown with \ufffd), and vx cannot read a file by it. Rename it, or exclude it with a ` +
@@ -1448,7 +1480,7 @@ function undecodableOnDisk(abs: string): boolean {
   } catch {
     return false
   }
-  const lossy = new TextDecoder()
+  const lossy = new TextDecoder('utf-8', { ignoreBOM: true })
   for (const name of raw) {
     if (lossy.decode(name) !== next) continue
     try {
@@ -1589,7 +1621,7 @@ function addedTo(
   return undefined
 }
 
-const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true })
+const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
 
 /**
  * Union of the OUTPUT files matching any positive pattern in `cwd`, minus
@@ -1676,9 +1708,7 @@ function globFor(pattern: string): Bun.Glob {
  */
 function inNestedProject(projectDir: string, nestedDirs: string[]): (rel: string) => boolean {
   if (nestedDirs.length === 0) return () => false
-  const dirs = new Set(
-    nestedDirs.map((d) => path.relative(projectDir, d).split(path.sep).join('/')),
-  )
+  const dirs = new Set(nestedDirs.map((d) => relPosix(projectDir, d)))
   return (rel) => {
     for (let i = rel.indexOf('/'); i !== -1; i = rel.indexOf('/', i + 1)) {
       if (dirs.has(rel.slice(0, i))) return true

package/src/cache/tar-stream.ts

@@ -38,7 +38,9 @@ const BLOCK = 512
  * numbers; a MiB is far past any writer's.
  */
 const MAX_EXTENDED_HEADER = 1024 * 1024
-const decoder = new TextDecoder()
+// `ignoreBOM`: a default decoder drops a leading U+FEFF, and a name or
+// prefix field that began with one read back without it.
+const decoder = new TextDecoder('utf-8', { ignoreBOM: true })
 
 function field(h: Uint8Array, off: number, len: number): string {
   let end = off

package/src/cli/cache.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { Cache } from '../cache/index.js'
-import { flagHint, refusedWord, seeHelp } from './help.js'
+import { flagHint, formatValue, refusedWord, seeHelp } from './help.js'
 import { nearest, parseDuration, parseSize } from '../util/index.js'
 import { acquireRunLock } from '../orchestrator/index.js'
 import { findWorkspaceRoot } from '../workspace/index.js'
@@ -125,10 +125,8 @@ export function parsePruneArgs(args: readonly string[]): PruneArgs {
     } else if (a === '--dry-run') {
       out.dryRun = true
     } else if (a === '--format' || a?.startsWith('--format=')) {
-      const v = a === '--format' ? args[++i] : a.slice('--format='.length)
-      if (v !== 'pretty' && v !== 'json') {
-        return { error: `--format must be pretty or json${seeHelp('cache')}` }
-      }
+      const v = formatValue(a === '--format' ? args[++i] : a.slice('--format='.length), 'cache')
+      if (typeof v === 'object') return v
       out.format = v
     } else {
       const cd = parseCacheDirFlag(args, i)

package/src/cli/foreign-flags.ts

@@ -6,7 +6,7 @@
 // on left a `turbo run --dry-run` user at a dead end. The table renders
 // cli.md's parity section (`renderForeignFlags`), pinned by a test.
 
-export interface ForeignFlag {
+interface ForeignFlag {
   runner: 'turbo' | 'nx'
   /** Every spelling, first the one shown. */
   names: readonly string[]
@@ -19,6 +19,13 @@ export interface ForeignFlag {
   outcome: 'same' | 'alias' | 'refuse'
   /** The vx spelling, or what to use instead. */
   vx: string
+  /**
+   * The runner reads `=true` / `=false` on it (Turbo's `--force [FORCE]`,
+   * Nx's yargs booleans): `=false` is the flag left out, `=true` the flag
+   * bare. `--skip-nx-cache=false` forced every task, `--summarize=true`
+   * wrote the summary to a file named `true`.
+   */
+  bool?: true
   /** For an alias: the vx argv. For a refusal: none. */
   to?: (value: string | undefined) => string[]
 }
@@ -100,6 +107,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--force'],
     value: false,
+    bool: true,
     outcome: 'same',
     vx: '`--force`: skip cache reads, keep writes',
   },
@@ -114,6 +122,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--summarize'],
     value: false,
+    bool: true,
     outcome: 'same',
     vx: '`--summarize[=<path>]`',
   },
@@ -268,6 +277,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--remote-only'],
     value: false,
+    bool: true,
     outcome: 'refuse',
     vx: 'use `--cache local:,remote:rw`',
   },
@@ -275,6 +285,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'turbo',
     names: ['--remote-cache-read-only'],
     value: false,
+    bool: true,
     outcome: 'refuse',
     vx: 'use `--cache local:rw,remote:r`',
   },
@@ -396,8 +407,13 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     names: ['-p', '--projects'],
     value: true,
     outcome: 'alias',
-    vx: '`--filter <pattern>`, one per project',
-    to: (v) => list(v).flatMap((p) => ['--filter', p]),
+    vx: "`--filter <pattern>`, one per project; a list opening with `!` starts from all (`--filter '*'`)",
+    // Nx reads a leading exclusion as "all projects but": `-p '!b,a'` is
+    // every project except b, where vx's filters alone would select a.
+    to: (v) => {
+      const ps = list(v)
+      return [...(ps[0]?.startsWith('!') ? ['*'] : []), ...ps].flatMap((p) => ['--filter', p])
+    },
   },
   {
     runner: 'nx',
@@ -436,6 +452,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--skip-nx-cache'],
     value: false,
+    bool: true,
     outcome: 'alias',
     vx: '`--force`',
     to: () => ['--force'],
@@ -445,6 +462,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--nx-bail'],
     value: false,
+    bool: true,
     outcome: 'alias',
     vx: '`--continue=never`',
     to: () => ['--continue=never'],
@@ -482,6 +500,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--exclude-task-dependencies'],
     value: false,
+    bool: true,
     outcome: 'alias',
     vx: '`--exclude-dependencies`',
     to: () => ['--exclude-dependencies'],
@@ -490,6 +509,7 @@ export const FOREIGN_FLAGS: readonly ForeignFlag[] = [
     runner: 'nx',
     names: ['--skip-remote-cache'],
     value: false,
+    bool: true,
     outcome: 'alias',
     vx: '`--cache local:rw,remote:`',
     to: () => ['--cache', 'local:rw,remote:'],
@@ -605,6 +625,13 @@ export function translateForeign(args: readonly string[]): string[] | { error: s
       name = kebab
       a = inline === undefined ? kebab : `${kebab}=${inline}`
     }
+    if (
+      (inline === 'true' || inline === 'false') &&
+      FOREIGN_FLAGS.some((f) => f.bool && f.names.includes(name))
+    ) {
+      if (inline === 'false') continue
+      a = name
+    }
     const entries = FOREIGN_FLAGS.filter((f) => f.names.includes(name) || f.names.includes(a))
     const next = before[i + 1]
     const spaced = inline === undefined && next !== undefined && !next.startsWith('-')
@@ -627,7 +654,9 @@ export function translateForeign(args: readonly string[]): string[] | { error: s
 /** cli.md's parity table, one row per entry. */
 export function renderForeignFlags(): string {
   const rows = FOREIGN_FLAGS.map((f) => {
-    const flag = f.shown ?? f.names.map((n) => `\`${n}${f.value ? ' <v>' : ''}\``).join(', ')
+    const flag =
+      f.shown ??
+      f.names.map((n) => `\`${n}${f.value ? ' <v>' : f.bool ? '[=<bool>]' : ''}\``).join(', ')
     return `| ${f.runner} | ${flag.replaceAll('|', '\\|')} | ${f.outcome} | ${f.vx.replaceAll('|', '\\|')} |`
   })
   return ['| runner | flag | outcome | in vx |', '| --- | --- | --- | --- |', ...rows].join('\n')

package/src/cli/help.ts

@@ -110,10 +110,10 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '  vx cache prune [--older-than <duration>] [--max-size <size>] [--dry-run] [--format pretty|json] [--cache-dir <path>]',
     '  vx lock [--check]',
     '  vx init [--dry] [--force] [--mjs] [--plugin <seam>]',
-    '  vx upgrade [tag]',
+    '  vx upgrade [TAG]',
     '  vx show [PROJECT[#TASK] | TASK] [--format pretty|json]',
     '  vx info [--format pretty|json] [--cache-dir <path>]',
-    '  vx why (TASK | PKG#TASK) [--run <runId>] [--format pretty|json] [--cache-dir <path>]',
+    '  vx why (TASK | PKG#TASK) [--run RUNID] [--format pretty|json] [--cache-dir <path>]',
     '  vx last [RUNID] [--list[=N]] [--failed] [--format pretty|json] [--cache-dir <path>]',
     '  vx completions bash|zsh|fish',
     '  vx help [VERB]',
@@ -215,16 +215,18 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       lock status.',
     '      --format <fmt>   pretty (default) | json.',
     "  vx why <task>        Why did this task re-run? Compares the task's latest",
-    '                       run (or --run <id>) against its previous run: names the',
+    '                       run (or --run RUNID) against its previous run: names the',
     '                       exact changed cache-key components (files / env / runtime',
     '                       / upstream) from the persisted input fingerprints.',
     '      --format <fmt>   pretty (default) | json.',
-    "  vx last [runId]      Replay a recorded run's summary from the local history —",
+    "  vx last [RUNID]      Replay a recorded run's summary from the local history —",
     '                       header (command, when, branch, counts) plus the per-task',
     '                       table, failures first. No re-execution, no cache probe.',
     '      --list[=N]       List the N most recent runs (default 10) with run ids.',
     '      --failed         Only failed runs: the latest one, or with --list the list.',
     '      --format <fmt>   pretty (default) | json.',
+    '  info, why and last:',
+    '      --cache-dir <path>  Read the cache a run with the same flag uses.',
     '',
     'Migration:',
     '  vx init              Generate vx.workspace.ts + one vx.config.ts per package',
@@ -233,6 +235,7 @@ export function helpText(pluginCommands: readonly string[] = []): string {
     '                       only vx.workspace.ts, declaring turbo() or nx().',
     '      --dry            Print the generated files instead of writing them.',
     '      --force          Overwrite existing vx.config.* files.',
+    '      --mjs            Write .mjs files (no type import) instead of .ts.',
     '      --plugin <seam>  Instead: write plugins/<seam>.ts, a runnable plugin, and its',
     '                       test (executor, cache, telemetry, schedule, admit, commands,',
     '                       project, graph, key).',
@@ -267,6 +270,20 @@ export function seeHelp(verb: string): string {
   return ` (see \`vx ${verb} --help\`)`
 }
 
+/** `--format`'s value, or the one refusal every verb gives for a bad one. */
+export function formatValue(
+  v: string | undefined,
+  verb: string,
+): 'pretty' | 'json' | { error: string } {
+  if (v === 'pretty' || v === 'json') return v
+  return {
+    error:
+      v === undefined || v === ''
+        ? `--format requires a value: pretty or json${seeHelp(verb)}`
+        : `--format must be pretty or json (got ${v})${seeHelp(verb)}`,
+  }
+}
+
 /** How a verb names a word it refuses: a flag, or a positional it takes no more of. */
 export function refusedWord(arg: string): string {
   return arg.startsWith('-') ? 'unknown flag' : 'unexpected argument'
@@ -339,7 +356,7 @@ export const WATCH_REFUSED_FLAGS: readonly string[] = [
  * The flags one verb accepts: those on its own Usage line, and for a verb
  * that takes `[OPTIONS]` (run, watch) the documented run flags — less the
  * ones watch refuses. The Usage line is the verb's synopsis; a section's
- * prose names other verbs' flags (`vx lock --check`, `--run <id>` under
+ * prose names other verbs' flags (`vx lock --check`, `--run RUNID` under
  * `vx why`) and is not read.
  */
 export function acceptedFlags(verb: string): string[] {