@nervur-org/dock 0.3.0

package/dist/cli/estate/quo.service

@@ -0,0 +1,35 @@
+# The daemon on a droplet, as one user, forever. Install with:
+#   sudo cp droplet/quo.service /etc/systemd/system/quo.service
+#   sudo systemctl enable --now quo
+# The unit runs as the `quo` user, whose home holds the estate folder and
+# the harbor folder, so the seed, the lease and the sockets are that user's
+# alone. The HTTP door is loopback only; Caddy fronts it. See Caddyfile
+# beside this file.
+[Unit]
+Description=quo: one harbor on this device
+After=network.target
+
+[Service]
+User=quo
+Group=quo
+Environment=QUO_DIR=/home/quo/.quo
+Environment=QUO_HTTP=8787
+# CLAUDE_CODE_OAUTH_TOKEN, when an agent folder runs `claude -p`: the agent
+# reads its credential from the device, never from cells.
+EnvironmentFile=-/etc/quo/env
+WorkingDirectory=/home/quo/ESTATE
+ExecStart=/usr/bin/node /home/quo/ESTATE/node_modules/@nervur-org/dock/dist/cli/quo.js serve
+Restart=always
+RestartSec=2
+KillSignal=SIGTERM
+TimeoutStopSec=10
+NoNewPrivileges=true
+ProtectSystem=strict
+# Agents run in their folders and Claude Code keeps its own state in the
+# user's home; both must be writable for a run to happen, and a harbor
+# with no agent has neither.
+ReadWritePaths=/home/quo/.quo -/home/quo/agents -/home/quo/.claude -/home/quo/.claude.json /tmp
+PrivateTmp=false
+
+[Install]
+WantedBy=multi-user.target

package/dist/cli/estate/systems.quo.plist

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  The daemon on a Mac, as the user, forever: a launchd agent. It holds the
+  harbor at ~/.quo and the socket to every quo. route ~/.quo/dial.json
+  names, so a Mac behind NAT is reached through the droplet it dialed. The
+  daemon runs the dock's emitted `dist/cli/quo.js` from where the estate
+  installed it, never the source. Install, with node on the path:
+
+    sed "s#HOME#$HOME#g; s#NODE#$(which node)#g" mac/systems.quo.plist > ~/Library/LaunchAgents/systems.quo.plist
+    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/systems.quo.plist
+
+  Remove with `launchctl bootout gui/$(id -u)/systems.quo`; restart after a
+  wire change with `launchctl kickstart -k gui/$(id -u)/systems.quo`. The
+  log is ~/.quo/serve.log. No HTTP door: a Mac is a dialer, not a listener.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>systems.quo</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>NODE</string>
+    <string>HOME/ESTATE/node_modules/@nervur-org/dock/dist/cli/quo.js</string>
+    <string>serve</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>QUO_DIR</key>
+    <string>HOME/.quo</string>
+  </dict>
+  <key>WorkingDirectory</key>
+  <string>HOME/ESTATE</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>2</integer>
+  <key>StandardOutPath</key>
+  <string>HOME/.quo/serve.log</string>
+  <key>StandardErrorPath</key>
+  <string>HOME/.quo/serve.log</string>
+</dict>
+</plist>

package/dist/cli/estate.d.ts

@@ -0,0 +1,5 @@
+export declare function estate(dir: string, domain: string): Promise<{
+    dir: string;
+    name: string;
+    files: string[];
+}>;

package/dist/cli/estate.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// `quo estate DIR --domain D`: an estate folder, written once, of the shape
+// every estate has. One folder per harbor: `droplet/`, the quo directory
+// that device runs minus what it mints, its routes under the domain, no
+// agents, no schedules, no classes of its own, and that device's unit and
+// Caddyfile; and `mac/`, the launchd agent that runs the daemon on an
+// operator's Mac as a dialer, with the dial list it holds. A package file
+// that depends on this dock and nothing else, and one document to fill in.
+// An estate needs nothing the dock does not give it, and this is the dock
+// giving it.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DOMAIN, routesFor } from './daemon.js';
+// This package's own version, read beside the emitted or the source tree.
+async function version() {
+    for (const rel of ['../package.json', '../../package.json']) {
+        const at = fileURLToPath(new URL(rel, import.meta.url));
+        if (!existsSync(at))
+            continue;
+        const pkg = JSON.parse(await readFile(at, 'utf8'));
+        if (pkg.name === '@nervur-org/dock' && pkg.version)
+            return pkg.version;
+    }
+    return '0.1.0';
+}
+const template = (name) => readFile(fileURLToPath(new URL(`estate/${name}`, import.meta.url)), 'utf8');
+export async function estate(dir, domain) {
+    if (!DOMAIN.test(domain))
+        throw new Error(`estate: ${domain} is not a domain`);
+    if (existsSync(join(dir, 'package.json')))
+        throw new Error(`estate: ${dir} already holds a package`);
+    const name = basename(dir);
+    const files = {
+        'package.json': JSON.stringify({ name, private: true, description: `The ${name} estate: one owner's harbors, built on the dock and nothing else.`, type: 'module', dependencies: { '@nervur-org/dock': `^${await version()}` } }, null, 2) + '\n',
+        [`${name}.md`]: `# ${name}\n\nAn estate: all of one owner's harbors. One folder per harbor, each the quo\ndirectory that device runs minus what it mints, plus that device's unit.\n\`droplet/\` is the first: its routes under \`${domain}\`, its agents, its\nclasses, its systemd unit and its Caddyfile. This folder depends on the\ndock and nothing else.\n\n## The droplet\n\nWhere it is, how it is reached, and what was done to stand it up: yours\nto write.\n`,
+        'droplet/routes.json': JSON.stringify(routesFor(domain)) + '\n',
+        'droplet/stand.ts': `// SPDX-License-Identifier: Apache-2.0\n// What the root stands up on this harbor, once, after the inits and with no\n// daemon over the folder: the beings the estate boots for its own working\n// and the relations between them, placed on real invitations. Run as\n// \`node droplet/stand.ts <dir>\`; twice is once.\nimport { stand } from '@nervur-org/dock/stand';\n\nconsole.log(await stand(process.argv[2] ?? process.env.QUO_DIR ?? '', { boot: [], wire: [] }));\n`,
+        'droplet/classes/index.ts': '// The classes this harbor holds beside the dock\'s built-in ones, exported\n// by name.\nexport {};\n',
+        'droplet/quo.service': (await template('quo.service')).replaceAll('ESTATE', name),
+        'droplet/Caddyfile': (await template('Caddyfile')).replaceAll('DOMAIN', domain),
+        'mac/systems.quo.plist': (await template('systems.quo.plist')).replaceAll('ESTATE', name),
+    };
+    for (const [rel, text] of Object.entries(files)) {
+        await mkdir(join(dir, rel, '..'), { recursive: true });
+        await writeFile(join(dir, rel), text);
+    }
+    return { dir, name, files: Object.keys(files) };
+}

package/dist/cli/folder.d.ts

@@ -0,0 +1,2 @@
+import { type Folder } from '../human/web.ts';
+export declare function diskFolder(dir: string): Folder;

package/dist/cli/folder.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+// The harbor folder as the web route asks for it. A route reads no file, so
+// what a world keeps beside its wards is answered here, where the daemon
+// already has a disk: `design/` for the face it wears and `tab/` for its own
+// code for the tab. Nothing is held between requests, because a folder is
+// worn, built and changed while the daemon runs and a restart is not how a
+// world puts on a face.
+//
+// A world wears a design only when it holds `tokens.css`: that file is the
+// design, and a folder with fonts and no tokens wears nothing, so nothing of
+// it is served.
+import { access, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { TAB_CODE, TAB_SOURCE } from '../human/web.js';
+const DESIGN = 'design';
+export function diskFolder(dir) {
+    const there = (at) => access(at).then(() => true, () => false);
+    const tokens = join(dir, DESIGN, 'tokens.css');
+    return {
+        wearing: async () => ((await there(tokens)) ? { tokens: true, fonts: await there(join(dir, DESIGN, 'fonts.css')) } : { tokens: false, fonts: false }),
+        design: async (file) => ((await there(tokens)) ? readFile(join(dir, DESIGN, file)).then((b) => new Uint8Array(b), () => null) : null),
+        serving: async () => (await there(join(dir, TAB_CODE))) || (await there(join(dir, TAB_SOURCE))),
+        beings: () => readFile(join(dir, TAB_CODE), 'utf8').catch(() => null),
+    };
+}

package/dist/cli/oauth.d.ts

@@ -0,0 +1,2 @@
+import { type Store } from '../mcp/oauth.ts';
+export declare function danceOnDisk(dir: string): Store;

package/dist/cli/oauth.js

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// The OAuth dance as the daemon keeps it: `<dir>/oauth.json`, the route's
+// own file and nobody else's, written whole through a temporary name so a
+// crash mid-write leaves the last good dance behind. A route reads no file,
+// so this is where the disk is, beside the folder and the wards.
+//
+// The writes are queued because the dance moves on a request and requests
+// overlap: two saves racing on one name is how a file ends up half of each.
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { emptyDance } from '../mcp/oauth.js';
+export function danceOnDisk(dir) {
+    const file = join(dir, 'oauth.json');
+    let queue = Promise.resolve();
+    return {
+        load: async () => {
+            const read = await readFile(file, 'utf8').catch(() => null);
+            if (read === null)
+                return emptyDance();
+            try {
+                return { ...emptyDance(), ...JSON.parse(read) };
+            }
+            catch {
+                return emptyDance(); // a dance nobody can read is a dance nobody is in the middle of
+            }
+        },
+        save: (dance) => (queue = queue.then(async () => {
+            await writeFile(file + '.tmp', JSON.stringify(dance), { mode: 0o600 });
+            await rename(file + '.tmp', file);
+        })),
+    };
+}

package/dist/cli/pilot.d.ts

@@ -0,0 +1,5 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Serving } from '../beings/side.ts';
+import { type Subject } from '../mcp/server.ts';
+export declare function owner(dir: string, ward: string, via?: string): Subject;
+export declare function pilotSide(dir: string, ward: string, transport: Transport, via?: string): Promise<Serving>;

package/dist/cli/pilot.js

@@ -0,0 +1,22 @@
+import { ask } from './client.js';
+import { mcpSide } from '../mcp/server.js';
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// The owner hears objects: the socket's own failure, a silence and a word
+// each come back as an error object named for what it was.
+export function owner(dir, ward, via) {
+    const one = async (method, args) => {
+        const out = await ask(dir, method, args, ward, via);
+        if ('error' in out)
+            return { error: out.error };
+        const r = out.result;
+        if (isRecord(r) && r.silence === true)
+            return { error: 'silence' };
+        if (isRecord(r) && typeof r.word === 'string')
+            return { error: r.word };
+        return r;
+    };
+    return { tools: () => one(undefined, {}), call: (name, args) => one(name, args ?? {}), ears: new Set() };
+}
+export function pilotSide(dir, ward, transport, via) {
+    return mcpSide(owner(dir, ward, via), transport);
+}

package/dist/cli/quo.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/quo.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// `quo`: the one command of the estate. Thin on purpose: each subcommand
+// picks a folder, reaches the daemon or the disk, and hands off. Logic that
+// appears here was missing from a being or a side, and moves there.
+//
+//   quo init   [--dir D] [--ward W] [--user U] [--class C] [--default] [--show] [--domain DOM]  mint a seed, boot a ward over a disk store, write both; C is the class of the ward's home being, User unless said; --default marks it the default ward; --show shows it at the web route; --domain writes the four routes under DOM
+//   quo default [--dir D] <ward>             mark one ward the default, the one a caller means when naming none; the one ward hosted is the default unmarked
+//   quo show|hide [--dir D] <ward>           show a ward at the web route, listed at its root and its public being's page painted for a stranger; hidden at init, and a hidden ward's page is the plain door
+//   quo domain [--dir D] <domain>            write routes.json by the convention: mcp., web., quo. and api. under the domain, over https
+//   quo serve  [--dir D] [--http PORT]      the daemon: harbor from disk, the two sockets, the HTTP door on loopback, a socket held to every route the dialers faculty keeps
+//   quo census [--dir D] [--ward W] [--via S]        the empty ask: pk and every being
+//   quo boot   [--dir D] [--ward W] [--via S] <json> { key, class, public? }
+//   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }; with routes.json naming web., the answer carries the link
+//   quo knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
+//   quo remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
+//   quo unboot [--dir D] [--ward W] [--via S] <json> { being }: a being out of the ward, with every relation she holds
+//   quo ask    [--dir D] [--ward W] <being> [method] [json]  the root asking a being of its own ward, as the device
+//   quo side   [--dir D] [--ward W] --as NAME  an avatar over stdio for a local MCP client; NAME is the client identity
+//   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
+//   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
+//   quo reach  [--dir D] <pk> <url>          a hint for the harbor's directory: that ward pk lives at that quo. route
+//   quo estate <dir> --domain D              an estate folder of the shape every estate has: a droplet's quo directory, unit and Caddyfile, a Mac's launchd agent, on this dock
+//
+// D defaults to $QUO_DIR, then ~/.quo. W defaults to the default ward, and
+// init names a new ward main when none is given. init takes
+// --user NAME for the user being, defaulting to the device's user. run
+// takes the model's base URL as --url or $QUO_MODEL_URL, its name as
+// --model or $QUO_MODEL, a bearer from $QUO_MODEL_KEY, read here and never
+// kept, and --turns as the ceiling of model calls in one turn. S is a
+// standing the user being holds at another ward, one the root there invited
+// as an owner: with --via, the owner asks go to that ward's door, sealed,
+// and the answers are its. Without it they are the root's, on the pointer.
+import { homedir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { isInvitation } from '@nervur-org/nervur';
+import { DiskHarbor } from '../harbor/disk.js';
+import { serve, readRoutes, writeRoutes } from './daemon.js';
+import { ask, askBeing, side, reach } from './client.js';
+import { link } from '../beings/link.js';
+import { pilotSide } from './pilot.js';
+import { estate } from './estate.js';
+const OWNER_ASKS = new Set(['boot', 'public', 'invite', 'knock', 'remove', 'unboot']);
+function parse(argv) {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? '';
+        // a flag takes the word after it, unless that word is a flag or there is
+        // none: --default stands alone
+        if (a.startsWith('--'))
+            flags[a.slice(2)] = argv[i + 1] === undefined || argv[i + 1].startsWith('--') ? '' : argv[++i];
+        else
+            rest.push(a);
+    }
+    const [cmd, json, more, third] = rest;
+    return { cmd, json, more, third, flags, dir: flags.dir ?? process.env.QUO_DIR ?? join(homedir(), '.quo'), ward: flags.ward, via: flags.via };
+}
+const print = (v) => console.log(JSON.stringify(v, null, 2));
+async function main(argv) {
+    const { cmd, json, more, third, flags, dir, via } = parse(argv);
+    if (cmd === 'init') {
+        const made = await DiskHarbor.init(dir, flags.ward, flags.user ?? userInfo().username, flags.class, 'default' in flags, 'show' in flags);
+        print(flags.domain ? { ...made, routes: await writeRoutes(dir, flags.domain) } : made);
+        return 0;
+    }
+    if (cmd === 'default') {
+        if (!json) {
+            console.error('quo default <ward>');
+            return 2;
+        }
+        await DiskHarbor.setDefault(dir, json);
+        print({ default: json });
+        return 0;
+    }
+    if (cmd === 'show' || cmd === 'hide') {
+        if (!json) {
+            console.error(`quo ${cmd} <ward>`);
+            return 2;
+        }
+        await DiskHarbor.setShown(dir, json, cmd === 'show');
+        print({ [cmd === 'show' ? 'shown' : 'hidden']: json });
+        return 0;
+    }
+    if (cmd === 'domain') {
+        if (!json) {
+            console.error('quo domain <domain>');
+            return 2;
+        }
+        print({ routes: await writeRoutes(dir, json) });
+        return 0;
+    }
+    // Every command that reaches a ward is on one: the one named, or the
+    // default, read from the folder the way the daemon reads it, and only once
+    // the command is held right.
+    const wardOf = async () => flags.ward ?? (await DiskHarbor.defaultOf(dir));
+    if (cmd === 'side' || cmd === 'run') {
+        if (!flags.as) {
+            console.error(`quo ${cmd} needs --as NAME`);
+            return 2;
+        }
+        let run;
+        if (cmd === 'run') {
+            const url = flags.url ?? process.env.QUO_MODEL_URL;
+            const model = flags.model ?? process.env.QUO_MODEL;
+            if (!url || !model) {
+                console.error('quo run needs --url URL and --model NAME, or QUO_MODEL_URL and QUO_MODEL');
+                return 2;
+            }
+            const key = process.env.QUO_MODEL_KEY;
+            const turns = flags.turns !== undefined ? Number(flags.turns) : undefined;
+            if (turns !== undefined && !(Number.isInteger(turns) && turns > 0)) {
+                console.error('--turns is a positive integer');
+                return 2;
+            }
+            run = { url, model, ...(key ? { key } : {}), ...(turns !== undefined ? { turns } : {}) };
+        }
+        await side(dir, flags.as, await wardOf(), run); // stdio to the daemon, until one end closes
+        return -1;
+    }
+    if (cmd === 'pilot') {
+        const ward = await wardOf();
+        await ask(dir, undefined, {}, ward); // no daemon is a clear word now, not at the first tool call
+        const serving = await pilotSide(dir, ward, new StdioServerTransport(), via);
+        process.stdin.once('end', () => void serving.close().then(() => process.exit(0)));
+        return -1;
+    }
+    if (cmd === 'serve') {
+        const port = flags.http ?? process.env.QUO_HTTP;
+        const s = await serve(dir, port !== undefined ? { http: { port: Number(port) } } : {});
+        print({ dir: s.harbor.dir, sock: s.sock, side: s.side, http: s.http ? `http://${s.http.host}:${s.http.port}` : null, dial: s.quo.dialers.map((d) => d.url), wards: Object.fromEntries([...s.harbor.wards].map(([n, h]) => [n, h.pk])) });
+        const stop = () => void s.close().then(() => process.exit(0));
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        return -1; // stays up
+    }
+    if (cmd === 'estate') {
+        if (!json || !flags.domain) {
+            console.error('quo estate needs <dir> --domain D');
+            return 2;
+        }
+        print(await estate(json, flags.domain));
+        return 0;
+    }
+    // The root reaching into a being of its own ward. Two positionals and the
+    // args as JSON, because a human writes this one by hand: `quo ask clock keep
+    // '{"id":"nightly","ask":"desk.hello","cron":"0 3 * * *"}'`. With no
+    // method it is that being's describe, as the device sees her.
+    if (cmd === 'ask') {
+        if (!json) {
+            console.error('quo ask needs <being> [method] [json]');
+            return 2;
+        }
+        const out = await askBeing(dir, json, more, third ? JSON.parse(third) : {}, await wardOf());
+        print('error' in out ? { error: out.error } : out.result);
+        const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
+        return failed ? 1 : 0;
+    }
+    if (cmd === 'reach') {
+        if (!json || !more) {
+            console.error('quo reach needs <pk> <url>');
+            return 2;
+        }
+        const out = await reach(dir, json, more);
+        print('error' in out ? { error: out.error } : out.result);
+        return 'error' in out ? 1 : 0;
+    }
+    if (cmd === 'census' || (cmd !== undefined && OWNER_ASKS.has(cmd))) {
+        const args = json ? JSON.parse(json) : {};
+        const ward = await wardOf();
+        let out = await ask(dir, cmd === 'census' ? undefined : cmd, args, ward, via);
+        // an invitation minted here is handed on as a link when the harbor's
+        // routes name a web. origin: the world's page with the invitation in
+        // the fragment, one string to send to the person it is for
+        const minted = cmd === 'invite' && !via && 'result' in out && isInvitation(out.result) ? out.result : null;
+        const routes = minted ? await readRoutes(dir) : null;
+        // the ward answers null to an invite on an id already held, standing or
+        // occupant, and null on a terminal is nothing to read: it is a refusal
+        // here, in words, and an exit code a script can tell apart
+        if (cmd === 'invite' && 'result' in out && out.result === null)
+            out = { result: { error: 'id taken' } };
+        if (minted && routes)
+            print({ ...minted, link: link(`${routes.web}/${encodeURIComponent(ward)}`, minted) });
+        else
+            print('error' in out ? { error: out.error } : out.result);
+        // an error object the ward answered is an ordinary answer, and still a
+        // non-zero exit, so a script can tell a boot that happened from one that did not.
+        const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
+        return failed ? 1 : 0;
+    }
+    console.error('usage: quo init|default|show|hide|domain|serve|census|boot|public|invite|knock|remove|unboot|ask|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [json]');
+    return 2;
+}
+main(process.argv.slice(2)).then((code) => {
+    if (code >= 0)
+        process.exit(code);
+}, (e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+});

package/dist/cli/stand.d.ts

@@ -0,0 +1,37 @@
+import type { JsonObject } from '@nervur-org/nervur';
+import type { Harbor } from '@nervur-org/nervur/harbor';
+export type Boot = {
+    ward: string;
+    key: string;
+    class: string;
+    public?: boolean;
+};
+export type Wire = {
+    from: string;
+    to: string;
+    as?: string;
+    known?: string;
+    notes?: JsonObject;
+};
+export type Stand = {
+    boot?: Boot[];
+    wire?: Wire[];
+};
+type Wards = {
+    wards: Map<string, {
+        being(key: string): unknown;
+        ask(method: string, args: JsonObject): Promise<unknown>;
+    }>;
+    partitionOf(name: string): Record<string, unknown> | undefined;
+};
+export declare function standUp(harbor: Harbor | Wards, decl: Stand): Promise<{
+    booted: string[];
+    wired: string[];
+    already: string[];
+}>;
+export declare function stand(dir: string, decl: Stand): Promise<{
+    booted: string[];
+    wired: string[];
+    already: string[];
+}>;
+export {};

package/dist/cli/stand.js

@@ -0,0 +1,110 @@
+import { DiskHarbor } from '../harbor/disk.js';
+const KEY = /^[\w.:-]+$/;
+const RESERVED = new Set(['knock', 'take', 'remove']);
+const fail = (why) => {
+    throw new Error(`stand: ${why}`);
+};
+// `<ward>.<key>`, split at the first dot: a ward's name is a plain word and a
+// being's key is not, so the ambiguity only ever falls one way.
+function at(v, what) {
+    const dot = v.indexOf('.');
+    if (dot < 1)
+        return fail(`${what}: "${v}" is not "<ward>.<being>"`);
+    return { ward: v.slice(0, dot), key: v.slice(dot + 1) };
+}
+// A name a wire would use, read off the partition the harbor already holds:
+// whether a being holds it as a standing and whether she holds it as an
+// occupant. Standings and occupants are one namespace, so a name held under
+// the other kind is a collision and never this wire.
+function holds(h, ward, key, id) {
+    const p = h.partitionOf(ward);
+    return { standing: Object.hasOwn(p?.bind?.[key]?.standings ?? {}, id), occupant: Object.hasOwn(p?.beings?.[key]?.occupants ?? {}, id) };
+}
+const ward = (h, name, why) => h.wards.get(name) ?? fail(`${why}: this device hosts no ward ${name}`);
+// Stand a booted harbor up. Everything declared and absent is placed;
+// everything declared and present is left exactly as it is.
+//
+// Idempotency is read off the mint and not off anybody's cells. A being is
+// whatever answers, `Being` or a bare object with one method, so there is no
+// shape here to reach into: what says a wire already stands is that the far
+// being refuses to mint that occupant a second time. `invite` answers null
+// for exactly one reason once the reader has held the id to a word the ward
+// does not reserve, which is that the id is taken, and an id taken is this
+// wire, placed the last time the script ran.
+export async function standUp(harbor, decl) {
+    const h = harbor;
+    const booted = [];
+    for (const b of decl.boot ?? []) {
+        const w = ward(h, b.ward, `boot ${b.ward}.${b.key}`);
+        if (!w.being(b.key)) {
+            const out = (await w.ask('boot', { key: b.key, class: b.class }));
+            if (out.error)
+                fail(`boot ${b.ward}.${b.key} as ${b.class}: ${out.error}`);
+            booted.push(`${b.ward}.${b.key}`);
+        }
+        // the mark is one per ward and the script is what says who holds it:
+        // taken off whoever holds it, the desk init put there, and put on her,
+        // which is the same two asks whether or not she held it already
+        if (b.public) {
+            const off = (await w.ask('public', { key: null }));
+            if (off.error)
+                fail(`public ${b.ward}.${b.key}: ${off.error}`);
+            const out = (await w.ask('public', { key: b.key }));
+            if (out.error)
+                fail(`public ${b.ward}.${b.key}: ${out.error}`);
+        }
+    }
+    const wired = [];
+    const already = [];
+    for (const one of decl.wire ?? []) {
+        const from = at(one.from, 'from'), to = at(one.to, 'to');
+        const as = one.as ?? to.key, known = one.known ?? from.key;
+        if (!KEY.test(as) || !KEY.test(known))
+            fail(`a name is a word: ${one.from} -> ${one.to}`);
+        // The three the stance keeps for itself. A ward refuses them at invite
+        // and at take, and refusing them here is what leaves `invite` answering
+        // null for one reason only, which is the whole of how this stays
+        // idempotent without reading anybody's cells.
+        if (RESERVED.has(as) || RESERVED.has(known))
+            fail(`knock, take and remove are the ward's own words: ${one.from} -> ${one.to}`);
+        const near = ward(h, from.ward, `wire ${one.from}`), far = ward(h, to.ward, `wire ${one.to}`);
+        if (!near.being(from.key))
+            fail(`wire ${one.from}: no such being`);
+        if (!far.being(to.key))
+            fail(`wire ${one.to}: no such being`);
+        // A name held under the other kind is not this wire and never will be:
+        // said now, before a heir is spent on it, rather than read as a wire
+        // already placed or refused at the knock with the far side already bound.
+        const atFar = holds(h, to.ward, to.key, known);
+        const atNear = holds(h, from.ward, from.key, as);
+        if (atFar.standing)
+            fail(`wire ${one.from} -> ${one.to}: ${to.key} already holds a standing named ${known}, and a name is one of the two`);
+        if (atNear.occupant)
+            fail(`wire ${one.from} -> ${one.to}: ${from.key} already holds an occupant named ${as}, and a name is one of the two`);
+        const inv = (await far.ask('invite', { being: to.key, id: known, ...(one.notes ? { notes: one.notes } : {}) }));
+        if (inv === null) {
+            already.push(`${one.from} -> ${one.to}`);
+            continue;
+        }
+        if ('error' in inv)
+            fail(`wire ${one.from} -> ${one.to}: ${inv.error}`);
+        const took = (await near.ask('knock', { being: from.key, id: as, invitation: inv }));
+        if (took.taken !== as)
+            fail(`wire ${one.from} -> ${one.to}: ${took.error ?? `${from.key} would not take ${as}`}`);
+        wired.push(`${one.from} -> ${one.to}`);
+    }
+    return { booted, wired, already };
+}
+// What an estate's `stand.ts` calls: the harbor folder booted here, with no
+// daemon over it, stood up and written back. The lease refuses a folder a
+// daemon holds, so the recipe is stop, stand, start, like an init.
+export async function stand(dir, decl) {
+    const h = new DiskHarbor(dir);
+    await h.boot();
+    try {
+        return await standUp(h, decl);
+    }
+    finally {
+        await h.close();
+    }
+}