@vzn/vx 0.0.636 → 0.0.637

package/src/util/hide-env.ts

@@ -0,0 +1,107 @@
+import { ESSENTIAL_ENV } from './essential-env.js'
+
+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).
+ *
+ * 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
+ * unaffected. Loading `bun:ffi` costs ~0.8 ms. `VX_DEBUG_DUMPABLE` keeps vx
+ * observable: strace cannot read a non-dumpable tracee's memory, nor a
+ * debugger `/proc/<pid>/fd`.
+ *
+ * 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").
+ * 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
+  try {
+    const { dlopen, FFIType } = await import('bun:ffi')
+    const libc = dlopen('libc.so.6', {
+      prctl: {
+        args: [FFIType.i32, FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u64],
+        returns: FFIType.i32,
+      },
+    })
+    const ok = libc.symbols.prctl(PR_SET_DUMPABLE, 0n, 0n, 0n, 0n) === 0
+    libc.close()
+    return ok
+  } catch {
+    // No glibc (musl names it otherwise): the env stays as readable as
+    // any process's, as it was.
+    return false
+  }
+}
+
+/**
+ * Zero the value of every startup variable a task does not see by
+ * default (`ESSENTIAL_ENV` stays: every task gets it anyway). The
+ * original `envp` array follows `argv`'s NULL on the stack and is never
+ * moved, unlike `environ`, which `setenv` may reallocate. libc's
+ * `getenv` reads that block, so it answers `''` for a wiped name; vx
+ * reads `process.env`.
+ */
+async function wipeStartupEnv(): Promise<boolean> {
+  try {
+    const { dlopen, FFIType, read, toArrayBuffer, CString } = await import('bun:ffi')
+    const sys = dlopen('/usr/lib/libSystem.B.dylib', {
+      _NSGetArgv: { args: [], returns: FFIType.ptr },
+      _NSGetArgc: { args: [], returns: FFIType.ptr },
+    })
+    const argv = read.ptr(sys.symbols._NSGetArgv()!, 0)
+    const argc = read.i32(sys.symbols._NSGetArgc()!, 0)
+    sys.close()
+    const keep = new Set(ESSENTIAL_ENV)
+    for (let i = argc + 1; ; i++) {
+      const p = read.ptr(argv, i * 8)
+      if (!p) break
+      const entry = new CString(p as never).toString()
+      const eq = entry.indexOf('=')
+      if (eq < 0 || keep.has(entry.slice(0, eq))) continue
+      new Uint8Array(toArrayBuffer(p as never, 0, Buffer.byteLength(entry))).fill(0, eq + 1)
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The env for a helper vx keeps running beside its tasks (the group
+ * guard, a port bridge): PATH alone. Without an `env`, a spawn hands the
+ * child vx's startup env, and that child, dumpable after its `exec`,
+ * would show a task what `hideEnvFromTasks` hid.
+ */
+export function helperEnv(): Record<string, string> {
+  return { PATH: process.env['PATH'] ?? '' }
+}
+
+/**
+ * The env for a `git` vx runs: what git reads (`GIT_*`, the locale,
+ * `XDG_CONFIG_HOME`, the essentials: `HOME`, `PATH`) and nothing else.
+ * A git child is readable after its `exec` like any helper, and `vx
+ * watch` runs git while its tasks run.
+ */
+export function gitEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [name, value] of Object.entries(process.env)) {
+    if (value === undefined) continue
+    if (
+      name.startsWith('GIT_') ||
+      name.startsWith('LC_') ||
+      name === 'XDG_CONFIG_HOME' ||
+      name === 'LANGUAGE' ||
+      ESSENTIAL_ENV.includes(name)
+    )
+      env[name] = value
+  }
+  return env
+}

package/src/util/index.ts

@@ -45,6 +45,8 @@ export {
   outputMatcher,
   printable,
   relPosix,
+  DOT_VX_GITATTRIBUTES,
+  DOT_VX_GITIGNORE,
   splitNegations,
   staticPrefix,
   stripTrailingSlash,
@@ -58,10 +60,12 @@ export {
   claimExitForSignal,
   exitClaimedBySignal,
   killGraceMs,
+  setSettleBounds,
+  type SettleBound,
   settleWithin,
   teardownTimeoutMs,
 } from './settle.js'
-export { formatBytes, parseDuration, parseSize } from './size.js'
+export { formatBytes, parseDuration, parseSize, treeBytes } from './size.js'
 export {
   cgroupCpuQuota,
   cgroupMemoryLimitBytes,
@@ -73,11 +77,13 @@ export { appendTail, createTail, resetTail, tailText, type Tail } from './tail.j
 export { ulid } from './ulid.js'
 export { splitTaskId } from './task-id.js'
 export { editDistance, listed, nearMatches, nearest } from './edit-distance.js'
-export { CORE_VERBS, MOVED_VERBS } from './verbs.js'
+export { CORE_VERBS } from './verbs.js'
 export { isUnsupportedBun, MIN_BUN, unsupportedBunMessage } from './bun-version.js'
 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 { gitEnv, helperEnv, hideEnvFromTasks } from './hide-env.js'
 export { realPath, realpathOf } from './real-path.js'
 export {
   maskedCommand,

package/src/util/paths.ts

@@ -11,6 +11,16 @@ export function toPosix(p: string): string {
   return IS_POSIX ? p : p.split(path.sep).join('/')
 }
 
+/**
+ * `.vx/.gitignore`: git ignores the machine-local `.vx/cache` and nothing
+ * else in `.vx`, so the workspace config and the lock beside it are
+ * committed. `vx init` and the cache write it when missing.
+ */
+export const DOT_VX_GITIGNORE = '/cache\n'
+
+/** `.vx/.gitattributes`' text: GitHub collapses the machine lock in a diff. */
+export const DOT_VX_GITATTRIBUTES = 'projects.lock.json linguist-generated=true\n'
+
 export function relPosix(from: string, to: string): string {
   return toPosix(path.relative(from, to))
 }

package/src/util/settle.ts

@@ -2,49 +2,68 @@
 // wrote; it must not hold the run's exit hostage.
 
 import { MAX_TIMEOUT_MS } from './num.js'
+import { parseDuration } from './size.js'
 
 /** Default upper bound on one end-of-run flush/teardown await. */
 const DEFAULT_TIMEOUT_MS = 3000
 
+/** A bound the run resolved from its flag or `.vx/workspace`. */
+export interface SettleBound {
+  readonly ms: number
+  readonly from: 'flag' | 'workspace'
+}
+
+let teardownSet: SettleBound | undefined
+let killGraceSet: SettleBound | undefined
+
 /**
- * The bound to apply, read per call so a test can drive the deadline
- * instead of waiting it out.
+ * The run's `run.teardownTimeout` and `run.killGrace` from its flag or
+ * workspace (the orchestrator resolves them; util sits below settings).
+ * The variable, read per call, sits between the two, so a test drives the
+ * deadline instead of waiting it out.
  */
-export function teardownTimeoutMs(): number {
-  const raw = process.env['VX_TEARDOWN_TIMEOUT_MS']
-  // Out-of-range falls back to the DEFAULT rather than clamping to
-  // MAX_TIMEOUT_MS, and the distinction matters. This value is a BOUND, not a
-  // duration: there is no "no limit" option here, because the whole reason the
-  // deadline exists is that a plugin's flush must not hold the run's exit
-  // hostage. Clamping would honour "wait ~24.8 days", which defeats it — the
-  // run would hang. Unbounded is worse still (the delay becomes 1 ms, so every
-  // flush times out and every buffered record is dropped). Falling back keeps
-  // the bound real in both directions.
-  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
-    const n = Number(raw)
-    if (n <= MAX_TIMEOUT_MS) return n
+export function setSettleBounds(b: { teardown?: SettleBound; killGrace?: SettleBound }): void {
+  teardownSet = b.teardown
+  killGraceSet = b.killGrace
+}
+
+/**
+ * A flag's bound, else the variable's (a positive duration inside the
+ * timer's range: the CLI refuses any other before a run, and an embedder's
+ * falls back), else the workspace's.
+ */
+function bound(name: string, set: SettleBound | undefined, zero = false): number | undefined {
+  if (set?.from === 'flag') return set.ms
+  const raw = process.env[name]
+  if (raw !== undefined && raw !== '') {
+    const n = parseDuration(raw)
+    if (n !== null && (n > 0 || zero) && n <= MAX_TIMEOUT_MS) return n
   }
-  return DEFAULT_TIMEOUT_MS
+  return set?.ms
 }
 
 /**
- * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM: the
- * one-shot timeout escalation (`exec/runner.ts`), the signal teardown
- * (`orchestrator/signals.ts`) and the end-of-run persistent shutdown
- * (`orchestrator/persistent.ts`) share it. Two seconds
+ * The bound on one end-of-run flush or teardown (`run.teardownTimeout`).
+ * There is no "no limit": the deadline exists so a plugin's flush cannot
+ * hold the run's exit hostage, so a timer past the platform's range (which
+ * would fire at once and drop every buffered record) is no value.
+ */
+export function teardownTimeoutMs(): number {
+  return bound('VX_RUN_TEARDOWN_TIMEOUT', teardownSet, true) ?? DEFAULT_TIMEOUT_MS
+}
+
+/**
+ * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM
+ * (`run.killGrace`): the one-shot timeout escalation (`exec/runner.ts`),
+ * the signal teardown (`orchestrator/signals.ts`) and the end-of-run
+ * persistent shutdown (`orchestrator/persistent.ts`) share it. Two seconds
  * is generous for a real server's cleanup and is what every run waits when
- * a child wedges. `VX_KILL_GRACE_MS` overrides it, read per call and bounded
- * like the teardown deadline (out of range falls back to the default): the
- * tests that prove the escalation used to wait the full two seconds each,
- * a third of the suite's wall time for a claim a 200 ms grace proves too.
+ * a child wedges; the tests that prove the escalation used to wait the
+ * full two seconds each, a third of the suite's wall time for a claim a
+ * 200 ms grace proves too.
  */
 export function killGraceMs(defaultMs: number): number {
-  const raw = process.env['VX_KILL_GRACE_MS']
-  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
-    const n = Number(raw)
-    if (n > 0 && n <= MAX_TIMEOUT_MS) return n
-  }
-  return defaultMs
+  return bound('VX_RUN_KILL_GRACE', killGraceSet) ?? defaultMs
 }
 
 /**

package/src/util/size.ts

@@ -1,3 +1,5 @@
+import { lstatSync, readdirSync } from 'node:fs'
+import path from 'node:path'
 import { parseDecimalInt } from './num.js'
 
 /**
@@ -20,25 +22,34 @@ export function parseSize(input: string): number | null {
 }
 
 /**
- * Parse `<n><unit>` where unit is s/m/h/d, case-insensitively (`parseSize`
+ * Parse `<n><unit>` where unit is ms/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)
+  const m = input.match(/^(\d+)(ms|[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
+  const mult =
+    unit === 'ms'
+      ? 1
+      : unit === 's'
+        ? 1000
+        : unit === 'm'
+          ? 60_000
+          : unit === 'h'
+            ? 3_600_000
+            : 86_400_000
   return n * mult
 }
 
 /**
  * Human-readable byte size with KB/MB/GB/TB/PB suffixes and one
- * decimal of precision below 10 of any unit. Used by `vx info`, `vx cache prune` and the
+ * decimal of precision below 10 of any unit. Used by `vx info`, `vx cache clean` and the
  * run's `cacheRetention` line.
  */
 export function formatBytes(n: number): string {
@@ -51,3 +62,11 @@ export function formatBytes(n: number): string {
   }
   return `${v.toFixed(0)} PB`
 }
+
+/** Bytes under `p` on disk, links not followed; 0 when it is missing. */
+export function treeBytes(p: string): number {
+  const st = lstatSync(p, { throwIfNoEntry: false })
+  if (st === undefined) return 0
+  if (!st.isDirectory()) return st.size
+  return readdirSync(p).reduce((n, e) => n + treeBytes(path.join(p, e)), 0)
+}

package/src/util/timing.ts

@@ -1,4 +1,5 @@
-// Stage timing for the run path, printed to stderr when `VX_TIMING` is set.
+// Stage timing for the run path, printed to stderr when `VX_DEBUG_TIMING` is
+// true (`debug.timing`; util reads it itself, below src/settings.ts).
 //
 // The CPU profiler attributes a tight loop's cost unreliably and hides
 // where an `await` waited; a stage table answers "where did the warm run
@@ -8,7 +9,7 @@
 // prints (a push per stage, ~15 a run): a telemetry sink draws them as
 // spans (`stageTimes`). The per-call `span`s stay off unless enabled.
 
-const enabled = process.env.VX_TIMING !== undefined && process.env.VX_TIMING !== ''
+const enabled = process.env.VX_DEBUG_TIMING === 'true' || process.env.VX_DEBUG_TIMING === '1'
 let t0 = Bun.nanoseconds()
 // The wall clock at t0, read then: `performance.timeOrigin` plus the
 // monotonic clock drifted 34 ms from `Date.now()` on macOS CI, so stages

package/src/util/ulid.ts

@@ -1,6 +1,6 @@
 // Run-id generator. Thin wrapper over `Bun.randomUUIDv7()` so the
 // `runId` column on `runs` carries a timestamp-ordered identifier —
-// `vx stats --since` queries can range-scan without an index on the
+// time-range queries can range-scan without an index on the
 // time column, and the IDs lexicographically sort by creation time
 // for grouping.
 //

package/src/util/verbs.ts

@@ -19,18 +19,3 @@ export const CORE_VERBS = [
   'help',
   'version',
 ] as const
-
-/**
- * Verbs core owned once and a package owns now. Not core verbs: a plugin
- * may declare them, and the dispatcher prints the
- * pointer only when no declared plugin claimed the name.
- */
-export const MOVED_VERBS: Readonly<Record<string, string>> = {
-  migrate:
-    'vx migrate moved to @vzn/vx-migrate: run `bunx @vzn/vx-migrate` (turbo.json or an Nx ' +
-    'project graph → vx.config.ts); `vx init` reads package.json scripts',
-  prune:
-    'vx prune comes from @vzn/vx-lockfile: declare pnpm(), bun(), npm() or yarn() in ' +
-    'vx.workspace.ts',
-  stats: 'vx stats was removed (H-19): run `vx info`, which prints the same report',
-}