@vzn/vx 0.0.18 → 0.0.21

package/src/workspace/project-loader.ts

@@ -1,10 +1,16 @@
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
-import { MAX_TIMEOUT_MS, UserError, xxh3hex } from '../util/index.js'
+import { UserError, xxh3hex } from '../util/index.js'
+import { validateProjectConfig, validateWorkspace } from './config-schema.js'
 import { evaluateConfigFresh } from './config-eval.js'
 import { configEvalKey, configEvalKeyFromClosure, type ConfigEvalStore } from './config-cache.js'
 
-const WORKSPACE_CONFIG_FILENAMES = [
+// The validator lives in config-schema.ts; re-exported so a reader that
+// reaches the loader for it (the tests do) keeps working.
+export { validateProjectConfig }
+
+/** The workspace config's filenames at the root, in lookup order. `vx watch` re-runs on an edit to whichever exists. */
+export const WORKSPACE_CONFIG_FILENAMES = [
   'vx.workspace.ts',
   'vx.workspace.mts',
   'vx.workspace.js',
@@ -44,7 +50,7 @@ async function loadDefaultExport(
   try {
     ns = (await import(`${configPath}?vx-bust=${bust}`)) as { default?: unknown }
   } catch (err) {
-    throw unresolvedImportError(err, configPath, kind) ?? err
+    throw configLoadError(err, configPath, kind) ?? err
   }
   const mod = ns?.default
   assertDefaultObject(mod, kind, configPath)
@@ -52,24 +58,55 @@ async function loadDefaultExport(
 }
 
 /**
- * A config whose import cannot be resolved is the user's to fix, and the
- * usual cause has one answer: the workspace runs the vx binary and never
- * installed `@vzn/vx`, which its own `vx.workspace.ts` imports. Bun's
- * resolver error also carries the module-cache bust query; the user
- * gets the file they wrote.
+ * Where a transpile error was found. Bun's `BuildMessage` carries it as
+ * `position`; the config worker forwards the same three fields (see
+ * config-eval.ts) so the repeat path names the line too.
  */
-export function unresolvedImportError(
-  err: unknown,
-  configPath: string,
-  kind: string,
-): UserError | null {
-  if (!(err instanceof Error) || err.name !== 'ResolveMessage') return null
-  const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(err.message)?.[1]
-  const what =
-    spec === undefined ? err.message.replace(/\?vx-bust=\S+/g, '') : `cannot find '${spec}'`
-  const hint =
-    spec?.startsWith('@vzn/vx') === true ? `; install it in the workspace: bun add -d @vzn/vx` : ''
-  return new UserError(`${kind} config ${configPath}: ${what}${hint}`)
+interface BuildPosition {
+  file?: string
+  line?: number
+  column?: number
+}
+
+/**
+ * Turn the two errors Bun's own loader throws into user errors naming the
+ * file the user wrote; every other throw is the config's own and already
+ * carries its location in its stack, so it passes through unchanged.
+ *
+ * `ResolveMessage` — an import that cannot be resolved. The usual cause has
+ * one answer: the workspace runs the vx binary and never installed `@vzn/vx`,
+ * which its own `vx.workspace.ts` imports. Bun's message also carries the
+ * module-cache bust query; the user gets the file they wrote.
+ *
+ * `BuildMessage` — a syntax or transpile error. Its message alone (`Expected
+ * "}" but found end of file`) names no file at all, and the file is not
+ * always the config: a preset the config imports fails the same way, so the
+ * location is taken from the error's position, with the config as the
+ * fallback.
+ */
+export function configLoadError(err: unknown, configPath: string, kind: string): UserError | null {
+  if (!(err instanceof Error)) return null
+  if (err.name === 'ResolveMessage') {
+    const spec = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(err.message)?.[1]
+    const what =
+      spec === undefined ? err.message.replace(/\?vx-bust=\S+/g, '') : `cannot find '${spec}'`
+    const hint =
+      spec?.startsWith('@vzn/vx') === true
+        ? `; install it in the workspace: bun add -d @vzn/vx`
+        : ''
+    return new UserError(`${kind} config ${configPath}: ${what}${hint}`)
+  }
+  if (err.name === 'BuildMessage') {
+    const pos = (err as { position?: BuildPosition | null }).position ?? {}
+    const file = typeof pos.file === 'string' && pos.file.length > 0 ? pos.file : configPath
+    const at =
+      typeof pos.line === 'number'
+        ? `:${pos.line}${typeof pos.column === 'number' ? `:${pos.column}` : ''}`
+        : ''
+    const where = file === configPath ? `${configPath}${at}` : `${configPath} (in ${file}${at})`
+    return new UserError(`${kind} config ${where}: ${err.message}`)
+  }
+  return null
 }
 
 export interface LoadProjectConfigOptions {
@@ -103,13 +140,29 @@ export async function loadProjectConfigs(
     hashFile !== undefined && store?.getConfigClosures !== undefined
       ? store.getConfigClosures(configPaths)
       : new Map<string, string[]>()
+  // Every indexed closure's files identified in ONE batch, then keyed from
+  // the map; a file the batch could not stat has no identity, which makes
+  // that config's fast key miss and sends it down the slow path exactly as
+  // a throwing per-file `hashFile` did.
+  let fastHashFile = hashFile
+  if (closures.size > 0 && store?.hashFiles !== undefined) {
+    const files = new Set<string>()
+    for (const closure of closures.values()) for (const f of closure) files.add(f)
+    const identities = await store.hashFiles([...files])
+    fastHashFile = (file: string): Promise<string> => {
+      const id = identities.get(file)
+      return id === undefined
+        ? Promise.reject(new Error(`no identity for ${file}`))
+        : Promise.resolve(id)
+    }
+  }
   const prepared = await Promise.all(
     configPaths.map(async (configPath) => {
       const closure = closures.get(configPath)
-      if (closure !== undefined && evalCache !== undefined && hashFile !== undefined) {
+      if (closure !== undefined && evalCache !== undefined && fastHashFile !== undefined) {
         const fastKey = await configEvalKeyFromClosure({
           closure,
-          hashFile,
+          hashFile: fastHashFile,
           workspaceFingerprint: evalCache.workspaceFingerprint,
         })
         if (fastKey !== null) return { configPath, bytes: null, cacheKey: fastKey, indexed: true }
@@ -187,7 +240,7 @@ export async function loadProjectConfigs(
     loadedConfigs.add(configPath)
     const mod = repeat
       ? await evaluateConfigFresh(configPath).catch((err: unknown) => {
-          throw unresolvedImportError(err, configPath, 'Project') ?? err
+          throw configLoadError(err, configPath, 'Project') ?? err
         })
       : await loadDefaultExport(configPath, 'Project', opts?.fresh === true, bytes!)
     assertDefaultObject(mod, 'Project', configPath)
@@ -231,726 +284,3 @@ export async function loadWorkspaceConfig(root: string): Promise<WorkspaceConfig
   validateWorkspace(mod, configPath)
   return mod
 }
-
-function validateWorkspace(config: WorkspaceConfig, configPath: string): void {
-  if (config.concurrency !== undefined) {
-    if (
-      typeof config.concurrency !== 'number' ||
-      !Number.isFinite(config.concurrency) ||
-      config.concurrency < 1 ||
-      !Number.isInteger(config.concurrency)
-    ) {
-      throw new UserError(`${configPath}: \`concurrency\` must be a positive integer`)
-    }
-  }
-  if (config.cacheDir !== undefined && typeof config.cacheDir !== 'string') {
-    throw new UserError(`${configPath}: \`cacheDir\` must be a string`)
-  }
-  if (config.timeout !== undefined) {
-    if (
-      typeof config.timeout !== 'number' ||
-      !Number.isInteger(config.timeout) ||
-      config.timeout <= 0
-    ) {
-      throw new UserError(`${configPath}: \`timeout\` must be a positive integer (milliseconds)`)
-    }
-    assertTimeoutInRange(config.timeout, `${configPath}: \`timeout\``)
-  }
-  if (config.plugins !== undefined) {
-    if (!Array.isArray(config.plugins)) {
-      throw new UserError(`${configPath}: \`plugins\` must be an array of plugin objects`)
-    }
-    for (const [i, p] of config.plugins.entries()) {
-      if (p === null || typeof p !== 'object') {
-        throw new UserError(`${configPath}: \`plugins[${i}]\` must be an object`)
-      }
-      const plug = p as {
-        name?: unknown
-        setup?: unknown
-        backend?: unknown
-        cache?: unknown
-        executor?: unknown
-        telemetry?: unknown
-        config?: unknown
-        project?: unknown
-        graph?: unknown
-        key?: unknown
-        schedule?: unknown
-        commands?: unknown
-        teardown?: unknown
-      }
-      if (typeof plug.name !== 'string' || plug.name.length === 0) {
-        throw new UserError(`${configPath}: \`plugins[${i}].name\` must be a non-empty string`)
-      }
-      // The whole-run `backend` seam was REMOVED on 2026-08-23 with vx
-      // cloud: a run always executes in the `vx run` process. Nothing
-      // consults `.backend` any more, so leaving it in `caps` below meant a
-      // plugin declaring ONLY `backend` — a third-party one written against
-      // the old API, say — validated as "contributes a capability" and was
-      // then silently ignored. Refuse it by name and point at the seam that
-      // replaced it; a silent no-op is the failure this validation exists
-      // to prevent.
-      if (plug.backend !== undefined) {
-        throw new UserError(
-          `${configPath}: \`plugins[${i}].backend\` is no longer a capability — the whole-run ` +
-            `backend seam was removed in 2026-08. Use \`executor\` to change where a single ` +
-            `task's command runs (see docs/architecture.md § plugin capabilities).`,
-        )
-      }
-      const caps = [
-        'config',
-        'project',
-        'graph',
-        'key',
-        'schedule',
-        'setup',
-        'cache',
-        'executor',
-        'telemetry',
-        'teardown',
-      ] as const
-      for (const cap of caps) {
-        if (plug[cap] !== undefined && typeof plug[cap] !== 'function') {
-          throw new UserError(`${configPath}: \`plugins[${i}].${cap}\` must be a function`)
-        }
-      }
-      if (plug.commands !== undefined) {
-        if (plug.commands === null || typeof plug.commands !== 'object') {
-          throw new UserError(`${configPath}: \`plugins[${i}].commands\` must be an object`)
-        }
-        for (const [verb, cmd] of Object.entries(plug.commands as Record<string, unknown>)) {
-          const c = cmd as { description?: unknown; run?: unknown } | null
-          if (
-            c === null ||
-            typeof c !== 'object' ||
-            typeof c.run !== 'function' ||
-            typeof c.description !== 'string'
-          ) {
-            throw new UserError(
-              `${configPath}: \`plugins[${i}].commands.${verb}\` must be { description: string, run: function }`,
-            )
-          }
-        }
-      }
-      // A plugin must contribute at least one capability or lifecycle hook
-      // — an empty `{ name }` object is a no-op authoring mistake.
-      if (caps.every((cap) => plug[cap] === undefined) && plug.commands === undefined) {
-        throw new UserError(
-          `${configPath}: \`plugins[${i}]\` must contribute at least one of ${[...caps, 'commands'].join('/')}`,
-        )
-      }
-    }
-  }
-}
-
-/**
- * Runtime validation for the user-authored config. TypeScript checks
- * shape at edit-time, but `vx run` may load configs that were never
- * typechecked (plain .js, or TS with errors ignored). Catch the worst
- * shape problems early with a clear message rather than letting them
- * crash deeper in the orchestrator. Also applied to configs loaded
- * back from `vx-lock.json` (a hand-editable file — same boundary).
- */
-export function validateProjectConfig(config: ProjectConfig, configPath: string): void {
-  const tasks = config.tasks
-  if (tasks === undefined) return
-  if (typeof tasks !== 'object' || tasks === null || Array.isArray(tasks)) {
-    // An ARRAY of task objects reads as valid to `typeof`, and
-    // `Object.entries` then yields a task literally named "0" — a config
-    // that loads, runs nothing the author asked for, and never says why.
-    throw new UserError(`${configPath}: \`tasks\` must be an object keyed by task name`)
-  }
-  for (const [name, task] of Object.entries(tasks)) {
-    const where = `${configPath}: tasks.${name}`
-    if (!task || typeof task !== 'object') {
-      throw new UserError(`${where} must be an object`)
-    }
-    assertKnownFields(task, TASK_FIELDS, where)
-    const exec = (task as { exec?: unknown }).exec
-    const dependsOn = (task as { dependsOn?: unknown }).dependsOn
-    const cache = (task as { cache?: unknown }).cache
-    if (exec !== undefined) {
-      if (typeof exec !== 'object' || exec === null) {
-        throw new UserError(`${where}.exec must be an object with a \`command\` string`)
-      }
-      assertKnownFields(exec, EXEC_FIELDS, `${where}.exec`)
-      const command = (exec as { command?: unknown }).command
-      if (typeof command !== 'string' || command.length === 0) {
-        throw new UserError(`${where}.exec.command must be a non-empty string`)
-      }
-      const timeout = (exec as { timeout?: unknown }).timeout
-      if (timeout !== undefined) {
-        if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout <= 0) {
-          throw new UserError(`${where}.exec.timeout must be a positive integer (milliseconds)`)
-        }
-        assertTimeoutInRange(timeout, `${where}.exec.timeout`)
-      }
-      const retries = (exec as { retries?: unknown }).retries
-      if (retries !== undefined) {
-        if (typeof retries !== 'number' || !Number.isInteger(retries) || retries < 0) {
-          throw new UserError(`${where}.exec.retries must be a non-negative integer`)
-        }
-      }
-      const remote = (exec as { remote?: unknown }).remote
-      if (remote !== undefined && typeof remote !== 'boolean' && remote !== 'only') {
-        throw new UserError(`${where}.exec.remote must be a boolean or 'only' (or omitted)`)
-      }
-      const resources = (exec as { resources?: unknown }).resources
-      if (resources !== undefined) {
-        validateResources(resources, `${where}.exec.resources`)
-      }
-      const env = (exec as { env?: unknown }).env
-      if (env !== undefined) {
-        if (typeof env !== 'object' || env === null) {
-          throw new UserError(`${where}.exec.env must be an object (or omitted)`)
-        }
-        const passThrough = (env as { passThrough?: unknown }).passThrough
-        if (passThrough !== undefined) {
-          // A non-array here reaches `buildIsolatedEnv`'s `for (const name of
-          // passThrough)` — a number throws "not iterable" mid-run, a string
-          // silently char-iterates. Fail loud at load with a config pointer.
-          if (
-            !Array.isArray(passThrough) ||
-            passThrough.some((n) => typeof n !== 'string' || n.length === 0)
-          ) {
-            throw new UserError(
-              `${where}.exec.env.passThrough must be an array of non-empty env var names`,
-            )
-          }
-        }
-        const define = (env as { define?: unknown }).define
-        if (define !== undefined) {
-          if (typeof define !== 'object' || define === null || Array.isArray(define)) {
-            throw new UserError(
-              `${where}.exec.env.define must be an object of name:value string pairs`,
-            )
-          }
-          for (const [k, val] of Object.entries(define as Record<string, unknown>)) {
-            if (typeof val !== 'string') {
-              throw new UserError(`${where}.exec.env.define.${k} must be a string`)
-            }
-          }
-        }
-      }
-      const persistent = (exec as { persistent?: unknown }).persistent
-      if (persistent !== undefined) {
-        if (typeof persistent !== 'object' || persistent === null) {
-          throw new UserError(`${where}.exec.persistent must be an object (or omitted)`)
-        }
-        // The one nested object that had no unknown-key check while every
-        // sibling did — and the failure it let through is the quiet kind:
-        // `readWhen` (typo) leaves `readyWhen` undefined, so the task is
-        // ready the moment it spawns instead of when its server actually
-        // listens, and the dependents that start too early fail in a way
-        // that points at the user's code rather than at their config.
-
-        assertKnownFields(persistent, PERSISTENT_FIELDS, `${where}.exec.persistent`)
-        const readyWhen = (persistent as { readyWhen?: unknown }).readyWhen
-        if (readyWhen !== undefined && typeof readyWhen !== 'string') {
-          throw new UserError(`${where}.exec.persistent.readyWhen must be a string regex`)
-        }
-        if (cache !== undefined) {
-          throw new UserError(
-            `${where}: \`cache\` is not allowed on a persistent task — persistent tasks ` +
-              `don't terminate, so there's no exit to cache`,
-          )
-        }
-        if (retries !== undefined) {
-          throw new UserError(
-            `${where}: \`retries\` is not allowed on a persistent task — persistent tasks ` +
-              `don't terminate, so there's no failed exit to retry`,
-          )
-        }
-      }
-    } else {
-      // Group task: no exec, just dependencies. Must declare something to
-      // depend on, otherwise the task is a literal no-op with nothing to
-      // chain (almost certainly a config mistake).
-      if (dependsOn === undefined) {
-        throw new UserError(
-          `${where}: a task with no \`exec\` must declare \`dependsOn\` ` +
-            `(group tasks exist to chain dependencies)`,
-        )
-      }
-      if (cache !== undefined) {
-        throw new UserError(
-          `${where}: \`cache\` requires \`exec\` — a group task has nothing to cache`,
-        )
-      }
-    }
-    const description = (task as { description?: unknown }).description
-    if (description !== undefined && typeof description !== 'string') {
-      throw new UserError(`${where}.description must be a string`)
-    }
-    if (dependsOn !== undefined) {
-      if (!Array.isArray(dependsOn) || dependsOn.some((s) => typeof s !== 'string')) {
-        throw new UserError(
-          `${where}.dependsOn must be an array of strings ` +
-            `(Turbo/Nx micro-syntax: 'name', '^name', 'pkg#name')`,
-        )
-      }
-    }
-    if (cache !== undefined) {
-      if (typeof cache !== 'object' || cache === null) {
-        throw new UserError(`${where}.cache must be an object when present`)
-      }
-      assertKnownFields(cache, CACHE_FIELDS, `${where}.cache`)
-      const inputs = (cache as { inputs?: unknown }).inputs
-      const outputs = (cache as { outputs?: unknown }).outputs
-      if (!inputs || typeof inputs !== 'object') {
-        throw new UserError(`${where}.cache.inputs is required when \`cache\` is set`)
-      }
-      assertKnownFields(inputs, CACHE_INPUT_FIELDS, `${where}.cache.inputs`)
-      if (!Array.isArray((inputs as { files?: unknown }).files)) {
-        throw new UserError(`${where}.cache.inputs.files must be an array of glob strings`)
-      }
-      const envList = (inputs as { env?: unknown }).env
-      if (envList !== undefined) {
-        if (
-          !Array.isArray(envList) ||
-          envList.some((s) => typeof s !== 'string' || s.length === 0)
-        ) {
-          throw new UserError(
-            `${where}.cache.inputs.env must be an array of non-empty env var names`,
-          )
-        }
-        for (const name of envList as string[]) {
-          // Reject wildcards explicitly so users don't silently miss
-          // env vars they thought they were tracking. Turbo supports
-          // `VERCEL_*` expansion; vx requires the literal names. If
-          // we add expansion later it'll be additive — until then,
-          // surface the footgun instead of returning '' for the
-          // literal env name `'VERCEL_*'`.
-          if (/[*?[\]]/.test(name)) {
-            throw new UserError(
-              `${where}.cache.inputs.env: wildcards in env names are not supported ` +
-                `(got "${name}") — list explicit env var names instead`,
-            )
-          }
-        }
-      }
-      if (!outputs || typeof outputs !== 'object') {
-        throw new UserError(`${where}.cache.outputs is required when \`cache\` is set`)
-      }
-      assertKnownFields(outputs, CACHE_OUTPUT_FIELDS, `${where}.cache.outputs`)
-      const outFiles = (outputs as { files?: unknown }).files
-      if (!Array.isArray(outFiles)) {
-        throw new UserError(`${where}.cache.outputs.files must be an array of glob strings`)
-      }
-      // Reject zero-length strings and absolute paths up front.
-      // Both reach `resolveOutputs` as undefined behavior; the error
-      // surfaces deep inside the glob resolver with no line pointing
-      // at the user's config. Fail loud at load time.
-      for (const g of outFiles as unknown[]) {
-        if (typeof g !== 'string' || g.length === 0) {
-          throw new UserError(`${where}.cache.outputs.files must be an array of non-empty strings`)
-        }
-        if (g.startsWith('/')) {
-          throw new UserError(
-            `${where}.cache.outputs.files: absolute paths are not allowed (got "${g}") — ` +
-              `outputs must be project-relative globs`,
-          )
-        }
-        if (hasParentSegment(g)) {
-          throw new UserError(
-            `${where}.cache.outputs.files: '..' path segments are not allowed (got "${g}") — ` +
-              `outputs must stay within the project (a glob that escapes the project dir would ` +
-              `let cleanOutputs delete files outside it)`,
-          )
-        }
-        if (g.startsWith('!')) {
-          throw new UserError(
-            `${where}.cache.outputs.files: negation is not supported (got "${g}") — ` +
-              `unlike inputs, output globs are never split on '!', so this is read as a literal ` +
-              `path beginning with '!' and matches nothing. List the outputs you DO produce.`,
-          )
-        }
-      }
-      // Same for inputs.files.
-      for (const g of (inputs as { files: unknown[] }).files) {
-        if (typeof g !== 'string' || g.length === 0) {
-          throw new UserError(`${where}.cache.inputs.files must be an array of non-empty strings`)
-        }
-        if (g.startsWith('/')) {
-          throw new UserError(
-            `${where}.cache.inputs.files: absolute paths are not allowed (got "${g}") — ` +
-              `inputs must be project-relative globs`,
-          )
-        }
-        if (hasParentSegment(g)) {
-          throw new UserError(
-            `${where}.cache.inputs.files: '..' path segments are not allowed (got "${g}") — ` +
-              `inputs must be project-relative (a '..' glob silently matches nothing; ` +
-              `use cache.inputs.workspaceFiles for workspace-root-relative inputs)`,
-          )
-        }
-        assertNotDoubleNegated(g, `${where}.cache.inputs.files`)
-      }
-      // A list of ONLY negations selects nothing at all. `resolveFiles`
-      // builds the file set from the POSITIVE globs and uses the `!` entries
-      // purely to subtract, so with no positive pattern it returns `[]` — the
-      // task folds ZERO file inputs and its key stops moving with its source,
-      // which is a stale hit waiting to happen.
-      //
-      // Every gitignore-trained reader parses `['!**/*.spec.ts']` as
-      // "everything except specs", and Turbo makes exactly this a hard config
-      // error for the same reason. Refusing costs nothing: such a config was
-      // already silently broken, so no working key changes.
-      assertNotNegationOnly((inputs as { files: string[] }).files, `${where}.cache.inputs.files`)
-      // The only CacheInputs field that reached the run unvalidated: a
-      // non-string entry crashes deep in `filterUpstreamHashes` /
-      // `parseDependencySpec` with a raw TypeError naming neither the task
-      // nor the config. Entry SYNTAX is already checked downstream (a
-      // `DependencySpecError` becomes a UserError naming the task) — this
-      // only pins the shape.
-      const taskFilters = (inputs as { tasks?: unknown }).tasks
-      if (taskFilters !== undefined) {
-        if (
-          !Array.isArray(taskFilters) ||
-          taskFilters.some((s) => typeof s !== 'string' || s.length === 0)
-        ) {
-          throw new UserError(
-            `${where}.cache.inputs.tasks must be an array of non-empty strings ` +
-              `(Turbo/Nx micro-syntax: 'name', '^name', 'pkg#name', '*', '^*', '!name')`,
-          )
-        }
-      }
-      for (const field of ['runtime', 'workspaceRuntime'] as const) {
-        const list = (inputs as Record<string, unknown>)[field]
-        if (list !== undefined) {
-          if (!Array.isArray(list) || list.some((s) => typeof s !== 'string' || s.length === 0)) {
-            throw new UserError(
-              `${where}.cache.inputs.${field} must be an array of non-empty shell command strings`,
-            )
-          }
-        }
-      }
-      // workspaceFiles mirror the files validation: non-empty strings,
-      // never absolute (they're workspace-root-relative by definition).
-      const wsInputs = (inputs as { workspaceFiles?: unknown }).workspaceFiles
-      if (wsInputs !== undefined) {
-        validateWorkspaceGlobs(wsInputs, `${where}.cache.inputs.workspaceFiles`, true)
-      }
-      const wsOutputs = (outputs as { workspaceFiles?: unknown }).workspaceFiles
-      if (wsOutputs !== undefined) {
-        validateWorkspaceGlobs(wsOutputs, `${where}.cache.outputs.workspaceFiles`, false)
-      }
-    }
-    const sandbox = (task as { sandbox?: unknown }).sandbox
-    if (sandbox !== undefined) validateSandbox(sandbox, where, exec !== undefined)
-  }
-}
-
-// Known fields per config level, mirroring the interfaces in src/config.ts.
-// Unknown keys are REJECTED rather than silently dropped: a typo in a
-// cache-key field (`workspaceFile`, `task`, `timeoutMs`) is otherwise
-// discarded, so the task hashes as if the field were never written and vx
-// serves a stale artifact — the same reasoning `exec.resources` and
-// `sandbox` already encode. A new field must be added here deliberately.
-const TASK_FIELDS = new Set(['description', 'exec', 'dependsOn', 'cache', 'sandbox'])
-const EXEC_FIELDS = new Set([
-  'command',
-  'env',
-  'timeout',
-  'retries',
-  'resources',
-  'persistent',
-  'remote',
-])
-const PERSISTENT_FIELDS = new Set(['readyWhen'])
-const CACHE_FIELDS = new Set(['inputs', 'outputs'])
-const CACHE_INPUT_FIELDS = new Set([
-  'files',
-  'workspaceFiles',
-  'env',
-  'tasks',
-  'runtime',
-  'workspaceRuntime',
-])
-const CACHE_OUTPUT_FIELDS = new Set(['files', 'workspaceFiles'])
-
-function assertKnownFields(value: object, allowed: ReadonlySet<string>, where: string): void {
-  for (const key of Object.keys(value)) {
-    if (!allowed.has(key)) {
-      throw new UserError(
-        `${where} has unknown field "${key}". Allowed: ${[...allowed].sort().join(', ')}`,
-      )
-    }
-  }
-}
-
-/**
- * True when a glob contains a `..` PATH SEGMENT (`../x`, `a/../b`, `x/..`), which
- * escapes its base dir — `foo..bar` / `a..b` inside a filename are fine. A
- * leading negation marker is stripped first so `!../x` is caught too. Used to
- * keep output globs inside the project and workspace globs inside the workspace
- * root: `cleanOutputs` rm()s resolved output paths before every run, and
- * `Bun.Glob.scan` follows `..` out of its cwd, so a `..` glob is a data-loss
- * vector (delete files outside the project / above the repo root).
- */
-/**
- * A millisecond delay past `MAX_TIMEOUT_MS` does not mean "effectively never" —
- * `setTimeout` silently reduces it to 1 ms, so the task is killed the instant it
- * spawns and reported `failed`. That is the exact inverse of the declaration,
- * and the only clue is a `TimeoutOverflowWarning` on stderr.
- *
- * Refused rather than clamped, because this is a value the user WROTE and reads
- * back: silently substituting ~24.8 days for the 317 years they asked for would
- * trade one surprise for a quieter one. Costs nothing — such a config never
- * worked, it killed the task in milliseconds, so refusing reports a state that
- * already existed.
- */
-function assertTimeoutInRange(ms: number, where: string): void {
-  if (ms <= MAX_TIMEOUT_MS) return
-  throw new UserError(
-    `${where}: ${ms} ms exceeds the maximum timer delay (${MAX_TIMEOUT_MS} ms, ~24.8 days). ` +
-      `Timers larger than this do NOT mean "no limit" — the platform reduces them to 1 ms, so ` +
-      `the task would be killed the moment it starts. Omit \`timeout\` for no limit.`,
-  )
-}
-
-function hasParentSegment(glob: string): boolean {
-  const g = glob.startsWith('!') ? glob.slice(1) : glob
-  return g.split('/').some((seg) => seg === '..')
-}
-
-/**
- * Refuse a non-empty glob list made up ENTIRELY of negations.
- *
- * The resolvers build their file set from the POSITIVE globs and use `!`
- * entries only to subtract, so with no positive pattern they return `[]` —
- * the task folds zero file inputs and its cache key stops moving with its
- * source. That is a stale hit, and it is silent.
- *
- * Refusing is free: such a config was ALREADY selecting nothing, so no
- * working task's key changes and no CACHE_VERSION bump is owed.
- */
-/**
- * `!!x` INVERTS the input set instead of double-negating it.
- *
- * The resolver strips ONE `!` and hands the remainder to `new Bun.Glob()` —
- * which applies its OWN leading-`!` negation. So `!!vendor/**` becomes the
- * exclude glob `Glob('!vendor/**')`, and that matches every path EXCEPT
- * vendor's. Everything else is therefore excluded and the task folds ONLY
- * `vendor/**`: its own source drops out of the cache key entirely, which is a
- * permanent stale hit.
- *
- * Neither neighbouring guard catches it — `assertNotNegationOnly` sees the
- * positive glob and is satisfied, and `hasParentSegment` strips one `!` before
- * splitting so `!!../x` shows no `..` segment.
- *
- * Refused rather than reinterpreted: `!!` has no coherent meaning here.
- * Negation in vx is subtraction from what a positive glob matched, not
- * gitignore's ordered re-inclusion, so there is nothing for a second `!` to
- * undo. Costs nothing to refuse — such a config already folds the wrong set,
- * so no working cache key changes.
- */
-function assertNotDoubleNegated(glob: string, where: string): void {
-  if (!glob.startsWith('!!')) return
-  const inner = glob.slice(2)
-  throw new UserError(
-    `${where}: '!!' is not a double negation (got "${glob}") — it INVERTS the set. ` +
-      `One '!' is stripped and the remainder is compiled as a glob, which applies its own ` +
-      `leading-'!' negation, so this excludes everything EXCEPT ${JSON.stringify(inner)} and ` +
-      `the task folds only that. Use ${JSON.stringify(`!${inner}`)} to subtract it, or ` +
-      `${JSON.stringify(inner)} to include it.`,
-  )
-}
-
-function assertNotNegationOnly(globs: readonly string[], where: string): void {
-  if (globs.length === 0) return
-  if (globs.some((g) => !g.startsWith('!'))) return
-  throw new UserError(
-    `${where}: every entry is a negation, which selects NOTHING (got ${JSON.stringify(globs)}) — ` +
-      `negations only subtract from the files a positive glob already matched, so this task ` +
-      `would fold zero file inputs and its cache key would stop tracking its source. ` +
-      `Add the positive glob you meant, e.g. ['**/*', ${JSON.stringify(globs[0])}].`,
-  )
-}
-
-/**
- * `negation: false` for OUTPUT globs — `resolveOutputs` /
- * `resolveWorkspaceOutputs` never split on `!`, so such an entry is read as a
- * literal path starting with `!` and matches nothing.
- */
-function validateWorkspaceGlobs(v: unknown, where: string, negation: boolean): void {
-  if (!Array.isArray(v)) {
-    throw new UserError(`${where} must be an array of glob strings`)
-  }
-  for (const g of v as unknown[]) {
-    if (typeof g !== 'string' || g.length === 0) {
-      throw new UserError(`${where} must be an array of non-empty strings`)
-    }
-    if (g.startsWith('/') || g.startsWith('!/')) {
-      throw new UserError(
-        `${where}: absolute paths are not allowed (got "${g}") — ` +
-          `entries are workspace-root-relative globs`,
-      )
-    }
-    if (hasParentSegment(g)) {
-      throw new UserError(
-        `${where}: '..' path segments are not allowed (got "${g}") — ` +
-          `entries are workspace-root-relative and must stay within the workspace root`,
-      )
-    }
-    if (!negation && g.startsWith('!')) {
-      throw new UserError(
-        `${where}: negation is not supported (got "${g}") — ` +
-          `unlike inputs, output globs are never split on '!', so this is read as a literal ` +
-          `path beginning with '!' and matches nothing. List the outputs you DO produce.`,
-      )
-    }
-    if (negation) assertNotDoubleNegated(g, where)
-  }
-  if (negation) assertNotNegationOnly(v as string[], where)
-}
-
-const SANDBOX_PATH_FIELDS = ['allowRead', 'allowWrite'] as const
-const SANDBOX_BOOL_FIELDS = [
-  'allowGitConfig',
-  'allowPty',
-  'enableWeakerNestedSandbox',
-  'enableWeakerNetworkIsolation',
-] as const
-const SANDBOX_NETWORK_PATH_FIELDS = [
-  'allowedDomains',
-  'deniedDomains',
-  'allowUnixSockets',
-  'allowMachLookup',
-] as const
-const SANDBOX_NETWORK_BOOL_FIELDS = ['allowAllUnixSockets', 'allowLocalBinding'] as const
-const SANDBOX_FIELDS = new Set<string>([
-  ...SANDBOX_PATH_FIELDS,
-  ...SANDBOX_BOOL_FIELDS,
-  'network',
-  'ignoreViolations',
-])
-const SANDBOX_NETWORK_FIELDS = new Set<string>([
-  ...SANDBOX_NETWORK_PATH_FIELDS,
-  ...SANDBOX_NETWORK_BOOL_FIELDS,
-])
-
-/**
- * Validate a `sandbox: {...}` block. The field set mirrors the user-
- * facing surface of SandboxConfig in src/config.ts; this is the only
- * place we enforce shape at runtime (TS users get compile-time checks
- * already).
- */
-function validateSandbox(sandbox: unknown, where: string, hasExec: boolean): void {
-  if (typeof sandbox !== 'object' || sandbox === null || Array.isArray(sandbox)) {
-    throw new UserError(
-      `${where}.sandbox must be an object (e.g. \`{}\` for the baseline, or ` +
-        `\`{ allowRead: [...], network: true }\`)`,
-    )
-  }
-  if (!hasExec) {
-    throw new UserError(`${where}.sandbox requires \`exec\` — a group task has nothing to wrap`)
-  }
-  for (const key of Object.keys(sandbox as object)) {
-    if (!SANDBOX_FIELDS.has(key)) {
-      throw new UserError(
-        `${where}.sandbox.${key} is not a known field. Allowed: ` +
-          `${[...SANDBOX_FIELDS].sort().join(', ')}`,
-      )
-    }
-  }
-  const obj = sandbox as Record<string, unknown>
-  for (const field of SANDBOX_PATH_FIELDS) {
-    if (obj[field] === undefined) continue
-    assertPathArray(obj[field], `${where}.sandbox.${field}`)
-  }
-  for (const field of SANDBOX_BOOL_FIELDS) {
-    if (obj[field] !== undefined && typeof obj[field] !== 'boolean') {
-      throw new UserError(`${where}.sandbox.${field} must be a boolean`)
-    }
-  }
-  const network = obj.network
-  if (network !== undefined && typeof network !== 'boolean') {
-    if (typeof network !== 'object' || network === null || Array.isArray(network)) {
-      throw new UserError(
-        `${where}.sandbox.network must be a boolean or an object (allowedDomains, ` +
-          `deniedDomains, allowUnixSockets, allowAllUnixSockets, allowLocalBinding, allowMachLookup)`,
-      )
-    }
-    for (const key of Object.keys(network)) {
-      if (!SANDBOX_NETWORK_FIELDS.has(key)) {
-        throw new UserError(
-          `${where}.sandbox.network.${key} is not a known field. Allowed: ` +
-            `${[...SANDBOX_NETWORK_FIELDS].sort().join(', ')}`,
-        )
-      }
-    }
-    const netObj = network as Record<string, unknown>
-    for (const field of SANDBOX_NETWORK_PATH_FIELDS) {
-      if (netObj[field] === undefined) continue
-      assertStringArray(netObj[field], `${where}.sandbox.network.${field}`)
-    }
-    for (const field of SANDBOX_NETWORK_BOOL_FIELDS) {
-      if (netObj[field] !== undefined && typeof netObj[field] !== 'boolean') {
-        throw new UserError(`${where}.sandbox.network.${field} must be a boolean`)
-      }
-    }
-  }
-  const ignoreViolations = obj.ignoreViolations
-  if (ignoreViolations !== undefined) {
-    if (
-      typeof ignoreViolations !== 'object' ||
-      ignoreViolations === null ||
-      Array.isArray(ignoreViolations)
-    ) {
-      throw new UserError(
-        `${where}.sandbox.ignoreViolations must be a record mapping command patterns to arrays of paths`,
-      )
-    }
-    for (const [k, v] of Object.entries(ignoreViolations)) {
-      assertStringArray(v, `${where}.sandbox.ignoreViolations[${JSON.stringify(k)}]`)
-    }
-  }
-}
-
-const RESOURCES_FIELDS = new Set(['cpus', 'memory', 'image'])
-
-function validateResources(resources: unknown, where: string): void {
-  if (typeof resources !== 'object' || resources === null || Array.isArray(resources)) {
-    throw new UserError(`${where} must be an object (e.g. \`{ cpus: 2, memory: 2048 }\`)`)
-  }
-  for (const key of Object.keys(resources as object)) {
-    if (!RESOURCES_FIELDS.has(key)) {
-      throw new UserError(
-        `${where} has unknown field "${key}". Allowed: ${[...RESOURCES_FIELDS].sort().join(', ')}`,
-      )
-    }
-  }
-  const { cpus, memory, image } = resources as {
-    cpus?: unknown
-    memory?: unknown
-    image?: unknown
-  }
-  if (cpus !== undefined && (typeof cpus !== 'number' || !Number.isFinite(cpus) || cpus < 0)) {
-    throw new UserError(`${where}.cpus must be a non-negative number of CPU cores`)
-  }
-  if (
-    memory !== undefined &&
-    (typeof memory !== 'number' || !Number.isInteger(memory) || memory < 0)
-  ) {
-    throw new UserError(`${where}.memory must be a non-negative integer number of megabytes`)
-  }
-  if (image !== undefined && (typeof image !== 'string' || image === '')) {
-    throw new UserError(`${where}.image must be a non-empty string (or omitted)`)
-  }
-}
-
-function assertStringArray(v: unknown, where: string): void {
-  if (!Array.isArray(v) || v.some((s) => typeof s !== 'string' || s.length === 0)) {
-    throw new UserError(`${where} must be an array of non-empty strings`)
-  }
-}
-
-function assertPathArray(v: unknown, where: string): void {
-  assertStringArray(v, where)
-  if ((v as string[]).some((s) => /[*?[\]]/.test(s))) {
-    throw new UserError(
-      `${where} entries must be path prefixes (no globs — bwrap on Linux can't enforce them)`,
-    )
-  }
-}