@vzn/vx-dte 0.0.0-stage → 0.0.649

package/src/local.ts

@@ -0,0 +1,256 @@
+// `local()`: workers as processes on this machine, each in its own git
+// worktree of the working tree's tracked state, and a relay of its own on
+// loopback. For tests, demos
+// and trying a distributed run before a CI starts the workers.
+
+import { mkdtemp, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { refuseUnknownOptions, type PluginOptionKinds } from '@vzn/vx'
+import type { DteAdapter } from './plugin.js'
+
+export interface LocalOptions {
+  /** A shell line each worktree runs before its worker starts, such as `bun install`. */
+  readonly prepare?: string
+}
+
+const KEYS: PluginOptionKinds<LocalOptions> = { prepare: 'string' }
+
+export function local(options: LocalOptions = {}): DteAdapter {
+  refuseUnknownOptions('local()', options, KEYS)
+  let relay: { url: string; stop(): void } | undefined
+  let base: Promise<string> | undefined
+  let closed = false
+  const procs = new Set<Bun.Subprocess>()
+  /** A worktree add or a prepare: what close stops at once. */
+  const helpers = new Set<Bun.Subprocess>()
+  const trees: Array<{ root: string; dir: string }> = []
+  const pending = new Set<Promise<unknown>>()
+
+  // Async throughout: a run starts its workers while it shows its first rows.
+  const start = <P extends Bun.Subprocess>(p: P): P => {
+    procs.add(p)
+    void p.exited.then(() => procs.delete(p))
+    return p
+  }
+  const run = async (
+    argv: string[],
+    cwd: string,
+    env?: Record<string, string | undefined>,
+    helper = true,
+    // A prepare's reason can be on stdout: pnpm prints its install errors there.
+    stdout = false,
+  ) => {
+    const p = start(
+      Bun.spawn(argv, {
+        cwd,
+        env: env ?? process.env,
+        stdin: 'ignore',
+        stdout: stdout ? 'pipe' : 'ignore',
+        stderr: 'pipe',
+        // Its own group, which close signals whole: SIGTERM to the shell
+        // alone left the install it started writing into a removed tree.
+        detached: helper,
+      }),
+    )
+    if (helper) {
+      helpers.add(p)
+      void p.exited.then(() => helpers.delete(p))
+    }
+    const chunks: Uint8Array[] = []
+    const read = async (from: ReadableStream<Uint8Array>) => {
+      for await (const c of from) chunks.push(c)
+    }
+    const reading = Promise.all([
+      read(p.stderr),
+      p.stdout instanceof ReadableStream ? read(p.stdout) : undefined,
+    ])
+    const code = await p.exited
+    // A grandchild of `sh -c` that outlives it keeps the pipe open; what it
+    // said by then is enough.
+    await Promise.race([reading, Bun.sleep(200)])
+    return { code, err: Buffer.concat(chunks).toString() }
+  }
+  const why = reasons()
+
+  return {
+    // Each run asks for one (`vx watch` runs again): a new run, on the tree as it is now.
+    async relay() {
+      closed = false
+      relay = await loopbackRelay()
+      return relay.url
+    },
+
+    async spawn(a) {
+      const work = (async () => {
+        base ??= mkdtemp(path.join(os.tmpdir(), 'vx-dte-'))
+        const dir = path.join(await base, String(a.index))
+        if (closed) return
+        // The run's own snapshot: one taken here, after a hit restored a
+        // committed file, was another tree, and every worker was refused
+        // (2026-10-25).
+        const add = await run(
+          ['git', 'worktree', 'add', '-q', '--detach', dir, a.commit],
+          a.workspaceRoot,
+          { ...process.env, GIT_INDEX_FILE: undefined },
+        )
+        if (add.code !== 0) throw new Error(`git worktree add: ${errorLine(add.err)}`)
+        trees.push({ root: a.workspaceRoot, dir })
+        // The workspace's own place in the checkout: from the worktree's
+        // root, a workspace in a subdirectory of its repository had no
+        // `.vx/workspace` above, and every worker exited (2026-10-25).
+        const prefix = Bun.spawn(['git', 'rev-parse', '--show-prefix'], {
+          cwd: a.workspaceRoot,
+          stdout: 'pipe',
+          stderr: 'ignore',
+        })
+        const at = path.join(dir, (await new Response(prefix.stdout).text()).trim())
+        const env: Record<string, string | undefined> = { ...process.env, ...a.env }
+        // The worktree is a repository of its own: a hook's index or
+        // repository would stand in for it.
+        for (const name of GIT_REPO_ENV) delete env[name]
+        // A cache dir the workspace names, relative, would name each
+        // worktree's own store, where the run cannot read what it saved.
+        if (a.cacheDir !== undefined) env['VX_CACHE_DIR'] = a.cacheDir
+        if (options.prepare !== undefined && !closed) {
+          const p = await run(['sh', '-c', options.prepare], at, env, true, true)
+          if (p.code !== 0 && !closed)
+            throw new Error(await why(`prepare exited ${p.code}`, a.id, p.err))
+        }
+        if (closed) return
+        void run([...vx(), 'dte', 'worker'], at, env, false).then(async (r) => {
+          if (!closed) a.exited(await why(`exited ${r.code}`, a.id, r.err))
+        })
+      })()
+      pending.add(work)
+      try {
+        await work
+      } finally {
+        pending.delete(work)
+      }
+    },
+
+    async close() {
+      closed = true
+      // The relay closing the run tells each worker to leave; a prepare
+      // still running is stopped.
+      relay?.stop()
+      relay = undefined
+      for (const p of helpers) group(p, 'SIGTERM')
+      const grace = setTimeout(() => {
+        for (const p of procs) {
+          if (helpers.has(p)) group(p, 'SIGKILL')
+          else p.kill('SIGKILL')
+        }
+      }, 5_000)
+      await Promise.allSettled([...pending])
+      await Promise.all([...procs].map((p) => p.exited))
+      clearTimeout(grace)
+      // A detached shell removes the worktrees after vx exits: removing ones
+      // an install filled took seconds after a Ctrl-C (2026-10-21), and a
+      // 300k-file tree 2.7 s. `prune` then drops git's record of each.
+      const roots = [...new Set(trees.splice(0).map((t) => t.root))]
+      if (base !== undefined) {
+        const dir = await base
+        base = undefined
+        Bun.spawn(
+          [
+            'sh',
+            '-c',
+            'rm -rf "$1"; shift; for r; do git -C "$r" worktree prune; done',
+            'sh',
+            dir,
+            ...roots,
+          ],
+          { stdio: ['ignore', 'ignore', 'ignore'], detached: true },
+        ).unref()
+      }
+    },
+  }
+}
+
+/** Signal `p`'s process group: a helper leads its own (`detached`). */
+function group(p: Bun.Subprocess, signal: NodeJS.Signals): void {
+  try {
+    process.kill(-p.pid, signal)
+  } catch {
+    // quiet: the group is gone
+  }
+}
+
+/**
+ * `<what>: <its error line> (log: <path>)`, a worker's whole stderr kept at
+ * that path, which outlives the run.
+ */
+export function reasons(): (what: string, id: string, err: string) => Promise<string> {
+  let logs: Promise<string> | undefined
+  return async (what, id, err) => {
+    const line = errorLine(err)
+    if (line === '') return what
+    logs ??= mkdtemp(path.join(os.tmpdir(), 'vx-dte-logs-'))
+    const file = path.join(await logs, `${id}.log`)
+    await writeFile(file, err)
+    return `${what}: ${line} (log: ${file})`
+  }
+}
+
+/**
+ * The line of a process's stderr that says what went wrong: vx's own `✗`
+ * line, else the first naming an error or git's `fatal:`, else the last. The last alone was
+ * often a hint (`fix  vx run …`) that hid the error above it.
+ */
+export function errorLine(text: string): string {
+  const lines = Bun.stripANSI(text)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+  return (
+    lines.find((l) => l.startsWith('✗')) ??
+    lines.find((l) => /\berror\b|^fatal:/i.test(l)) ??
+    lines.at(-1) ??
+    ''
+  )
+}
+
+/** A relay of the run's own on loopback, with no auth: only this machine reaches it. */
+export async function loopbackRelay(): Promise<{ url: string; stop(): void }> {
+  const { serveRelay } = await import('@vzn/vx-dte-server')
+  const server = serveRelay({ hostname: '127.0.0.1', port: 0 })
+  return {
+    url: server.url,
+    stop() {
+      void server.stop()
+    },
+  }
+}
+
+/**
+ * What `git rev-parse --local-env-vars` names: variables that tie a
+ * process to one repository and its index. A git hook sets
+ * `GIT_INDEX_FILE` (and, in a linked worktree, `GIT_DIR`); a worktree add
+ * under them wrote its checkout to the hook's index, or failed on a
+ * relative one, and a worker read the hook's repository.
+ */
+const GIT_REPO_ENV = [
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_CONFIG',
+  'GIT_CONFIG_PARAMETERS',
+  'GIT_CONFIG_COUNT',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_IMPLICIT_WORK_TREE',
+  'GIT_GRAFT_FILE',
+  'GIT_INDEX_FILE',
+  'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE',
+  'GIT_PREFIX',
+  'GIT_SHALLOW_FILE',
+  'GIT_COMMON_DIR',
+]
+
+/** The argv that runs this vx: the binary when compiled, else Bun and its entry. */
+function vx(): string[] {
+  const compiled = Bun.main.startsWith('/$bunfs/') || Bun.main.startsWith('B:/~BUN/')
+  return compiled ? [process.execPath] : [process.execPath, Bun.main]
+}

package/src/messages.ts

@@ -0,0 +1,219 @@
+// What the orchestrator and its workers say to each other through the relay
+// (the relay never reads it): orders and status only. Every task's files
+// and output go through the workspace's cache, by the keys these name.
+
+import type { CacheFacts, CapturedChunk, ExecuteResult, SandboxConfig } from '@vzn/vx'
+
+/**
+ * A worker says what it holds every this many heartbeats, and a task's
+ * lease is three of them. Every heartbeat (2026-10-25: the fastest, not
+ * a free plan's message count): a task its worker dropped while alive
+ * goes back in 15 s, not 90.
+ */
+export const HELD_EVERY = 1
+
+/** A worker's `join` info. */
+export interface WorkerInfo {
+  readonly v: 1
+  /** `WorkerSpawn.id` (`VX_DTE_WORKER`), for a worker the run started. */
+  readonly id?: string
+  /** What its machine has (core's `machineParallelism`, `machineMemoryBytes`), not what its size says. */
+  readonly cores: number
+  readonly memory: number
+  /** Its machine's platform, `os-arch` (`linux-x64`): a task naming `exec.platforms` goes only to a worker of its platform. */
+  readonly platform?: string
+  /** Its checkout's tree: a worker with other tracked files than the run is refused. */
+  readonly tree: string
+  /** When its `vx` started, wall-clock ms: the run's trace splits its warm-up there. */
+  readonly booted?: number
+}
+
+/** A task whose files the worker restores before it runs one that needs them. */
+export interface DepOrder {
+  task: string
+  /** Where its entry is: its cache key, or the run key it was saved under. */
+  key: string
+  /** Workspace-relative. */
+  project: string
+  outputs: { files: string[]; workspaceFiles: string[] }
+}
+
+/** One task a worker is sent. */
+export interface RunOrder {
+  task: string
+  /** Its cache key, which a success with no violation is saved under; absent, uncached. */
+  key?: string
+  /** What anything else is saved under: no hit ever serves it. */
+  runKey: string
+  /**
+   * The run reads no cache (`--force`): a success is saved under `key`, which
+   * keeps an entry it holds, and under `runKey`, whose fresh bytes this run's
+   * machines restore.
+   */
+  fresh?: true
+  /** The run's probe found `key` in no cache: its upload asks the remote nothing first. */
+  absent?: true
+  /** The tasks it depends on, transitively, whose files the worker does not hold yet. */
+  deps: DepOrder[]
+  /** Workspace-relative projects inside `project`, whose files are not its outputs. */
+  nested: string[]
+  command: string
+  /** Workspace-relative, as `project` is. */
+  cwd: string
+  project: string
+  env: Record<string, string>
+  /** Its `exec.env.secret`: the names in `env` whose values its saved output masks. */
+  secret?: string[]
+  timeoutMs?: number
+  outputs: { files: string[]; workspaceFiles: string[] }
+  /** Its recorded peak: the worker starts it when that much is free. */
+  cores: number
+  memory: number
+  /**
+   * Its `exec.sandbox`, and for a cached task the projects its key answers
+   * for (workspace-relative): the worker builds the request on its own
+   * paths and OS (`sandboxRequestFor`), as its orchestrator may run another.
+   */
+  sandbox?: { config: SandboxConfig; keyed?: string[] }
+  /** Its persistent dependencies (`ServerSpec`), `cwd` workspace-relative: the worker starts each once. */
+  servers?: ServerOrder[]
+  /** The runtime probes its key includes, as the orchestrator answered them: the worker's must answer the same. */
+  runtime?: RuntimeOrder[]
+}
+
+export interface RuntimeOrder {
+  command: string
+  output: string
+  /** A `workspaceRuntime` probe, run at the root; else in `project`. */
+  workspace?: true
+}
+
+export interface ServerOrder {
+  task: string
+  command: string
+  cwd: string
+  env: Record<string, string>
+  readyWhen?: string
+  timeoutMs?: number
+  /** Its `exec.sandbox` and the projects nested in its own, workspace-relative: it starts inside it. */
+  sandbox?: { config: SandboxConfig; nested: string[] }
+}
+
+export type ToWorker =
+  /** Tasks that fit what it has free, each begun at once; `root` is swapped for the worker's in `env`. */
+  | {
+      type: 'batch'
+      root: string
+      /** `root`'s real path, as sandbox paths spell it. */
+      realRoot: string
+      tasks: RunOrder[]
+      /** The run's sandboxed tasks' `exec.sandbox`, in a worker's first batch that has a sandboxed task. */
+      sandboxes?: SandboxConfig[]
+    }
+  /** Part of an order's `deps`, ahead of the batch whose order was too long for one frame. */
+  | { type: 'deps'; task: string; deps: DepOrder[] }
+  | { type: 'cancel'; task: string }
+  /**
+   * It was taken into the run, under the name the run's output gives it,
+   * and reads the cache as the run does: its refs, and the access the
+   * run's remotes lend, for one with none of its own.
+   */
+  | {
+      type: 'welcome'
+      name: string
+      cache: CacheFacts
+    }
+  /** The run's remotes lent again, before the last tokens end. */
+  | { type: 'cache'; cache: CacheFacts }
+  | { type: 'refused'; reason: string }
+  /** The run needs it no more: it leaves. */
+  | { type: 'exit' }
+
+/**
+ * What its machine uses now: cores busy over the last second and bytes of
+ * memory in use. Each frame a worker sends carries it, so the run places
+ * by what is free, not only by what history booked (2026-10-23: "you
+ * watch instruments and play most efficient as they go").
+ */
+export interface Load {
+  readonly cpu: number
+  readonly memory: number
+  /** Cores its running tasks' process trees used over the last look: the rest of `cpu` is no task's. */
+  readonly tasks?: number
+  /**
+   * Cores busy on average since the worker started: the summary's
+   * `machine avg`. A worker sends few frames, so the run cannot average
+   * `cpu` (one that sent 3, each as a task started, read 0.6 of 2.0 used).
+   */
+  readonly avg?: number
+}
+
+export type ToOrchestrator =
+  /** It began the task. */
+  | { type: 'start'; task: string; load?: Load }
+  /** Its command is done; its outputs save now, its cores are free. */
+  | { type: 'ran'; task: string; load?: Load }
+  /** Each heartbeat while it runs any: what it runs, which renews its lease on each. */
+  | { type: 'held'; running: string[]; load?: Load }
+  /** It could not run a task it began, not a non-zero exit: a full disk, a failed unpack. */
+  | { type: 'fault'; task: string; reason: string }
+  /** It ran the task and saved it under `key`; its output is in that entry. */
+  | { type: 'end'; task: string; key: string; result: WiredResult; load?: Load }
+  /**
+   * Ahead of an `end` too long for one relay frame, some of its lists:
+   * the `end` that follows adds its own to them. One `end` with a sandboxed
+   * task's 9000 violations was over the relay's 1 MiB, and the run waited
+   * for it (2026-10-25).
+   */
+  | ({ type: 'part'; task: string } & Partial<Pick<WiredResult, PartList>>)
+
+/**
+ * A message's JSON in UTF-8 bytes, what a relay frame holds: counted in
+ * UTF-16 units, a part of CJK output sealed past the relay's 1 MiB and its
+ * result never arrived (2026-10-25).
+ */
+export const bytesOf = (body: unknown): number => Buffer.byteLength(JSON.stringify(body))
+
+/** The lists a long result sends ahead of its `end`, in parts. */
+export const PART_LISTS = ['violations', 'changed', 'removed', 'output'] as const
+export type PartList = (typeof PART_LISTS)[number]
+
+/** A result as JSON carries it: its output stays in the cache entry, and a violation's time is a string. */
+export type WiredResult = Omit<ExecuteResult, 'violations' | 'outputs' | 'stdout' | 'stderr'> & {
+  violations?: (Omit<ExecuteResult['violations'][number], 'timestamp'> & { timestamp: string })[]
+  /** The share of a core each runnable thread got on the worker while it ran (`ExecuteResult.machine.cpuShare`). */
+  cpuShare?: number
+  /** Workspace-relative upstream outputs the task removed: this machine removes them too. */
+  removed?: string[]
+  /** Dependency keys whose remote copy did not read back: this machine sends its own over them. */
+  unread?: string[]
+  /**
+   * No remote took its entry's upload (too big, a 429): its files are on
+   * that worker alone, and its output comes here in `output`.
+   */
+  unshared?: true
+  /** Its output, both streams in the order written, when `unshared`. */
+  output?: CapturedChunk[]
+}
+
+/**
+ * Names whose value is the worker's own: the orchestrator sends one only
+ * when a task's `env.define` sets it, a value its key includes.
+ */
+export const HOST_ENV = [
+  'HOME',
+  'SHELL',
+  'USER',
+  'LOGNAME',
+  'TMPDIR',
+  'TEMP',
+  'TMP',
+  'npm_execpath',
+  'PNPM_HOME',
+  'COREPACK_HOME',
+  'XDG_CONFIG_HOME',
+  'XDG_DATA_HOME',
+  'XDG_CACHE_HOME',
+  'XDG_STATE_HOME',
+  'XDG_RUNTIME_DIR',
+]