babavoss 0.0.1 → 0.0.2

package/src/http/server.ts

@@ -0,0 +1,310 @@
+// The HTTP edge, kernel side: the projects' Nodes, the GUI's build, the
+// page token and the address. The registry says what runs; a refresh
+// re-reads it. The server itself is a child process (src/server/) that holds
+// no files; this side fills its memory and answers what it forwards.
+import { join, resolve } from "node:path";
+import { mkdir, writeFile, chmod } from "node:fs/promises";
+import { dirname } from "node:path";
+import { readFileSync, unlinkSync } from "node:fs";
+import { openProject, exists } from "../baba/project.ts";
+import { init } from "../baba/init.ts";
+import { homedir } from "node:os";
+import { readdir } from "node:fs/promises";
+import { Node, NodeError } from "../baba/node.ts";
+import type { BuildOutput } from "../build/builder.ts";
+import type { Registry } from "../baba/registry.ts";
+import { page, buildGui } from "../gui/index.ts";
+import type { Transport } from "../transport/transport.ts";
+import type { ViewIndex, Asset, Failure, FromServer, ProjectEntry, ToServer, Refreshed, Browsed } from "../server/messages.ts";
+import { connectFor, builderFor, serverSpawn } from "../kernel/children.ts";
+import { dev, framework } from "../kernel/where.ts";
+import { takeLock, LockError } from "../kernel/lock.ts";
+import { thisBuild, buildOf, buildName, tellApart, type Build } from "../kernel/build.ts";
+import type { Voss } from "../server/messages.ts";
+import { stat } from "node:fs/promises";
+
+export type ServerTransport = Transport<ToServer, FromServer>;
+
+export interface ServeOptions {
+  /** Starts the server child from its command line; by default behind the wall with loopback. */
+  spawn?: (cmd: string[]) => ServerTransport;
+  /** Runs the projects in process workers instead of walled runtimes: for tests. */
+  inProcess?: boolean;
+  /** false: no DIR/address and no DIR/lock, so the CLI does not take this server for the root's daemon: `serve` for one project. */
+  address?: boolean;
+  /** Under the service (launchd, systemd): a clean exit is a restart. */
+  kept?: boolean;
+  /** The package.json to watch for a newer install: the framework's own, installed and the root's daemon; false for none; given, for tests. */
+  binary?: { path: string; every?: number; version?: (path: string) => Promise<Build | null> } | false;
+  /** What a restart does once answered: by default stops everything and exits, re-running itself when not kept. */
+  restart?: () => Promise<void> | void;
+  /** What a baba made from the picker depends on, as `voss init` would write it; absent, the picker can only remember a baba that exists. */
+  init?: { framework: string; extra?: Record<string, string>; install?: boolean };
+}
+
+export interface Served { hostname: string; port: number; token: string; nodes: Map<string, Node>; voss: Voss; stop(): Promise<void> }
+
+/** The command that starts the GUI server: Bun on bin/voss.ts in the server role. */
+export function serverCommand(): string[] {
+  return [process.execPath, join(framework, "bin", "voss.ts"), "--server"];
+}
+
+/** $VOSS_TOKEN, else 32 random bytes written to DIR/http-token, readable by the user alone. */
+async function pageToken(dir: string, log: (l: string) => void): Promise<string> {
+  if (process.env.VOSS_TOKEN) return process.env.VOSS_TOKEN;
+  const token = Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("hex");
+  const path = join(dir, "http-token");
+  await mkdir(dir, { recursive: true });
+  await writeFile(path, token + "\n", { mode: 0o600 });
+  await chmod(path, 0o600);
+  log(`token in ${path}`);
+  return token;
+}
+
+const attr = (s: string) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+const withToken = (html: string, token: string) => html.replace("<title>", `<meta name="voss-token" content="${attr(token)}"><title>`);
+
+async function readTree(dir: string): Promise<Record<string, Asset>> {
+  const out: Record<string, Asset> = {};
+  for await (const path of new Bun.Glob("**/*").scan({ cwd: dir, onlyFiles: true })) {
+    const f = Bun.file(join(dir, path));
+    out[path] = { mime: f.type, bytes: new Uint8Array(await f.arrayBuffer()) };
+  }
+  return out;
+}
+
+/** The entry to import and the stylesheets to attach: the entry's own, and any chunk's, in build order. */
+function indexOf(outputs: BuildOutput[]): ViewIndex {
+  return {
+    entry: outputs.find((o) => o.kind === "entry-point")!.path,
+    css: outputs.filter((o) => o.path.endsWith(".css")).map((o) => o.path),
+    paths: outputs.map((o) => o.path),
+  };
+}
+
+/** A directory and the directories under it, the hidden and node_modules left out, each marked when it holds a baba or is already remembered. */
+async function browse(path: string, known: string[]): Promise<Browsed> {
+  path = resolve(path);
+  const remembered = new Set(known.map((d) => resolve(d)));
+  const hasBaba = (dir: string) => exists(join(dir, ".baba", "package.json"));
+  const entries = await readdir(path, { withFileTypes: true });
+  const dirs: Browsed["dirs"] = [];
+  for (const e of entries.filter((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules").sort((a, b) => a.name.localeCompare(b.name))) {
+    const full = join(path, e.name);
+    dirs.push({ name: e.name, path: full, baba: await hasBaba(full), known: remembered.has(full) });
+  }
+  const parent = dirname(path);
+  return { path, home: homedir(), parent: parent === path ? null : parent, baba: await hasBaba(path), known: remembered.has(path), dirs };
+}
+
+function failure(err: unknown): Failure {
+  return { ok: false, code: err instanceof NodeError ? err.code : "failed", message: err instanceof Error ? err.message : String(err) };
+}
+
+/** Where a root's daemon says it listens: DIR/address, written on listen and removed on stop. */
+export const addressPath = (rootDir: string) => join(rootDir, "address");
+export interface Address { hostname: string; port: number; pid: number }
+/** DIR/lock: the daemon's, beside its address and token. */
+export const lockPath = (dir: string) => join(dir, "lock");
+
+export async function serve(reg: Registry, hostname: string, port: number, log = (l: string) => console.error(`voss: ${l}`), options: ServeOptions = {}): Promise<Served> {
+  const nodes = new Map<string, Node>();
+  // The server child, once it runs: every round's frame and every generation go to it, for the windows.
+  let child: ServerTransport | null = null;
+  const hook = (n: Node) => {
+    n.onRound = (frame, round) => child?.send({ type: "round", name: n.name, round, frame });
+    n.onGeneration = (gen) => child?.send({ type: "generation", name: n.name, gen });
+  };
+  // One daemon per root: a second one would overwrite the address and the token and run every project twice.
+  let lock: { release(): void } | null = null;
+  if (options.address !== false) {
+    await mkdir(reg.dir, { recursive: true });
+    try { lock = takeLock(lockPath(reg.dir), { role: "daemon" }, (h) => `a voss daemon already runs this root, pid ${h.pid}`); }
+    catch (err) { if (err instanceof LockError) throw new NodeError("busy", err.message); throw err; }
+  }
+
+  // The registry is the list of what runs: a refresh opens what it gained and retires what it lost, one at a time.
+  let refreshing: Promise<unknown> = Promise.resolve();
+  const reread = async (): Promise<Refreshed> => {
+    const dirs = (await reg.list()).map((d) => resolve(d));
+    const errors: Refreshed["errors"] = [];
+    for (const [name, n] of nodes) {
+      if (dirs.includes(n.project.dir)) continue;
+      nodes.delete(name);
+      await n.stop();
+      log(`${name}: stopped`);
+    }
+    for (const dir of dirs) {
+      if ([...nodes.values()].some((n) => n.project.dir === dir)) continue;
+      try {
+        if (voss.stale) throw new Error(`not opened: voss ${buildName(voss.installed!)} is installed and this one is stale; restart to update`);
+        const p = await openProject(dir);
+        const other = nodes.get(p.name);
+        if (other) throw new Error(`name ${p.name} is already taken by ${other.project.dir}`);
+        const builder = options.inProcess ? undefined : builderFor(p, reg.dir, log);
+        const n = options.inProcess ? new Node(p, log) : new Node(p, log, connectFor(p, reg.dir, builder!), undefined, builder);
+        hook(n);
+        await n.start();
+        nodes.set(p.name, n);
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        log(`${dir}: ${error}`);
+        errors.push({ dir, error });
+      }
+    }
+    return { projects: listing(), errors };
+  };
+  const refresh = (): Promise<Refreshed> => { const r = refreshing.then(reread); refreshing = r.catch(() => {}); return r; };
+  const stopNodes = async () => { await refreshing; await Promise.all([...nodes.values()].map((n) => n.stop())); };
+
+  // Which voss this is. A newer package installed over it makes this one stale: it serves what it has,
+  // loads no change and opens no project, until the restart brings the new one up.
+  const voss: Voss = { ...thisBuild, pid: process.pid, kept: options.kept ?? false, stale: false, installed: null };
+  const stale = (b: Build) => {
+    voss.stale = true;
+    voss.installed = { version: b.version, sha: b.sha, at: b.at };
+    const [installed, running] = tellApart(b, thisBuild);
+    const why = `voss ${installed} is installed and this one is ${running}; restart to update`;
+    for (const n of nodes.values()) n.freeze(why);
+    log(why);
+    child?.send({ type: "voss", voss });
+  };
+  const watched = options.binary === false ? null : options.binary ?? (!dev && options.address !== false ? { path: join(framework, "package.json") } : null);
+  let watcher: ReturnType<typeof setInterval> | null = null;
+  const watchBinary = async () => {
+    if (!watched) return;
+    const first = await stat(watched.path).catch(() => null);
+    if (!first) return;
+    const read = watched.version ?? buildOf;
+    let asking = false;
+    watcher = setInterval(() => {
+      if (voss.stale || asking) return;
+      asking = true;
+      void (async () => {
+        const now = await stat(watched.path).catch(() => null);   // gone for a moment: an install under way
+        if (now && now.ino !== first.ino) {
+          const b = await read(watched.path);                          // not yet a package that answers: ask again next time
+          if (b && (b.version !== thisBuild.version || b.sha !== thisBuild.sha || b.at !== thisBuild.at)) stale(b);
+        }
+      })().finally(() => { asking = false; });
+    }, watched.every ?? 5_000);
+    watcher.unref();
+  };
+
+  // The GUI, packed with a release under the framework's gui/; built here from a checkout, or a package without one.
+  // Either way it goes into memory for the child, which reads no files.
+  const packed = join(framework, "gui");
+  let built = !dev && await exists(join(packed, "gui.js")) ? packed : null;
+  if (!built) { built = join(reg.dir, "gui"); await buildGui(built); }
+  const assets = await readTree(built);
+  const token = await pageToken(reg.dir, log);
+  function listing(): ProjectEntry[] {
+    const all = [...nodes.values()];
+    const parentOf = (n: Node) => all
+      .filter((o) => o !== n && n.project.dir.startsWith(o.project.dir + "/"))
+      .sort((a, b) => b.project.dir.length - a.project.dir.length)[0]?.name ?? null;
+    return all.map((n) => ({ name: n.name, title: n.project.title, dir: n.project.dir, parent: parentOf(n) }));
+  }
+  const pagesOf = () => {
+    const pages: Record<string, string> = { "": withToken(page(null), token) };
+    for (const name of nodes.keys()) pages[name] = withToken(page(name), token);
+    return pages;
+  };
+  await refresh();
+
+  child = (options.spawn ?? serverSpawn(reg.dir))(serverCommand());
+
+  // A restart: the answer goes out, then everything stops and the process ends. Kept by the service, it is started again
+  // as the installed voss; otherwise it runs the same command again itself, once the lock is free.
+  let shutdown: () => Promise<void> = async () => {};
+  const restart = options.restart ?? (async () => {
+    log(`restarting${voss.installed ? ` as voss ${buildName(voss.installed)}` : ""}`);
+    await shutdown();
+    if (!voss.kept) Bun.spawn([process.execPath, ...process.argv.slice(1)], { stdio: ["ignore", "inherit", "inherit"], env: process.env }).unref();
+    process.exit(0);
+  });
+  async function answer(m: FromServer): Promise<ToServer | null> {
+    if (m.type === "ready" || m.type === "listening" || m.type === "failed") return null;
+    if (m.type === "restart") {
+      setTimeout(() => void restart(), 300);
+      return { type: "restart-answer", id: m.id, ok: true, value: { restarting: true, kept: voss.kept } };
+    }
+    if (m.type === "refresh") {
+      try {
+        const value = await refresh();
+        child?.send({ type: "projects", projects: value.projects, pages: pagesOf() });
+        return { type: "refresh-answer", id: m.id, ok: true, value };
+      } catch (err) { return { type: "refresh-answer", id: m.id, ...failure(err) }; }
+    }
+    if (m.type === "browse") {
+      try { return { type: "browse-answer", id: m.id, ok: true, value: await browse(m.path || homedir(), await reg.list()) }; }
+      catch (err) { return { type: "browse-answer", id: m.id, ...failure(err) }; }
+    }
+    if (m.type === "add") {
+      try {
+        const dir = resolve(m.dir);
+        if (m.init) {
+          if (!options.init) throw new NodeError("failed", "this voss cannot make a baba; `voss init` does");
+          await init(dir, { name: m.name, title: m.title, framework: options.init.framework, extra: options.init.extra, install: options.init.install });
+        }
+        const p = await openProject(dir);
+        await reg.add(p.dir);
+        const value = await refresh();
+        child?.send({ type: "projects", projects: value.projects, pages: pagesOf() });
+        const own = value.errors.find((e) => e.dir === p.dir);
+        if (own) throw new NodeError("failed", own.error);
+        return { type: "add-answer", id: m.id, ok: true, value: { ...value, name: p.name, dir: p.dir } };
+      } catch (err) { return { type: "add-answer", id: m.id, ...failure(err) }; }
+    }
+    const n = nodes.get(m.name);
+    try {
+      if (!n) throw new NodeError("nokey", `no project ${m.name}`);
+      if (m.type === "describe") {
+        if (m.since) await n.waitFor(m.since, 25_000);
+        return { type: "describe-answer", id: m.id, ok: true, value: n.describe() };
+      }
+      if (m.type === "view") {
+        const b = await n.bundle();
+        if (m.path === undefined) return { type: "view-answer", id: m.id, ok: true, gen: b.gen, index: indexOf(b.outputs) };
+        const o = b.outputs.find((x) => x.path === m.path);
+        if (!o) throw new NodeError("notfound", `the view has no ${m.path}`);
+        return { type: "view-answer", id: m.id, ok: true, gen: b.gen, file: { type: o.type, bytes: o.bytes } };
+      }
+      let value: unknown, round: number | undefined;
+      if (m.kind === "state") value = m.parts ? await n.parts(m.parts) : m.frame ? await n.frame(m.since, m.wait !== false) : await n.state(m.since);
+      else if (m.kind === "raw") ({ value, round } = await n.rawIn(m.raw));
+      else if (m.kind === "fire") ({ value, round } = await n.fireIn(m.target, m.args, m.coerce, m.key));
+      else value = await n.read(m.target, m.args, m.coerce);
+      return { type: "call-answer", id: m.id, ok: true, value, ...(round !== undefined ? { round } : {}) };
+    } catch (err) {
+      return { type: `${m.type}-answer`, id: m.id, ...failure(err) };
+    }
+  }
+
+  return new Promise<Served>((resolve, reject) => {
+    let up = false;
+    child.onClose((reason) => {
+      if (!up) { lock?.release(); void stopNodes(); reject(new Error(`the GUI server ${reason}`)); return; }
+      log(`the GUI server ${reason}`);
+    });
+    child.onMessage((m) => {
+      if (m.type === "ready") {
+        child.send({ type: "serve", hostname, port, token, voss, projects: listing(), home: homedir(), pages: pagesOf(), assets });
+      } else if (m.type === "listening") {
+        up = true;
+        // The address goes next to the token, for the CLI to find the daemon by; it goes when the daemon does.
+        const path = addressPath(reg.dir);
+        const text = JSON.stringify({ hostname: m.hostname, port: m.port, pid: process.pid } satisfies Address) + "\n";
+        const forget = () => { try { if (readFileSync(path, "utf8") === text) unlinkSync(path); } catch { /* already gone */ } };
+        const written = options.address === false ? Promise.resolve() : writeFile(path, text, { mode: 0o600 }).then(() => { process.once("exit", forget); });
+        shutdown = async () => { if (watcher) clearInterval(watcher); process.off("exit", forget); forget(); child.close(); await stopNodes(); lock?.release(); };
+        written.then(() => { void watchBinary(); resolve({ hostname: m.hostname, port: m.port, token, nodes, voss, stop: shutdown }); }, reject);
+      } else if (m.type === "failed") {
+        child.close(); void stopNodes(); lock?.release();
+        reject(new Error(`the GUI server could not listen on ${hostname}:${port}: ${m.error}`));
+      } else {
+        answer(m).then((a) => a && child.send(a));
+      }
+    });
+  });
+}

package/src/kernel/build.ts

@@ -0,0 +1,21 @@
+// Which voss this is: the package version, the commit and time a release
+// was packed from, and whether it runs from a developer checkout. What
+// `voss --version` prints, what the daemon reports, what a newer install
+// is compared by.
+import { build } from "../generated/build.ts";
+import { dev } from "./where.ts";
+import pkg from "../../package.json";
+
+export interface Build { version: string; sha: string; at: string; dev: boolean }
+
+export const thisBuild: Build = { version: (pkg as { version: string }).version, sha: build.sha, at: build.at, dev };
+
+export { buildName, tellApart } from "./names.ts";
+
+/** The build of a package on disk, from its package.json; null when there is none. */
+export async function buildOf(packageJson: string): Promise<Build | null> {
+  try {
+    const b = JSON.parse(await Bun.file(packageJson).text()) as Partial<Build>;
+    return typeof b.version === "string" ? { version: b.version, sha: "", at: "", dev: false } : null;
+  } catch { return null; }
+}

package/src/kernel/builder.ts

@@ -0,0 +1,105 @@
+// The kernel's builder for a project: a walled process started when a
+// build is asked for, kept while builds keep coming, gone after a quiet
+// spell. A build that outruns its time is killed, and whoever waited hears
+// a failure; the old bundle stays, as with any failed build.
+import type { Transport } from "../transport/transport.ts";
+import { PROTOCOL, type ToBuilder, type FromBuilder, type Built } from "../transport/messages.ts";
+import { ViewFailed, type ViewFailure } from "../build/failure.ts";
+import { validateOutputs, entryOf, type Builder, type BuildOutput, type ViewSpec } from "../build/builder.ts";
+import type { Project } from "../baba/project.ts";
+
+export interface BuilderOptions { idleMs?: number; timeoutMs?: number }
+
+interface Pending { resolve: (b: Extract<Built, { ok: true }>) => void; reject: (e: Error) => void }
+
+export class ProcessBuilder implements Builder {
+  private t: Transport<ToBuilder, FromBuilder> | null = null;
+  private pending = new Map<number, Pending>();
+  private nextId = 1;
+  private idle: ReturnType<typeof setTimeout> | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private readonly idleMs: number;
+  private readonly timeoutMs: number;
+
+  constructor(private spawn: () => Transport<ToBuilder, FromBuilder>, private log: (line: string) => void = () => {}, o: BuilderOptions = {}) {
+    this.idleMs = o.idleMs ?? 30_000;
+    this.timeoutMs = o.timeoutMs ?? 60_000;
+  }
+
+  async project(p: Project): Promise<string> {
+    const b = await this.ask({ type: "build-project", id: 0, project: p });
+    return entryOf(b.outputs);
+  }
+
+  async view(spec: ViewSpec): Promise<BuildOutput[]> {
+    const b = await this.ask({ type: "build-view", id: 0, spec });
+    return validateOutputs(b.outputs);
+  }
+
+  stop(): void {
+    this.fail("the builder was stopped");
+    if (this.idle) { clearTimeout(this.idle); this.idle = null; }
+    this.t?.close();
+    this.t = null;
+  }
+
+  private transport(): Transport<ToBuilder, FromBuilder> {
+    if (this.t) return this.t;
+    const t = this.spawn();
+    t.onMessage((m) => {
+      if (m.type === "hello") {
+        if (m.protocol !== PROTOCOL) { this.log(`the builder speaks protocol ${m.protocol}, this kernel ${PROTOCOL}`); this.stop(); }
+        return;
+      }
+      if (m.type !== "built") return;
+      const p = this.pending.get(m.id);
+      if (!p) return;
+      this.pending.delete(m.id);
+      this.armTimer();
+      if (m.ok) p.resolve(m); else p.reject(new ViewFailed(m.failure));
+    });
+    t.onClose((reason) => {
+      if (this.t === t) this.t = null;
+      this.fail(`the builder exited: ${reason}`);
+    });
+    t.send({ type: "hello", protocol: PROTOCOL, role: "kernel" });
+    this.t = t;
+    return t;
+  }
+
+  private ask(m: Exclude<ToBuilder, { type: "hello" }>): Promise<Extract<Built, { ok: true }>> {
+    const id = this.nextId++;
+    if (this.idle) { clearTimeout(this.idle); this.idle = null; }
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.transport().send({ ...m, id });
+      this.armTimer();
+    });
+  }
+
+  /** While builds are pending the clock runs for the oldest; with none, the idle clock runs. */
+  private armTimer(): void {
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    if (this.pending.size > 0) {
+      this.timer = setTimeout(() => this.kill(`the build took longer than ${this.timeoutMs / 1000} s and was stopped`), this.timeoutMs);
+    } else if (this.t) {
+      this.idle = setTimeout(() => { this.t?.close(); this.t = null; }, this.idleMs);
+      this.idle.unref?.();
+    }
+  }
+
+  private kill(why: string): void {
+    this.log(why);
+    const t = this.t;
+    this.t = null;
+    t?.close();
+    this.fail(why);
+  }
+
+  private fail(why: string): void {
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    const failure: ViewFailure = { stage: "build", message: why };
+    for (const p of this.pending.values()) p.reject(new ViewFailed(failure));
+    this.pending.clear();
+  }
+}

package/src/kernel/children.ts

@@ -0,0 +1,117 @@
+// How the kernel starts its children: a runtime per project and the GUI
+// server, each voss in a role, behind the wall. The child reads the
+// framework's tree and its dependencies, nothing else of the machine.
+import { dirname, join } from "node:path";
+import { readdirSync, lstatSync, realpathSync, readlinkSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { framework } from "./where.ts";
+import { seatbeltProfile } from "../wall/profile.ts";
+import { spawnWalled } from "../wall/spawn.ts";
+import { runtimeConnect, roleCommand, type Spawn } from "../runtime/connect.ts";
+import { ProcessBuilder } from "./builder.ts";
+import type { Builder } from "../build/builder.ts";
+import type { ToBuilder, FromBuilder } from "../transport/messages.ts";
+import type { Project } from "../baba/project.ts";
+import type { Connect } from "../baba/node.ts";
+import type { Transport } from "../transport/transport.ts";
+import type { ServerTransport } from "../http/server.ts";
+import type { ToServer, FromServer } from "../server/messages.ts";
+
+/**
+ * Where the framework's dependencies really are: its own node_modules, or the
+ * node_modules a workspace installs them into above it, `.bun/` and all, when the framework is a member.
+ */
+function dependencies(): string[] {
+  const out = new Set<string>();
+  const pkg = JSON.parse(readFileSync(join(framework, "package.json"), "utf8")) as { dependencies?: Record<string, string> };
+  for (const name of Object.keys(pkg.dependencies ?? {})) {
+    const target = real(join(framework, "node_modules", name));
+    if (target === framework || target.startsWith(framework + "/")) continue;
+    const at = target.indexOf("/node_modules/");
+    if (at >= 0) out.add(target.slice(0, at + "/node_modules".length));
+  }
+  return [...out];
+}
+
+/** What a child may read besides Bun: the framework's tree and its dependencies. */
+let sourceTree: string[] | null = null;
+const readable = () => (sourceTree ??= [framework, ...dependencies()]);
+
+/** A project's runtime, walled: no files, no network, no programs. */
+export function runtimeSpawn(rootDir: string): Spawn {
+  return (cmd, o) => spawnWalled(cmd, {
+    profile: seatbeltProfile({ binary: cmd[0]!, readable: readable() }),
+    env: o.env, dir: join(rootDir, "wall"), stdout: o.stdout, stderr: o.stderr,
+  });
+}
+
+/** The Node's connect for a project: a walled runtime process, its bundle from `builder`. */
+export function connectFor(project: Project, rootDir: string, builder: Builder): Connect {
+  return runtimeConnect(project, runtimeSpawn(rootDir), builder);
+}
+
+const real = (p: string) => { try { return realpathSync(p); } catch { return p; } };
+
+/**
+ * Where a project's node_modules points outside the project: a `link:`
+ * dependency or a workspace member elsewhere. The wall grants by real path,
+ * so each target is granted on its own; the framework already is.
+ * `links` are the symbolic links passed through on the way, outside the
+ * project: a global install's link to a package, say. The wall must read
+ * each as the link it is, or the path cannot be followed.
+ */
+export function linkTargets(baba: string): { targets: string[]; links: string[] } {
+  const home = real(baba);
+  const inside = (p: string) => p === home || p.startsWith(home + "/");
+  const out = new Set<string>();
+  const links = new Set<string>();
+  const dir = join(baba, "node_modules");
+  let names: string[] = [];
+  try { names = readdirSync(dir); } catch { return { targets: [], links: [] }; }
+  const entries: string[] = [];
+  for (const n of names) {
+    if (n.startsWith(".")) continue;
+    if (n.startsWith("@")) { try { for (const s of readdirSync(join(dir, n))) entries.push(join(dir, n, s)); } catch {} }
+    else entries.push(join(dir, n));
+  }
+  for (const e of entries) {
+    try { if (!lstatSync(e).isSymbolicLink()) continue; } catch { continue; }
+    // Every link on the chain after the first, which is inside the project.
+    for (let p = e, hops = 0; hops < 32; hops++) {
+      let next: string;
+      try { if (!lstatSync(p).isSymbolicLink()) break; next = resolve(dirname(p), readlinkSync(p)); } catch { break; }
+      if (p !== e && !inside(p)) links.add(p);
+      p = next;
+    }
+    const target = real(e);
+    if (!inside(target) && !readable().some((r) => target === r || target.startsWith(r + "/"))) out.add(target);
+  }
+  return { targets: [...out], links: [...links] };
+}
+
+/**
+ * A project's builder, walled: it may read its project's `.baba` and what
+ * the project links to, starts there, and may read, write or reach nothing
+ * else. The kernel's own state under `rootDir` stays out even when it lies
+ * inside a granted tree, as `.voss-dev` does in a checkout.
+ */
+export function builderFor(project: Project, rootDir: string, log: (line: string) => void = () => {}): Builder {
+  const spawn = (): Transport<ToBuilder, FromBuilder> => {
+    const { targets, links } = linkTargets(project.baba);
+    for (const t of targets) log(`${project.name}: the builder may read ${t}, linked from node_modules`);
+    const cmd = roleCommand("--builder");
+    return spawnWalled<ToBuilder, FromBuilder>(cmd, {
+      profile: seatbeltProfile({ binary: cmd[0]!, readable: [...readable(), project.baba, ...targets], links, unreadable: [rootDir] }),
+      env: {}, dir: join(rootDir, "wall"), cwd: project.baba, stdout: "inherit", stderr: "inherit",
+    });
+  };
+  return new ProcessBuilder(spawn, (l) => log(`${project.name}: ${l}`));
+}
+
+/** The GUI server, walled with loopback only. */
+export function serverSpawn(rootDir: string): (cmd: string[]) => ServerTransport {
+  return (cmd) => spawnWalled<ToServer, FromServer>(cmd, {
+    profile: seatbeltProfile({ binary: cmd[0]!, loopback: true, readable: readable() }),
+    env: {}, dir: join(rootDir, "wall"), stdout: "inherit", stderr: "inherit",
+  });
+}

package/src/kernel/context.ts

@@ -0,0 +1,90 @@
+// The context: an effect's whole reach beyond computation. Every part is a
+// message to the kernel, which serves it and logs every reach beyond the
+// project, attributed to the system, the effect and the job that asked.
+
+export interface Context {
+  /** The project directory, as a path the kernel understands. */
+  project: string;
+  /** Files, scoped to the project: a path is relative to it, or absolute inside it. */
+  fs: Fs;
+  /** The network, through the kernel: every request observed and attributed. */
+  http: Http;
+  /** Programs on the machine, owned by the job and supervised by the kernel. */
+  exec: Exec;
+  /** Secrets from the keychain, through the kernel. */
+  secrets: Secrets;
+  /** The environment: the project's .env files. */
+  env: Readonly<Record<string, string>>;
+  /** Aborted when the job settles or is cancelled: its entity despawned, its request removed, the baba retired. */
+  signal: AbortSignal;
+}
+
+export interface Fs {
+  read(path: string): Promise<string>;
+  readBytes(path: string): Promise<Uint8Array>;
+  write(path: string, content: string | Uint8Array): Promise<void>;
+  list(path: string): Promise<Entry[]>;
+  /** Every change under `path` from now on, as it happens: the entry as it is, or `{ path, gone: true }`; `{ resync: true }` when too many arrived to tell. */
+  watch(path: string): AsyncIterable<Change>;
+  stat(path: string): Promise<Entry | null>;
+  remove(path: string): Promise<void>;
+  mkdir(path: string): Promise<void>;
+}
+export interface Entry { name: string; path: string; dir: boolean; size: number; updated: string }
+export type Change = Entry | { path: string; gone: true } | { resync: true };
+
+export interface Http {
+  fetch(url: string, init?: { method?: string; headers?: Record<string, string>; body?: string }): Promise<{ status: number; headers: Record<string, string>; body: string }>;
+}
+
+export interface ExecOptions {
+  cwd?: string; input?: string; env?: Record<string, string>;
+  /** Milliseconds; null explicitly requests an unlimited lifetime. Default: ten minutes. */
+  timeout?: number | null;
+  /** Keep stdin open for exec.write. stream only. */
+  interactive?: boolean;
+}
+export type ExecEvent =
+  | { type: "started"; process: string; pid: number }
+  | { type: "stdout" | "stderr"; data: Uint8Array }
+  | { type: "exit"; code: number; signal: string | null };
+export interface Exec {
+  run(program: string, args?: string[], options?: ExecOptions): Promise<{ code: number; stdout: string; stderr: string }>;
+  stream(program: string, args?: string[], options?: ExecOptions): AsyncIterable<ExecEvent>;
+  /** null closes stdin. Acknowledges bytes accepted, not application completion. */
+  write(process: string, input: string | null): Promise<void>;
+}
+
+export interface Secrets {
+  get(name: string): Promise<string | null>;
+}
+
+/** What a project's package.json may say under `baba`. */
+export interface BabaConfig {
+  /** The baba's name when the package's own must differ, as in a workspace that has a package of that name. */
+  name?: string;
+  title?: string;
+  harnesses?: string[];
+  /** What the build needs: bundler plugins from the project's node_modules, directories served beside the view. */
+  build?: { plugins?: string[]; assets?: string[] };
+}
+
+/**
+ * What the kernel implements, one method per service operation. A request
+ * names the system, the effect and the job it belongs to, so the kernel can
+ * attribute what it serves. Every method may throw a ServiceError.
+ */
+/** A service's answer: once, or many times for a streaming operation. `signal` is the job's: aborted, the service lets go. */
+export interface Services {
+  fs(who: Who, op: keyof Fs, args: unknown[], signal?: AbortSignal): Promise<unknown> | AsyncIterable<unknown>;
+  http(who: Who, op: keyof Http, args: unknown[], signal?: AbortSignal): Promise<unknown> | AsyncIterable<unknown>;
+  exec(who: Who, op: keyof Exec, args: unknown[], signal?: AbortSignal): Promise<unknown> | AsyncIterable<unknown>;
+  secrets(who: Who, op: keyof Secrets, args: unknown[], signal?: AbortSignal): Promise<unknown> | AsyncIterable<unknown>;
+}
+
+/** Who asks: the project, the system, the effect, and the job the request belongs to. */
+export interface Who { project: string; system: string; effect: string; job: number; generation?: string; entity?: number | null }
+
+export class ServiceError extends Error {
+  constructor(readonly code: "denied" | "notfound" | "failed" | "args", msg: string) { super(msg); }
+}