@sibylline-labs/eris 0.0.0-stage → 0.3.0

package/src/runtime/logging.ts

@@ -0,0 +1,43 @@
+/**
+ * logging.ts — the four diagnostics, as the earlier Bash implementation
+ * printed them:
+ *
+ *   eris::die()  { printf 'ERROR %s\n' "$1" >&2; exit 1; }
+ *   eris::warn() { printf 'WARN %s\n'  "$1" >&2; }
+ *   eris::info() { printf 'INFO %s\n'  "$1" >&2; }
+ *   eris::ok()   { printf 'INFO ✓ %s\n' "$1" >&2; }
+ *
+ * Byte-identical, stderr only, unconditional (no TTY or colour branch): this
+ * is the `LEVEL<space>message` shape docs/OUTPUT-CONTRACT.md §1/§4 pins and
+ * consumers line-prefix-parse. `tests/runtime-logging.test.ts` holds every
+ * function to those bytes. The sink is injectable for tests; it defaults to
+ * process.stderr and is NEVER stdout.
+ */
+
+export interface LogSink {
+  write(chunk: string): unknown;
+}
+
+export type ExitFn = (code: number) => never;
+
+const defaultExit: ExitFn = (code) => process.exit(code);
+
+export function warn(msg: string, sink: LogSink = process.stderr): void {
+  sink.write(`WARN ${msg}\n`);
+}
+
+export function info(msg: string, sink: LogSink = process.stderr): void {
+  sink.write(`INFO ${msg}\n`);
+}
+
+export function ok(msg: string, sink: LogSink = process.stderr): void {
+  sink.write(`INFO ✓ ${msg}\n`);
+}
+
+/** `eris::die` — the ERROR line, then exit 1. Prefer `emitFailureAndExit`
+ *  (ts/lib/eris-fail.ts) for anything an operator must act on: an unslugged
+ *  die carries no `slug:`/`docs:` pointer. */
+export function die(msg: string, sink: LogSink = process.stderr, exit: ExitFn = defaultExit): never {
+  sink.write(`ERROR ${msg}\n`);
+  return exit(1);
+}

package/src/runtime/process.ts

@@ -0,0 +1,388 @@
+/**
+ * process.ts — the subprocess adapter.
+ *
+ * Every external binary the TS side runs goes through a `Runner`, so tests
+ * inject a fake (`createFakeRunner`, testing/fake-runner.ts) instead of stubbing
+ * PATH, and the safety rules live in ONE place:
+ *
+ *   - argv arrays only, never a shell string (`shell` is never set).
+ *   - stdout/stderr captured as Buffers. The ONLY stderr a result exposes is
+ *     the one passed through `redact`, so a caller echoing it into a failure
+ *     block cannot leak what the hook removes (a tool's `--log-http` mode
+ *     streams request bodies to stderr).
+ *   - `BUN_CONFIG_VERBOSE_FETCH` is stripped from every child env: under it
+ *     bun prints request bodies and `Authorization` headers to stderr.
+ *   - an explicit timeout on every call; on expiry the WHOLE tree dies.
+ *   - the result distinguishes ok / exit / signal / timeout / spawn-failed,
+ *     so "could not tell" never reads as a clean non-zero.
+ *
+ * WHY THE TREE IS ENUMERATED:
+ * a child spawned `detached` leads its own process group, but that is not
+ * sufficient — any wrapped tool may `setpgid` into a group of its own (GNU
+ * `timeout` does), and a group kill cannot reach it. It then reparents to
+ * PID 1 holding the capture pipe, and the reader never sees EOF. So the tree
+ * is read out of ONE `ps` snapshot taken BEFORE the first signal (a killed
+ * parent's children reparent within milliseconds and become unreachable by
+ * ppid), and every group found is signalled except our own, then every pid.
+ * TERM first; KILL after `killGraceMs`; and if the pipes still have not closed
+ * after that, they are destroyed and the result says so (`forcedClose`), so
+ * the call always settles and a leaked kill is never reported as clean.
+ *
+ * WHY A SIGNAL REGISTRY: a `detached` child is outside the terminal's
+ * foreground group, so a Ctrl-C no longer reaches it — bun would die and the
+ * child would run on under PID 1 holding the pipe (an orphan seen in practice). While
+ * any child is live, SIGINT/SIGTERM/SIGHUP are forwarded to every tracked
+ * tree, and when ours is the only listener the signal is re-raised so the
+ * default 128+n death is preserved. `detached: false` opts out, for a child
+ * that must share the caller's group and owns its own signal handling.
+ */
+
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { resolveConcurrency, runPool } from "../../ts/lib/pool";
+
+export interface RunOptions {
+  /** Hard deadline in ms. Required: an unbounded wait is how CLIs hang. */
+  timeoutMs: number;
+  /** TERM → KILL escalation delay once the deadline fires. Default 2000. */
+  killGraceMs?: number;
+  cwd?: string;
+  /** Child env. Defaults to process.env. BUN_CONFIG_VERBOSE_FETCH is always removed. */
+  env?: Record<string, string | undefined>;
+  /** Written to the child's stdin, which is then closed. Absent → stdin is /dev/null. */
+  input?: string | Buffer;
+  /** Applied to captured stderr before it is exposed on the result. */
+  redact?: (stderr: string) => string;
+  /** Own process group (default true). See the file header before turning it off. */
+  detached?: boolean;
+}
+
+interface Captured {
+  stdout: Buffer;
+  /** Already redacted. There is no raw copy. */
+  stderr: Buffer;
+}
+
+export type RunResult =
+  | (Captured & { kind: "ok"; code: 0 })
+  | (Captured & { kind: "exit"; code: number })
+  | (Captured & { kind: "signal"; signal: string })
+  | (Captured & {
+      kind: "timeout";
+      timeoutMs: number;
+      /** TERM was not enough; the tree was sent KILL. */
+      escalated: boolean;
+      /** The pipes were still open after KILL and were destroyed. Something
+       *  outside the enumerated tree may still hold them. */
+      forcedClose: boolean;
+    })
+  | (Captured & { kind: "spawn-failed"; errno: string; message: string });
+
+export interface Runner {
+  run(argv: readonly string[], opts: RunOptions): Promise<RunResult>;
+}
+
+const STRIPPED_ENV = ["BUN_CONFIG_VERBOSE_FETCH"];
+const FORCE_CLOSE_MS = 1000;
+
+export function childEnv(env: Record<string, string | undefined> = process.env): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (v !== undefined && !STRIPPED_ENV.includes(k)) out[k] = v;
+  }
+  return out;
+}
+
+// --- tree enumeration -------------------------------------------------------------
+
+interface PsRow {
+  pid: number;
+  ppid: number;
+  pgid: number;
+}
+
+/** (pid, ppid, pgid) for every process — POSIX `ps`, same columns on procps
+ *  and BSD. Empty on failure (the caller falls back to the roots alone). */
+function psSnapshot(): PsRow[] {
+  const r = spawnSync("ps", ["-A", "-o", "pid=,ppid=,pgid="], { encoding: "utf8" });
+  if (r.status !== 0 || typeof r.stdout !== "string") return [];
+  const rows: PsRow[] = [];
+  for (const line of r.stdout.split("\n")) {
+    const [pid, ppid, pgid] = line.trim().split(/\s+/).map(Number);
+    if (pid && ppid !== undefined && pgid !== undefined && !Number.isNaN(ppid) && !Number.isNaN(pgid)) {
+      rows.push({ pid, ppid, pgid });
+    }
+  }
+  return rows;
+}
+
+/** Every pid in the subtrees rooted at `roots` (roots included). */
+function subtree(rows: PsRow[], roots: Iterable<number>): Set<number> {
+  const all = new Set(roots);
+  let frontier = new Set(all);
+  while (frontier.size > 0) {
+    const next = new Set<number>();
+    for (const row of rows) {
+      if (frontier.has(row.ppid) && !all.has(row.pid)) {
+        all.add(row.pid);
+        next.add(row.pid);
+      }
+    }
+    frontier = next;
+  }
+  return all;
+}
+
+function trySignal(target: number, sig: NodeJS.Signals): void {
+  try {
+    process.kill(target, sig);
+  } catch {
+    // Already gone (ESRCH) or not ours (EPERM): nothing to reap.
+  }
+}
+
+/**
+ * Signal every process in the trees rooted at `roots`, plus `known` pids
+ * enumerated earlier (they may have reparented to PID 1 since). Groups first
+ * (reaching anything spawned into a target's group after the snapshot), never
+ * our own group or 0/1; then every pid. Returns the pids it found, for a later
+ * escalation to include.
+ */
+export function signalTree(
+  roots: Iterable<number>,
+  sig: NodeJS.Signals | readonly NodeJS.Signals[],
+  known: Iterable<number> = [],
+): Set<number> {
+  const sigs = typeof sig === "string" ? [sig] : sig;
+  const rows = psSnapshot();
+  const live = new Set(rows.map((r) => r.pid));
+  const targets = subtree(rows, roots);
+  for (const pid of known) if (live.has(pid)) targets.add(pid);
+  if (rows.length === 0) {
+    for (const pid of roots) targets.add(pid);
+  }
+  const selfPgid = rows.find((r) => r.pid === process.pid)?.pgid;
+  const groups = new Set<number>();
+  for (const row of rows) if (targets.has(row.pid)) groups.add(row.pgid);
+  for (const s of sigs) {
+    for (const g of groups) {
+      if (g > 1 && g !== selfPgid) trySignal(-g, s);
+    }
+    for (const pid of targets) if (pid > 1 && pid !== process.pid) trySignal(pid, s);
+  }
+  return targets;
+}
+
+// --- live-child registry (signal forwarding) --------------------------------------
+
+const FORWARDED: NodeJS.Signals[] = ["SIGINT", "SIGTERM", "SIGHUP"];
+const liveRoots = new Set<number>();
+const handlers = new Map<NodeJS.Signals, () => void>();
+let exitHook: (() => void) | undefined;
+
+const SIGNAL_GRACE_MS = 1000;
+let pending: { sig: NodeJS.Signals; known: Set<number>; timer: ReturnType<typeof setTimeout> } | undefined;
+
+/**
+ * Forward the signal AND a TERM to every tracked tree: a background job in a
+ * non-interactive bash runs with SIGINT ignored, so the signal alone leaves
+ * exactly the orphan this exists to prevent (observed: a `perl … &` grandchild
+ * survived a forwarded SIGINT). Then give the trees `SIGNAL_GRACE_MS` to close
+ * — their `run` calls settle normally — KILL whatever is left, and, when ours
+ * is the only listener, re-raise so the caller dies by the default 128+n. A
+ * second signal during the grace escalates immediately.
+ */
+function onSignal(sig: NodeJS.Signals): void {
+  if (pending) {
+    finishSignal();
+    return;
+  }
+  const known = signalTree(liveRoots, sig === "SIGTERM" ? ["SIGTERM"] : [sig, "SIGTERM"]);
+  pending = { sig, known, timer: setTimeout(finishSignal, SIGNAL_GRACE_MS) };
+  if (liveRoots.size === 0) finishSignal();
+}
+
+function finishSignal(): void {
+  if (!pending) return;
+  const { sig, known, timer } = pending;
+  pending = undefined;
+  clearTimeout(timer);
+  signalTree(liveRoots, "SIGKILL", known);
+  if (process.listenerCount(sig) === 1 && handlers.get(sig)) {
+    // Ours is the only listener: restore the default disposition and die by
+    // the same signal, so the caller sees 128+n exactly as without us.
+    uninstall();
+    process.kill(process.pid, sig);
+    return;
+  }
+  if (liveRoots.size === 0) uninstall();
+}
+
+function install(): void {
+  if (handlers.size > 0) return;
+  for (const sig of FORWARDED) {
+    const h = () => onSignal(sig);
+    handlers.set(sig, h);
+    process.on(sig, h);
+  }
+  exitHook = () => {
+    if (liveRoots.size > 0) signalTree(liveRoots, "SIGTERM");
+  };
+  process.on("exit", exitHook);
+}
+
+function uninstall(): void {
+  for (const [sig, h] of handlers) process.removeListener(sig, h);
+  handlers.clear();
+  if (exitHook) process.removeListener("exit", exitHook);
+  exitHook = undefined;
+}
+
+function track(pid: number): void {
+  liveRoots.add(pid);
+  install();
+}
+
+/** `pid` is undefined for a run that never produced a child (spawn failed): it only disarms. */
+function untrack(pid: number | undefined): void {
+  if (pid !== undefined) liveRoots.delete(pid);
+  if (liveRoots.size > 0) return;
+  if (pending) finishSignal();
+  else uninstall();
+}
+
+// --- the real runner ---------------------------------------------------------------
+
+export const nodeRunner: Runner = {
+  run(argv, opts) {
+    return new Promise<RunResult>((resolveResult) => {
+      const [cmd, ...args] = argv;
+      const detached = opts.detached ?? true;
+      const out: Buffer[] = [];
+      const err: Buffer[] = [];
+      const captured = (): Captured => ({
+        stdout: Buffer.concat(out),
+        // Decode only when there is a hook: an identity round-trip through
+        // UTF-8 would rewrite non-UTF-8 bytes.
+        stderr: opts.redact
+          ? Buffer.from(opts.redact(Buffer.concat(err).toString("utf8")), "utf8")
+          : Buffer.concat(err),
+      });
+
+      let settled = false;
+      let child: ChildProcess;
+      const timers: ReturnType<typeof setTimeout>[] = [];
+      let timedOut = false;
+      let escalated = false;
+      let forcedClose = false;
+      let enumerated = new Set<number>();
+
+      const settle = (r: RunResult) => {
+        if (settled) return;
+        settled = true;
+        for (const t of timers) clearTimeout(t);
+        untrack(child?.pid);
+        resolveResult(r);
+      };
+
+      if (!cmd) {
+        settle({ kind: "spawn-failed", errno: "EINVAL", message: "empty argv", ...captured() });
+        return;
+      }
+
+      // Armed BEFORE the spawn: the child is running from inside spawn(), which
+      // can take milliseconds to return on a cold process, and a signal in that
+      // window would find no handler and kill us by the default disposition,
+      // orphaning the tree. A JS handler only runs once the synchronous
+      // spawn + track below has finished, so a signal never sees a live child
+      // that is not yet tracked. A spawn that yields no pid (ENOENT) stays armed
+      // with nothing tracked until its `error` settles; a signal in that gap
+      // takes finishSignal's no-live-roots path, which re-raises it.
+      install();
+      try {
+        child = spawn(cmd, args, {
+          cwd: opts.cwd,
+          env: childEnv(opts.env ?? process.env),
+          stdio: [opts.input !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
+          detached,
+        });
+      } catch (e) {
+        const ex = e as NodeJS.ErrnoException;
+        settle({ kind: "spawn-failed", errno: ex.code ?? "UNKNOWN", message: ex.message, ...captured() });
+        return;
+      }
+
+      child.stdout?.on("data", (d: Buffer) => out.push(d));
+      child.stderr?.on("data", (d: Buffer) => err.push(d));
+      if (child.pid) track(child.pid);
+
+      child.on("error", (e: NodeJS.ErrnoException) => {
+        // A spawn failure fires `error` (then `close`); an error after a
+        // successful spawn is left to `close`, which still reports the exit.
+        if (!child.pid) settle({ kind: "spawn-failed", errno: e.code ?? "UNKNOWN", message: e.message, ...captured() });
+      });
+
+      child.on("close", (code, signal) => {
+        if (timedOut) {
+          settle({ kind: "timeout", timeoutMs: opts.timeoutMs, escalated, forcedClose, ...captured() });
+        } else if (signal) {
+          settle({ kind: "signal", signal, ...captured() });
+        } else if (code === 0) {
+          settle({ kind: "ok", code: 0, ...captured() });
+        } else if (code !== null) {
+          settle({ kind: "exit", code, ...captured() });
+        }
+      });
+
+      if (opts.input !== undefined && child.stdin) {
+        child.stdin.on("error", () => {}); // EPIPE when the child ignores stdin
+        child.stdin.end(opts.input);
+      }
+
+      const pid = child.pid;
+      timers.push(
+        setTimeout(() => {
+          if (settled || !pid) return;
+          timedOut = true;
+          enumerated = signalTree([pid], "SIGTERM");
+          timers.push(
+            setTimeout(() => {
+              if (settled) return;
+              escalated = true;
+              enumerated = signalTree([pid], "SIGKILL", enumerated);
+              timers.push(
+                setTimeout(() => {
+                  if (settled) return;
+                  forcedClose = true;
+                  child.stdout?.destroy();
+                  child.stderr?.destroy();
+                  settle({ kind: "timeout", timeoutMs: opts.timeoutMs, escalated, forcedClose, ...captured() });
+                }, FORCE_CLOSE_MS),
+              );
+            }, opts.killGraceMs ?? 2000),
+          );
+        }, opts.timeoutMs),
+      );
+    });
+  },
+};
+
+// --- fan-out -------------------------------------------------------------
+
+export interface RunJob {
+  argv: readonly string[];
+  opts: RunOptions;
+}
+
+/**
+ * Run `jobs` at most N in flight, results in input order. N is
+ * `ERIS_BATCH_CONCURRENCY`, CLAMPED to 8 when unset/invalid (ts/lib/pool.ts)
+ * — a typo must never turn a batch into an unbounded fan-out.
+ */
+export function runMany(
+  jobs: readonly RunJob[],
+  opts: { runner?: Runner; env?: Record<string, string | undefined> } = {},
+): Promise<RunResult[]> {
+  const runner = opts.runner ?? nodeRunner;
+  const env = opts.env ?? process.env;
+  return runPool(jobs, resolveConcurrency(env.ERIS_BATCH_CONCURRENCY), (job) => runner.run(job.argv, job.opts));
+}

package/src/runtime/settings.ts

@@ -0,0 +1,191 @@
+/**
+ * settings.ts — `~/.eris/settings.json`, the operator's standing environment.
+ *
+ *   {
+ *     "source": ["~/creds/.dev-credentials"],
+ *     "env":    { "API_TOKEN": "${API_EDITOR_TOKEN}" },
+ *     "unset":  ["READ_ONLY_TOKEN"]
+ *   }
+ *
+ * The three keys are the file form of
+ * `set -a; source <file>; set +a; env -u <NAME> NAME=value … eris`:
+ *
+ *   - `source` — files of `KEY=value` lines (`export` prefix, `#` comments, single
+ *     or double quotes, `$VAR` / `${VAR}` outside single quotes), read in order,
+ *     a later file winning. They are PARSED, never executed: a command
+ *     substitution stays literal text.
+ *   - `env` — entries over the sourced values, each value `${VAR}`-expanded
+ *     against the environment as it will be (caller first, then the settings
+ *     resolved so far). An unset reference expands to "", as in a shell.
+ *   - `unset` — names removed from the result, the caller's own value INCLUDED:
+ *     it exists to drop a variable a shell profile exports.
+ *
+ * `source` and `env` fill only variables the caller left UNSET; a variable in the
+ * environment wins, an empty one included. The router applies the result to its
+ * own process before routing, so a TS verb and every child it spawns see the
+ * same values.
+ *
+ * Fail-open: a missing settings file is silence; an unreadable or malformed one,
+ * a missing source file, an unparseable line, a non-string value and a DENIED name
+ * are each one stderr warning and skipped — never a refusal. Warnings name files,
+ * line numbers and keys, never a value. Denied: `BUN_CONFIG_VERBOSE_FETCH` (bun
+ * would print bearers and secret bodies, see the `eris` shim) and the router's
+ * own `_ERIS_*` handover.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readEnv } from "./env";
+
+type Env = Record<string, string | undefined>;
+type Warn = (msg: string) => void;
+
+export interface Settings {
+  source: string[];
+  env: Record<string, string>;
+  unset: string[];
+}
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function home(env: Env): string {
+  return env.HOME || homedir();
+}
+
+export function settingsPath(env: Env): string {
+  return join(home(env), ".eris", "settings.json");
+}
+
+function denied(name: string): boolean {
+  return name === "BUN_CONFIG_VERBOSE_FETCH" || name.startsWith("_ERIS_");
+}
+
+/** `$VAR` and `${VAR}` against `lookup`; an unset name expands to "". */
+export function expand(value: string, lookup: (name: string) => string | undefined): string {
+  return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, a, b) => lookup(a ?? b) ?? "");
+}
+
+function stringList(doc: Record<string, unknown>, key: string, path: string, warn: Warn): string[] {
+  const raw = doc[key];
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) {
+    warn(`${path}: "${key}" must be a list of strings — ignored`);
+    return [];
+  }
+  return raw.filter((v, i) => {
+    if (typeof v === "string") return true;
+    warn(`${path}: ${key}[${i}] is not a string — skipped`);
+    return false;
+  });
+}
+
+/** The validated settings document, or an empty one when there is none to use. */
+export function readSettings(path: string, warn: Warn): Settings {
+  const none: Settings = { source: [], env: {}, unset: [] };
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "ENOENT") warn(`ignoring ${path}: ${(e as Error).message}`);
+    return none;
+  }
+  let doc: unknown;
+  try {
+    doc = JSON.parse(text);
+  } catch (e) {
+    warn(`ignoring ${path}: not valid JSON (${(e as Error).message})`);
+    return none;
+  }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+    warn(`ignoring ${path}: expected a JSON object`);
+    return none;
+  }
+  const d = doc as Record<string, unknown>;
+  const env: Record<string, string> = {};
+  if (d.env !== undefined) {
+    if (d.env === null || typeof d.env !== "object" || Array.isArray(d.env)) {
+      warn(`${path}: "env" must be an object of strings — ignored`);
+    } else {
+      for (const [k, v] of Object.entries(d.env)) {
+        if (denied(k)) warn(`${path}: env.${k} is not settable here — skipped`);
+        else if (typeof v !== "string") warn(`${path}: env.${k} is not a string — skipped`);
+        else env[k] = v;
+      }
+    }
+  }
+  const unset = stringList(d, "unset", path, warn).filter((k) => {
+    if (!denied(k)) return true;
+    warn(`${path}: unset ${k} is not allowed here — skipped`);
+    return false;
+  });
+  return { source: stringList(d, "source", path, warn), env, unset };
+}
+
+/** One sourced file's assignments, in order. Values are expanded by the caller's
+ *  `lookup` as each line is read, so a line can use one assigned above it. */
+export function parseEnvFile(
+  text: string,
+  path: string,
+  lookup: (name: string) => string | undefined,
+  warn: Warn,
+): [string, string][] {
+  const out: [string, string][] = [];
+  const local = new Map<string, string>();
+  const see = (n: string) => (local.has(n) ? local.get(n) : lookup(n));
+  text.split(/\r?\n/).forEach((raw, i) => {
+    const line = raw.trim().replace(/^export\s+/, "");
+    if (line === "" || line.startsWith("#")) return;
+    const eq = line.indexOf("=");
+    const key = eq > 0 ? line.slice(0, eq) : "";
+    if (!NAME.test(key)) {
+      warn(`${path}:${i + 1}: not a KEY=value line — skipped`);
+      return;
+    }
+    let rest = line.slice(eq + 1);
+    let value: string;
+    const q = rest[0];
+    if (q === "'" || q === '"') {
+      const end = rest.indexOf(q, 1);
+      if (end < 0) {
+        warn(`${path}:${i + 1}: unterminated quote — skipped`);
+        return;
+      }
+      value = rest.slice(1, end);
+      if (q === '"') value = expand(value.replace(/\\(["\\$`])/g, "$1"), see);
+    } else {
+      rest = rest.replace(/\s+#.*$/, "").trim();
+      value = expand(rest, see);
+    }
+    local.set(key, value);
+    out.push([key, value]);
+  });
+  return out;
+}
+
+/** Apply the settings file to `env`, in place. */
+export function applySettings(env: Env, warn: Warn): void {
+  const path = settingsPath(env);
+  const s = readSettings(path, warn);
+  const layer: Record<string, string> = {};
+  const lookup = (n: string) => readEnv(env, n) ?? readEnv(layer, n);
+  for (const src of s.source) {
+    const file = src.startsWith("~/") ? join(home(env), src.slice(2)) : src;
+    let text: string;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch (e) {
+      warn(`${path}: source ${file}: ${(e as NodeJS.ErrnoException).code ?? (e as Error).message} — skipped`);
+      continue;
+    }
+    for (const [k, v] of parseEnvFile(text, file, lookup, warn)) {
+      if (denied(k)) warn(`${file}: ${k} is not settable here — skipped`);
+      else layer[k] = v;
+    }
+  }
+  for (const [k, v] of Object.entries(s.env)) layer[k] = expand(v, lookup);
+  for (const [k, v] of Object.entries(layer)) {
+    if (readEnv(env, k) === undefined) env[k] = v;
+  }
+  for (const k of s.unset) delete env[k];
+}

package/src/sdk.ts

@@ -0,0 +1,62 @@
+/**
+ * sdk.ts — `eris/sdk`, the one module through which another repository reaches
+ * core: a distribution's entry, its plugins and the libraries they share
+ * (docs/dev/PLUGINS.md#distributions). The package's `exports` map names it,
+ * `eris/sdk/testing` (the test helpers, testing/, which this module does not
+ * export, so no binary carries them), `eris/yak-contract` (the Yaks wire
+ * contract, a workspace package of its own rather than core), `eris/yak-redact`
+ * (the client's redaction pass, plugins/yak/yak-redact.ts, which imports
+ * nothing) and nothing deeper, so a core file can move without breaking a
+ * distribution.
+ *
+ * What it carries:
+ *
+ *   - the plugin SDK (src/cli/plugin.ts): `definePlugin`, `readArgs`,
+ *     `groupArgs` (over a plugin's own rows), `readEnv`, the failure block;
+ *   - composition: core's rows (`REGISTRY`) and handlers (`HANDLERS`), this
+ *     build's plugin list (`PLUGINS`), `composeCli` and its `menu` option, and
+ *     `RELEASE_UPDATE`, the in-place `eris update` a distribution that
+ *     publishes binaries composes in place of core's;
+ *   - the program: `runProgram({ cli })`, a distribution's process entry, and
+ *     `main`, the seam a test drives;
+ *   - argv and output helpers a handler shares with core's verbs, the global
+ *     `--output` pre-pass (`parseGlobal`, `GlobalFlagError`) included;
+ *   - the runtime: subprocesses (the only way eris spawns), the bounded pool
+ *     (`runPool`, and the `ERIS_BATCH_*` readers), the diagnostics, the
+ *     install root, and the build's identity (`BUILD_ID`, `releaseRepo()`, the
+ *     `DistributionIdentity` that `build()` and `runProgram` take);
+ *   - `build()`, which compiles a distribution (src/build.ts), loaded on its
+ *     first call so a plugin manifest importing this module stays light on the
+ *     completion path.
+ *
+ * This package's own plugins import src/cli/plugin.ts, not this module.
+ */
+
+import type { BuildOptions, BuildResult } from "./build";
+
+export * from "./cli/plugin";
+export type { VerbPath } from "./cli/registry";
+export { flagsOf, REGISTRY, rowsOfGroup } from "./cli/registry";
+export type { ArgError, SubOf } from "./cli/args";
+export { argErrorWhat, GlobalFlagError, parseGlobal, readVerbArgs, refuseArg, usageLine } from "./cli/args";
+export { sanitizeDisplay } from "./cli/output";
+export { onPath } from "./cli/ts-verb";
+export { RELEASE_UPDATE } from "./cli/commands/update/opt-in";
+export type { Cli, ComposeOptions, Session } from "./cli/compose";
+export { composeCli, NO_ENTITLEMENTS, PluginCompositionError } from "./cli/compose";
+export type { MainOptions, ProgramOptions } from "./main";
+export { HANDLERS, main, runProgram } from "./main";
+export { PLUGINS } from "../plugins";
+export type { RunJob, RunOptions, RunResult, Runner } from "./runtime/process";
+export { childEnv, nodeRunner, runMany, signalTree } from "./runtime/process";
+export { resolveConcurrency, resolveDeadlineMs, runPool } from "../ts/lib/pool";
+export { info, ok, warn } from "./runtime/logging";
+export type { DistributionIdentity } from "./runtime/home";
+export { BUILD_ID, installRoot, installRootIsUnwritten, isCompiled, releaseRepo } from "./runtime/home";
+export type { ErisFailureInput } from "../ts/lib/eris-fail";
+export type { BuildOptions, BuildResult, BuildStub } from "./build";
+
+/** Compile a distribution into one executable (src/build.ts). */
+export async function build(opts: BuildOptions): Promise<BuildResult> {
+  return (await import("./build")).build(opts);
+}