babavoss 0.0.1 → 0.0.2

package/src/shell/codes.ts

@@ -0,0 +1,26 @@
+// The shell's exit statuses over the core's closed set of codes (door/core.ts):
+// each code with its exit status and whether the same call may succeed if
+// tried again. Every error the shell answers goes through here, whatever
+// raised it.
+import { CODES as RETRY, DoorError, codeOf, errorOf, type Code, type ErrorBody } from "../door/core.ts";
+
+/** 0 ok; 1 the baba or the daemon failed; 2 the arguments; 3 time ran out; 4 gone or not found. */
+const EXIT: Record<Code, number> = {
+  failed: 1, result: 1, down: 1, busy: 1, timeout: 1, unknown: 1,
+  usage: 2, args: 2, noaction: 2, noquery: 2, name: 2, owner: 2, noproject: 2,
+  entity: 4, gone: 4, nokey: 4,
+};
+
+/** Each code's exit status and retry. */
+export const CODES = Object.fromEntries((Object.keys(RETRY) as Code[]).map((c) => [c, [EXIT[c], RETRY[c]] as const])) as { [C in Code]: readonly [number, boolean] };
+export type { Code };
+export type ErrorLine = ErrorBody;
+
+export { codeOf };
+export const exitOf = (code: Code) => EXIT[code];
+
+/** A shell error: a code of the set, with the call's usage line or idempotency key when they help. */
+export class ShellError extends DoorError {}
+
+/** Anything thrown, as the one error line. */
+export const errorLine = (err: unknown): ErrorLine => errorOf(err);

package/src/shell/positional.ts

@@ -0,0 +1,20 @@
+// Positionals: the args a shell fills from bare words, in order. Pure.
+import type { Json } from "../kernel/schema.ts";
+
+/** Each positional is an args property holding a scalar, or an array of scalars in last place. */
+export function checkPositional(args: Json, names: string[]): string[] {
+  const props = (args.properties ?? {}) as Record<string, Json>;
+  const scalar = (j: Json | undefined) => {
+    const t = j?.type;
+    return t === undefined || ["string", "number", "integer", "boolean"].includes(Array.isArray(t) ? String(t[0]) : String(t));
+  };
+  names.forEach((n, i) => {
+    const p = props[n];
+    if (!p) throw new Error(`positional ${JSON.stringify(n)} is not one of the args`);
+    if (names.indexOf(n) !== i) throw new Error(`positional ${JSON.stringify(n)} is listed twice`);
+    const array = p.type === "array";
+    if (array && i !== names.length - 1) throw new Error(`positional ${JSON.stringify(n)} is an array, so it must come last`);
+    if (!scalar(array ? (p.items as Json | undefined) : p)) throw new Error(`positional ${JSON.stringify(n)} must be a scalar or an array of scalars`);
+  });
+  return [...names];
+}

package/src/shell/run.ts

@@ -0,0 +1,470 @@
+// The shell: words to a baba, answers to a person or a script.
+//
+//   voss baba                                            the index: every call with an example, as JSON
+//   voss baba NAME '{…}' | [WORD …] [--flag VALUE …] [--key K]   fire an action or read a query of the nearest baba
+//   voss baba NAME --schema                              one call's args and result schemas, as JSON
+//   voss BABA NAME …                                     the same, for a remembered baba, from anywhere
+//   voss baba start | stop | status                      the baba as a child of the root's daemon
+//   voss baba state [ENTITY | COMPONENT [KEY] | RESOURCE] [--where k=v] [--deep] [--limit N] [--all]
+//   voss baba follow ENTITY | COMPONENT KEY [--until C | C.field=value] [--for 30s] [--changes]
+//   voss baba follow QUERY [args…] --changed [--for 30s]
+//   voss baba run [FILE | LINE …] | raw spawn JSON | add E COMPONENT [JSON] | remove E COMPONENT … | despawn E | set RESOURCE JSON
+//   voss baba check | install | add-system NAME | promptware … | serve [HOST:PORT]
+//   voss init [DIR] | babas … | gui [HOST:PORT] | service …
+//
+// Stdout is one line of JSON per answer (`--pretty` indents it); stderr is
+// one line, {"error":{"code","message","usage"?,"retry"}}, and nothing else.
+// The exit status is the code's (codes.ts). Human text only for --help, and
+// the contract listing is `voss baba --help`. The index, the schemas, follow,
+// watch, state, the budget and the error shape are the core's (door/core.ts),
+// which the MCP server answers too.
+import { DEFAULT_ADDRESS, hostPort } from "./address.ts";
+import { appendFileSync } from "node:fs";
+import { thisBuild, buildName } from "../kernel/build.ts";
+import { join } from "node:path";
+import { Registry } from "../baba/registry.ts";
+import { findProject } from "../baba/find.ts";
+import { openProject, type Project } from "../baba/project.ts";
+import { Node, NodeError, manifestPath, readManifest, type Described } from "../baba/node.ts";
+import { serve } from "../http/server.ts";
+import { words, callArgs, usage, describeArgs, UsageError } from "./args.ts";
+import { init, install, addSystem } from "../baba/init.ts";
+import { check } from "../baba/check.ts";
+import { planProject, syncProject, outputOf, sources } from "../promptware/disk.ts";
+import { report } from "../promptware/sync.ts";
+import * as service from "./service.ts";
+import { connect, daemon, type Client, type Daemon } from "./client.ts";
+import { runMcp } from "../mcp/main.ts";
+import { ShellError, errorLine, exitOf } from "./codes.ts";
+import { errorOf } from "../door/core.ts";
+import { BUDGET, budget, index, schemaOf, exampleCall } from "../door/core.ts";
+import { state, follow, batch, rawOp, type Io } from "./state.ts";
+import type { Manifest } from "../ecs/baba.ts";
+import type { Snapshot } from "../ecs/state.ts";
+
+export interface Shell {
+  cwd: string;
+  rootDir: string;
+  /** What a new project's package.json depends on for the framework: a version, or link:babavoss from source. */
+  framework: string;
+  /** From source, the types a linked framework does not carry over; nothing when published. */
+  extra?: Record<string, string>;
+  stdout: (s: string) => void;
+  stderr: (s: string) => void;
+  /** The whole of standard input, for `run` and `--NAME @-`. */
+  stdin?: () => Promise<string>;
+  /** Whether standard input is a terminal: `run` with no lines then refuses rather than wait. */
+  stdinTTY?: boolean;
+  /** Ctrl-C: calls the handler on each interrupt until the returned function unsubscribes. */
+  interrupt?: (handler: () => void) => () => void;
+  /** Whether rootDir is the one the system service runs on, so `start` may install the service when no daemon answers. */
+  service?: boolean;
+}
+
+/** Only the one project, for serving it alone; the root's directory still holds the GUI's assets. */
+class OneProject extends Registry {
+  constructor(rootDir: string, private project: string) { super(rootDir); }
+  override async list() { return [this.project]; }
+}
+
+/** A server's log lines: to $VOSS_LOG when set, else as {"log"} lines on stdout; never on stderr. */
+function logTo(sh: Shell): (l: string) => void {
+  const file = process.env.VOSS_LOG;
+  if (file) return (l) => { try { appendFileSync(file, `${new Date().toISOString()} ${l}\n`); } catch { /* a log that cannot be written is dropped */ } };
+  return (l) => sh.stdout(JSON.stringify({ log: l }) + "\n");
+}
+
+const rootUsage = `Usage: voss BABA NAME …
+
+Babas:
+  baba                       the nearest baba above the working directory
+  NAME                       a remembered baba, from anywhere
+
+  voss init [DIR] [--name N] [--title T] [--no-install]
+                             a .baba in DIR, the working directory by default, remembered
+  voss babas add [DIR]       remember a baba (the nearest one by default)
+  voss babas remove DIR      forget it
+  voss babas list            the babas, by name and directory
+  voss gui [HOST:PORT]       serve the GUI and the API, ${DEFAULT_ADDRESS} by default;
+                             started inside a baba, remembers it first
+  voss service install [HOST:PORT] | remove | restart | status
+                             the GUI kept running by the system, at login and after a crash
+
+A baba runs as a child of the daemon (\`voss gui\`, kept by \`voss service\`):
+\`voss baba start\` opens it there, installing the service first if need be;
+\`stop\` retires it, \`status\` says how it is.
+
+A baba answers actions and queries, by name. \`voss baba\` answers the index,
+every call with an example to copy, as JSON; \`voss baba NAME --schema\` one
+call's args and result schemas; \`voss baba --help\` the same as a listing.
+The canonical spelling of a call is its args as one JSON word:
+voss baba NAME '{"field":"value"}'. Positionals and flags work too: the
+<positionals> as bare words, in order, and every argument as --name VALUE; a
+flag wins. --name=VALUE spells a value starting with --; a boolean is --flag,
+--flag=false or --no-flag; an object argument takes JSON. A secret is never on
+the command line: --name @- reads it from stdin. --key K on an action is its
+idempotency key: the same call with the same key answers the same without
+running again. An action runs inside the next round and answers what it
+returned; a query reads between rounds and answers its value. \`voss baba
+state\` summarises the state; \`follow\` waits on an entity or a query; \`run\`
+sends lines of calls in order.
+
+Stdout is one line of JSON per answer; --pretty indents it. An answer over
+20000 characters goes to .baba/.voss/out/ and the line says where, with its
+head; --max N sets the limit, --max 0 lifts it. An error is one line on
+stderr, {"error":{"code","message","usage"?,"retry"}}, and the exit status
+says its kind: 1 the baba or the daemon failed, 2 the arguments, 3 time ran
+out, 4 gone or not found. --help after any word explains it.
+`;
+
+const builtinHelp: Record<string, string> = {
+  state: "the state: state (a summary) | state --all | state ENTITY | state COMPONENT [KEY] [--where k=v] [--deep] [--limit N] | state RESOURCE",
+  raw: "the state's own writes: raw spawn JSON | add ENTITY COMPONENT [JSON] | remove ENTITY COMPONENT … | despawn ENTITY | set RESOURCE JSON",
+  run: "calls in order, one answer per line: run [FILE | LINE …] or lines on stdin, each {\"NAME\": args, \"key\"?: K}; \"$N.field\" is line N's answer",
+  follow: "follow ENTITY | COMPONENT KEY [--until COMPONENT | COMPONENT.field=value] [--for 30s] [--changes]; follow QUERY [args…] --changed [--for 30s]",
+  start: "the baba, opened by the daemon and remembered: start",
+  stop: "the baba retired, its state written, and forgotten: stop",
+  status: "whether it runs, its generation and where: status",
+  check: "the TypeScript checker over the baba",
+  manifest: "the baba loaded once here and let go, so .baba/.voss/manifest.json exists before it runs under the daemon",
+  install: "its dependencies, with Bun",
+  "add-system": "a system under .baba/systems/NAME: add-system NAME",
+  serve: "the GUI for this baba alone: serve [HOST:PORT]",
+  mcp: "an MCP server over stdio for agents, a client of the running voss",
+  promptware: "the harness files: promptware compile | sync | output PATH",
+};
+
+/**
+ * An action called as a harness's hook: the answer in the harness's own
+ * protocol. `{ decision: "block", reason }` is exit 2 with the reason on
+ * stderr, which Claude Code shows the agent and stops on; `{ context }` is
+ * told to the agent; anything else lets the event through. A baba that does
+ * not answer lets through too, unless `strict`.
+ */
+async function asHook(sh: Shell, call: () => Promise<unknown>, event: string, strict: boolean): Promise<number> {
+  let r: { decision?: string; reason?: string; context?: string } | null;
+  try { r = (await call()) as typeof r; } catch (err) {
+    const line = errorOf(err);
+    if (strict) { sh.stderr(`the baba did not answer the hook: ${line.message}\n`); return 2; }
+    sh.stdout(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: `the baba did not answer its ${event} hook: ${line.message}` } }) + "\n");
+    return 0;
+  }
+  if (r && r.decision === "block") { sh.stderr(`${r.reason ?? "blocked by the baba"}\n`); return 2; }
+  const out: Record<string, unknown> = { hookEventName: event };
+  if (event === "PreToolUse" && r?.decision === "allow") { out.permissionDecision = "allow"; if (r.reason) out.permissionDecisionReason = r.reason; }
+  if (r?.context) out.additionalContext = r.context;
+  if (Object.keys(out).length > 1) sh.stdout(JSON.stringify({ hookSpecificOutput: out }) + "\n");
+  return 0;
+}
+
+/** The words every command shares: --pretty, --max N, and --json, accepted and ignored for one release. */
+function globals(argv: string[]): { ws: string[]; pretty: boolean; max: number } {
+  const ws: string[] = [];
+  let pretty = false;
+  let max = BUDGET;
+  const limit = (v: string | undefined) => { if (v === undefined || !/^\d+$/.test(v)) throw new UsageError(`--max takes a number of characters, 0 for none; got ${v ?? "nothing"}`); return Number(v); };
+  for (let i = 0; i < argv.length; i++) {
+    const w = argv[i]!;
+    if (w === "--") { ws.push(...argv.slice(i)); break; }
+    if (w === "--pretty") pretty = true;
+    else if (w === "--json") { /* the old way to ask for JSON: it is the only way now */ }
+    else if (w === "--max") max = limit(argv[++i]);
+    else if (w.startsWith("--max=")) max = limit(w.slice(6));
+    else ws.push(w);
+  }
+  return { ws, pretty, max };
+}
+
+export async function run(argv: string[], sh: Shell): Promise<number> {
+  const reg = new Registry(sh.rootDir);
+  // Every answer is JSON; the promptware block below still reads this.
+  const json = true;
+  let callUsage: string | undefined;
+  let outDir: string | undefined;
+  const fail = (err: unknown) => {
+    const line = errorLine(err);
+    if (callUsage && (line.code === "args" || line.code === "usage") && !line.usage) line.usage = callUsage;
+    sh.stderr(JSON.stringify({ error: { code: line.code, message: line.message, ...(line.usage ? { usage: line.usage } : {}), retry: line.retry, ...(line.key ? { key: line.key } : {}) } }) + "\n");
+    return exitOf(line.code);
+  };
+  let g: ReturnType<typeof globals>;
+  try { g = globals(argv); } catch (err) { return fail(err); }
+  let ws = g.ws;
+  const help = ws.at(-1) === "--help" || ws.at(-1) === "-h";
+  if (help) ws = ws.slice(0, -1);
+  const [node, ...rest] = ws;
+
+  const print = (v: unknown) => sh.stdout(JSON.stringify(v ?? null, null, g.pretty ? 2 : undefined) + "\n");
+  /** One answer, at once: whole when it fits, else written under .baba/.voss/out/ and its marker printed. */
+  const out = (v: unknown, name = "answer"): void => print(budget(v, { dir: outDir, name, limit: g.max }));
+
+  try {
+    if (!node) { sh.stdout(rootUsage); return 0; }
+    if (node === "--version" || node === "-v") { print(thisBuild); return 0; }
+
+    if (node === "init") {
+      if (help) { sh.stdout(rootUsage); return 0; }
+      let dir: string | undefined;
+      let installing = true;
+      const opts: Record<string, string> = {};
+      for (let i = 0; i < rest.length; i++) {
+        const w = rest[i]!;
+        if (w === "--name" || w === "--title") { const v = rest[++i]; if (v === undefined || v.startsWith("--")) throw new UsageError(`${w} needs a value`); opts[w.slice(2)] = v; }
+        else if (w === "--no-install") installing = false;
+        else if (w.startsWith("--")) throw new UsageError(`init takes --name, --title and --no-install, not ${w}`);
+        else if (dir === undefined) dir = w;
+        else throw new UsageError(`init takes one directory, got ${w}`);
+      }
+      const made = await init(dir ?? sh.cwd, { name: opts.name, title: opts.title, framework: sh.framework, extra: sh.extra, install: installing });
+      await reg.add(made.dir);
+      await out(made);
+      return 0;
+    }
+
+    if (node === "babas") {
+      const [cmd, arg] = rest;
+      if (help || !cmd) { sh.stdout(rootUsage); return 0; }
+      if (cmd === "add") {
+        const dir = arg ?? (await findProject(sh.cwd));
+        if (!dir) throw new ShellError("noproject", "no .baba here or above; give a directory");
+        const p = await openProject(dir);
+        await reg.add(p.dir);
+        await out({ name: p.name, dir: p.dir });
+        return 0;
+      }
+      if (cmd === "remove" && arg) {
+        if (!(await reg.remove(arg))) throw new ShellError("noproject", `${arg} is not remembered`);
+        await out({ removed: arg });
+        return 0;
+      }
+      if (cmd === "list") {
+        const list = [];
+        for (const dir of await reg.list()) {
+          try { const p = await openProject(dir); list.push({ name: p.name, title: p.title, dir }); }
+          catch (err) { list.push({ name: null, title: null, dir, error: err instanceof Error ? err.message : String(err) }); }
+        }
+        await out(list);
+        return 0;
+      }
+      throw new UsageError("babas: add, remove or list");
+    }
+
+    if (node === "service") {
+      const [cmd, ...more] = rest;
+      if (help || !cmd) { sh.stdout(rootUsage); return 0; }
+      if (cmd === "install") {
+        const [host, port] = hostPort(more[0]);
+        const st = await service.install(`${host}:${port}`);
+        await out({ ...st, hint: `the GUI is kept running at ${st.url}` });
+        return 0;
+      }
+      if (cmd === "remove") { await out(await service.remove()); return 0; }
+      if (cmd === "restart") { await out(await service.restart()); return 0; }
+      if (cmd === "status") { await out(await service.status()); return 0; }
+      throw new UsageError("service: install, remove, restart or status");
+    }
+
+    if (node === "gui") {
+      const near = await findProject(sh.cwd);
+      if (near) await reg.add(near);
+      const [host, port] = hostPort(rest[0]);
+      // Under the service, this very process is the one it keeps: then a clean exit is a restart.
+      const st = sh.service ? await service.status() : null;
+      const kept = !!st?.installed && st.running && st.pid === process.pid;
+      const server = await serve(reg, host, port, logTo(sh), { kept, init: { framework: sh.framework, extra: sh.extra } });
+      await out({ url: `http://${server.hostname}:${server.port}/`, build: buildName(thisBuild), ...(st?.installed ? {} : { hint: "to keep it running, `voss service install`" }) });
+      return -1;
+    }
+
+    // A project: `baba` is the nearest one, anything else a remembered name.
+    let project: Project;
+    if (node === "baba") {
+      const dir = await findProject(sh.cwd);
+      if (!dir) throw new ShellError("noproject", "no .baba here or above; `voss babas list` names the known ones");
+      project = await openProject(dir);
+    } else {
+      let found: Project | null = null;
+      for (const dir of await reg.list()) {
+        try { const p = await openProject(dir); if (p.name === node) { found = p; break; } } catch { /* a stale entry answers under list */ }
+      }
+      if (!found) throw new ShellError("noproject", `no baba ${node}; \`voss babas list\` names the known ones`);
+      project = found;
+    }
+    outDir = join(project.baba, ".voss", "out");
+    const [name, ...args] = rest;
+    const prog = `voss ${node}`;
+    if (name === "fire" && help) { sh.stdout(`Usage: ${prog} ${builtinHelp.run}\n`); return 0; }
+    if (name && Object.hasOwn(builtinHelp, name) && help) { sh.stdout(`Usage: ${prog} ${builtinHelp[name]}\n`); return 0; }
+    if (name === "check") {
+      let text = "";
+      const code = await check(project, (s) => { text += s; }, (s) => { text += s; });
+      await out({ ok: code === 0, output: text });
+      if (code !== 0) throw new ShellError("failed", "the check found errors; the output says which");
+      return 0;
+    }
+    if (name === "manifest") {
+      // The baba loaded once, in this process, and let go: what every load writes, .baba/.voss/manifest.json, is there
+      // for the index, --schema and the promptware before the baba ever runs under the daemon, as in a fresh worktree.
+      const lines: string[] = [];
+      const n = new Node(project, (l) => lines.push(l));
+      try { await n.start(); } finally { await n.stop(); }
+      const m = await readManifest(project);
+      await out({ manifest: manifestPath(project), systems: m?.systems.map((c) => c.name) ?? [], actions: Object.keys(m?.actions ?? {}).length, queries: Object.keys(m?.queries ?? {}).length, log: lines.slice(-5) });
+      return 0;
+    }
+    if (name === "install") { await install(project.baba); await out({ installed: project.baba }); return 0; }
+    if (name === "serve") {
+      if (args.length > 1) throw new UsageError(`serve takes one HOST:PORT`);
+      const [host, port] = hostPort(args[0]);
+      const server = await serve(new OneProject(sh.rootDir, project.dir), host, port, logTo(sh), { address: false });
+      await out({ url: `http://${server.hostname}:${server.port}/${project.name}/` });
+      return -1;
+    }
+    if (name === "mcp") return await runMcp(project, sh.rootDir);
+    if (name === "add-system") {
+      const w = words(args, ["name"]);
+      if (typeof w.name !== "string" || !w.name) throw new UsageError(`add-system takes a NAME`);
+      await out(await addSystem(project.baba, w.name));
+      return 0;
+    }
+    if (name === "start") return await start(project, prog, reg, sh, out);
+    if (name === "stop") {
+      await reg.remove(project.dir);
+      const d = await daemon(sh.rootDir);
+      if (d) await d.refresh();
+      await out({ stopped: true });
+      return 0;
+    }
+    if (name === "status") {
+      const c = await connect(project, sh.rootDir, prog).catch(downOnly);
+      await out(c instanceof NodeError ? { running: false, name: project.name, hint: `${prog} start` } : statusOf(await c.describe(), c.where));
+      return 0;
+    }
+
+    // The state is the daemon's; what only reads the contract does with the manifest the last load wrote.
+    const c = await connect(project, sh.rootDir, prog).catch(downOnly);
+    const down = c instanceof NodeError ? c : null;
+    const d = c instanceof NodeError ? null : await c.describe();
+    // Down, the promptware compiles from a manifest of the code as it is now: the baba is loaded once in this process and let
+    // go, as \`manifest\` does, so a fresh worktree has one and an edit to the promptware is in it. Busy or broken, the last one stands.
+    let loadError: string | null = null;
+    if (down && name === "promptware") {
+      const n = new Node(project, () => {});
+      try { await n.start(); } catch (err) { loadError = err instanceof Error ? err.message : String(err); } finally { await n.stop().catch(() => {}); }
+    }
+    const m = d ? d.manifest : await readManifest(project);
+    if (!m && loadError) throw new ShellError("failed", `${project.name} did not load: ${loadError}`);
+    if (!m) { if (down) throw down; throw new ShellError("down", `${project.name} is not running${d?.error ? `: ${d.error}` : ""}`); }
+    if (name === "promptware") {
+      // Running, the baba's promptware system syncs, and the answer waits for it; down, the same compiler runs here over the files.
+      const [cmd, path] = args;
+      if (cmd === "sync" && d && !d.error && "promptware-sync" in m.actions) {
+        const live = c as Client;
+        const syncs = async () => await live.read("promptware-plan", {}) as { syncs: number; error: string | null };
+        const before = (await syncs()).syncs;
+        await live.fire("promptware-sync", {});
+        for (let i = 0; i < 200; i++) {
+          const p = await syncs();
+          if (p.syncs > before) { if (p.error) return fail(`promptware sync: ${p.error}`); out(p); return 0; }
+          await new Promise((r) => setTimeout(r, 50));
+        }
+        return fail("promptware sync: asked, not finished within 10s; promptware-plan says how it went");
+      }
+      const input = sources(project.dir, m, project.title);
+      if (cmd === "compile") { out(report(await planProject(project.dir, input))); return 0; }
+      if (cmd === "sync") { out(await syncProject(project.dir, input)); return 0; }
+      if (cmd === "output" && path) { const o = await outputOf(project.dir, input, path); out(json ? o : { path: o.path, status: o.status }); if (!json) sh.stdout(o.text); return 0; }
+      sh.stdout(`Usage: ${prog} promptware compile | sync | output PATH\n`);
+      return help ? 0 : 2;
+    }
+    if (!name) {
+      if (help) { sh.stdout(contract(prog, project.title, m, d?.error ?? null, down ? `down · ${prog} start` : (c as Client).where)); return 0; }
+      out(index(m, { via: down || !d ? "down" : (c as Client).where, ...(d ? { gen: d.gen, error: d.error } : {}), prog }), "index");
+      return 0;
+    }
+    const action = m.actions[name];
+    const query = m.queries[name];
+    const def = action ?? query;
+    if (def) callUsage = [`${prog} ${name}`, ...usage(def.args, def.positional ?? []), ...(action ? ["[--key K]"] : [])].join(" ");
+    if (def && args.length === 1 && args[0] === "--schema") { out(schemaOf(m, name, prog), `${name}-schema`); return 0; }
+    if (def && help) {
+      const positional = def.positional ?? [];
+      const lines = describeArgs(def.args, positional);
+      const flagsToo = positional.length ? `\nA <positional> is also accepted as --name VALUE.\n` : "";
+      const key = action ? `\n--key K makes it idempotent: a retry with the same key answers the same without running again.\n` : "";
+      const example = exampleCall(name, def, prog).cli;
+      sh.stdout(`Usage: ${callUsage}\n\n${action ? "action" : "query"} of ${def.owner}${def.summary ? `: ${def.summary}` : ""}\n${lines.length ? "\n" + lines.join("\n") + "\n" : ""}${flagsToo}${key}\n${prog} ${name} --schema answers its schemas as JSON. The args as one JSON word are the canonical spelling:\n\n  ${example}\n`);
+      return 0;
+    }
+    // A hook with the baba down answers in the hook's protocol: let through with a note, or block when strict.
+    if (down && args.includes("--hook")) return await asHook(sh, () => Promise.reject(down), args[args.indexOf("--hook") + 1] ?? "", args.includes("--strict=true"));
+    if (down) throw down;
+    const client = c as Client;
+    const io: Io = { out, fit: (v, n) => budget(v, { dir: outDir, name: n, limit: g.max }), outDir, cwd: sh.cwd, stdin: sh.stdin, stdinTTY: sh.stdinTTY, interrupt: sh.interrupt };
+    if (name === "state") return await state(client, m, args, io);
+    if (name === "follow") return await follow(client, m, args, io);
+    if (name === "run" || name === "fire") return await batch(client, m, args, io);
+    if (name === "raw") return await rawOp(client, args, io);
+    if (!def) throw new ShellError("noaction", `${project.name} has no action or query ${name}; ${Object.keys(m.actions).length + Object.keys(m.queries).length ? `it has: ${[...Object.keys(m.actions), ...Object.keys(m.queries)].join(", ")}` : "it has none"}`);
+    const { args: a, extra } = await callArgs(args, def, sh.stdin, action ? ["key", "hook", "strict"] : []);
+    if (extra.hook !== undefined) return await asHook(sh, () => client.fire(name, a, { key: extra.key, coerce: true }), extra.hook, extra.strict === "true");
+    await out(query ? await client.read(name, a) : await client.fire(name, a, { key: extra.key, coerce: true }), name);
+    return 0;
+  } catch (err) {
+    // A hook that could not reach its action answers in the hook's protocol, whatever went wrong on the way.
+    const ws = g.ws;
+    if (ws.includes("--hook")) return await asHook(sh, () => Promise.reject(err), ws[ws.indexOf("--hook") + 1] ?? "", ws.includes("--strict=true"));
+    return fail(err);
+  }
+}
+
+/** A baba the daemon does not run answers `down`; anything else is an error to raise. */
+const downOnly = (err: unknown): NodeError => { if (err instanceof NodeError && err.code === "down") return err; throw err; };
+
+/** What `status` and `start` answer: from describe, and where. */
+function statusOf(d: Described, via: string) {
+  return { running: true, name: d.name, title: d.title, gen: d.gen, view: d.view, error: d.error, via };
+}
+
+/** start: remembered, the daemon up (the service installed for it if need be), the baba opened there and answering. */
+async function start(project: Project, prog: string, reg: Registry, sh: Shell, out: (v: unknown) => void): Promise<number> {
+  await reg.add(project.dir);
+  let d: Daemon | null = await daemon(sh.rootDir);
+  if (!d) {
+    if (!sh.service || (process.platform !== "darwin" && process.platform !== "linux")) throw new ShellError("down", `no daemon answers for ${sh.rootDir}; run \`voss gui\` with this root, then ${prog} start again`);
+    const st = await service.install((await service.status()).address ?? DEFAULT_ADDRESS);
+    for (const until = Date.now() + 60_000; !d && Date.now() < until;) { await Bun.sleep(250); d = await daemon(sh.rootDir); }
+    if (!d) throw new ShellError("down", `the daemon did not answer within 60 s; its log is ${st.log}`);
+  }
+  const r = await d.refresh();
+  const e = r.errors.find((x) => x.dir === project.dir);
+  if (e) throw new ShellError("failed", `${project.name} did not load: ${e.error}`);
+  for (const until = Date.now() + 10_000; ;) {
+    try {
+      const c = await connect(project, sh.rootDir, prog);
+      await out(statusOf(await c.describe(), c.where));
+      return 0;
+    } catch (err) {
+      if (!(err instanceof NodeError) || Date.now() > until) throw err;
+      await Bun.sleep(100);
+    }
+  }
+}
+
+/** `voss baba` with no name: the contract, and where the state is. */
+function contract(prog: string, title: string, m: Manifest, error: string | null, where: string): string {
+  const pad = (s: string) => s.padEnd(18);
+  const lines = [`${title}`, "", `Usage: ${prog} NAME '{…}' [--key K] | ${prog} NAME [WORD …] [--flag VALUE | @- …] | ${prog} NAME --schema`, ""];
+  const section = (head: string, rows: [string, string][]) => { if (rows.length) lines.push(`${head}:`, ...rows.map(([n, s]) => `  ${pad(n)} ${s}`), ""); };
+  section("Actions", Object.entries(m.actions).map(([n, a]) => [[n, ...usage(a.args, a.positional)].join(" "), `${a.owner}${a.summary ? ` · ${a.summary}` : ""}`]));
+  section("Queries", Object.entries(m.queries).map(([n, q]) => [[n, ...usage(q.args, q.positional)].join(" "), `${q.owner}${q.summary ? ` · ${q.summary}` : ""}`]));
+  section("Components", Object.entries(m.components).map(([n, c]) => [n, c.owner]));
+  section("Resources", Object.entries(m.resources).map(([n, r]) => [n, r.owner]));
+  section("Effects", Object.entries(m.effects).map(([n, e]) => [n, `${e.owner}${e.every ? ` · every ${e.every} ms` : ""}${e.retry ? ` · retry ${e.retry} ms` : ""}${e.summary ? ` · ${e.summary}` : ""}`]));
+  section("The state", Object.entries(builtinHelp).filter(([k]) => ["state", "follow", "run", "raw"].includes(k)).map(([k, h]) => [k, h]));
+  section("Voss", Object.entries(builtinHelp).filter(([k]) => ["start", "stop", "status", "mcp", "check", "manifest", "install", "add-system", "serve", "promptware"].includes(k)).map(([k, h]) => [k, h]));
+  lines.push(`State: ${where}${error ? ` · the last load failed: ${error}` : ""}`);
+  return lines.join("\n") + "\n";
+}
+
+export type { Snapshot };