babavoss 0.0.1 → 0.12.0

package/src/wall/probe.ts

@@ -0,0 +1,67 @@
+// A probe the tests run behind the wall, sent as text through `bun -e`, so
+// it needs no file of its own. It tries what the wall must deny and reports
+// each attempt as allowed or denied, through IPC when spawned with it, else
+// as one line of JSON on stdout. Targets come from the environment:
+// PROBE_READ (a file to read), PROBE_WRITE (a file to create), PROBE_EXEC (a
+// program to run), PROBE_URL (a URL to fetch).
+// Kept free of imports: it runs as a single script.
+
+type Outcome = { allowed: boolean; detail: string };
+
+async function attempt(f: () => Promise<unknown> | unknown): Promise<Outcome> {
+  try {
+    const v = await f();
+    return { allowed: true, detail: String(v).slice(0, 80) };
+  } catch (e) {
+    return { allowed: false, detail: e instanceof Error ? `${(e as { code?: string }).code ?? e.name}: ${e.message}`.slice(0, 120) : String(e) };
+  }
+}
+
+const env = process.env;
+const results: Record<string, Outcome> = {};
+if (env.PROBE_READ) results.read = await attempt(() => Bun.file(env.PROBE_READ!).text());
+results.readEtc = await attempt(() => Bun.file("/private/etc/hosts").text());
+results.list = await attempt(async () => (await import("node:fs")).readdirSync("/").length);
+if (env.PROBE_WRITE) results.write = await attempt(() => Bun.write(env.PROBE_WRITE!, "written from behind the wall"));
+if (env.PROBE_EXEC) results.exec = await attempt(async () => {
+  const p = Bun.spawn([env.PROBE_EXEC!, "-e", "1"], { stdout: "ignore", stderr: "ignore", env: {} });
+  return `exit ${await p.exited}`;
+});
+results.execSelf = await attempt(async () => {
+  const p = Bun.spawn([process.execPath, "-e", "1"], { stdout: "ignore", stderr: "ignore", env: {} });
+  return `exit ${await p.exited}`;
+});
+if (env.PROBE_URL) results.fetch = await attempt(async () => (await fetch(env.PROBE_URL!, { signal: AbortSignal.timeout(3000) })).status);
+results.fetchIp = await attempt(async () => (await fetch("http://1.1.1.1/", { signal: AbortSignal.timeout(3000) })).status);
+
+// What the wall must keep working: a worker from text, the local time zone.
+results.worker = await attempt(async () => {
+  const url = URL.createObjectURL(new Blob(["self.onmessage = (e) => postMessage(e.data * 2)"], { type: "application/javascript" }));
+  const w = new Worker(url);
+  const doubled = await new Promise((resolve) => { w.onmessage = (e) => resolve(e.data); w.postMessage(21); });
+  w.terminate();
+  return doubled;
+});
+results.timezone = await attempt(() => Intl.DateTimeFormat().resolvedOptions().timeZone);
+
+// Loopback: serve, then fetch ourselves. The server stays up until told to stop,
+// so the parent can reach it from outside the wall.
+let server: ReturnType<typeof Bun.serve> | null = null;
+results.serve = await attempt(() => {
+  server = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response("inside") });
+  return server.port;
+});
+results.loopback = await attempt(async () => {
+  if (!server) throw new Error("no server");
+  return await (await fetch(`http://127.0.0.1:${server.port}/`, { signal: AbortSignal.timeout(3000) })).text();
+});
+
+const report = { type: "probes", results, port: (server as { port?: number } | null)?.port ?? 0, env: Object.keys(env).sort() };
+if (typeof process.send === "function") {
+  process.send(report);
+  process.on("message", (m) => { if ((m as { type?: string }).type === "stop") process.exit(0); });
+  process.on("disconnect", () => process.exit(0));
+} else {
+  console.log(JSON.stringify(report));
+  process.exit(0);
+}

package/src/wall/profile.ts

@@ -0,0 +1,103 @@
+// The Seatbelt profile a walled child runs under on macOS. It starts from
+// (deny default) and allows only what Bun needs to start and to run code it
+// is sent as text, in workers too:
+//
+// - process-exec of the Bun binary itself, by the path given and its real
+//   path, so sandbox-exec can start it and nothing else can be started.
+//   There is no process-fork, so the child cannot spawn even itself.
+// - file-read of the binary's directory, to map the executable, and
+//   file-read-metadata of the directories above it, for the realpath walk.
+// - file-read of /usr/lib, /System/Library and /private/var/db/dyld: the
+//   system libraries and the dyld shared cache every process links against.
+// - file-read of /dev/null, /dev/random, /dev/urandom, and file-write of
+//   /dev/null: stdio redirection and the entropy Bun seeds its hashing and
+//   crypto with.
+// - file-read of /usr/share/icu, /usr/share/zoneinfo, /private/var/db/timezone
+//   and /private/etc/localtime, with file-read-metadata of the links on the
+//   way (/etc, /var, /private...): Intl needs ICU data, Date the local zone.
+//   Without them Date quietly runs in UTC.
+// - file-read of "/" itself, the directory and not what is under it: the
+//   child starts in "/" and Bun opens its working directory at startup. It
+//   lets the child list the top-level names, nothing below.
+// - sysctl-read: CPU count, page size, OS version; Bun aborts without it.
+//
+// No mach-lookup at all: Bun starts, runs workers, serves loopback and
+// speaks IPC without any. The one thing lost is os.homedir() with no HOME,
+// which would need opendirectoryd; a walled child has no home anyway.
+//
+// With `loopback`, the child may bind, accept and connect on localhost only;
+// the GUI server needs that, a runtime does not. `readable` and
+// `writable` add subpaths an integrator may grant later; by default none.
+// Everything else is denied: other files, writes, exec, fork, mach services,
+// outbound network including DNS.
+import { realpathSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Directories a path passes through, "/" excluded: /a/b/c gives /a, /a/b. */
+function ancestors(path: string): string[] {
+  const out: string[] = [];
+  for (let d = dirname(path); d !== "/" && d !== "."; d = dirname(d)) out.unshift(d);
+  return out;
+}
+
+export interface ProfileOptions {
+  /** The program the wall may run: the Bun binary. */
+  binary: string;
+  /** Allow listening and connecting on localhost. */
+  loopback?: boolean;
+  /** Extra subpaths the child may read. */
+  readable?: string[];
+  /** Extra subpaths the child may read and write. */
+  writable?: string[];
+  /** Subpaths taken back out of `readable`: a later deny beats an earlier allow. */
+  unreadable?: string[];
+  /** Symbolic links on the way to a readable target, granted as the paths they are, not their targets. */
+  links?: string[];
+}
+
+/** Seatbelt strings are double-quoted; a path with a quote or backslash is refused rather than escaped wrong. */
+function quote(path: string): string {
+  if (!path.startsWith("/")) throw new Error(`the wall needs absolute paths, got ${JSON.stringify(path)}`);
+  if (/["\\\n\0]/.test(path)) throw new Error(`the wall refuses a path with quotes, backslashes or newlines: ${JSON.stringify(path)}`);
+  return `"${path}"`;
+}
+
+/** The real path, so a symlinked /tmp or binary matches what the kernel sees. */
+function real(path: string): string {
+  try { return realpathSync(path); } catch { return path; }
+}
+
+export function seatbeltProfile(o: ProfileOptions): string {
+  const binary = real(o.binary);
+  const execs = [...new Set([o.binary, binary])];
+  const readable = (o.readable ?? []).map(real);
+  const writable = (o.writable ?? []).map(real);
+  const unreadable = (o.unreadable ?? []).map(real);
+  const binaryDir = dirname(binary);
+  const lines = [
+    "(version 1)",
+    "(deny default)",
+    `(allow process-exec ${execs.map((p) => `(literal ${quote(p)})`).join(" ")})`,
+    `(allow file-read* (subpath ${quote(binaryDir)}))`,
+    ...ancestors(binary).map((p) => `(allow file-read-metadata (literal ${quote(p)}))`),
+    '(allow file-read* (subpath "/usr/lib") (subpath "/System/Library") (subpath "/private/var/db/dyld"))',
+    '(allow file-read* (literal "/dev/null") (literal "/dev/random") (literal "/dev/urandom"))',
+    '(allow file-write* (literal "/dev/null"))',
+    '(allow file-read* (subpath "/usr/share/icu") (subpath "/usr/share/zoneinfo") (subpath "/private/var/db/timezone") (literal "/private/etc/localtime"))',
+    '(allow file-read-metadata (literal "/etc") (literal "/var") (literal "/private") (literal "/private/etc") (literal "/private/var") (literal "/private/var/db") (literal "/usr") (literal "/usr/share"))',
+    '(allow file-read* (literal "/"))',
+    "(allow sysctl-read)",
+  ];
+  if (o.loopback) {
+    lines.push(
+      '(allow network-bind (local ip "localhost:*"))',
+      '(allow network-inbound (local ip "localhost:*"))',
+      '(allow network-outbound (remote ip "localhost:*"))',
+    );
+  }
+  for (const p of readable) lines.push(`(allow file-read* (subpath ${quote(p)}))`);
+  for (const p of o.links ?? []) lines.push(`(allow file-read* (literal ${quote(p)}))`, ...ancestors(p).map((a) => `(allow file-read-metadata (literal ${quote(a)}))`));
+  for (const p of writable) lines.push(`(allow file-read* file-write* (subpath ${quote(p)}))`);
+  for (const p of unreadable) lines.push(`(deny file-read* (subpath ${quote(p)}))`);
+  return lines.join("\n") + "\n";
+}

package/src/wall/spawn.ts

@@ -0,0 +1,59 @@
+// Starting a child behind the wall. On macOS the child runs under
+// sandbox-exec with a Seatbelt profile, in "/", with exactly the
+// environment given. Elsewhere it refuses, so nothing runs unwalled by accident.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { tmpdir } from "node:os";
+import { ProcessTransport } from "../transport/transport.ts";
+import type { Message } from "../transport/messages.ts";
+
+const SANDBOX = "/usr/bin/sandbox-exec";
+
+export interface WallOptions {
+  /** The profile text, from seatbeltProfile. */
+  profile: string;
+  /** The child's whole environment; nothing is inherited from the parent. */
+  env: Record<string, string>;
+  /** Where the profile file is written: the kernel's state directory. Defaults to the system temp directory. */
+  dir?: string;
+  /** The child's working directory: "/" unless the profile lets it read somewhere, since Bun opens it at startup. */
+  cwd?: string;
+  stdout?: "inherit" | "pipe" | "ignore";
+  stderr?: "inherit" | "pipe" | "ignore";
+}
+
+export interface Walled {
+  cmd: string[];
+  cwd: string;
+  env: Record<string, string>;
+  stdout?: "inherit" | "pipe" | "ignore";
+  stderr?: "inherit" | "pipe" | "ignore";
+}
+
+function assertSupported() {
+  if (process.platform !== "darwin") throw new Error(`the wall is not implemented on ${process.platform} yet`);
+}
+
+/** Writes the profile to a file named by its content, so equal profiles share one file. */
+function profileFile(profile: string, dir: string): string {
+  mkdirSync(dir, { recursive: true });
+  const name = `wall-${Bun.hash(profile).toString(16)}.sb`;
+  const path = join(dir, name);
+  writeFileSync(path, profile, { mode: 0o600 });
+  return path;
+}
+
+/** The spawn options that run `cmd` behind the wall. `cmd[0]` must be absolute: the wall grants exec of one path. */
+export function walled(cmd: string[], o: WallOptions): Walled {
+  assertSupported();
+  const program = cmd[0];
+  if (!program || !isAbsolute(program)) throw new Error(`the wall runs an absolute program path, got ${JSON.stringify(program)}`);
+  const file = profileFile(o.profile, o.dir ?? join(tmpdir(), "babavoss-wall"));
+  return { cmd: [SANDBOX, "-f", file, ...cmd], cwd: o.cwd ?? "/", env: { ...o.env }, stdout: o.stdout, stderr: o.stderr };
+}
+
+/** Spawns `cmd` behind the wall, with IPC as its transport. */
+export function spawnWalled<Out extends { type: string } = Message, In extends { type: string } = Message>(cmd: string[], o: WallOptions): ProcessTransport<Out, In> {
+  const w = walled(cmd, o);
+  return new ProcessTransport<Out, In>(w.cmd, { cwd: w.cwd, env: w.env, stdout: w.stdout, stderr: w.stderr });
+}

package/src/web/app.tsx

@@ -0,0 +1,53 @@
+// The state a component reads, provided. The hooks, useQuery, useComponent,
+// useColumn and the rest, read whatever state the component is shown over:
+// live, the page's store, following the rounds; in the Maker, a simulated
+// state; in a test, a fixed frame. An app written with hooks draws the same
+// in all three, and its hand, from useHand, is there only when it may act.
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import type { Replica } from "../ecs/replica.ts";
+import type { Probe } from "./store.ts";
+
+/** What an app may do to the state it draws. */
+export interface Hand { fire(name: string, args?: unknown): void }
+
+/** What the hooks need of a state: a replica to read, and a way to hear it change. The page's live store is one; a fixed replica is another. */
+export interface HookStore {
+  replica: Replica<any>;
+  probe: Probe;
+  subscribe(fn: () => void): () => void;
+  retain(): () => void;
+  committed(): void;
+  wantAll(): () => void;
+  wantPresence(c: { name: string }): () => void;
+  wantValues(c: { name: string }): () => void;
+  wantPart(e: number, c: { name: string }): () => void;
+  wantResource(r: { name: string }): () => void;
+  wantSelect(sel: unknown): () => void;
+}
+
+const none = () => () => {};
+/** A state that does not move: a frame, a sketch. Its interests ask nothing of a socket; a new frame is a new store. */
+export function fixedStore(replica: Replica<any>): HookStore {
+  return { replica, probe: { samples: [] }, subscribe: none, retain: none, committed: () => {}, wantAll: none, wantPresence: none, wantValues: none, wantPart: none, wantResource: none, wantSelect: none };
+}
+
+/** The state the hooks read when a component is shown over a fixed one; null means the live store: a LiveStoreContext's, else the page's own. */
+export const AppStoreContext = createContext<HookStore | null>(null);
+/** No hand was given here: useHand finds the live store's. */
+export const UNSET: unique symbol = Symbol("no hand given");
+/** The hand given to a subtree, or `UNSET` where none was. */
+export const HandContext = createContext<Hand | undefined | typeof UNSET>(UNSET);
+
+/**
+ * Shows its children over a state: every hook inside reads `w`, and useHand answers `hand`, none when it is not given.
+ * Without `w`, the hooks read the state they read outside, and only the hand is given.
+ */
+export function AppState({ w, hand, children }: { w?: Replica<any>; hand?: Hand; children: ReactNode }) {
+  const store = useMemo(() => (w ? fixedStore(w) : null), [w]);
+  const outer = useContext(AppStoreContext);
+  return (
+    <AppStoreContext.Provider value={store ?? outer}>
+      <HandContext.Provider value={hand}>{children}</HandContext.Provider>
+    </AppStoreContext.Provider>
+  );
+}

package/src/web/core.tsx

@@ -0,0 +1,140 @@
+// The core of babavoss/web: the interface, the scope, the API, the manifest.
+import { createContext, createElement, useContext, useEffect, useState, type ComponentType } from "react";
+import type { Manifest } from "../ecs/baba.ts";
+import type { AppProps } from "../desktop/view.tsx";
+import type { VossApp } from "../desktop/index.ts";
+import { matchRoute } from "../desktop/routes.ts";
+
+/**
+ * The interface: a component for each app the baba declares, shown by voss's shell, one window at a
+ * time. An app's component is given `AppProps` and reads the state through the hooks; the Maker draws
+ * the same components over a simulated state.
+ */
+export interface AppsDef { apps: Record<string, ComponentType<AppProps>> }
+/** The interface before the shell was voss's: one root component, full page. Read for one release. */
+export interface InterfaceDef { shell: ComponentType }
+/** The old spelling. */
+export type ViewDef = InterfaceDef;
+/** What `interface.tsx` exports: a component per app, or, the old way, a shell. */
+export type Interface = AppsDef | InterfaceDef;
+export const isApps = (d: Interface): d is AppsDef => typeof (d as InterfaceDef).shell !== "function" && typeof (d as AppsDef).apps === "object" && (d as AppsDef).apps !== null;
+
+/** A component per route of an app that declares routes: the one whose route takes the window's path draws it. */
+export type RouteTable<P extends string = string> = { [K in P]: ComponentType<AppProps> };
+type RoutesFor<V, K> = V extends { $routes: infer R } ? K extends keyof R ? R[K] : never : never;
+/** What compose takes for an app: a component, or, for an app with routes, a component per route. */
+type EntryFor<P> = [P] extends [never] ? ComponentType<AppProps> : ComponentType<AppProps> | RouteTable<P & string>;
+
+const isTable = (v: unknown): v is RouteTable => typeof v === "object" && v !== null && !("$$typeof" in v) && Object.keys(v).every((k) => k.startsWith("/"));
+
+/**
+ * One component over a route table: it draws the component of the route that took the window's path. The route is the
+ * one the shell matched against the app's declared routes; a frame that matched none, an older one, is matched here against the table.
+ */
+function routed(key: string, table: RouteTable): ComponentType<AppProps> {
+  const routes = Object.keys(table);
+  const Routed = (props: AppProps) => {
+    const m = props.route ? { route: props.route, params: props.params } : matchRoute(routes, props.path);
+    const View = m && table[m.route];
+    return View ? createElement(View, { ...props, route: m.route, params: m.params }) : createElement("p", { className: "desktop-empty" }, m ? `${key} has no component for its route ${m.route}.` : `No route of ${key} takes ${props.path}.`);
+  };
+  Routed.displayName = `Routes(${key})`;
+  return Routed;
+}
+
+/**
+ * `interface.tsx` exports `compose<typeof baba>({ apps: { lab: Lab, … } })`: a component for every app
+ * the baba declares in `baba({ apps })`, and none other; the keys are checked against them. An app that
+ * declares routes may be given a component per route instead, `{ "/": Prs, "/pr/:n": Pr }`, checked
+ * against its routes: every route, none other. One of voss's own apps, `maker`, `state`, `contract`,
+ * `promptware`, `settings`, may be given a component of the baba's to replace voss's.
+ * The old form, `compose({ shell })`, still loads.
+ */
+export function compose<V extends { $app: string }>(def: { apps: { [K in V["$app"]]: EntryFor<RoutesFor<V, K>> } & { [K in VossApp]?: ComponentType<AppProps> } }): AppsDef;
+export function compose(def: InterfaceDef): InterfaceDef;
+export function compose(def: Interface | { apps: Record<string, ComponentType<AppProps> | RouteTable> }): Interface {
+  if ("scenes" in def) throw new Error("compose: `scenes` is now `apps`; rename it");
+  if (!("apps" in def) || typeof def.apps !== "object" || def.apps === null) return def as Interface;
+  return { apps: Object.fromEntries(Object.entries(def.apps).map(([k, v]) => [k, isTable(v) ? routed(k, v) : v])) };
+}
+/** The old spelling, `view({ component })`. */
+export function view(def: { component: ComponentType }): InterfaceDef { return { shell: def.component }; }
+
+/** Which baba the page is: the project's name. */
+export const ScopeContext = createContext<string | null>(null);
+export const ScopeProvider = ScopeContext.Provider;
+export function useScope(): string {
+  const s = useContext(ScopeContext);
+  if (s === null) throw new Error("useScope: not inside a baba's page");
+  return s;
+}
+
+export class ApiError extends Error {
+  constructor(readonly code: string, msg: string, readonly status: number) { super(msg); }
+}
+
+// The page token: read once from the page the server served, unless configure() set one.
+let token: string | null | undefined;
+
+/** Overrides what the page says, for a page the server did not serve. */
+export function configure(options: { token?: string }): void {
+  if (options.token !== undefined) token = options.token;
+}
+
+/** The page token the server put in the page: the API's header, the socket's hello. */
+export function pageToken(): string | null {
+  if (token === undefined) token = globalThis.document?.querySelector('meta[name="voss-token"]')?.getAttribute("content") ?? null;
+  return token;
+}
+
+/** The headers every /api/ request carries: the page token, when the page has one. */
+export function apiHeaders(): Record<string, string> {
+  const t = pageToken();
+  return t ? { authorization: `Bearer ${t}` } : {};
+}
+
+/** One API call: `/api/KIND/SCOPE[/TARGET]`, a JSON body, a JSON answer. */
+export async function api(kind: "fire" | "read" | "state" | "raw", scope: string, target: string | null, body: unknown, init: { signal?: AbortSignal } = {}): Promise<any> {
+  const path = [kind, scope, target].filter((x) => x !== null).map((x) => encodeURIComponent(x!)).join("/");
+  const res = await fetch(`/api/${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...apiHeaders() },
+    body: JSON.stringify(body ?? {}),
+    signal: init.signal,
+  });
+  const data = await res.json() as { value?: unknown; error?: { code: string; message: string } };
+  if (!res.ok || data.error) throw new ApiError(data.error?.code ?? "http", data.error?.message ?? res.statusText, res.status);
+  return data.value;
+}
+
+/**
+ * The baba's manifest, as the server describes it: null until it arrives.
+ * Asked once, then asked again "since the generation I have", so the answer
+ * comes when the baba reloads: a page that draws the manifest, the Maker's
+ * objects or the promptware, follows a change to the code as the state
+ * follows a round. A baba that is down is asked again in a moment.
+ */
+export function useManifest(): Manifest | null {
+  const scope = useScope();
+  const [m, setM] = useState<Manifest | null>(null);
+  useEffect(() => {
+    const ctl = new AbortController();
+    (async () => {
+      let since = 0;
+      while (!ctl.signal.aborted) {
+        try {
+          const r = await fetch(`/api/describe/${encodeURIComponent(scope)}${since ? `?since=${since}` : ""}`, { signal: ctl.signal, headers: apiHeaders() });
+          const d = await r.json() as { gen?: number; manifest?: Manifest | null; error?: { message: string } };
+          if (!r.ok || typeof d.gen !== "number") throw new Error(d.error?.message ?? r.statusText);
+          since = d.gen;
+          if (d.manifest) setM(d.manifest);
+        } catch {
+          if (ctl.signal.aborted) return;
+          await new Promise((done) => setTimeout(done, 2_000));
+        }
+      }
+    })();
+    return () => ctl.abort();
+  }, [scope]);
+  return m;
+}

package/src/web/form.ts

@@ -0,0 +1,155 @@
+// The generated form: which input each argument of a command gets, how the
+// inputs become the arguments, and how a result is best shown. Pure, so the
+// mapping is tested without a DOM; the runner renders it.
+
+type Json = { [k: string]: unknown };
+
+export type FieldKind = "string" | "number" | "integer" | "boolean" | "enum" | "list" | "json";
+
+export interface Field {
+  name: string;
+  kind: FieldKind;
+  required: boolean;
+  /** Takes null as a value: an empty required input sends null. */
+  nullable: boolean;
+  description?: string;
+  /** For an enum. */
+  options?: string[];
+  /** For a list: the type of each line. */
+  item?: "string" | "number" | "integer" | "boolean";
+}
+
+export interface Plan {
+  /** The arguments are not an object with properties: one JSON field edits them whole. */
+  whole: boolean;
+  fields: Field[];
+}
+
+/** What the inputs hold: text for most, a flag for a boolean. */
+export type Values = Record<string, string | boolean>;
+
+export class FieldError extends Error {
+  constructor(readonly field: string, message: string) { super(`${field}: ${message}`); }
+}
+
+const scalars = ["string", "number", "integer", "boolean"] as const;
+type Scalar = typeof scalars[number];
+const isScalar = (t: unknown): t is Scalar => scalars.includes(t as Scalar);
+
+/** The type of a schema without its null: `["string","null"]` is a nullable string. */
+function typeOf(s: Json | undefined): { type: unknown; nullable: boolean } {
+  const t = s?.type;
+  if (Array.isArray(t)) return { type: t.find((x) => x !== "null"), nullable: t.includes("null") };
+  return { type: t, nullable: false };
+}
+
+export function fieldOf(name: string, schema: Json | undefined, required: boolean): Field {
+  const { type, nullable } = typeOf(schema);
+  const description = typeof schema?.description === "string" ? schema.description : undefined;
+  const base = { name, required, nullable, ...(description ? { description } : {}) };
+  if (Array.isArray(schema?.enum) && schema.enum.every((x) => typeof x === "string")) return { ...base, kind: "enum", options: schema.enum as string[] };
+  if (isScalar(type)) return { ...base, kind: type };
+  if (type === "array") {
+    const it = typeOf(schema?.items as Json | undefined);
+    if (isScalar(it.type) && !it.nullable && !(schema?.items as Json | undefined)?.enum) return { ...base, kind: "list", item: it.type };
+  }
+  return { ...base, kind: "json" };
+}
+
+/** The form of a command from its args schema: one field per property, required first, then by name. */
+export function plan(args: Json | undefined): Plan {
+  const { type } = typeOf(args);
+  const props = args?.properties as Record<string, Json> | undefined;
+  if (type !== "object" || !props) {
+    // An object with no properties takes nothing; anything else is edited as JSON.
+    if (type === "object" && args?.additionalProperties === false) return { whole: false, fields: [] };
+    return { whole: true, fields: [{ name: "args", kind: "json", required: false, nullable: false }] };
+  }
+  const required = Array.isArray(args?.required) ? (args.required as string[]) : [];
+  const names = Object.keys(props);
+  names.sort((a, b) => Number(required.includes(b)) - Number(required.includes(a)));
+  return { whole: false, fields: names.map((n) => fieldOf(n, props[n], required.includes(n))) };
+}
+
+function item(f: Field, line: string): unknown {
+  if (f.item === "string") return line;
+  const t = line.trim();
+  if (f.item === "boolean") {
+    if (t === "true") return true;
+    if (t === "false") return false;
+    throw new FieldError(f.name, `each line is true or false, not ${JSON.stringify(t)}`);
+  }
+  const n = Number(t);
+  if (t === "" || !isFinite(n)) throw new FieldError(f.name, `not a number: ${JSON.stringify(t)}`);
+  if (f.item === "integer" && !Number.isInteger(n)) throw new FieldError(f.name, `not an integer: ${t}`);
+  return n;
+}
+
+/** One input's value, or undefined when it sends nothing. Throws a FieldError naming the input. */
+export function read(f: Field, v: string | boolean | undefined): unknown {
+  if (f.kind === "boolean") {
+    if (v === true) return true;
+    return f.required ? false : undefined;
+  }
+  const text = typeof v === "string" ? v : "";
+  const empty = f.kind === "string" ? text === "" : text.trim() === "";
+  if (empty) {
+    // An empty input sends nothing; a required field that takes null sends null.
+    if (!f.required) return undefined;
+    if (f.nullable) return null;
+    throw new FieldError(f.name, "required");
+  }
+  switch (f.kind) {
+    case "string": return text;
+    case "enum":
+      if (!f.options?.includes(text)) throw new FieldError(f.name, `one of ${f.options?.join(", ")}`);
+      return text;
+    case "number":
+    case "integer": {
+      const n = Number(text.trim());
+      if (!isFinite(n)) throw new FieldError(f.name, "not a number");
+      if (f.kind === "integer" && !Number.isInteger(n)) throw new FieldError(f.name, "not an integer");
+      return n;
+    }
+    case "list": {
+      const lines = text.split("\n");
+      while (lines.length && lines.at(-1)!.trim() === "") lines.pop();
+      return lines.map((l) => item(f, l));
+    }
+    case "json":
+      try { return JSON.parse(text); } catch (e) { throw new FieldError(f.name, `not JSON: ${e instanceof Error ? e.message : String(e)}`); }
+  }
+}
+
+/** The arguments the inputs make. Throws a FieldError on the first input that does not read. */
+export function collect(p: Plan, values: Values): unknown {
+  if (p.whole) return read(p.fields[0]!, values.args) ?? {};
+  const out: Record<string, unknown> = {};
+  for (const f of p.fields) {
+    const v = read(f, values[f.name]);
+    if (v !== undefined) out[f.name] = v;
+  }
+  return out;
+}
+
+/** A short label of a field's type. */
+export function describeType(f: Field): string {
+  const t = f.kind === "list" ? `${f.item}[]` : f.kind;
+  return f.nullable ? `${t} | null` : t;
+}
+
+const flat = (v: unknown) => v === null || ["string", "number", "boolean"].includes(typeof v);
+
+/** A result as a table, when it is a non-empty array of objects whose values are all scalars. */
+export function tableOf(value: unknown): { columns: string[]; rows: Record<string, unknown>[] } | null {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  const columns: string[] = [];
+  for (const row of value) {
+    if (typeof row !== "object" || row === null || Array.isArray(row)) return null;
+    for (const [k, v] of Object.entries(row)) {
+      if (!flat(v)) return null;
+      if (!columns.includes(k)) columns.push(k);
+    }
+  }
+  return { columns, rows: value as Record<string, unknown>[] };
+}