@vzn/vx 0.0.16 → 0.0.21

package/src/workspace/project-loader.ts

@@ -1,14 +1,31 @@
 import path from 'node:path'
 import type { ProjectConfig, WorkspaceConfig } from '../config.js'
-import { parseSize, 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',
   'vx.workspace.mjs',
 ]
 
+/** Project configs already loaded in this process, by absolute path. */
+const loadedConfigs = new Set<string>()
+
+function assertDefaultObject(mod: unknown, kind: string, configPath: string): void {
+  if (!mod || typeof mod !== 'object') {
+    throw new UserError(`${kind} config at ${configPath} did not export a default object`)
+  }
+}
+
 // Bun has native TS / ESM execution — no transpiler dep needed. We fold
 // a short content hash into the import URL as a cache-bust key so that:
 //   same content   → same URL → Bun's module cache hits (fast)
@@ -21,492 +38,249 @@ async function loadDefaultExport(
   configPath: string,
   kind: string,
   fresh = false,
+  bytes?: Uint8Array,
 ): Promise<unknown> {
-  const bytes = await Bun.file(configPath).bytes()
+  bytes ??= await Bun.file(configPath).bytes()
   // `fresh` opts out of module-cache reuse entirely: `vx lock` and
   // `vx lock --check` must observe the CURRENT environment, and the
   // content-hash bust would replay an evaluation made under earlier
   // env values when the file bytes are unchanged in this process.
   const bust = fresh ? `${xxh3hex(bytes)}-${Bun.randomUUIDv7()}` : xxh3hex(bytes)
-  const ns = (await import(`${configPath}?vx-bust=${bust}`)) as { default?: unknown }
-  const mod = ns?.default
-  if (!mod || typeof mod !== 'object') {
-    throw new UserError(`${kind} config at ${configPath} did not export a default object`)
+  let ns: { default?: unknown }
+  try {
+    ns = (await import(`${configPath}?vx-bust=${bust}`)) as { default?: unknown }
+  } catch (err) {
+    throw configLoadError(err, configPath, kind) ?? err
   }
+  const mod = ns?.default
+  assertDefaultObject(mod, kind, configPath)
   return mod
 }
 
-export async function loadProjectConfig(
-  configPath: string,
-  opts?: { fresh?: boolean },
-): Promise<ProjectConfig> {
-  const mod = (await loadDefaultExport(
-    configPath,
-    'Project',
-    opts?.fresh === true,
-  )) as ProjectConfig
-  validateProjectConfig(mod, configPath)
-  return mod
+/**
+ * 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.
+ */
+interface BuildPosition {
+  file?: string
+  line?: number
+  column?: number
 }
 
 /**
- * Find and load `vx.workspace.{ts,mts,js,mjs}` from the workspace
- * root. Returns `null` if no such file exists (the common case;
- * the schema is fully optional). Validates the shape and throws
- * a `UserError` on malformed input.
+ * 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 async function loadWorkspaceConfig(root: string): Promise<WorkspaceConfig | null> {
-  let configPath: string | null = null
-  for (const candidate of WORKSPACE_CONFIG_FILENAMES.map((f) => path.join(root, f))) {
-    if (await Bun.file(candidate).exists()) {
-      configPath = candidate
-      break
-    }
+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 (!configPath) return null
-  const mod = (await loadDefaultExport(configPath, 'Workspace')) as WorkspaceConfig
-  validateWorkspace(mod, configPath)
-  return mod
+  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
 }
 
-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)`)
-    }
-  }
-  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
-        telemetry?: unknown
-        eventSink?: 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`)
-      }
-      for (const cap of [
-        'setup',
-        'backend',
-        'cache',
-        'telemetry',
-        'eventSink',
-        'teardown',
-      ] as const) {
-        if (plug[cap] !== undefined && typeof plug[cap] !== 'function') {
-          throw new UserError(`${configPath}: \`plugins[${i}].${cap}\` must be a function`)
-        }
-      }
-      // A plugin must contribute at least one capability or lifecycle hook
-      // — an empty `{ name }` object is a no-op authoring mistake.
-      if (
-        plug.setup === undefined &&
-        plug.backend === undefined &&
-        plug.cache === undefined &&
-        plug.telemetry === undefined &&
-        plug.eventSink === undefined &&
-        plug.teardown === undefined
-      ) {
-        throw new UserError(
-          `${configPath}: \`plugins[${i}]\` must contribute at least one of setup/backend/cache/telemetry/eventSink`,
-        )
-      }
-    }
-  }
-  if (config.predictive !== undefined && typeof config.predictive !== 'boolean') {
-    throw new UserError(`${configPath}: \`predictive\` must be a boolean`)
-  }
+export interface LoadProjectConfigOptions {
+  /** Observe the CURRENT environment: no module-cache reuse, no eval cache. */
+  fresh?: boolean
+  /**
+   * Serve a provably-pure config from its cached evaluation (see
+   * config-cache.ts) and store a fresh one for next time. Off for `fresh`.
+   */
+  evalCache?: { store: ConfigEvalStore; workspaceFingerprint: string }
 }
 
 /**
- * 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).
+ * Load many configs at once: every file's bytes and cache key in parallel,
+ * ONE store lookup for all keys, then only the misses are evaluated (in the
+ * order given, so a failure names the first broken file the way a
+ * one-by-one load did). A single-path load is the one-element case.
  */
-export function validateProjectConfig(config: ProjectConfig, configPath: string): void {
-  const tasks = config.tasks
-  if (tasks === undefined) return
-  if (typeof tasks !== 'object' || tasks === null) {
-    throw new UserError(`${configPath}: \`tasks\` must be an object`)
-  }
-  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`)
+export async function loadProjectConfigs(
+  configPaths: readonly string[],
+  opts?: LoadProjectConfigOptions,
+): Promise<ProjectConfig[]> {
+  const evalCache = opts?.fresh === true ? undefined : opts?.evalCache
+  const store = evalCache?.store
+  const hashFile = store?.hashFile?.bind(store)
+  // The warm fast path: a config whose ordered closure the store remembers
+  // is keyed from per-file identities (a stat each, no read, no scan); the
+  // slow path below reads, gates and scans, and indexes the closure for
+  // next time when every import is explicit.
+  const closures =
+    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 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`)
-      }
-      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)`)
-        }
-      }
-      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 prepared = await Promise.all(
+    configPaths.map(async (configPath) => {
+      const closure = closures.get(configPath)
+      if (closure !== undefined && evalCache !== undefined && fastHashFile !== undefined) {
+        const fastKey = await configEvalKeyFromClosure({
+          closure,
+          hashFile: fastHashFile,
+          workspaceFingerprint: evalCache.workspaceFingerprint,
+        })
+        if (fastKey !== null) return { configPath, bytes: null, cacheKey: fastKey, indexed: true }
       }
-      const resources = (exec as { resources?: unknown }).resources
-      if (resources !== undefined) {
-        validateResources(resources, `${where}.exec.resources`)
+      const bytes = await Bun.file(configPath).bytes()
+      const keyed =
+        evalCache === undefined
+          ? null
+          : await configEvalKey({
+              configPath,
+              bytes,
+              workspaceFingerprint: evalCache.workspaceFingerprint,
+              ...(hashFile !== undefined ? { hashFile } : {}),
+            })
+      return {
+        configPath,
+        bytes,
+        cacheKey: keyed?.key ?? null,
+        indexed: false,
+        closure: keyed !== null && keyed.indexable ? keyed.closure : undefined,
       }
-      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)`)
-        }
-        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`,
-          )
+    }),
+  )
+  let hits = new Map<string, string>()
+  if (evalCache !== undefined) {
+    const keys = prepared.map((p) => p.cacheKey).filter((k): k is string => k !== null)
+    if (keys.length > 0) {
+      if (evalCache.store.getConfigEvals !== undefined) {
+        hits = evalCache.store.getConfigEvals(keys)
+      } else {
+        for (const k of keys) {
+          const hit = evalCache.store.getConfigEval(k)
+          if (hit !== null) hits.set(k, hit)
         }
       }
-    } 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`)
+  }
+  const out: ProjectConfig[] = []
+  for (const entry of prepared) {
+    const { configPath, cacheKey } = entry
+    const hit = cacheKey === null ? undefined : hits.get(cacheKey)
+    // Stored AFTER validation, so a hit needs none; the key covers every
+    // byte the evaluation could have read.
+    if (hit !== undefined) {
+      out.push(JSON.parse(hit) as ProjectConfig)
+      continue
     }
-    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')`,
-        )
+    // A fast key that missed: the closure is stale or the file changed.
+    // Take the slow path for this one config, which re-indexes it.
+    let bytes = entry.bytes
+    let closure = entry.closure
+    let key = cacheKey
+    if (entry.indexed) {
+      bytes = await Bun.file(configPath).bytes()
+      const keyed = await configEvalKey({
+        configPath,
+        bytes,
+        workspaceFingerprint: evalCache!.workspaceFingerprint,
+        ...(hashFile !== undefined ? { hashFile } : {}),
+      })
+      key = keyed?.key ?? null
+      closure = keyed !== null && keyed.indexable ? keyed.closure : undefined
+      const slowHit = key === null ? null : (store!.getConfigEval(key) ?? null)
+      if (slowHit !== null) {
+        out.push(JSON.parse(slowHit) as ProjectConfig)
+        if (closure !== undefined) store!.putConfigClosure?.(configPath, closure)
+        continue
       }
     }
-    if (cache !== undefined) {
-      if (typeof cache !== 'object' || cache === null) {
-        throw new UserError(`${where}.cache must be an object when present`)
-      }
-      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`)
-      }
-      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`)
-      }
-      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`,
-          )
-        }
-      }
-      // 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`,
-          )
-        }
-      }
-      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`)
-      }
-      const wsOutputs = (outputs as { workspaceFiles?: unknown }).workspaceFiles
-      if (wsOutputs !== undefined) {
-        validateWorkspaceGlobs(wsOutputs, `${where}.cache.outputs.workspaceFiles`)
-      }
+    // A REPEAT load in this process re-evaluates in a worker, because the
+    // bust above cannot reach the config's import closure — see
+    // config-eval.ts. A FIRST load keeps the in-process import, so the
+    // single `vx run` hot path never pays for a worker.
+    const repeat = loadedConfigs.has(configPath)
+    loadedConfigs.add(configPath)
+    const mod = repeat
+      ? await evaluateConfigFresh(configPath).catch((err: unknown) => {
+          throw configLoadError(err, configPath, 'Project') ?? err
+        })
+      : await loadDefaultExport(configPath, 'Project', opts?.fresh === true, bytes!)
+    assertDefaultObject(mod, 'Project', configPath)
+    // Validation runs HERE, on whichever object we ended up with, so a
+    // malformed config reports the identical UserError whether it was
+    // evaluated in-process or in a worker.
+    validateProjectConfig(mod as ProjectConfig, configPath)
+    if (key !== null) {
+      evalCache!.store.putConfigEval(key, JSON.stringify(mod))
+      if (closure !== undefined) evalCache!.store.putConfigClosure?.(configPath, closure)
     }
-    const sandbox = (task as { sandbox?: unknown }).sandbox
-    if (sandbox !== undefined) validateSandbox(sandbox, where, exec !== undefined)
+    out.push(mod as ProjectConfig)
   }
+  return out
 }
 
-function validateWorkspaceGlobs(v: unknown, where: string): 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`,
-      )
-    }
-  }
+export async function loadProjectConfig(
+  configPath: string,
+  opts?: LoadProjectConfigOptions,
+): Promise<ProjectConfig> {
+  const [config] = await loadProjectConfigs([configPath], opts)
+  return config!
 }
 
-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).
+ * Find and load `vx.workspace.{ts,mts,js,mjs}` from the workspace
+ * root. Returns `null` if no such file exists (the common case;
+ * the schema is fully optional). Validates the shape and throws
+ * a `UserError` on malformed input.
  */
-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'])
-const PERCENT_RE = /^\d+(\.\d+)?%$/
-
-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: '2GB' }\`)`)
-  }
-  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 } = resources as { cpus?: unknown; memory?: unknown }
-  if (cpus !== undefined) {
-    const ok =
-      typeof cpus === 'number'
-        ? Number.isFinite(cpus) && cpus >= 0
-        : typeof cpus === 'string' && PERCENT_RE.test(cpus)
-    if (!ok) {
-      throw new UserError(`${where}.cpus must be a non-negative number or a "<n>%" string`)
-    }
-  }
-  if (memory !== undefined) {
-    const ok =
-      typeof memory === 'number'
-        ? Number.isInteger(memory) && memory >= 0
-        : typeof memory === 'string' && (PERCENT_RE.test(memory) || parseSize(memory) !== null)
-    if (!ok) {
-      throw new UserError(
-        `${where}.memory must be a non-negative integer (bytes), ` +
-          `a size string like "512MB", or a "<n>%" string`,
-      )
+export async function loadWorkspaceConfig(root: string): Promise<WorkspaceConfig | null> {
+  let configPath: string | null = null
+  for (const candidate of WORKSPACE_CONFIG_FILENAMES.map((f) => path.join(root, f))) {
+    if (await Bun.file(candidate).exists()) {
+      configPath = candidate
+      break
     }
   }
-}
-
-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)`,
-    )
-  }
+  if (!configPath) return null
+  const mod = (await loadDefaultExport(configPath, 'Workspace')) as WorkspaceConfig
+  validateWorkspace(mod, configPath)
+  return mod
 }