@vzn/vx 0.0.18 → 0.0.21

package/src/util/settle.ts

@@ -27,6 +27,25 @@ export function teardownTimeoutMs(): number {
   return DEFAULT_TIMEOUT_MS
 }
 
+/**
+ * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM: the
+ * one-shot timeout escalation (`exec/runner.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.
+ */
+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
+}
+
 /**
  * Await `p`, giving up after `ms`. Returns true when `p` settled first,
  * false when the deadline won — the caller decides whether a lost result

package/src/util/verbs.ts

@@ -0,0 +1,39 @@
+/**
+ * The verbs the CLI dispatcher (`cli/index.ts`) owns; `stats` is a
+ * deprecated alias of `info` and stays out of hints but is still matched
+ * first. Lives in util rather than cli because the workspace VALIDATOR
+ * refuses a plugin verb that names one of these — a verb core matches
+ * first could never run — and the workspace module cannot import cli.
+ */
+export const CORE_VERBS = [
+  'run',
+  'watch',
+  'cache',
+  'lock',
+  'init',
+  'upgrade',
+  'show',
+  'info',
+  'why',
+  'last',
+  'completions',
+  'help',
+  'version',
+] as const
+
+/** Every word the dispatcher matches before consulting plugins. */
+export const DISPATCHED_VERBS: readonly string[] = [...CORE_VERBS, 'stats']
+
+/**
+ * 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 was removed (2026-09-11): the Docker-subset verb is not shipped; copy the ' +
+    'workspace and `--filter` the build instead',
+}

package/src/workspace/affected.ts

@@ -1,13 +1,10 @@
 // `--affected` — git-relative project selection.
 //
 // Resolves the set of project names whose files have changed since a
-// given git ref. The diff is `<since>...HEAD` plus working-tree
-// changes (uncommitted edits), so it captures everything you've
-// touched on the current branch.
-//
-// We use `git diff --name-only <since>` which by default compares the
-// `<since>` commit to the working tree — i.e. commits-from-`<since>`
-// + index + unstaged. Matches Turbo's `[<since>]` filter semantics.
+// given git ref: `git diff --name-only <merge-base(since, HEAD)>`, which
+// compares that commit to the working tree — commits on this branch +
+// index + unstaged — so it captures everything you touched and nothing
+// the base branch moved on with. Matches Turbo's `[<since>]` semantics.
 
 import path from 'node:path'
 import { UserError } from '../util/index.js'
@@ -37,6 +34,23 @@ export interface AffectedArgs {
    * — never invokes it and pays nothing.
    */
   workspaceGlobOwners?: (orphanPaths: readonly string[]) => Promise<Iterable<string>>
+  /**
+   * The fingerprint files a plugin claims (`VxPlugin.fingerprint`) and its
+   * answer for a change to one. Resolved lazily: loading the workspace
+   * file costs an evaluation, and a diff that touches no fingerprint file
+   * — the common one — never needs it.
+   */
+  fingerprintClaims?: () => Promise<FingerprintClaims>
+}
+
+export interface FingerprintClaims {
+  readonly files: ReadonlySet<string>
+  /** Project names a change to a claimed file affects; `undefined` = all. */
+  affected(change: {
+    file: string
+    before: Uint8Array | null
+    after: Uint8Array | null
+  }): Promise<ReadonlySet<string> | undefined>
 }
 
 /**
@@ -45,7 +59,26 @@ export interface AffectedArgs {
  * or `<since>` doesn't resolve to a commit.
  */
 export async function affectedProjects(args: AffectedArgs): Promise<Set<string>> {
+  // The base reaches git as an argument, never through a shell, so `$(…)`
+  // is opaque — but an option-like value is not: `--output=<path>` is a
+  // real `git diff` option and an arbitrary file write. This is a security
+  // boundary, so it is a check that knows it is one, before any spawn, and
+  // every git call below also ends its options (`--end-of-options`) so a
+  // second caller cannot lose the guard by accident.
+  if (args.since.length === 0 || args.since.startsWith('-')) {
+    throw new UserError(
+      `git ref "${args.since}" is not a ref: a base cannot be empty or start with "-".`,
+    )
+  }
   await verifyRef(args.workspaceRoot, args.since)
+  // Diff from the MERGE BASE of `since` and HEAD, not from `since` itself:
+  // on a branch whose base has moved on, `git diff <base>` reports every
+  // file OTHER people changed on the base (over-selection that defeats a
+  // CI `--affected`), and hides your own edit when the base later landed
+  // byte-identical content. Turbo and Nx both diff from the merge base;
+  // when there is none (unrelated histories, a detached probe) the ref
+  // itself is the base, as before.
+  const base = await mergeBase(args.workspaceRoot, args.since)
 
   const [diffed, untracked] = await Promise.all([
     // `--no-renames` is crucial for project-affected detection: with
@@ -73,7 +106,8 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
       '--relative',
       '--name-only',
       '-z',
-      args.since,
+      '--end-of-options',
+      base,
     ]),
     // `git diff` never reports untracked-but-not-ignored files, but input
     // enumeration does (`git ls-files --cached --others --exclude-standard`),
@@ -96,11 +130,31 @@ export async function affectedProjects(args: AffectedArgs): Promise<Set<string>>
   // principle: "input hashing sees it, so `--affected` must too."
   //
   // Selection is not hashed, so widening it here changes no cache key.
-  if (changed.some((p) => FINGERPRINT_SET.has(p))) {
-    return new Set(args.projects.map((p) => p.name))
+  //
+  // A file a plugin CLAIMS is the exception: the key folds what the plugin
+  // says per project, so selection asks the plugin the same question, with
+  // the bytes at the base ref and in the working tree. Its answer is
+  // unioned with the path-owned projects below; only "cannot tell" widens.
+  const fingerprintChanged = changed.filter((p) => FINGERPRINT_SET.has(p))
+  const claimedOwned = new Set<string>()
+  if (fingerprintChanged.length > 0) {
+    const claims = args.fingerprintClaims === undefined ? undefined : await args.fingerprintClaims()
+    for (const file of fingerprintChanged) {
+      if (claims === undefined || !claims.files.has(file)) {
+        return new Set(args.projects.map((p) => p.name))
+      }
+      const answer = await claims.affected({
+        file,
+        before: await gitBytesAt(args.workspaceRoot, base, file),
+        after: await bytesOrNull(path.join(args.workspaceRoot, file)),
+      })
+      if (answer === undefined) return new Set(args.projects.map((p) => p.name))
+      for (const name of answer) claimedOwned.add(name)
+    }
   }
 
   const { owned, orphans } = projectsContaining(args.workspaceRoot, changed, args.projects)
+  for (const name of claimedOwned) owned.add(name)
 
   // THIRD CHANNEL: a project whose `vx.config.*` IMPORTS a changed file.
   // Resolved-config hashing folds those values into the key, so the same
@@ -149,6 +203,39 @@ export function workspaceGlobsMatch(globs: readonly string[], rel: string): bool
  */
 const FINGERPRINT_SET: ReadonlySet<string> = new Set(WORKSPACE_FINGERPRINT_FILES)
 
+/**
+ * A root file's bytes at `ref`, or null when the ref has no such file.
+ * `./` anchors the path to the cwd (the workspace root) rather than the
+ * repository root, for a workspace that is a subdirectory of its repo.
+ */
+async function gitBytesAt(
+  workspaceRoot: string,
+  ref: string,
+  file: string,
+): Promise<Uint8Array | null> {
+  const proc = Bun.spawn({
+    cmd: ['git', 'show', '--end-of-options', `${ref}:./${file}`],
+    cwd: workspaceRoot,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [bytes, stderr, exit] = await Promise.all([
+    new Response(proc.stdout).bytes(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  if (exit === 0) return bytes
+  // "exists on disk but not in <ref>" and "path does not exist in <ref>"
+  // are the file being absent at the ref; anything else is git failing.
+  if (/does not exist in|exists on disk, but not in/.test(stderr)) return null
+  throw new UserError(`git show ${ref}:./${file} failed (exit ${exit}): ${stderr.trim()}`)
+}
+
+async function bytesOrNull(file: string): Promise<Uint8Array | null> {
+  const f = Bun.file(file)
+  return (await f.exists()) ? await f.bytes() : null
+}
+
 /** Run a NUL-separated path-listing git command from the workspace root. */
 async function gitPaths(workspaceRoot: string, cmd: string[]): Promise<string[]> {
   const proc = Bun.spawn({
@@ -184,9 +271,22 @@ export async function defaultAffectedBase(workspaceRoot: string): Promise<string
   return 'HEAD~1'
 }
 
+/** `git merge-base <ref> HEAD`, or `ref` itself when the two share no ancestor. */
+async function mergeBase(workspaceRoot: string, ref: string): Promise<string> {
+  const proc = Bun.spawn({
+    cmd: ['git', 'merge-base', '--end-of-options', ref, 'HEAD'],
+    cwd: workspaceRoot,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [out, exit] = await Promise.all([new Response(proc.stdout).text(), proc.exited])
+  const sha = out.trim()
+  return exit === 0 && sha.length > 0 ? sha : ref
+}
+
 async function verifyRef(workspaceRoot: string, ref: string): Promise<void> {
   const proc = Bun.spawnSync({
-    cmd: ['git', 'rev-parse', '--verify', '--quiet', ref],
+    cmd: ['git', 'rev-parse', '--verify', '--quiet', '--end-of-options', ref],
     cwd: workspaceRoot,
     stdout: 'pipe',
     stderr: 'pipe',

package/src/workspace/config-cache.ts

@@ -52,6 +52,12 @@ export interface ConfigEvalStore {
    * shadow, is never indexed.
    */
   hashFile?(file: string): Promise<string>
+  /**
+   * `hashFile` over many paths with one memo query; a path that cannot be
+   * stat'ed is absent. The warm load identifies every indexed closure's
+   * files through this in a single call when the store offers it.
+   */
+  hashFiles?(files: readonly string[]): Promise<Map<string, string>>
   getConfigClosures?(configPaths: readonly string[]): Map<string, string[]>
   putConfigClosure?(configPath: string, files: readonly string[]): void
   getConfigEval(key: string): string | null
@@ -95,9 +101,12 @@ const MAX_CLOSURE_FILES = 32
 // `global` and `self` are live objects in Bun (aliases of `globalThis`), so
 // a computed `global['proc' + 'ess']` reaches process without ever
 // spelling it; `Temporal` is a clock. All three were CACHED AS PURE before
-// they were listed (2026-09-03).
+// they were listed (2026-09-03). `constructor` reaches `Function` through a
+// property name (`({}).constructor.constructor('return process')()`, the
+// body hidden in a literal the strip removes) and `localeCompare` answers
+// by the host locale; both listed 2026-09-09.
 const IMPURE_RE =
-  /\b(?:process|Bun|globalThis|global|self|fetch|Date|Temporal|Intl|crypto|performance|navigator|require|eval|Function|await|toLocale\w*)\b|import\s*\.\s*meta|Math\s*\.\s*random|\bimport\s*\(/
+  /\b(?:process|Bun|globalThis|global|self|fetch|Date|Temporal|Intl|crypto|performance|navigator|require|eval|Function|constructor|localeCompare|await|toLocale\w*)\b|import\s*\.\s*meta|Math\s*\.\s*random|\bimport\s*\(/
 
 // Static `import … from '…'` / `export … from '…'` / `import '…'` forms.
 // `[^;'"]*?` spans newlines, so multi-line specifier lists match.

package/src/workspace/config-eval.ts

@@ -52,6 +52,10 @@ self.onmessage = async (e) => {
       name: err?.name ?? 'Error',
       message: err?.message ?? String(err),
       stack: err?.stack ?? null,
+      position:
+        err?.position && typeof err.position === 'object'
+          ? { file: err.position.file, line: err.position.line, column: err.position.column }
+          : null,
     })
   }
 }
@@ -66,6 +70,8 @@ interface WorkerReply {
   name: string
   message: string
   stack: string | null
+  /** A transpile error's location — `BuildMessage.position`, trimmed to what the loader reads. */
+  position: { file?: string; line?: number; column?: number } | null
 }
 
 interface Pending {
@@ -136,12 +142,13 @@ function acquireWorker(): Worker {
       p.resolve(msg.json)
       return
     }
-    // Rebuild the error the config actually threw. Name, message and
-    // stack all survive the hop, so a broken config reports the same
-    // text it would from an in-process import.
-    const err = new Error(msg.message)
+    // Rebuild the error the config actually threw. Name, message, stack
+    // and a transpile error's position all survive the hop, so a broken
+    // config reports the same text it would from an in-process import.
+    const err = new Error(msg.message) as Error & { position?: WorkerReply['position'] }
     err.name = msg.name
     if (msg.stack !== null) err.stack = msg.stack
+    if (msg.position !== null) err.position = msg.position
     p.reject(err)
   }
   w.onerror = (event: ErrorEvent): void => {

package/src/workspace/config-imports.ts

@@ -19,10 +19,11 @@
 //   - RELATIVE specifiers only. A bare specifier is a package; it moves when
 //     the lockfile moves, which the workspace fingerprint already covers.
 //   - Descend only through files owned by NO project. A config reaching into
-//     another project (this repo's `apps/docs/vx.config.ts` imports
-//     `../../src/index.ts`) records that edge and STOPS there — following it
-//     would drag substantially all of core `src/` into the closure, and the
-//     containment channel already selects the project that owns it.
+//     another project (say a site's `vx.config.ts` importing
+//     `../core/src/index.ts`) records that edge and STOPS there — following
+//     it would drag substantially all of that project's `src/` into the
+//     closure, and the containment channel already selects the project that
+//     owns it.
 
 import { realpath } from 'node:fs/promises'
 import path from 'node:path'