babavoss 0.0.1 → 0.12.0

package/src/services/fs.ts

@@ -0,0 +1,139 @@
+// Files, scoped to the project: the project is the baba's own ground, so
+// everything inside is granted, and nothing outside is reachable, not
+// through "..", not through an absolute path, not through a symlink.
+import { realpath, stat, lstat, readdir, mkdir, rename, unlink, rmdir } from "node:fs/promises";
+import { watch as fsWatch } from "node:fs";
+import { dirname, basename, isAbsolute, join, normalize, relative, sep } from "node:path";
+import { ServiceError, type Fs, type Entry, type Change, type Who } from "../kernel/context.ts";
+import { string, bytes, type Ops } from "./args.ts";
+
+/** How many distinct paths a burst may hold before it becomes one resync; how long to wait for a burst to settle. */
+const COALESCE = 2000;
+const SETTLE = 50;
+
+const missing = (e: unknown) => typeof e === "object" && e !== null && (e as { code?: string }).code === "ENOENT";
+
+/** The absolute path `path` names inside the project, with symlinks followed; denied if it leaves. */
+export async function inside(who: Who, path: string): Promise<string> {
+  const root = await realpath(who.project);
+  // Follow symlinks on the deepest existing prefix; the rest does not exist yet, so it cannot point anywhere.
+  let existing = isAbsolute(path) ? normalize(path) : join(who.project, path);
+  const rest: string[] = [];
+  for (;;) {
+    try { existing = await realpath(existing); break; } catch (e) {
+      if (!missing(e) || existing === dirname(existing)) throw e;
+      rest.unshift(basename(existing));
+      existing = dirname(existing);
+    }
+  }
+  const real = join(existing, ...rest);
+  if (real !== root && !real.startsWith(root + sep)) throw new ServiceError("denied", `${who.system} asked for ${path}, which is outside its project ${who.project}; a baba reaches only files under its project`);
+  return real;
+}
+
+async function entry(who: Who, real: string): Promise<Entry | null> {
+  let s;
+  // A symlink is followed only where it stays inside the project; one that leaves is not listed.
+  try { if ((await lstat(real)).isSymbolicLink()) await inside(who, real); } catch (e) { if (missing(e) || e instanceof ServiceError) return null; throw e; }
+  try { s = await stat(real); } catch (e) { if (missing(e)) return null; throw e; }
+  const root = await realpath(who.project);
+  return { name: basename(real), path: relative(root, real).split(sep).join("/"), dir: s.isDirectory(), size: s.size, updated: s.mtime.toISOString() };
+}
+
+/** Whatever the file system refuses, said with the path the baba asked for. */
+function failed(path: string, e: unknown): never {
+  if (e instanceof ServiceError) throw e;
+  if (missing(e)) throw new ServiceError("notfound", `${path}: no such file or directory`);
+  throw new ServiceError("failed", `${path}: ${e instanceof Error ? e.message : String(e)}`);
+}
+
+export const fs: Ops<Fs> = {
+  async read(who, [p]) {
+    const path = string(p, "path");
+    try { return await Bun.file(await inside(who, path)).text(); } catch (e) { failed(path, e); }
+  },
+  async readBytes(who, [p]) {
+    const path = string(p, "path");
+    try { return await Bun.file(await inside(who, path)).bytes(); } catch (e) { failed(path, e); }
+  },
+  async write(who, [p, c]) {
+    const path = string(p, "path");
+    const content = bytes(c, "content");
+    try {
+      const real = await inside(who, path);
+      await mkdir(dirname(real), { recursive: true });
+      // Atomic: a sibling temp file, then a rename; a reader never sees half a file.
+      const temp = `${real}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+      try { await Bun.write(temp, content); await rename(temp, real); } catch (e) { await unlink(temp).catch(() => {}); throw e; }
+    } catch (e) { failed(path, e); }
+  },
+  async list(who, [p]) {
+    const path = string(p, "path");
+    try {
+      const real = await inside(who, path);
+      const names = (await readdir(real)).sort();
+      const entries = await Promise.all(names.map((n) => entry(who, join(real, n))));
+      return entries.filter((e): e is Entry => e !== null);
+    } catch (e) { failed(path, e); }
+  },
+  async stat(who, [p]) {
+    const path = string(p, "path");
+    try { return await entry(who, await inside(who, path)); } catch (e) { failed(path, e); }
+  },
+  /**
+   * Every change under the directory, as the OS reports it, each looked
+   * up as it is now: the entry, or gone. Changes are coalesced by path
+   * between reads; past COALESCE paths a single `resync` stands for them
+   * all, so a burst never grows without bound. Ends when the signal says.
+   */
+  async *watch(who, [p], signal) {
+    const path = string(p, "path");
+    let real: string;
+    try { real = await inside(who, path); if (!(await stat(real)).isDirectory()) throw new ServiceError("notfound", `${path}: not a directory`); } catch (e) { failed(path, e); }
+    const root = await realpath(who.project);
+    const pending = new Map<string, true>();
+    let resync = false;
+    let wake: (() => void) | null = null;
+    const watcher = fsWatch(real, { recursive: true }, (_, name) => {
+      if (name === null || name === undefined) resync = true;
+      else if (pending.size >= COALESCE) { resync = true; pending.clear(); }
+      else pending.set(String(name), true);
+      wake?.();
+    });
+    let error: Error | null = null;
+    watcher.on("error", (e) => { error = e; wake?.(); });
+    const stop = () => { watcher.close(); wake?.(); };
+    signal.addEventListener("abort", stop, { once: true });
+    try {
+      while (!signal.aborted) {
+        if (!resync && pending.size === 0 && !error) await new Promise<void>((r) => { wake = r; });
+        wake = null;
+        if (error) throw error;
+        if (signal.aborted) break;
+        // A short quiet after the first report, so a save's several events read as one.
+        await new Promise((r) => setTimeout(r, SETTLE));
+        if (resync) { resync = false; pending.clear(); yield { resync: true } satisfies Change; continue; }
+        const names = [...pending.keys()];
+        pending.clear();
+        const out: Change[] = [];
+        for (const name of names) {
+          const e = await entry(who, join(real, name)).catch(() => null);
+          out.push(e ?? { path: relative(root, join(real, name)).split(sep).join("/"), gone: true });
+        }
+        for (const c of out) yield c;
+      }
+    } finally { signal.removeEventListener("abort", stop); watcher.close(); }
+  },
+  async remove(who, [p]) {
+    const path = string(p, "path");
+    try {
+      const real = await inside(who, path);
+      if (real === await realpath(who.project)) throw new ServiceError("denied", `${who.system} asked to remove ${path}, the project itself; a baba removes files and empty directories under it`);
+      if ((await lstat(real)).isDirectory()) await rmdir(real); else await unlink(real);
+    } catch (e) { failed(path, e); }
+  },
+  async mkdir(who, [p]) {
+    const path = string(p, "path");
+    try { await mkdir(await inside(who, path), { recursive: true }); } catch (e) { failed(path, e); }
+  },
+};

package/src/services/http.ts

@@ -0,0 +1,30 @@
+// The network, through the kernel: every request is attributed to the
+// system, effect and job that made it, and the log says where it went.
+import { ServiceError, type Http, type Who } from "../kernel/context.ts";
+import { string, optional, record, object, type Ops } from "./args.ts";
+
+export const Timeout = 30_000;
+
+
+export const http: Ops<Http> = {
+  async fetch(who, [u, i], signal) {
+    const text = string(u, "url");
+    const init = optional(i, "init", object) ?? {};
+    const method = optional(init.method, "init.method", string);
+    const headers = optional(init.headers, "init.headers", record);
+    const body = optional(init.body, "init.body", string);
+    let url: URL;
+    try { url = new URL(text); } catch { throw new ServiceError("args", `url: ${text} is not a URL`); }
+    if (url.protocol !== "http:" && url.protocol !== "https:") throw new ServiceError("denied", `${who.system} asked to fetch ${url.protocol}//; a baba fetches http: and https: only`);
+    // Redirects are answered, not followed: a followed one could land on an undeclared host.
+    try {
+      const r = await fetch(url, { method, headers, body, signal: AbortSignal.any([signal, AbortSignal.timeout(Timeout)]), redirect: "manual" });
+      const out: Record<string, string> = {};
+      r.headers.forEach((v, k) => { out[k.toLowerCase()] = v; });
+      return { status: r.status, headers: out, body: await r.text() };
+    } catch (e) {
+      const why = e instanceof Error && e.name === "TimeoutError" ? `no answer in ${Timeout / 1000} s` : e instanceof Error ? e.message : String(e);
+      throw new ServiceError("failed", `fetch ${url.href}: ${why}`);
+    }
+  },
+};

package/src/services/index.ts

@@ -0,0 +1,113 @@
+// The kernel's services: the only door a baba has to the machine. One
+// class dispatches a request to its service, checks the operation exists,
+// times it, and logs every grant and denial with who asked.
+import { ServiceError, type Services, type Who } from "../kernel/context.ts";
+import { isStream, type ServiceRequest, type Serviced, type ServiceName } from "../transport/messages.ts";
+import type { Ops } from "./args.ts";
+import { fs } from "./fs.ts";
+import { http } from "./http.ts";
+import { execution } from "./exec.ts";
+import { secrets } from "./secrets.ts";
+
+/** One line of the kernel's log: what was asked, by whom, and how it went. */
+export interface Served { who: Who; service: ServiceName; op: string; args: unknown[]; ok: boolean; ms: number; code?: ServiceError["code"]; error?: string }
+
+/**
+ * The log's line for a served request: every reach beyond the project,
+ * the network, programs and secrets, whether it went well or not; files
+ * only when they fail. Empty when nothing is worth a line.
+ */
+export function describe(e: Served): string {
+  const beyond = e.service === "http" || e.service === "exec" || e.service === "secrets";
+  if (e.ok && !beyond) return "";
+  const what = e.service === "http" ? String(e.args[0] ?? "").replace(/^(https?:\/\/[^/]+)(\/.*)?$/, "$1") : e.service === "exec" ? [e.args[0], ...(Array.isArray(e.args[1]) ? e.args[1] : [])].map(String).join(" ") : e.service === "secrets" ? String(e.args[0] ?? "") : "";
+  const how = e.ok ? `${e.ms.toFixed(0)} ms` : `${e.code}: ${e.error}`;
+  return `${e.who.system}.${e.who.effect} ${e.service}.${e.op}${what ? ` ${what}` : ""}: ${how}`;
+}
+
+const modules = { fs, http, exec: null, secrets };
+
+export class KernelServices implements Services {
+  private readonly modules: Record<ServiceName, Ops<any>> = { fs, http, exec: execution(), secrets };
+  constructor(private log: (entry: Served) => void = () => {}) {}
+
+  fs = (who: Who, op: string, args: unknown[], signal?: AbortSignal) => this.serve("fs", who, op, args, signal);
+  http = (who: Who, op: string, args: unknown[], signal?: AbortSignal) => this.serve("http", who, op, args, signal);
+  exec = (who: Who, op: string, args: unknown[], signal?: AbortSignal) => this.serve("exec", who, op, args, signal);
+  secrets = (who: Who, op: string, args: unknown[], signal?: AbortSignal) => this.serve("secrets", who, op, args, signal);
+
+  private serve(service: ServiceName, who: Who, op: string, args: unknown[], signal = new AbortController().signal): Promise<unknown> | AsyncIterable<unknown> {
+    const ops = this.modules[service];
+    const started = performance.now();
+    const fail = (e: unknown): ServiceError => {
+      if (e instanceof Error && e.name === "ExecutionCleanupError") throw e;
+      const error = e instanceof ServiceError ? e : new ServiceError("failed", e instanceof Error ? e.message : String(e));
+      this.log({ who, service, op, args, ok: false, ms: performance.now() - started, code: error.code, error: error.message });
+      return error;
+    };
+    try {
+      if (!Object.hasOwn(ops, op)) throw new ServiceError("args", `${service} has no operation ${op}; operations: ${Object.keys(ops).join(", ")}`);
+      if (!Array.isArray(args)) throw new ServiceError("args", `${service} ${op}: expected an array of arguments`);
+    } catch (e) { return Promise.reject(fail(e)); }
+    if (isStream(service, op)) {
+      // A stream is logged when it opens and when it closes, never per answer.
+      const log = this.log;
+      const inner = ops[op]!(who, args, signal) as AsyncIterable<unknown>;
+      return (async function* () {
+        log({ who, service, op, args, ok: true, ms: 0 });
+        try { for await (const v of inner) yield v; } catch (e) { throw fail(e); }
+        finally { log({ who, service, op: `${op} closed`, args, ok: true, ms: performance.now() - started }); }
+      })();
+    }
+    return (async () => {
+      try {
+        const value = await (ops[op]!(who, args, signal) as Promise<unknown>);
+        this.log({ who, service, op, args, ok: true, ms: performance.now() - started });
+        return value;
+      } catch (e) { throw fail(e); }
+    })();
+  }
+}
+
+/** How many values one streamed answer carries at most. */
+export const BATCH = 500;
+
+/**
+ * Answers one service request of a runtime, through `send`: once, or for a
+ * streaming operation many times, batched, then once more to end it. The
+ * kernel resolves `who` from the request; `signal` is the request's, aborted
+ * when the runtime cancels or goes away.
+ */
+export async function serveRequest(services: Services, who: Who, req: ServiceRequest, send: (m: Serviced) => void, signal: AbortSignal, credit?: () => Promise<void>): Promise<void> {
+  const { id, service, op, args } = req;
+  const failed = (e: unknown): Serviced => e instanceof ServiceError
+    ? { type: "serviced", id, ok: false, code: e.code, error: e.message }
+    : { type: "serviced", id, ok: false, code: "failed", error: e instanceof Error ? e.message : String(e) };
+  try {
+    if (!Object.hasOwn(modules, service)) throw new ServiceError("args", `no service ${service}; services: ${Object.keys(modules).join(", ")}`);
+    if (!Array.isArray(args)) throw new ServiceError("args", `${service} ${op}: expected an array of arguments`);
+    const answer = services[service](who, op as never, args, signal);
+    if (!isStream(service, op)) { send({ type: "serviced", id, ok: true, value: await (answer as Promise<unknown>) }); return; }
+    if (service === "exec") {
+      for await (const v of answer as AsyncIterable<unknown>) {
+        await credit?.();
+        if (signal.aborted) return;
+        send({ type: "serviced", id, ok: true, more: true, values: [v] });
+      }
+      if (!signal.aborted) send({ type: "serviced", id, ok: true });
+      return;
+    }
+    let batch: unknown[] = [];
+    for await (const v of answer as AsyncIterable<unknown>) {
+      if (signal.aborted) return;
+      batch.push(v);
+      if (batch.length >= BATCH) { send({ type: "serviced", id, ok: true, more: true, values: batch }); batch = []; }
+      else queueMicrotask(() => { if (batch.length) { send({ type: "serviced", id, ok: true, more: true, values: batch }); batch = []; } });
+    }
+    if (batch.length) send({ type: "serviced", id, ok: true, more: true, values: batch });
+    if (!signal.aborted) send({ type: "serviced", id, ok: true });
+  } catch (e) {
+    if (e instanceof Error && e.name === "ExecutionCleanupError") throw e;
+    if (!signal.aborted) send(failed(e));
+  }
+}

package/src/services/secrets.ts

@@ -0,0 +1,18 @@
+// Secrets, read from the operating
+// system's keychain under the service "babavoss"; the value never rests in
+// a file of the project.
+import { ServiceError, type Secrets, type Who } from "../kernel/context.ts";
+import { string, type Ops } from "./args.ts";
+
+export const Service = "babavoss";
+
+export const secrets: Ops<Secrets> = {
+  async get(who, [n]) {
+    const name = string(n, "name");
+    const keychain = (Bun as { secrets?: typeof Bun.secrets }).secrets;
+    if (typeof keychain?.get !== "function") throw new ServiceError("failed", `the keychain is not available on this platform (${process.platform}); secret ${name} cannot be read`);
+    try { return await keychain.get({ service: Service, name }); } catch (e) {
+      throw new ServiceError("failed", `secret ${name}: the keychain answered ${e instanceof Error ? e.message : String(e)}`);
+    }
+  },
+};

package/src/shell/address.ts

@@ -0,0 +1,21 @@
+import { UsageError } from "./args.ts";
+
+/** Voss's conventional TCP port: 0xBABA. Explicit addresses override it. */
+export const DEFAULT_PORT = 0xBABA;
+export const DEFAULT_HOST = "127.0.0.1";
+export const DEFAULT_ADDRESS = `${DEFAULT_HOST}:${DEFAULT_PORT}`;
+
+export function hostPort(word: string | undefined): [string, number] {
+  const split = word?.lastIndexOf(":") ?? -1;
+  const host = split >= 0 ? word!.slice(0, split) || DEFAULT_HOST : DEFAULT_HOST;
+  const port = split >= 0 ? word!.slice(split + 1) : word ?? String(DEFAULT_PORT);
+  if (!/^\d+$/.test(port) || Number(port) > 65535) throw new UsageError(`expected HOST:PORT or PORT, got ${word}`);
+  return [host.replace(/^\[(.*)\]$/, "$1"), Number(port)];
+}
+
+/** A browser address for the installed service, including explicit hosts. */
+export function browserUrl(address: string): string {
+  const [host, port] = hostPort(address);
+  const browserHost = ["127.0.0.1", "0.0.0.0", "::"].includes(host) ? "localhost" : host;
+  return `http://${browserHost.includes(":") ? `[${browserHost}]` : browserHost}:${port}/`;
+}

package/src/shell/args.ts

@@ -0,0 +1,219 @@
+// Words to arguments, and a command's usage line from its manifest.
+import type { Json } from "../kernel/schema.ts";
+import { redact } from "../ecs/handles.ts";
+
+export class UsageError extends Error {
+  /** The code it answers: `usage` for the words, `args` for what they say. */
+  constructor(msg: string, readonly code: "usage" | "args" = "usage") { super(msg); }
+}
+
+export interface Spec {
+  /** The args filled from bare words, in order. */
+  positional?: string[];
+  /** Flags that take no value: `--flag`, `--flag=false`, `--no-flag`. */
+  booleans?: string[];
+  /** The last positional takes the rest of the bare words when it is one of these. */
+  arrays?: string[];
+}
+
+/**
+ * A command's words to its args. `--name VALUE` and `--name=VALUE` are
+ * flags; `--name=VALUE` is the spelling for a value starting with `--`. A
+ * flag that needs a value and has none is a UsageError. A boolean (named in
+ * `booleans`) never takes the next word: it is "true" bare, and
+ * `--flag=false` or `--no-flag` for false; a bare true or false right after
+ * it is a UsageError. A flag given twice is an array. Bare words fill the
+ * positionals not given as flags, in order; the last positional takes the
+ * rest when it is an array (`arrays`). After `--` every word is bare. An
+ * extra bare word is a UsageError.
+ */
+export function words(ws: string[], spec: Spec | string[] = {}, booleansOld: string[] = [], arraysOld: string[] = []): Record<string, string | string[]> {
+  const { positional = [], booleans = [], arrays = [] } = Array.isArray(spec) ? { positional: spec, booleans: booleansOld, arrays: arraysOld } : spec;
+  const out: Record<string, string | string[]> = {};
+  const bare = barewords(ws, booleans, out);
+  const open = positional.filter((p) => !(p in out));
+  for (let i = 0; i < open.length && bare.length; i++) {
+    const p = open[i]!;
+    const last = p === positional.at(-1);
+    out[p] = last && arrays.includes(p) ? bare.splice(0) : bare.shift()!;
+  }
+  if (bare.length) {
+    const took = positional.length ? `takes ${positional.map((p) => `<${p}>`).join(" ")}` : "takes no bare words";
+    throw new UsageError(`${took}; extra: ${bare.map((b) => JSON.stringify(b)).join(" ")}`);
+  }
+  return out;
+}
+
+/** The flags of `ws` into `out`; answers the bare words, in order. */
+function barewords(ws: string[], booleans: string[], out: Record<string, string | string[]>, at: number[] = []): string[] {
+  const bare: string[] = [];
+  const set = (name: string, v: string) => {
+    const had = out[name];
+    out[name] = had === undefined ? v : Array.isArray(had) ? [...had, v] : [had, v];
+  };
+  let rest = false;
+  for (let i = 0; i < ws.length; i++) {
+    const w = ws[i]!;
+    if (rest || !w.startsWith("--")) { bare.push(w); at.push(i); continue; }
+    if (w === "--") { rest = true; continue; }
+    const eq = w.indexOf("=");
+    if (eq > 0) { set(w.slice(2, eq), w.slice(eq + 1)); continue; }
+    const name = w.slice(2);
+    const next = ws[i + 1];
+    if (booleans.includes(name)) {
+      if (next === "true" || next === "false") throw new UsageError(`--${name} is a flag on its own; write --${name}=${next}`);
+      set(name, "true");
+      continue;
+    }
+    if (name.startsWith("no-") && booleans.includes(name.slice(3))) { set(name.slice(3), "false"); continue; }
+    if (next === undefined || next.startsWith("--")) throw new UsageError(`--${name} needs a value; write --${name}=VALUE for a value starting with --`);
+    set(name, next);
+    i++;
+  }
+  return bare;
+}
+
+type Props = Record<string, Json>;
+const propsOf = (args: Json) => (args.properties ?? {}) as Props;
+/** A schema's type, its null removed: "string", "object", … or undefined. */
+const typeOf = (j: Json | undefined): string | undefined => {
+  const t = j?.type;
+  return Array.isArray(t) ? (t.find((x) => x !== "null") as string | undefined) : (t as string | undefined);
+};
+const scalar = (j: Json | undefined) => { const t = typeOf(j); return t === undefined ? !(j && "properties" in j) : ["string", "number", "integer", "boolean"].includes(t); };
+/** Whether a flag's value is JSON: an object, or an array whose items are not scalars. */
+const jsonValued = (j: Json | undefined) => !!j && (typeOf(j) === "object" || "properties" in j || (typeOf(j) === "array" && !scalar(j.items as Json | undefined)));
+const secret = (j: Json | undefined) => j?.format === "secret";
+
+/** What words() needs from a command's args schema: its boolean and array properties. */
+export function kinds(args: Json): { booleans: string[]; arrays: string[] } {
+  const props = propsOf(args);
+  const of = (t: string) => Object.keys(props).filter((n) => typeOf(props[n]) === t);
+  return { booleans: of("boolean"), arrays: of("array") };
+}
+
+/** A call as the shell sees it: its args schema and positionals. */
+export interface Call { args: Json; positional?: string[] }
+
+/**
+ * A call's words to its args, by the schema: flags and positionals as
+ * words() reads them; an object field, or an array of non-scalars, takes its
+ * flag's value as JSON; one bare word that is a JSON object is the whole args,
+ * the canonical spelling (a flag wins over it); with positionals declared, a
+ * bare `{` word that is not JSON is a positional like any other. A secret is never
+ * taken from the command line: `--NAME @-` reads the whole of stdin, trimmed,
+ * for any field. `extra` names flags the caller takes for itself (`--key`):
+ * they are answered apart, not as args.
+ */
+export async function callArgs(ws: string[], def: Call, stdin?: () => Promise<string>, extra: string[] = []): Promise<{ args: Record<string, unknown>; extra: Record<string, string> }> {
+  const props = propsOf(def.args);
+  const positional = def.positional ?? [];
+  const { booleans, arrays } = kinds(def.args);
+  let whole: Record<string, unknown> = {};
+  let rest = ws;
+  const at: number[] = [];
+  const bare = barewords(ws, booleans, {}, at);
+  if (bare.length === 1 && bare[0] === "@-") {
+    // The whole args from stdin, as a harness hands an event to a hook.
+    if (!stdin) throw new UsageError("@- reads the args from standard input, and there is none");
+    let parsed: unknown;
+    try { parsed = JSON.parse((await stdin()).trim() || "{}"); } catch { throw new UsageError("the args on stdin are not JSON", "args"); }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new UsageError("the args are a JSON object", "args");
+    whole = parsed as Record<string, unknown>;
+    rest = [...ws.slice(0, at[0]), ...ws.slice(at[0]! + 1)];
+  } else if (bare.length === 1 && bare[0]!.startsWith("{")) {
+    // One bare {…} word is the whole args, the canonical spelling; with positionals declared, a word that is not a JSON object is a positional like any other.
+    let parsed: unknown;
+    try { parsed = JSON.parse(bare[0]!); } catch { if (!positional.length) throw new UsageError(`the args are not JSON: ${bare[0]}`, "args"); }
+    if (parsed !== undefined || !positional.length) {
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new UsageError("the args are a JSON object", "args");
+      whole = parsed as Record<string, unknown>;
+      if (JSON.stringify(redact(def.args, whole)) !== JSON.stringify(whole)) throw new UsageError("a secret is never on the command line; pass it as --NAME @- to read it from stdin", "args");
+      rest = [...ws.slice(0, at[0]), ...ws.slice(at[0]! + 1)];
+    }
+  }
+  const w = words(rest, { positional, booleans, arrays });
+  const out: Record<string, unknown> = { ...whole };
+  const taken: Record<string, string> = {};
+  let read = false;
+  for (const [n, v] of Object.entries(w)) {
+    if (extra.includes(n)) {
+      if (Array.isArray(v)) throw new UsageError(`--${n} is given once`);
+      taken[n] = v;
+      continue;
+    }
+    const p = props[n];
+    if (v === "@-") {
+      if (!stdin) throw new UsageError(`--${n} @- reads standard input, and there is none`);
+      if (read) throw new UsageError(`only one field reads standard input`);
+      read = true;
+      out[n] = (await stdin()).trim();
+      continue;
+    }
+    if (secret(p) || secret(p?.items as Json | undefined)) {
+      throw new UsageError(`${n} is a secret, never on the command line; pass it as --${n} @- to read it from stdin`, "args");
+    }
+    if (jsonValued(p)) {
+      const one = (s: string) => {
+        let x: unknown;
+        try { x = JSON.parse(s); } catch { throw new UsageError(`--${n} takes JSON, got ${s}`, "args"); }
+        if (JSON.stringify(redact(p!, x)) !== JSON.stringify(x)) throw new UsageError(`--${n} holds a secret, never on the command line; pass it as --${n} @- to read it from stdin`, "args");
+        return x;
+      };
+      const all = (Array.isArray(v) ? v : [v]).map(one);
+      // An array field: one flag holding a JSON array is the array; else each flag is one item.
+      out[n] = typeOf(p) === "array" ? (all.length === 1 && Array.isArray(all[0]) ? all[0] : all) : Array.isArray(v) ? all : all[0];
+      continue;
+    }
+    out[n] = v;
+  }
+  return { args: out, extra: taken };
+}
+
+/** The word a value takes in usage: its enum, entity, JSON or stdin, else VALUE. */
+function valueWord(p: Json | undefined): string {
+  if (!p) return "VALUE";
+  if (secret(p)) return "@-";
+  if (Array.isArray(p.enum)) return (p.enum as unknown[]).map(String).join("|");
+  if (typeof p["x-entity"] === "string") return "entity";
+  if (jsonValued(p)) return "JSON";
+  return "VALUE";
+}
+
+/** A command's words from its args schema: positionals in order, then flags, required first, booleans bare; types where they are cheap. */
+export function usage(args: Json, positional: string[] = []): string[] {
+  const props = propsOf(args);
+  const required = new Set((args.required as string[] | undefined) ?? []);
+  const pos = positional.map((n) => {
+    const t = valueWord(typeOf(props[n]) === "array" ? props[n]!.items as Json : props[n]);
+    const word = `<${n}${t === "VALUE" ? "" : `:${t}`}${typeOf(props[n]) === "array" ? "…" : ""}>`;
+    return required.has(n) ? word : `[${word}]`;
+  });
+  const names = Object.keys(props).filter((n) => !positional.includes(n))
+    .sort((a, b) => Number(required.has(b)) - Number(required.has(a)) || a.localeCompare(b));
+  return [...pos, ...names.map((n) => {
+    const flag = typeOf(props[n]) === "boolean" ? `--${n}` : `--${n} ${valueWord(props[n])}`;
+    return required.has(n) ? flag : `[${flag}]`;
+  })];
+}
+
+/** One line per argument for help: positionals as <name>, the rest as --name, with type and description. */
+export function describeArgs(args: Json, positional: string[] = []): string[] {
+  const props = propsOf(args);
+  const names = [...positional.filter((n) => n in props), ...Object.keys(props).filter((n) => !positional.includes(n))];
+  return names.map((n) => {
+    const p = props[n]!;
+    const type = Array.isArray(p.type) ? p.type.join("|") : String(p.type ?? (p.enum ? (p.enum as string[]).join("|") : "value"));
+    const word = positional.includes(n) ? (p.type === "array" ? `<${n}…>` : `<${n}>`) : `--${n}`;
+    const how = secret(p) ? ", read from stdin with --" + n + " @-" : jsonValued(p) ? ", as JSON" : "";
+    return `  ${word.padEnd(16)} ${type}${how}${p.description ? `: ${p.description}` : ""}`;
+  });
+}
+
+/** `30`, `30s`, `2m`, `500ms`: milliseconds. */
+export function duration(s: string): number {
+  const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(s.trim());
+  if (!m) throw new UsageError(`a duration is seconds, 30s, 2m or 500ms; got ${s}`);
+  const n = Number(m[1]);
+  return Math.round(n * ({ ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[m[2] ?? "s"]!));
+}

package/src/shell/client.ts

@@ -0,0 +1,107 @@
+// The shell's way to a baba's state. A baba runs as a child of the root's
+// daemon or it does not run: the daemon writes its address next to its page
+// token, and the shell speaks to the state over loopback with both. Nothing
+// here loads a baba.
+import { join } from "node:path";
+import type { Project } from "../baba/project.ts";
+import { NodeError, type Described } from "../baba/node.ts";
+import type { StateAnswer } from "../ecs/snapshot.ts";
+import type { Raw } from "../ecs/runtime.ts";
+import { addressPath, type Address } from "../http/server.ts";
+import type { ProjectEntry, Refreshed } from "../server/messages.ts";
+
+export interface Client {
+  /** Where the state is: the daemon's address. */
+  where: string;
+  describe(): Promise<Described>;
+  /** An action; `key` is its idempotency key; `coerce` reads shell strings as the schema's numbers and booleans. */
+  fire(name: string, args: unknown, o?: { key?: string; coerce?: boolean }): Promise<unknown>;
+  read(name: string, args: unknown, o?: { coerce?: boolean }): Promise<unknown>;
+  /** The state once a round past `since` has run, or as it is after the daemon's wait (~25 s); `signal` cuts it short. */
+  state(since?: number, signal?: AbortSignal): Promise<StateAnswer>;
+  raw(raw: Raw): Promise<unknown>;
+}
+
+/** The root's daemon, answering. */
+export interface Daemon {
+  where: string;
+  /** The base URL the calls go to. */
+  base: string;
+  projects(): Promise<ProjectEntry[]>;
+  /** Asks it to re-read the registry: what was added opens, what was removed retires. */
+  refresh(): Promise<Refreshed>;
+  get(path: string, signal?: AbortSignal): Promise<unknown>;
+  post(path: string, body: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+
+/** How long a call waits for its answer by default. */
+export const CALL_MS = 30_000;
+
+/** A fetch whose failure is a NodeError: `timeout` when the time ran out, `down` when nothing answered. */
+async function request(url: string, init: RequestInit, signal = AbortSignal.timeout(CALL_MS)): Promise<Response> {
+  try { return await fetch(url, { ...init, signal }); }
+  catch (err) {
+    const name = err instanceof Error ? err.name : "";
+    if (name === "TimeoutError") throw new NodeError("timeout", `no answer from ${new URL(url).host} in time`);
+    if (name === "AbortError") throw err;
+    throw new NodeError("down", `the daemon at ${new URL(url).host} does not answer: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/** The daemon whose address and token are in `rootDir`, if it answers. */
+export async function daemon(rootDir: string): Promise<Daemon | null> {
+  let addr: Address;
+  try { addr = (await Bun.file(addressPath(rootDir)).json()) as Address; } catch { return null; }
+  const token = (await Bun.file(join(rootDir, "http-token")).text().catch(() => "")).trim();
+  if (!token || typeof addr.port !== "number") return null;
+  const headers = { authorization: `Bearer ${token}`, "content-type": "application/json" };
+  const host = !addr.hostname || addr.hostname === "0.0.0.0" || addr.hostname === "::" ? "127.0.0.1" : addr.hostname;
+  const base = `http://${host.includes(":") ? `[${host}]` : host}:${addr.port}`;
+  try {
+    const r = await fetch(`${base}/api/projects`, { headers, signal: AbortSignal.timeout(1500) });
+    if (!r.ok) return null;
+  } catch { return null; }
+  const answer = async (r: Response) => {
+    const j = await r.json() as { value?: unknown; error?: { code: string; message: string } };
+    if (!r.ok || j.error) throw new NodeError(j.error?.code ?? "failed", j.error?.message ?? r.statusText);
+    return j;
+  };
+  const d: Daemon = {
+    where: `${host}:${addr.port}`,
+    base,
+    get: async (path, signal) => answer(await request(`${base}/api/${path}`, { headers }, signal)),
+    post: async (path, body, signal) => answer(await request(`${base}/api/${path}`, { method: "POST", headers, body: JSON.stringify(body ?? {}) }, signal)),
+    projects: async () => ((await d.get("projects")) as { projects: ProjectEntry[] }).projects,
+    refresh: async () => (await d.post("projects/refresh", {})) as Refreshed,
+  };
+  return d;
+}
+
+/** The baba as the daemon runs it; `down` with the way to start it when the daemon does not answer or does not run it. */
+export async function connect(project: Project, rootDir: string, prog = "voss baba"): Promise<Client> {
+  const down = new NodeError("down", `${project.name} is not running; ${prog} start`);
+  const d = await daemon(rootDir);
+  if (!d) throw down;
+  if (!(await d.projects()).some((p) => p.name === project.name && p.dir === project.dir)) throw down;
+  const name = encodeURIComponent(project.name);
+  const value = async (path: string, body: unknown, signal?: AbortSignal) => ((await d.post(path, body, signal)) as { value: unknown }).value;
+  const query = (o: { key?: string; coerce?: boolean }) => {
+    const q = [...(o.coerce ? ["coerce"] : []), ...(o.key ? [`key=${encodeURIComponent(o.key)}`] : [])];
+    return q.length ? `?${q.join("&")}` : "";
+  };
+  return {
+    where: d.where,
+    describe: async () => (await d.get(`describe/${name}`)) as Described,
+    // A fire that was sent and got no answer may have run: `unknown`, not `down`; its key, if any, makes a retry safe.
+    fire: async (n, args, o = { coerce: true }) => {
+      try { return await value(`fire/${name}/${encodeURIComponent(n)}${query(o)}`, args); }
+      catch (err) {
+        if (!(err instanceof NodeError) || err.code !== "timeout") throw err;
+        throw Object.assign(new NodeError("unknown", `${n} was sent and its answer did not come in time; it may have run${o.key ? `: the same call with --key ${o.key} answers the same` : ""}`), o.key ? { key: o.key } : {});
+      }
+    },
+    read: (n, args, o = { coerce: true }) => value(`read/${name}/${encodeURIComponent(n)}${query(o)}`, args),
+    state: (since = 0, signal) => value(`state/${name}`, { since }, signal) as Promise<StateAnswer>,
+    raw: (raw) => { const { op, ...rest } = raw; return value(`raw/${name}/${op}`, rest); },
+  };
+}