@vzn/vx 0.0.645 → 0.0.648

package/src/{graph → util}/dependency-spec.ts

@@ -1,6 +1,8 @@
 // Parser for the Turbo/Nx-style task-edge micro-syntax used in
 // `dependsOn` and `inputs.tasks`. Returns a small discriminated
-// union the graph builder + cache filter both consume.
+// union the graph builder + cache filter both consume. In util, not
+// graph: the schema parses `inputs.tasks` at load (`vx lock`), and the
+// workspace module cannot import the graph.
 
 export type DependencySpec =
   | { kind: 'self'; task: string; negated: boolean }
@@ -9,9 +11,12 @@ export type DependencySpec =
   | { kind: 'wildcardSelf'; negated: boolean }
   | { kind: 'wildcardDeps'; negated: boolean }
 
+/** The field an entry came from, which the error names. */
+type SpecField = 'dependsOn' | 'inputs.tasks'
+
 export class DependencySpecError extends Error {
-  constructor(raw: string, message: string) {
-    super(`invalid dependsOn "${raw}": ${message}`)
+  constructor(field: SpecField, raw: string, message: string) {
+    super(`invalid ${field} "${raw}": ${message}`)
   }
 }
 
@@ -31,49 +36,53 @@ export function compileTaskPattern(pattern: string): RegExp {
   return new RegExp(`^${escaped}$`)
 }
 
+// `*` is the matcher's only metacharacter, so a run of them (`**`) matches
+// every name: the bare wildcard, not a pattern that names a namespace.
+const ALL_STARS = /^\*+$/
+
 /**
  * Parse one `dependsOn` / `inputs.tasks` entry.
  *
  *   `name`       → self.name
  *   `^name`      → every dep workspace's `name` task
  *   `pkg#name`   → specific package's `name` task (cross-edge)
- *   `*`          → all same-project upstream (filter-only)
- *   `^*`         → all dep upstream (filter-only)
+ *   `*`          → all same-project upstream (filter-only; `**` too)
+ *   `^*`         → all dep upstream (filter-only; `^**` too)
  *   `!<form>`    → negation of any of the above (filter-only)
  *
  * Wildcards and negation are accepted everywhere — callers (the graph
  * builder vs the filter) decide which ones make semantic sense and
  * surface their own validation errors. This keeps the parser pure.
  */
-export function parseDependencySpec(raw: string): DependencySpec {
-  if (raw.length === 0) throw new DependencySpecError(raw, 'empty spec')
+export function parseDependencySpec(raw: string, field: SpecField): DependencySpec {
+  if (raw.length === 0) throw new DependencySpecError(field, raw, 'empty spec')
 
   let negated = false
   let s = raw
   if (s.startsWith('!')) {
     negated = true
     s = s.slice(1)
-    if (s.length === 0) throw new DependencySpecError(raw, 'negation with no body')
+    if (s.length === 0) throw new DependencySpecError(field, raw, 'negation with no body')
   }
 
   if (s.startsWith('^')) {
     const rest = s.slice(1)
-    if (rest.length === 0) throw new DependencySpecError(raw, '"^" with no task name')
-    if (rest === '*') return { kind: 'wildcardDeps', negated }
+    if (rest.length === 0) throw new DependencySpecError(field, raw, '"^" with no task name')
+    if (ALL_STARS.test(rest)) return { kind: 'wildcardDeps', negated }
     if (rest.includes('#')) {
-      throw new DependencySpecError(raw, '"^" cannot combine with "pkg#task" — pick one')
+      throw new DependencySpecError(field, raw, '"^" cannot combine with "pkg#task" — pick one')
     }
     return { kind: 'deps', task: rest, negated }
   }
 
-  if (s === '*') return { kind: 'wildcardSelf', negated }
+  if (ALL_STARS.test(s)) return { kind: 'wildcardSelf', negated }
 
   const hashIdx = s.indexOf('#')
   if (hashIdx >= 0) {
     const project = s.slice(0, hashIdx)
     const task = s.slice(hashIdx + 1)
     if (!project || !task) {
-      throw new DependencySpecError(raw, 'pkg#task requires a non-empty project AND task')
+      throw new DependencySpecError(field, raw, 'pkg#task requires a non-empty project AND task')
     }
     return { kind: 'cross', project, task, negated }
   }

package/src/util/edit-distance.ts

@@ -23,7 +23,8 @@ export function editDistance(a: string, b: string, cap = 3): number {
 
 /**
  * The ONE near-miss rule every "did you mean" hint applies: the closest
- * candidate within two edits of `name`, or undefined — an exact match is
+ * candidate within two edits of `name` (for a name of four letters or
+ * fewer, one or a swap of two), or undefined — an exact match is
  * not a hint, and anything further would guess rather than help. Task
  * names, `pkg#task` halves, project names, flags and verbs all go through
  * here so a typo is hinted the same way wherever it is typed.
@@ -33,6 +34,9 @@ export function nearest(
   candidates: Iterable<string>,
   maxEdits = 2,
 ): string | undefined {
+  // Two edits rewrite half of a word of four letters or fewer (`--poll`
+  // read as `--all`, `vx test` as `last`), unless they swap two letters.
+  const short = maxEdits === 2 && name.replace(/^-+/, '').length <= 4
   let best: string | undefined
   let bestD = maxEdits + 1
   for (const c of candidates) {
@@ -40,6 +44,10 @@ export function nearest(
     // `--continue-on-error` was nine edits from `--concurrency`, capped to
     // the three `vx run`'s same-prefix hint allows, and offered.
     const d = editDistance(name, c, maxEdits + 1)
+    // Edits that rewrite the whole of both leave nothing in common:
+    // `--filter=x9` offered the root, `//`.
+    if (d >= Math.max(name.length, c.length)) continue
+    if (short && d === 2 && !sameLetters(name, c)) continue
     if (d < bestD) {
       bestD = d
       best = c
@@ -48,6 +56,10 @@ export function nearest(
   return best === name ? undefined : best
 }
 
+function sameLetters(a: string, b: string): boolean {
+  return a.length === b.length && a.split('').sort().join('') === b.split('').sort().join('')
+}
+
 /**
  * Up to `limit` candidates worth offering for `name`: the nearest by edit
  * distance first, then any that contain it (or that it contains), case-

package/src/util/env-flag.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a flag-like variable (`CI`, `GITHUB_ACTIONS`) is on: set, and not
+ * `''`, `0` or `false` in any case. Several vendors set `CI=true`, and a
+ * PowerShell `$false` writes `False`; each reader of CI asks this one, so a
+ * run cannot be CI to one part of vx and a laptop to another.
+ */
+export function envFlagOn(v: string | undefined): boolean {
+  return v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false'
+}

package/src/util/errors.ts

@@ -57,8 +57,12 @@ export function refusal(
 }
 
 // A refusal that opens with the config that caused it: the schema's
-// `<file>: tasks.<name> …` and the loader's `<file> has unknown field …`.
-const CONFIG_REFUSAL = /^\/\S*\/(?:vx\.config|\.vx\/workspace)\.[cm]?[jt]s\b/
+// `<file>: tasks.<name> …`, the loader's `<file> has unknown field …`, and
+// its `Project config <file>: …` and `Workspace config at <file> …` (a load
+// that failed: a syntax error, a missing import, no default object), which
+// answered VX_E_REFUSED.
+const CONFIG_REFUSAL =
+  /^(?:(?:Project|Workspace) config (?:at )?)?\/\S*\/(?:vx\.config|\.vx\/workspace)\.[cm]?[jt]s\b/
 
 /**
  * The stable code of anything `bin.ts` catches. A UserError's own, but
@@ -106,6 +110,30 @@ export function errorDocument(code: string, message: string): string {
   return `${JSON.stringify({ ok: false, error: { code, message, ...docs } })}\n`
 }
 
+/**
+ * What a thrown value says, for a line that names its thrower. A plugin
+ * may throw anything: `String(err)` read `[object Object]` for an
+ * error-like `{ message }`, `undefined` for a bare `throw`, and itself threw
+ * on an object with no prototype. Never throws.
+ */
+export function thrownMessage(err: unknown): string {
+  try {
+    if (typeof err === 'string') return err === '' ? 'threw an empty string' : err
+    if (typeof err === 'object' && err !== null) {
+      const message = (err as { message?: unknown }).message
+      if (typeof message === 'string' && message !== '') return message
+      if (err instanceof Error) return `threw ${err.name} with no message`
+      const json = JSON.stringify(err)
+      if (json !== undefined) return `threw ${json.length > 200 ? `${json.slice(0, 200)}…` : json}`
+      return 'threw an object'
+    }
+    if (typeof err === 'bigint') return `threw ${err}n`
+    return `threw ${String(err)}`
+  } catch {
+    return 'threw an object'
+  }
+}
+
 /**
  * `instanceof UserError`, plus the same class arriving from ANOTHER COPY of
  * core. A compiled `vx` binary carries core inside it while a plugin in the
@@ -164,9 +192,21 @@ export function isFsRefusal(err: unknown): err is NodeJS.ErrnoException {
 
 export const DISK_FULL_HINT = 'the disk that path is on is full'
 
+/** What follows the path when the refused call only reads. */
+const READ_PERMISSION_HINT = 'a path vx must read is not readable by this user'
+
+/**
+ * Calls that only read. `open` is either, so it keeps the write hint: the
+ * reads vx opens name their own refusal (`hashFileFromDisk`).
+ */
+const READ_SYSCALLS = new Set(['scandir', 'stat', 'lstat', 'readlink', 'read', 'realpath'])
+
 /** The one-line hint after a refusal's path. */
 export function fsRefusalHint(err: NodeJS.ErrnoException): string {
-  return isDiskFull(err) ? DISK_FULL_HINT : PERMISSION_HINT
+  const { syscall } = err
+  if (isDiskFull(err)) return DISK_FULL_HINT
+  // A listing told to be a write sent the user to chmod the wrong thing.
+  return READ_SYSCALLS.has(syscall ?? '') ? READ_PERMISSION_HINT : PERMISSION_HINT
 }
 
 /**
@@ -188,6 +228,7 @@ export function isExecutableMissing(err: unknown): boolean {
 export function gitSpawnRefusal(cwd: string): UserError {
   return new UserError(
     `vx requires git: failed to spawn 'git' (working dir: ${cwd}). Install git and re-run.`,
+    'VX_E_NO_GIT',
   )
 }
 
@@ -200,6 +241,21 @@ export function notAWorkTree(cwd: string, stderr = ''): UserError {
   return new UserError(
     `vx requires git: ${cwd} is not inside a git work tree. ` +
       `Run 'git init' in your workspace root.${stderr ? ` (git: ${stderr})` : ''}`,
+    'VX_E_NO_GIT',
+  )
+}
+
+/**
+ * A git that ran in `cwd` and failed: no repository there is
+ * `notAWorkTree`, anything else (a corrupt index, a missing object) is git's
+ * own failure, `VX_E_GIT`. Every failed `ls-files` read as "not a work
+ * tree", telling a user with a broken index to `git init` (2026-10-28).
+ */
+export function gitFailure(cwd: string, args: string, exitCode: number, stderr: string): UserError {
+  if (/not a git repository/i.test(stderr)) return notAWorkTree(cwd, stderr)
+  return new UserError(
+    `git ${args} failed (exit ${exitCode}) in ${cwd}: ${stderr || 'no output'}. Run it there to see why.`,
+    'VX_E_GIT',
   )
 }
 

package/src/util/essential-env.ts

@@ -1,3 +1,6 @@
+import { existsSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+
 /**
  * Every task gets these (`exec/env.ts`), so `hideEnvFromTasks` leaves
  * them. Exported so the schema doc's enumeration of it can be PINNED against the
@@ -28,4 +31,58 @@ export const ESSENTIAL_ENV: readonly string[] = [
   // manager (offline or sandboxed: fails) and pnpm loses its global dir.
   'COREPACK_HOME',
   'PNPM_HOME',
+  // The XDG base directories, machine paths as HOME is. Stripped, a task
+  // resolved other homes than the shell did: pnpm used another store, and
+  // a CLI keeping its login there ran signed out (vercel/turborepo#13145).
+  'XDG_CONFIG_HOME',
+  'XDG_DATA_HOME',
+  'XDG_CACHE_HOME',
+  'XDG_STATE_HOME',
+  'XDG_RUNTIME_DIR',
 ]
+
+/**
+ * `PATH` less each `node_modules/.bin` inside `workspaceRoot`. `npm run`
+ * in a member puts that member's bins, its parents' and the root's on the
+ * PATH vx inherits; a task that kept them ran a sibling's bin, which no
+ * key sees. A task gets back the two it may see (`taskBinDirs`). Inside
+ * by spelling, or by canonical path: an entry spelled through a symlink
+ * (macOS's `/tmp`, a linked home, a shell's `$PWD`) kept a sibling's bin
+ * beside a canonical root.
+ */
+export function withoutWorkspaceBins(PATH: string, workspaceRoot: string): string {
+  const bin = `${path.sep}node_modules${path.sep}.bin`
+  const within = (dir: string, root: string): boolean =>
+    dir.startsWith(root.endsWith(path.sep) ? root : root + path.sep)
+  let root: string | undefined
+  return PATH.split(path.delimiter)
+    .filter((entry) => {
+      const dir = entry.endsWith(path.sep) ? entry.slice(0, -1) : entry
+      if (!dir.endsWith(bin)) return true
+      if (within(dir, workspaceRoot)) return false
+      // Relative, it is the task's cwd's: not a place this check can name.
+      if (!path.isAbsolute(dir)) return true
+      const real = canonical(dir)
+      if (real === undefined) return true
+      root ??= canonical(workspaceRoot) ?? workspaceRoot
+      return !within(real, root)
+    })
+    .join(path.delimiter)
+}
+
+/**
+ * `p`'s canonical spelling; undefined when it is not there, and a missing
+ * directory on PATH resolves nothing. Asked per call, never memoized: a
+ * task may create the bin directory (an install) or a link above it, and a
+ * fact about a file a task can write is not reused across tasks.
+ */
+function canonical(p: string): string | undefined {
+  // A stat, not a throw: most such entries are npm's ancestors of the
+  // root, and an ENOENT thrown per entry was 3 µs a spawn each.
+  if (!existsSync(p)) return undefined
+  try {
+    return realpathSync.native(p)
+  } catch {
+    return undefined
+  }
+}

package/src/util/git-ignored.ts

@@ -1,4 +1,4 @@
-// Whether git ignores everything an output glob can write (M, 2026-10-15):
+// Whether git ignores everything an output glob can write (2026-10-15):
 // a key reads only what git lists, so such an output never reaches a
 // reader's key. Asked of git, never read from a `.gitignore`: git alone
 // knows every rule source (nested files, `info/exclude`, `core.excludesFile`)

package/src/util/hash.ts

@@ -32,3 +32,38 @@ export function xxh3(input: string | Uint8Array, seed: bigint = 0n): bigint {
 export function xxh3hex(input: string | Uint8Array, seed: bigint = 0n): string {
   return xxh3(input, seed).toString(16).padStart(16, '0')
 }
+/**
+ * `v` with every object's keys sorted, all the way down: `v` itself when
+ * they are already, a copy when not. A key hashes a config's JSON, and the
+ * order a file or a plugin spells its keys in says nothing. Checked first,
+ * a config the lock wrote sorted costs a walk, not a copy.
+ */
+export function keysSorted<T>(v: T): T {
+  return isSorted(v) ? v : (sortedDeep(v) as T)
+}
+
+function isSorted(v: unknown): boolean {
+  if (v === null || typeof v !== 'object') return true
+  if (Array.isArray(v)) return v.every(isSorted)
+  let prev: string | undefined
+  for (const k in v) {
+    if (prev !== undefined && prev > k) return false
+    prev = k
+    if (!isSorted((v as Record<string, unknown>)[k])) return false
+  }
+  return true
+}
+
+function sortedDeep(v: unknown): unknown {
+  if (v === null || typeof v !== 'object') return v
+  if (Array.isArray(v)) return v.map(sortedDeep)
+  const out: Record<string, unknown> = {}
+  for (const k of Object.keys(v).sort()) {
+    const value = sortedDeep((v as Record<string, unknown>)[k])
+    // Assigned, `__proto__` sets the copy's prototype and leaves the JSON.
+    if (k === '__proto__')
+      Object.defineProperty(out, k, { value, enumerable: true, writable: true, configurable: true })
+    else out[k] = value
+  }
+  return out
+}

package/src/util/hide-env.ts

@@ -1,3 +1,5 @@
+import { readFileSync, realpathSync } from 'node:fs'
+import path from 'node:path'
 import { ESSENTIAL_ENV } from './essential-env.js'
 
 const PR_SET_DUMPABLE = 4
@@ -5,8 +7,8 @@ const PR_SET_DUMPABLE = 4
 /**
  * Hide vx's environment from a same-user task. A task gets only declared
  * variables, but vx itself holds the rest. Not a boundary (`exec.sandbox`
- * is): it hides the environment, not files. On every verb (owner,
- * 2026-10-13).
+ * is): it hides the environment, not files. On every verb
+ * (2026-10-13).
  *
  * Linux: make vx non-dumpable, so its `/proc/<pid>/environ` (and ptrace)
  * close to the task. A child is dumpable again after `exec`, so tasks are
@@ -16,13 +18,16 @@ const PR_SET_DUMPABLE = 4
  *
  * macOS: `ps eww` reads the env strings the kernel copied above the
  * stack, and no flag closes that to the same user, so vx zeroes the
- * values there (owner, 2026-10-13: "Do the override then on macOS").
+ * values there (2026-10-13: "Do the override then on macOS").
  * Bun copied the env at startup, so `process.env`, and every task built
  * from it, keeps them.
  */
 export async function hideEnvFromTasks(): Promise<boolean> {
   if (process.platform === 'darwin') return wipeStartupEnv()
-  if (process.platform !== 'linux' || process.env['VX_DEBUG_DUMPABLE']) return false
+  // `debug.dumpable` is a bool (util sits below src/settings.ts, so it reads
+  // it itself, as util/timing.ts does): `0` and `false` hide too.
+  const dumpable = process.env['VX_DEBUG_DUMPABLE']
+  if (process.platform !== 'linux' || dumpable === 'true' || dumpable === '1') return false
   try {
     const { dlopen, FFIType } = await import('bun:ffi')
     const libc = dlopen('libc.so.6', {
@@ -97,11 +102,46 @@ export function gitEnv(): Record<string, string> {
     if (
       name.startsWith('GIT_') ||
       name.startsWith('LC_') ||
-      name === 'XDG_CONFIG_HOME' ||
       name === 'LANGUAGE' ||
       ESSENTIAL_ENV.includes(name)
     )
       env[name] = value
   }
+  if (env['GIT_DIR'] !== undefined && env['GIT_WORK_TREE'] === undefined) {
+    if (rediscovers(env['GIT_DIR'])) delete env['GIT_DIR']
+  }
   return env
 }
+
+const rediscovered = new Map<string, boolean>()
+
+/**
+ * Whether a plain `git` where vx started finds the repository `gitDir`
+ * names anyway. A linked worktree's hook exports its gitdir as GIT_DIR and
+ * no GIT_WORK_TREE, and git then takes ITS cwd as the work tree's top: vx
+ * runs git in the workspace root, a subfolder there, and git read every
+ * file as untracked. Without the variable git finds the top itself. A
+ * GIT_DIR naming any other repository (a bare one, dotfiles) is kept.
+ */
+function rediscovers(gitDir: string): boolean {
+  const cwd = process.cwd()
+  const key = `${cwd}\0${gitDir}`
+  let hit = rediscovered.get(key)
+  if (hit === undefined) {
+    hit = false
+    try {
+      const abs = path.resolve(cwd, gitDir)
+      let dotGit = abs
+      // A linked worktree's admin dir names its checkout's `.git` file.
+      try {
+        dotGit = path.resolve(abs, readFileSync(path.join(abs, 'gitdir'), 'utf8').trim())
+      } catch {}
+      if (path.basename(dotGit) === '.git') {
+        const rel = path.relative(realpathSync(path.dirname(dotGit)), realpathSync(cwd))
+        hit = !rel.startsWith('..') && !path.isAbsolute(rel)
+      }
+    } catch {}
+    rediscovered.set(key, hit)
+  }
+  return hit
+}

package/src/util/index.ts

@@ -19,11 +19,14 @@ export {
   gitSpawnRefusal,
   isExecutableMissing,
   isOutOfFds,
+  gitFailure,
   notAWorkTree,
   OUT_OF_FDS_HINT,
+  thrownMessage,
   wantsJson,
 } from './errors.js'
 export { configErrorFrame, configRefusal } from './config-frame.js'
+export { envFlagOn } from './env-flag.js'
 export {
   detectColors,
   dumbTerminal,
@@ -34,11 +37,11 @@ export {
   WARN,
   type ColorSupport,
 } from './colors.js'
-export { barWidth, gradientRule } from './report.js'
+export { barWidth, gradientRule, ruleWidth } from './report.js'
 import * as ui from './ui.js'
 export { refusalNotice, sayLine, sayNotice } from './refusal-notice.js'
 export { ui }
-export { xxh3, xxh3hex } from './hash.js'
+export { keysSorted, xxh3, xxh3hex } from './hash.js'
 export {
   beginRun,
   mark,
@@ -48,7 +51,7 @@ export {
   stageTimes,
   type StageTime,
 } from './timing.js'
-export { clampInt, formatElapsed, MAX_TIMEOUT_MS, parseDecimalInt } from './num.js'
+export { clampInt, formatElapsed, isMeasure, MAX_TIMEOUT_MS, parseDecimalInt } from './num.js'
 export {
   asTrees,
   BUN_GLOB_WILDCARDS,
@@ -63,6 +66,7 @@ export {
   outputNever,
   restorableOutput,
   printable,
+  hasControl,
   relPosix,
   DOT_VX_GITATTRIBUTES,
   DOT_VX_GITIGNORE,
@@ -72,9 +76,13 @@ export {
   anyTaskGlob,
   isInstalledPath,
   taskGlob,
+  outputDirPrefixes,
   wholeSubtreePrefixes,
   slashBraceExpansions,
   braceAlternatives,
+  braceRange,
+  BRACE_RANGE_LIMIT,
+  writableUnder,
 } from './paths.js'
 export {
   claimExitForSignal,
@@ -101,7 +109,7 @@ export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.
 export { executablePath, shellArgv, taskShell } from './which.js'
 export { procfsIsOwn } from './procfs.js'
 export { hangupIgnored } from './hangup.js'
-export { ESSENTIAL_ENV } from './essential-env.js'
+export { ESSENTIAL_ENV, withoutWorkspaceBins } from './essential-env.js'
 export { gitEnv, helperEnv, hideEnvFromTasks } from './hide-env.js'
 export {
   checkIgnore,
@@ -111,9 +119,11 @@ export {
   wholeIgnored,
 } from './git-ignored.js'
 export { realPath, realpathOf } from './real-path.js'
+export { IGNORE_ALL, ignoreDir, refuseSymlink, writeNoFollow } from './write-file.js'
 export {
+  heldSecrets,
   maskedCommand,
-  maskedEmitter,
+  maskedStreams,
   maskedLine,
   MASKED,
   secretMask,
@@ -130,3 +140,10 @@ export {
   type SecretUnavailableReason,
 } from './secrets.js'
 export { terminalOf, type SecretTerminal } from './hidden-prompt.js'
+export {
+  DependencySpecError,
+  compileTaskPattern,
+  isTaskPattern,
+  parseDependencySpec,
+  type DependencySpec,
+} from './dependency-spec.js'

package/src/util/num.ts

@@ -21,6 +21,14 @@ export function clampInt(n: number, min: number, max: number): number {
   return Math.min(max, Math.max(min, Math.floor(n)))
 }
 
+/**
+ * A timing or need SQLite may keep: finite and not below zero. Infinity
+ * stored as REAL reads back through `group_concat` as `Inf`, a NaN forecast.
+ */
+export function isMeasure(v: number): boolean {
+  return Number.isFinite(v) && v >= 0
+}
+
 /**
  * Parse a PLAIN decimal integer from user input; `null` for anything else.
  *