@vzn/vx 0.0.0 → 0.0.14

package/src/orchestrator/options.ts

@@ -0,0 +1,197 @@
+// Run option/summary types live in a leaf file (not the module entry)
+// so internals like prepare.ts can import them without an upward
+// import of index.ts — the module entry must stay cycle-free.
+
+import type { CachePolicy, RemoteCacheLayer } from '../cache/index.js'
+import type { ContinueMode } from '../graph/index.js'
+import type { TaskOutcome } from '../graph/index.js'
+import type { EventBus } from './events.js'
+import type { TelemetrySink } from './telemetry.js'
+import type { Logger } from './logger.js'
+
+export interface RunOptions {
+  cwd: string
+  /**
+   * Task specs to run. Each may be a bare task name (`'build'`) —
+   * applied across `projects` to every project that declares it —
+   * or an anchored `'pkg#task'` — added directly to the requested
+   * set regardless of `projects`.
+   */
+  tasks: readonly string[]
+  projects?: string[]
+  concurrency?: number
+  /**
+   * Cache directory override (`--cache-dir <path>`). Absolute, or relative
+   * to `cwd`. Takes precedence over the workspace `cacheDir` field and the
+   * `.vx/cache` default. A per-run knob — never folded into a cache key.
+   */
+  cacheDir?: string
+  /**
+   * Granular cache read/write control across the local + remote layers.
+   * Each of the four axes (localRead / localWrite / remoteRead /
+   * remoteWrite) is independent. Undefined → {@link FULL_CACHE_POLICY}
+   * (everything on). `--no-cache` sets all four false; `--force` sets
+   * both reads false (re-execute, still refresh the cache).
+   */
+  cache?: CachePolicy
+  /**
+   * CI mode: load configs FROM the committed vx-lock.json instead of
+   * evaluating them (frozen-env reproducibility). Requires the lock
+   * to exist and pass its content-hash tripwire. Local runs default
+   * to live evaluation — byte hashes can't see a config's import
+   * closure, so a strict local mode would give false confidence.
+   * Pair with `vx lock --check` in CI for the full evaluation audit.
+   */
+  frozen?: boolean
+  /**
+   * Explicit per-task output volume for the default logger. ALWAYS
+   * overrides the flow default. 'full': frames for work + one-liners
+   * for quiet hits. 'errors-only': only failed tasks print. 'none':
+   * no per-task output at all. Status lines (header, summary) always
+   * print.
+   */
+  outputLogs?: 'full' | 'errors-only' | 'none'
+  /**
+   * Run intent, derived by the CLI from selection flags: 'broad' iff
+   * `--all` / `--filter` / `--affected` was passed, else 'focused'.
+   * Drives the default logger's per-task output policy when neither
+   * `outputLogs` nor a truthy CI env overrides it. Undefined
+   * (programmatic callers) behaves like today's 'full'.
+   */
+  flow?: 'focused' | 'broad'
+  /**
+   * Run-level retry default (`--retry <n>`): max additional attempts
+   * after a failed attempt, for tasks that don't declare their own
+   * `exec.retries` (explicit config wins, including `retries: 0`).
+   * Threaded as an option only — never folded into any cache key, so
+   * the same run with and without `--retry` derives identical keys.
+   */
+  retries?: number
+  /**
+   * Cache-correctness verification (`vx run --verify`). When set, an
+   * executed + cacheable task is re-run after its save and its outputs are
+   * content-compared: a divergence means the task is non-hermetic and its
+   * cache entry is provably unsafe (see docs/design/cache-correctness).
+   * `fingerprint` computes + ships an output-tree fingerprint on executed
+   * tasks (no re-run — the cross-machine diff feed; `--verify`/`=all` set
+   * it too, for free). `allow` (from `--verify-allow=<pkg#task>,…`) exempts
+   * known-nondeterministic tasks from failing the run. A pure side-channel —
+   * never folded into a cache key; the re-run never saves. Undefined = off
+   * (a plain run is byte-identical).
+   */
+  verify?: {
+    determinism: boolean
+    inputs: boolean
+    fingerprint: boolean
+    allow: ReadonlySet<string>
+  }
+  /**
+   * Run-level default task timeout (ms), for tasks that declare no
+   * `exec.timeout`. Highest of the run-level defaults: `--timeout` /
+   * this option → `VX_TASK_TIMEOUT` env → workspace `timeout`. Per-task
+   * `exec.timeout` always wins. Threaded as an option only — never
+   * folded into any cache key (a timed-out task fails and is never
+   * cached), so a `--timeout` run cache-hits a plain run's entry.
+   */
+  timeout?: number
+  /**
+   * Memory budget (bytes) that per-task `exec.resources.memory`
+   * reservations pack against (`--memory <size>`). Defaults to
+   * `os.totalmem()` — override it in cgroup-limited containers, where
+   * totalmem() reports the HOST's RAM, not the limit. A per-run
+   * scheduling knob only — never folded into any cache key.
+   */
+  memory?: number
+  /**
+   * Failure propagation: 'never' stops dispatch on the first failure
+   * (in-flight tasks finish; everything queued skips), 'deps-ok'
+   * (default) skips only a failure's dependents, 'always' runs
+   * dependents even when an upstream failed — sound under pure-input
+   * hashing (failed outcomes carry the upstream's input key). CLI:
+   * `--continue[=never|deps-ok|always]`; bare `--continue` = 'always'.
+   */
+  continueMode?: ContinueMode
+  /**
+   * Filter `dependsOn` expansion. `'all'` drops every edge (just the
+   * requested task runs). A string array drops only those task names
+   * from both `self` and `dependencies` buckets.
+   */
+  excludeDependencies?: 'all' | readonly string[]
+  /** Forwarded to the last step of each task's exec array (shell-quoted). */
+  forwardArgs?: readonly string[]
+  /**
+   * If set, write a per-run JSON summary at end of run. Empty string
+   * picks the default path `<cacheDir>/runs/<run_id>.json`; anything
+   * else is treated as the literal file path (cwd-relative).
+   */
+  summarize?: string
+  /**
+   * If set, write a Chrome-trace JSON profile of the run's wallclock
+   * spans. Path is cwd-relative. Default `profile.json` is selected
+   * by the CLI parser, not here.
+   */
+  profile?: string
+  /**
+   * Install SIGINT/SIGTERM handlers for the run's duration: forward
+   * SIGTERM to every live child, close the cache, exit 128+signo
+   * (130/143). Default true. The watch loop disables this — it owns
+   * signal disposition for its whole lifetime and a cycle must never
+   * exit the process out from under it.
+   */
+  handleSignals?: boolean
+  log?: Logger
+  /**
+   * Inject the run's event bus. When provided, the orchestrator emits
+   * onto it instead of creating its own — letting a caller subscribe a
+   * surface (e.g. the `--ui` devframe dev server) BEFORE the run starts
+   * emitting. The terminal renderer is still attached as a subscriber, so
+   * default output is unchanged. Default: a fresh internal bus.
+   */
+  bus?: EventBus
+  /**
+   * Shared in-flight execution registry, keyed by task hash. Supplied by a
+   * long-lived service (`vx serve`) so concurrent runs DEDUP work: a task
+   * already executing for one run is awaited by another (which then
+   * restores the just-saved artifact from cache) instead of re-running.
+   * A stateless `vx run` passes none and is byte-identical to before.
+   */
+  inflight?: Map<string, Promise<void>>
+  /**
+   * `--tag k=v` pairs (Tier-3). Persisted verbatim on the run's
+   * `invocations` row (JSON object) so dashboards can filter runs by
+   * label. CLI parsing is the CLI's job; the orchestrator just records.
+   */
+  tags?: Record<string, string>
+  /**
+   * Additional observe-only telemetry sinks, merged with whatever the
+   * workspace plugins contribute. The embedder seam: a host executing
+   * runs on behalf of others (a serve recording delegated runs
+   * into its ingest store) attaches a sink without needing a workspace
+   * plugin. Undefined → zero cost, identical to before; the telemetry
+   * host's zero-sink invariant still applies when both sources are
+   * empty.
+   */
+  telemetrySinks?: readonly TelemetrySink[]
+  /**
+   * The raw command string for the `invocations` row (e.g.
+   * `'vx run build test --all'`). When absent, run() falls back to
+   * `process.argv.slice(1).join(' ')` so programmatic callers still
+   * record something useful.
+   */
+  command?: string
+  /**
+   * An injected remote cache layer — the embedder seam mirroring
+   * `telemetrySinks`: a host that already holds a wire client (a
+   * distribution agent, a serve executing on behalf of a submitter)
+   * passes it here and run() composes `LayeredCache(local, injected)`.
+   * Explicit injection WINS over the plugin `cache` capability (the
+   * host knows best; prevents double-wrapping when the workspace also
+   * declares a cache plugin). Undefined → identical to before.
+   */
+  remoteCache?: RemoteCacheLayer
+}
+
+export interface RunSummary {
+  ok: boolean
+  outcomes: TaskOutcome[]
+}

package/src/orchestrator/plan.ts

@@ -0,0 +1,129 @@
+// Planning: walk the task graph, compute every task's cache key, and
+// probe the cache to predict what would happen if `vx run` actually
+// ran. Used by `--dry-run` (preview output) and `--graph` (DOT export).
+//
+// No TASK execution happens: no task spawn, no cleanOutputs, no
+// restoreOutputs. Cache probing uses the byte-free `cache.has()`
+// existence probe (a remote layer answers with an HTTP HEAD — no
+// artifact download, no local ingest), so the plan is read-only — with
+// one deliberate exception: `cache.inputs.runtime` / `workspaceRuntime`
+// probe commands DO run, because predicting a task's key requires
+// resolving them (same as a real run). Keep runtime inputs
+// side-effect-free pure probes.
+
+import type { CacheLayer, CachePolicy, GitFilesCache } from '../cache/index.js'
+import { FULL_CACHE_POLICY } from '../cache/index.js'
+import { isGroupTask, runGraph, type TaskNode, type TaskOutcome } from '../graph/index.js'
+import { computeGroupHash, computeTaskHash } from './task-hash.js'
+
+export type CacheStatus =
+  | 'hit-local' // entry exists in local cache
+  | 'hit-remote' // entry exists in the remote layer (would be fetched)
+  | 'miss' // caching enabled but no entry — would execute
+  | 'no-cache' // task opts out of caching (no `cache` block) or --no-cache
+  | 'group' // no `exec`; just an aggregator
+
+export interface PlannedTask {
+  node: TaskNode
+  hash: string
+  cacheStatus: CacheStatus
+  /** Sorted task ids this task depends on (same as TaskNode.deps). */
+  deps: readonly string[]
+}
+
+export interface RunPlan {
+  tasks: PlannedTask[]
+}
+
+export interface PlanArgs {
+  nodes: Map<string, TaskNode>
+  workspaceRoot: string
+  workspaceFingerprint: string
+  cache: CacheLayer
+  cachePolicy?: CachePolicy
+  forwardArgs?: readonly string[] | undefined
+  nestedDirsByProject: Map<string, string[]>
+  gitFilesCache?: GitFilesCache
+  hashCache?: import('./task-hash.js').HashCache
+}
+
+/**
+ * Walk the task graph in topological order and produce a `RunPlan`.
+ * We piggyback on the existing `runGraph` scheduler with a planning
+ * `execute` closure — gets us topo ordering + upstream propagation
+ * for free. Concurrency is capped at 1 because planning is fast and
+ * sequential is easier to reason about.
+ *
+ * For each node we compute the cache key (same key the real run
+ * would) and probe `cache.has(hash)` to decide hit vs miss. The probe
+ * is a pure existence check — no artifact bytes move, no accessed_at
+ * bump, no remote download/ingest.
+ */
+export async function plan(args: PlanArgs): Promise<RunPlan> {
+  const cacheStatusById = new Map<string, CacheStatus>()
+
+  const outcomes = await runGraph({
+    nodes: args.nodes,
+    concurrency: 1,
+    execute: async (node, upstream) => {
+      if (isGroupTask(node)) {
+        cacheStatusById.set(node.id, 'group')
+        return planOutcome(node, computeGroupHash(upstream))
+      }
+
+      const hash = await computeTaskHash({
+        node,
+        upstream,
+        workspaceRoot: args.workspaceRoot,
+        workspaceFingerprint: args.workspaceFingerprint,
+        cache: args.cache,
+        forwardArgs: args.forwardArgs,
+        nestedProjectDirs: args.nestedDirsByProject.get(node.projectName) ?? [],
+        ...(args.gitFilesCache !== undefined ? { gitFilesCache: args.gitFilesCache } : {}),
+        ...(args.hashCache !== undefined ? { hashCache: args.hashCache } : {}),
+      })
+
+      // Prediction keys off READS: a no-read policy (--no-cache /
+      // --force / --cache=local:,remote:) would re-execute every task,
+      // so we predict misses for it. The probe below routes through the
+      // policy-aware cache layer, which itself respects local/remote
+      // read gating.
+      const policy = args.cachePolicy ?? FULL_CACHE_POLICY
+      const cacheEnabled =
+        node.config.cache !== undefined && (policy.localRead || policy.remoteRead)
+      let status: CacheStatus
+      if (!cacheEnabled) {
+        status = 'no-cache'
+      } else {
+        const where = await args.cache.has(hash)
+        status = where === null ? 'miss' : where === 'remote' ? 'hit-remote' : 'hit-local'
+      }
+      cacheStatusById.set(node.id, status)
+      return planOutcome(node, hash)
+    },
+  })
+
+  const tasks: PlannedTask[] = []
+  for (const id of args.nodes.keys()) {
+    const o = outcomes.get(id)
+    const node = args.nodes.get(id)
+    if (!o || !node) continue
+    tasks.push({
+      node,
+      hash: o.hash ?? '',
+      cacheStatus: cacheStatusById.get(id) ?? 'no-cache',
+      deps: node.deps,
+    })
+  }
+  return { tasks }
+}
+
+function planOutcome(node: TaskNode, hash: string): TaskOutcome {
+  return {
+    node,
+    status: 'success',
+    exitCode: 0,
+    durationMs: 0,
+    hash,
+  }
+}

package/src/orchestrator/plugin-host.ts

@@ -0,0 +1,185 @@
+// Plugin consultation for the three run-level extension points
+// (backend / cache / eventSink). Each function asks the declared plugins
+// in order and falls back to today's exact default, so a workspace with
+// no capability plugin is byte-identical to before the inversion.
+//
+// See docs/design/core-cloud-split-2026-06.md §5.1.
+
+import type { Cache, CacheLayer } from '../cache/index.js'
+import { UserError } from '../util/index.js'
+import type { EventBus } from './events.js'
+import { wireForwarder } from './events.js'
+import type { Logger } from './logger.js'
+import type {
+  BackendContext,
+  CacheContext,
+  EventSink,
+  EventSinkContext,
+  VxPlugin,
+} from './plugin.js'
+import type { RunBackend } from './protocol.js'
+
+/**
+ * Run a capability factory with crash isolation. A throw becomes a clean
+ * `UserError` naming the plugin + hook for the load-bearing capabilities
+ * (`backend`/`cache`/`setup`) — a broken backend or cache must abort with
+ * a clear message, never silently degrade. For `eventSink` the caller
+ * logs-and-skips instead (observability must never break a run).
+ */
+async function safe<T>(plugin: VxPlugin, hook: string, fn: () => T | Promise<T>): Promise<T> {
+  try {
+    return await fn()
+  } catch (err) {
+    throw new UserError(
+      `plugin '${plugin.name}' failed in ${hook}: ${err instanceof Error ? err.message : String(err)}`,
+    )
+  }
+}
+
+/**
+ * Resolve the run backend. First plugin returning a non-undefined
+ * `backend` wins (declaration order); otherwise the caller's `fallback`
+ * (today's local/serve env-probe). A broken backend factory aborts.
+ */
+export async function resolveBackend(
+  plugins: readonly VxPlugin[],
+  ctx: BackendContext,
+  fallback: () => Promise<RunBackend>,
+): Promise<RunBackend> {
+  for (const plugin of plugins) {
+    if (plugin.backend === undefined) continue
+    const backend = await safe(plugin, 'backend', () => plugin.backend!(ctx))
+    if (backend !== undefined) return backend
+  }
+  return await fallback()
+}
+
+/**
+ * Resolve the cache layer. First plugin returning a non-undefined `cache`
+ * wins; otherwise the caller's `fallback` (the plain local cache — core
+ * ships no wire client; a remote layer comes from a plugin or from
+ * `RunOptions.remoteCache`). A broken cache factory aborts.
+ */
+export async function resolveCache(
+  plugins: readonly VxPlugin[],
+  _localCache: Cache,
+  ctx: CacheContext,
+  _log: Logger,
+  fallback: () => CacheLayer,
+): Promise<CacheLayer> {
+  for (const plugin of plugins) {
+    if (plugin.cache === undefined) continue
+    const cache = await safe(plugin, 'cache', () => plugin.cache!(ctx))
+    if (cache !== undefined) return cache
+  }
+  return fallback()
+}
+
+export interface SubscribedEventSinks {
+  /** Removes every bus subscription. Called in run()'s finally. */
+  dispose(): void
+  /** The installed sinks (with the owning plugin's name for warnings),
+   *  so run() can await each sink's `flush()` at end-of-run. */
+  sinks: ReadonlyArray<{ pluginName: string; sink: EventSink }>
+}
+
+/**
+ * Subscribe every plugin's `eventSink` to the bus via `wireForwarder`,
+ * each isolated so a throwing sink can never break the run. Additive: with
+ * no eventSink plugin nothing subscribes and behavior is unchanged.
+ * Returns the disposer plus the installed sinks (for the end-of-run flush).
+ */
+export async function subscribeEventSinks(
+  plugins: readonly VxPlugin[],
+  bus: EventBus,
+  ctx: EventSinkContext,
+): Promise<SubscribedEventSinks> {
+  const disposers: Array<() => void> = []
+  const sinks: Array<{ pluginName: string; sink: EventSink }> = []
+  for (const plugin of plugins) {
+    if (plugin.eventSink === undefined) continue
+    let sink
+    try {
+      sink = await plugin.eventSink(ctx)
+    } catch (err) {
+      ctx.warn(
+        `[vx] plugin '${plugin.name}' eventSink failed to initialize; disabled for this run: ${err instanceof Error ? err.message : String(err)}`,
+      )
+      continue
+    }
+    if (sink === undefined) continue
+    sinks.push({ pluginName: plugin.name, sink })
+    disposers.push(
+      bus.subscribe(
+        wireForwarder((event) => {
+          try {
+            sink.onEvent(event)
+          } catch {
+            // observability is isolated — a sink fault can't break the run
+          }
+        }),
+      ),
+    )
+  }
+  return {
+    dispose: () => {
+      for (const dispose of disposers) dispose()
+    },
+    sinks,
+  }
+}
+
+/** Upper bound on each teardown()/flush() await — a wedged plugin must
+ *  not hold the run's exit hostage. */
+const TEARDOWN_TIMEOUT_MS = 3000
+
+async function settleWithin(p: Promise<unknown>, ms: number): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, ms)
+  })
+  try {
+    await Promise.race([p, deadline])
+  } finally {
+    clearTimeout(timer)
+    // A rejection landing after the deadline won already resolved the
+    // race must not surface as an unhandled-rejection crash.
+    void p.catch(() => {})
+  }
+}
+
+/**
+ * End-of-run plugin lifecycle: await each event sink's optional
+ * `flush()` (its last chance to ship buffered records), then each
+ * plugin's optional `teardown()`. Crash-isolated — a throwing
+ * flush/teardown is logged and skipped, never propagated — and each
+ * call is time-bounded at {@link TEARDOWN_TIMEOUT_MS}. Runs on the
+ * normal completion path only; the finally-path disposers just
+ * unsubscribe.
+ */
+export async function teardownPlugins(
+  plugins: readonly VxPlugin[],
+  sinks: ReadonlyArray<{ pluginName: string; sink: EventSink }>,
+  warn: (message: string) => void,
+): Promise<void> {
+  for (const { pluginName, sink } of sinks) {
+    if (sink.flush === undefined) continue
+    try {
+      await settleWithin(Promise.resolve(sink.flush()), TEARDOWN_TIMEOUT_MS)
+    } catch (err) {
+      warn(
+        `[vx] plugin '${pluginName}' event sink flush failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  }
+  for (const plugin of plugins) {
+    if (plugin.teardown === undefined) continue
+    try {
+      await settleWithin(Promise.resolve(plugin.teardown()), TEARDOWN_TIMEOUT_MS)
+    } catch (err) {
+      warn(
+        `[vx] plugin '${plugin.name}' teardown failed: ${err instanceof Error ? err.message : String(err)}`,
+      )
+    }
+  }
+}