nervur 0.19.2 → 0.20.1

package/src/being/types.ts

@@ -1,170 +1,74 @@
 // SPDX-License-Identifier: Apache-2.0
-// The Being side of Quo, as types. Everything a being author can hold.
-// Nothing here knows a runtime, a key, or a wire.
-import type { silence } from './silence.ts';
+// Everything a being author holds, as types.
+import type { Json } from '../crypto/index.ts';
+import type { Invitation } from '../quo/index.ts';
+import type { Silence, Word } from './words.ts';
 
-// I-JSON. Everything that crosses an edge.
-export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export type { Invitation, Json };
 export type JsonObject = { [key: string]: Json };
 
-// The asker: her own id for the being at the door. {} at a public being.
-export type Asker = { id: string } | { id?: undefined };
-
-// The ids the ward speaks under, and no being may mint. An asker id is hers:
-// she chooses the strings, and the ward has no business in her namespace. But
-// the ward must sometimes stand at her door itself — its describe asks every
-// being under OWNER — and an id it shares with one of her occupants is two
-// different parties wearing one name. She could not tell them apart, and the
-// ward would shape its describe through an occupant's gate.
-//
-// So the ward's words are shouted, and refused at the mint. A word can only
-// be reserved before anyone has used it: a partition already holding an
-// occupant of that name could never have it taken back. PUBLIC guards nothing
-// today — a public asker is {} and carries no id at all — and that is exactly
-// why it is claimed now, while claiming it is free.
+// Who is at the door: the id she filed the occupant under, `{}` for nobody,
+// and `{ id: OWNER }` for whoever holds the ward's unsealed ask.
+export type Asker = { readonly id: string } | { readonly id?: undefined };
 export const OWNER = 'OWNER';
-export const PUBLIC = 'PUBLIC';
-export const RESERVED_IDS: readonly string[] = [OWNER, PUBLIC];
 
-// An invitation is a value. Opaque to her: the far ward's pk, a heir pk,
-// and the heir's secret. Without a heir it addresses a ward's public being.
-export type Invitation = { ward: string; heir?: string; secret?: string };
+// The ward-being's key in her ward, and so the id every being she makes
+// knows her by.
+export const WARD = 'ward';
 
-// An invitation as one object of values, which is what it already is. A being
-// who hands one on sends it as args, and args are values; this is the one
-// place that is spelled, so nobody spells it with a cast. Absent stays absent:
-// an invitation to a public being carries no heir and no secret, and a key
-// present and undefined is not the same object once JSON has been through it.
-export const invitationArgs = (inv: Invitation): JsonObject => ({
-  ward: inv.ward,
-  ...(inv.heir !== undefined ? { heir: inv.heir } : {}),
-  ...(inv.secret !== undefined ? { secret: inv.secret } : {}),
-});
+// What comes back from an ask, and what a being answers.
+export type Answer = Json | Silence | Word;
+export type Reply = Json | Silence | undefined;
 
-// Whether a value that arrived is an invitation. The shape is the spec's, so
-// the reading of it is too, and it is one reading: a form that
-// asks a guest for one, a lent being handed one to wake her maker by, and a
-// shell that finds one in a link all ask the same question, and a kinder
-// answer in one of them is a value that fails at a door instead of at the
-// edge it came in by. A ward pk is a hundred and twenty-eight lowercase hex,
-// and a heir comes with its secret or neither comes: an invitation to a
-// public being carries no heir, and a heir with no secret opens nothing.
-export const isInvitation = (v: unknown): v is Invitation => {
-  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
-  const o = v as Record<string, unknown>;
-  if (typeof o.ward !== 'string' || !/^[0-9a-f]{128}$/.test(o.ward)) return false;
-  const heir = typeof o.heir === 'string',
-    secret = typeof o.secret === 'string';
-  return (heir && secret) || (!heir && !secret && !('heir' in o) && !('secret' in o));
-};
+export type Wanted = { readonly time?: number };
 
-// A blueprint is an MCP tool list plus notes.
+// A blueprint: the asks a being can be asked, as an MCP tool list, and notes.
 export type Schema = JsonObject;
-export type Ask = { name: string; description?: string; input: Schema; output?: Schema };
+export type Ask = { name: string; description?: string; input: Schema };
 export type Blueprint = { asks: Ask[]; notes: Json };
 
-// Whether what came back from an empty ask is a blueprint. Every describe on
-// the far side of a door is somebody else's code, so nothing may be written
-// into a standing's record as a blueprint without being read as one first: a
-// side walks `asks` by name, and a list of anything else, or no list at all,
-// is a side that breaks on a far ward's answer. The asks are checked to the
-// depth a side reads them, a name and an input each, and no further: what a
-// far being puts beside those is hers.
-export const isBlueprint = (v: unknown): v is Blueprint => {
-  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
-  const { asks, notes } = v as { asks?: unknown; notes?: unknown };
-  if (!Array.isArray(asks) || notes === undefined) return false;
-  return asks.every((a) => a !== null && typeof a === 'object' && !Array.isArray(a) && typeof (a as Ask).name === 'string' && (a as Ask).input !== null && typeof (a as Ask).input === 'object' && !Array.isArray((a as Ask).input));
-};
-
-export type StandingRecord = { id: string; digest: string | null; blueprint: Blueprint | null; seen: string | null };
-export type OccupantRecord = { id: string; notes: JsonObject };
-export type Cells = {
-  standings: Record<string, StandingRecord>;
-  occupants: Record<string, OccupantRecord>;
-  [hers: string]: Json;
-};
-
-export type Silence = typeof silence;
-
-// The ward's words: what her ward says when no object came back and it knows
-// why. A door says the first five to a key it has bound, and rides them on
-// the wire as `{ quo: word }`; her own ward says the last four to her and
-// they never leave the ward. Each is one frozen object under one symbol key,
-// so no being makes one by accident and none crosses an edge as a value. A
-// being who reaches for the symbol on purpose makes an object her ward reads
-// as her having thrown, which is what a being who returns nonsense gets: the
-// key is a guard against collision, never against her.
-export type DoorWord = 'removed' | 'absent' | 'unannounced' | 'repeated' | 'threw';
-export type WardWord = 'unreached' | 'late' | 'invitation' | 'dropped';
-export type WordName = DoorWord | WardWord;
-export const WORD_KEY: unique symbol = Symbol.for('quo.word');
-export type Word<W extends WordName = WordName> = { readonly [K in typeof WORD_KEY]: W };
-export type Unreached = Word<'unreached'>;
-
-// What comes back from an ask or a knock.
-export type Answer = Json | Silence | Word;
-// What a being answers.
-export type Reply = Json | Silence;
-
-// What a being may ask for when she wants to say so herself: the time this
-// one ask may spend. Optional, and so is saying anything at all: an ask that
-// says nothing gets her ward's default, which is the ordinary way to ask.
-export type Wanted = { time?: number };
-
-export type Standing = {
+export interface Standing {
   readonly id: string;
   ask(method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
-};
+}
 
-export type Standings = {
-  knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+// Her side of the relations she holds.
+export interface Standings {
+  // Knocks with the empty ask and holds the relation under `id`: the id, or
+  // null where the id is taken or reserved, or no object came back.
   take(id: string, invitation: Invitation): Promise<string | null>;
-  remove(id: string): void;
-} & { readonly [id: string]: Standing | undefined };
+  get(id: string): Standing | undefined;
+  ids(): string[];
+  remove(id: string): boolean;
+}
 
-export type Occupants = {
-  // awaitable: a key is minted. The notes are the terms it is minted under,
-  // written on the occupant for her gate to read, and hers alone after that.
+// The door's side: the ids she invited.
+export interface Occupants {
   invite(id: string, notes?: JsonObject): Promise<Invitation | null>;
+  notes(id: string): JsonObject | undefined;
+  ids(): string[];
+  remove(id: string): boolean;
+}
 
-  remove(id: string): void;
-};
-
-// The stance. What every being, in every language, is handed at birth.
-export type Stance = {
-  readonly cells: Cells;
+// What every being is handed at birth.
+export interface Stance {
+  readonly key: string;
+  readonly cells: JsonObject;
   readonly occupants: Occupants;
   readonly standings: Standings;
-  // A standing at one of the things this device can do, by the harbor's name
-  // for it, under an id of hers. The id back, or null: this box lends no such
-  // name, the id already names a record or is a reserved word, or the
-  // relation was refused.
-  //
-  // Her ward asks the ground, then knocks and takes in her name, as it does
-  // for a being she boots. So the invitation never reaches her, because it is
-  // the device's capability and not her own relation to give away; what she
-  // holds afterwards is an ordinary standing that counts, rotates, can be
-  // removed and hears `removed`.
-  //
-  // The ground is the booting harbor's, so this reaches the box she is
-  // running on and no other. A standing she wakes up holding names a being on
-  // the box she was on when it was made, and a migration is a restart she
-  // cannot tell from any other, so a being who wants the box she is on asks
-  // again at every birth.
-  lend(name: string, id: string): Promise<string | null>;
-  // A new being of her ward, by class name, under a key she chooses. The key
-  // back, or null: the key is taken, the harbor holds no such class, or the
-  // class threw at birth. A being may make; only the owner reaches into
-  // another. Naming an id asks for a way back too: the being made holds an
-  // occupant for her maker under the maker's own key, and the maker holds
-  // the standing under that id. A relation that could not be made is a boot
-  // that made nobody, and the being made goes with it.
-  boot(className: string, key: string, id?: string): Promise<string | null>;
-};
+  // A new being of her ward, by kind, under a key she chooses. With an id,
+  // the new being invites her under her key, and she takes it under id.
+  boot(kind: string, key: string, id?: string): Promise<string | null>;
+  // A standing under `id` at the faculty this harbor opened for a contract:
+  // the id, or null where none is open, the contract declares no kind of
+  // its own, or the relation was refused.
+  lend(contract: abstract new (...args: never[]) => unknown, id: string): Promise<string | null>;
+}
 
-// The raw shape of a being. Anything with these two is a being.
+// Anything with `answer` is a being.
 export interface BeingLike {
-  answer(asker: Asker, method?: string, args?: JsonObject): Reply | Promise<Reply>;
+  answer(asker: Asker, method: string | undefined, args: JsonObject): Reply | Promise<Reply>;
+  describe?(asker: Asker): Blueprint;
 }
-export type BeingClass = new (stance: Stance) => BeingLike;
+// A class that stands. Its kind is its own, as `kind.ts` says.
+export type BeingClass = (new (stance: Stance) => BeingLike) & { readonly name: string; readonly kind: string };

package/src/being/words.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// What a being is told when no object came back. Silence is one symbol.
+// A word is one frozen object per name, so a being never makes one by
+// accident, and two copies of the package in one bundle still agree.
+//
+//   removed, unannounced, repeated   a far door's words, as Quo says them
+//   unreached                        nothing came back: asking again is safe
+//   late                             the allowance ran out
+//   dropped                          the standing was removed while asking
+//   invitation                       what was handed is no invitation
+import type { Word as DoorWord } from '../quo/index.ts';
+
+export const silence: unique symbol = Symbol.for('nervur.silence');
+export type Silence = typeof silence;
+export const isSilence = (x: unknown): x is Silence => x === silence;
+
+export type WordName = DoorWord | 'unreached' | 'late' | 'dropped' | 'invitation';
+const KEY: unique symbol = Symbol.for('nervur.word');
+export type Word<W extends WordName = WordName> = { readonly [KEY]: W };
+
+const made = new Map<WordName, Word>();
+export const word = <W extends WordName>(name: W): Word<W> => {
+  let w = made.get(name);
+  if (!w) made.set(name, (w = Object.freeze({ [KEY]: name })));
+  return w as Word<W>;
+};
+export const isWord = (x: unknown): x is Word => typeof x === 'object' && x !== null && typeof (x as Record<symbol, unknown>)[KEY] === 'string';
+
+// A word by its name, and anything else as it is, so one comparison says
+// which answer came back.
+export const told = (x: unknown): unknown => (isWord(x) ? x[KEY] : x);

package/src/cli/command.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur`: a harbor on this machine. Each command is one root request, the
+// same the root line carries from any front, printed as one JSON line.
+//
+//   nervur init   [--dir D]                         the harbor made: its seed drawn,
+//                                                   its catalogue stood, and an owner
+//                                                   invitation for whoever made it
+//   nervur serve  [--dir D] [--host H] [--port P]   the harbor served: Quo over TCP,
+//                                                   and the root line on its socket
+//   nervur module add <file>                        a module the catalogue runs
+//   nervur module remove <module>                   a module it runs no more
+//   nervur modules                                  what the catalogue runs
+//   nervur census [--ward W]                        the empty ask
+//   nervur open   <key> <kind>                      a faculty stands in the box ward
+//   nervur host   <ward> [--seed S]                 a hosted ward stands
+//   nervur route  <ward pk> <host:port | none>      where a ward is reached
+//   nervur boot   [--ward W] <key> <kind>           a being stands
+//   nervur unboot [--ward W] <being>                a being goes
+//   nervur public [--ward W] <key | none>           the being a stranger reaches
+//   nervur invite [--ward W] <being> <id>           an invitation on a being
+//   nervur ask    [--ward W] [being] [method] [args] a being, asked as the owner
+//   nervur own    [--ward W] <id>                   an invitation for an owner
+//   nervur disown [--ward W] <id>                   an owner no more
+//   nervur pilot  <name> <invitation> <host:port>   a far ward held as its owner, by a
+//                                                   pilot being of the box ward
+//   nervur <command> --via <name> ...               the command asked of the far ward
+//                                                   that pilot holds, as its owner
+//
+// D is --dir, then $NERVUR_DIR, then ~/.nervur. A module file is named from
+// where the command runs and kept by its absolute path. No --ward is the box
+// ward, and a pilot holds one ward, so --via takes no --ward. The exit is 1
+// when the answer is an error.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import type { JsonObject } from '../being/index.ts';
+import type { RootRequest } from '../harbor/index.ts';
+import { open, request, serve } from './harbor.ts';
+
+const USAGE = 'usage: nervur <init|serve|module|modules|census|open|host|route|boot|unboot|public|invite|ask|own|disown|pilot> [args] [--dir D] [--ward W] [--via V] [--seed S] [--host H] [--port P]';
+const FLAGS = new Set(['dir', 'ward', 'via', 'seed', 'host', 'port']);
+
+export const parse = (argv: string[]): { command?: string; words: string[]; flags: Record<string, string> } => {
+  const flags: Record<string, string> = {};
+  const words: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    const name = arg.startsWith('--') ? arg.slice(2) : undefined;
+    if (name === undefined) words.push(arg);
+    else if (!FLAGS.has(name) || argv[i + 1] === undefined) throw new Error(`--${name} is no flag with a value`);
+    else flags[name] = argv[(i += 1)]!;
+  }
+  const [command, ...rest] = words;
+  return { ...(command === undefined ? {} : { command }), words: rest, flags };
+};
+
+const none = (word: string): string | null => (word === 'none' ? null : word);
+const json = (word: string | undefined): JsonObject | undefined => (word === undefined ? undefined : (JSON.parse(word) as JsonObject));
+const catalogue = (method: string, args: JsonObject = {}): RootRequest => ({ method: 'ask', args: { being: 'catalogue', method, args } });
+
+// The root request a command names, or a throw saying what it lacks.
+export const requestOf = (command: string, words: string[], flags: Record<string, string>): RootRequest => {
+  const need = (n: number): string[] => {
+    if (words.length !== n) throw new Error(`${command} takes ${n} argument${n === 1 ? '' : 's'}`);
+    return words;
+  };
+  const at = flags.ward === undefined ? {} : { ward: flags.ward };
+  switch (command) {
+    case 'module': {
+      const [verb, what] = need(2);
+      if (verb === 'add') return catalogue('add', { from: resolve(what!) });
+      if (verb === 'remove') return catalogue('remove', { module: what! });
+      throw new Error('module is add or remove');
+    }
+    case 'modules':
+      return (need(0), catalogue('modules'));
+    case 'census':
+      return (need(0), at);
+    case 'open': {
+      const [key, kind] = need(2);
+      return { method: 'open', args: { key: key!, class: kind! } };
+    }
+    case 'host': {
+      const [ward] = need(1);
+      return { method: 'host', args: { ward: ward!, ...(flags.seed === undefined ? {} : { seed: flags.seed }) } };
+    }
+    case 'route': {
+      const [ward, where] = need(2);
+      return { method: 'route', args: { ward: ward!, at: none(where!) } };
+    }
+    case 'boot': {
+      const [key, kind] = need(2);
+      return { ...at, method: 'boot', args: { key: key!, class: kind! } };
+    }
+    case 'unboot':
+      return { ...at, method: 'unboot', args: { being: need(1)[0]! } };
+    case 'public':
+      return { ...at, method: 'public', args: { key: none(need(1)[0]!) } };
+    case 'invite': {
+      const [being, id] = need(2);
+      return { ...at, method: 'invite', args: { being: being!, id: id! } };
+    }
+    case 'ask': {
+      if (words.length > 3) throw new Error('ask takes at most a being, a method and its args');
+      const [being, method, args] = words;
+      return { ...at, method: 'ask', args: { ...(being === undefined ? {} : { being }), ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args: json(args)! }) } };
+    }
+    case 'own':
+    case 'disown':
+      return { ...at, method: command, args: { id: need(1)[0]! } };
+    default:
+      throw new Error(USAGE);
+  }
+};
+
+// An error answer at any depth the root line or an ask carries it.
+const failed = (answer: unknown): boolean => {
+  if (typeof answer !== 'object' || answer === null) return false;
+  const a = answer as JsonObject;
+  return 'error' in a || failed(a.answer);
+};
+
+export const main = async (argv: string[], env: Record<string, string | undefined>, print: (line: string) => void): Promise<number> => {
+  const { command, words, flags } = parse(argv);
+  if (command === undefined) throw new Error(USAGE);
+  const dir = flags.dir ?? env.NERVUR_DIR ?? join(homedir(), '.nervur');
+  const out = (answer: JsonObject): number => {
+    print(JSON.stringify(answer));
+    return failed(answer) ? 1 : 0;
+  };
+  if (command === 'init') {
+    if (words.length > 0) throw new Error('init takes no argument');
+    if (existsSync(join(dir, 'seed'))) return out({ error: `a harbor stands at ${dir}` });
+    const { harbor, carrier } = await open(dir);
+    try {
+      const owner = await harbor.root('own', { id: 'owner' });
+      return out({ pk: harbor.box.pk, owner: owner as JsonObject });
+    } finally {
+      await carrier.close();
+    }
+  }
+  if (command === 'serve') {
+    if (words.length > 0) throw new Error('serve takes no argument');
+    const served = await serve(dir, flags.host, flags.port === undefined ? undefined : Number(flags.port));
+    const stop = (): void => void served.close().then(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    print(JSON.stringify({ pk: served.pk, at: served.at, root: served.root }));
+    return SERVING;
+  }
+  if (command === 'pilot') {
+    if (words.length !== 3) throw new Error('pilot takes 3 arguments');
+    const [name, invitation, at] = words as [string, string, string];
+    const held = JSON.parse(invitation) as JsonObject;
+    for (const req of pilotRequests(name, held, at)) {
+      const answer = await request(dir, req);
+      if (!failed(answer)) continue;
+      if (req.method === 'ask') await request(dir, { method: 'unboot', args: { being: name } });
+      return out(answer);
+    }
+    return out({ piloting: name, ward: held.ward! });
+  }
+  if (flags.via === undefined) return out(await request(dir, requestOf(command, words, flags)));
+  if (flags.ward !== undefined) throw new Error('--via takes no --ward');
+  return out(farAnswer(await request(dir, via(flags.via, requestOf(command, words, flags)))));
+};
+
+// The root requests that hold a far ward: its route, the pilot, the take.
+export const pilotRequests = (name: string, invitation: JsonObject, at: string): RootRequest[] => [
+  { method: 'route', args: { ward: invitation.ward ?? null, at } },
+  { method: 'boot', args: { key: name, class: 'org.nervur.pilot' } },
+  { method: 'ask', args: { being: name, method: 'hold', args: { invitation } } },
+];
+
+// A root request, asked of the far ward a pilot holds.
+export const via = (pilot: string, far: RootRequest): RootRequest => ({
+  method: 'ask',
+  args: { being: pilot, method: 'pilot', args: { ...(far.method === undefined ? {} : { method: far.method }), ...(far.args === undefined ? {} : { args: far.args }) } },
+});
+
+// The far ward-being's answer out of the pilot's, or the local error.
+export const farAnswer = (local: JsonObject): JsonObject => {
+  const inner = (local.answer as JsonObject | undefined)?.answer;
+  return typeof inner === 'object' && inner !== null && !Array.isArray(inner) ? inner : local;
+};
+
+// What `main` answers for a harbor it keeps serving: no exit yet.
+export const SERVING = -1;

package/src/cli/harbor.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: Apache-2.0
+// A harbor on this machine, as the `nervur` command stands it: its seed and
+// sealed memory in a folder, its code imported from the files its
+// catalogue names, Quo over TCP as its carrier, and the root line on a
+// local socket beside them.
+//
+//   <dir>/seed        the harbor's seed
+//   <dir>/<place>/    its sealed memory
+//   <dir>/root.sock   the root line while the harbor is served, open to
+//                     this user alone, or in the temporary folder for a
+//                     folder too deep for a socket path
+//
+// A root request goes to a served harbor over its socket. With none served,
+// the command unpacks the harbor from its folder, asks, and closes it, so
+// one process at a time writes the folder.
+import { createHash } from 'node:crypto';
+import { chmod, rm } from 'node:fs/promises';
+import { connect, createServer, type Server } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { JsonObject } from '../being/index.ts';
+import { Loader, type Loaded } from '../contract/index.ts';
+import { FolderCustody, FolderMemory } from '../folder/index.ts';
+import { Harbor, rootLine, type RootRequest } from '../harbor/index.ts';
+import { CryptoEntropy, PointerTerrain } from '../pointer/index.ts';
+import { TcpCarrier, TcpListener } from '../tcp/index.ts';
+
+// A socket path has a hundred bytes or so on every system, so a folder too
+// deep for one puts its socket in this user's temporary folder, under a
+// name drawn from the folder's own path.
+const SOCKET_PATH = 100;
+export const socketOf = (dir: string): string => {
+  const beside = join(resolve(dir), 'root.sock');
+  if (Buffer.byteLength(beside) <= SOCKET_PATH) return beside;
+  return join(tmpdir(), `nervur-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 32)}.sock`);
+};
+
+// Code from a file: a module that exports `module`, `version` and
+// `classes`, found again by its absolute path. A file that cannot be
+// imported, or exports no module, is none.
+export class ImportLoader extends Loader {
+  async load(from: string): Promise<Loaded | null> {
+    const path = resolve(from);
+    let exported: { module?: unknown; version?: unknown; classes?: unknown };
+    try {
+      exported = (await import(pathToFileURL(path).href)) as typeof exported;
+    } catch {
+      return null;
+    }
+    const { module, version, classes } = exported;
+    if (typeof module !== 'string' || typeof version !== 'string' || !Array.isArray(classes)) return null;
+    return { module, version, classes, from: path };
+  }
+}
+
+export type Opened = { harbor: Harbor; carrier: TcpCarrier };
+
+export const open = async (dir: string): Promise<Opened> => {
+  const entropy = new CryptoEntropy();
+  const carrier = new TcpCarrier();
+  const harbor = await Harbor.open(new PointerTerrain({ entropy, carrier, loader: new ImportLoader(), custody: new FolderCustody(dir, entropy), memory: new FolderMemory(dir) }));
+  return { harbor, carrier };
+};
+
+// One root request over a served harbor's socket, or undefined where none
+// is served.
+const overSocket = (dir: string, request: RootRequest): Promise<JsonObject | undefined> =>
+  new Promise((done, fail) => {
+    const socket = connect(socketOf(dir));
+    let text = '';
+    socket.once('connect', () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on('data', (chunk: Buffer) => {
+      text += chunk.toString('utf8');
+      const end = text.indexOf('\n');
+      if (end < 0) return;
+      socket.end();
+      done(JSON.parse(text.slice(0, end)) as JsonObject);
+    });
+    socket.once('error', (e: NodeJS.ErrnoException) => (e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? done(undefined) : fail(e)));
+  });
+
+export const request = async (dir: string, req: RootRequest): Promise<JsonObject> => {
+  const served = await overSocket(dir, req);
+  if (served !== undefined) return served;
+  const { harbor, carrier } = await open(dir);
+  try {
+    return await rootLine(harbor, req);
+  } finally {
+    await carrier.close();
+  }
+};
+
+export type Served = { pk: string; at: string; root: string; close(): Promise<void> };
+
+// The harbor served: Quo over TCP on host and port, the root line on the
+// socket. A socket file nobody answers on is a stale one, and is replaced.
+export const serve = async (dir: string, host?: string, port?: number): Promise<Served> => {
+  if ((await overSocket(dir, {})) !== undefined) throw new Error(`a harbor is already served from ${dir}`);
+  const { harbor, carrier } = await open(dir);
+  const listener = await TcpListener.listen(harbor, host, port);
+  const root = socketOf(dir);
+  await rm(root, { force: true });
+  const server: Server = createServer((socket) => {
+    let text = '';
+    socket.on('data', (chunk: Buffer) => {
+      text += chunk.toString('utf8');
+      for (let end = text.indexOf('\n'); end >= 0; end = text.indexOf('\n')) {
+        const line = text.slice(0, end);
+        text = text.slice(end + 1);
+        let value: unknown;
+        try {
+          value = JSON.parse(line);
+        } catch {
+          value = undefined;
+        }
+        void rootLine(harbor, value)
+          .catch(() => ({ error: 'the harbor threw' }))
+          .then((answer) => socket.write(`${JSON.stringify(answer)}\n`));
+      }
+    });
+    socket.on('error', () => socket.destroy());
+  });
+  await new Promise<void>((done) => server.listen(root, done));
+  await chmod(root, 0o600);
+  return {
+    pk: harbor.box.pk,
+    at: listener.at,
+    root,
+    close: async () => {
+      await new Promise((done) => server.close(done));
+      await rm(root, { force: true });
+      await listener.close();
+      await carrier.close();
+    },
+  };
+};

package/src/cli/main.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// The `nervur` program: `command.ts` over this process's arguments. A
+// command that cannot run exits 2 and says why on stderr.
+import { main, SERVING } from './command.ts';
+
+try {
+  const code = await main(process.argv.slice(2), process.env, (line) => process.stdout.write(`${line}\n`));
+  if (code !== SERVING) process.exitCode = code;
+} catch (e) {
+  process.stderr.write(`nervur: ${(e as Error).message}\n`);
+  process.exitCode = 2;
+}