@nervur-org/dock 0.3.0

package/cli/estate/Caddyfile

@@ -0,0 +1,33 @@
+# Four hostnames, one daemon, one loopback port. Caddy faces the world and
+# terminates TLS; the daemon never does. Each hostname is a route, and a
+# route is a path on the daemon's HTTP door. A route says the grammar a
+# caller speaks and never who the caller is: a bearer the box granted is
+# honoured on every one of them. Replace DOMAIN.
+#
+#   mcp.   the model side: streamable HTTP MCP, with the OAuth dance in front
+#   web.   the bundle for plain tabs, and the exchange pages
+#   quo.   the socket door for other harbors: requests in, sockets held, the rendezvous
+#   api.   a describe and its asks as plain JSON, for a program
+#
+# There is no cli. route. The root owner is the unix socket, reached on the
+# device or over SSH, and never through here.
+
+mcp.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /mcp{uri}
+}
+
+web.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /web{uri}
+}
+
+quo.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /quo{uri}
+}
+
+api.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /api{uri}
+}

package/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/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/cli/estate.ts

@@ -0,0 +1,48 @@
+// 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.ts';
+
+// This package's own version, read beside the emitted or the source tree.
+async function version(): Promise<string> {
+  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')) as { name?: string; version?: string };
+    if (pkg.name === '@nervur-org/dock' && pkg.version) return pkg.version;
+  }
+  return '0.1.0';
+}
+const template = (name: string) => readFile(fileURLToPath(new URL(`estate/${name}`, import.meta.url)), 'utf8');
+
+export async function estate(dir: string, domain: string): Promise<{ dir: string; name: string; files: string[] }> {
+  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: Record<string, string> = {
+    '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/cli/folder.ts

@@ -0,0 +1,27 @@
+// 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, type Folder } from '../human/web.ts';
+
+const DESIGN = 'design';
+
+export function diskFolder(dir: string): Folder {
+  const there = (at: string) => 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/cli/oauth.ts

@@ -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, type Dance, type Store } from '../mcp/oauth.ts';
+
+export function danceOnDisk(dir: string): Store {
+  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) as Partial<Dance>) };
+      } catch {
+        return emptyDance(); // a dance nobody can read is a dance nobody is in the middle of
+      }
+    },
+    save: (dance: Dance) =>
+      (queue = queue.then(async () => {
+        await writeFile(file + '.tmp', JSON.stringify(dance), { mode: 0o600 });
+        await rename(file + '.tmp', file);
+      })),
+  };
+}

package/cli/pilot.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// The owner pilot: `quo pilot`. The model side pointed at a ward instead of
+// an avatar. The ward is a being to her owner, so her describe is the tool
+// list and a tool call is an owner ask, exactly as for anyone; nothing here
+// names an ask. Whoever runs this process is the owner, by the device's own
+// rules: the root of the ward here, through the daemon's socket, or, with
+// `via`, an owner at another ward's door, on a standing the user being here
+// holds there. The owner creates and places; the work goes through
+// `quo side`, under a gate.
+//
+// It stands here and not in `mcp/`, because what it is made of is the
+// daemon's socket: `mcp/` holds the model side itself, the subject it is
+// given comes from a client of the daemon, and the client is this folder's.
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Answer, Blueprint, JsonObject } from '@nervur-org/nervur';
+import { ask } from './client.ts';
+import type { Serving } from '../beings/side.ts';
+import { mcpSide, type Subject } from '../mcp/server.ts';
+
+const isRecord = (v: unknown): v is Record<string, unknown> => 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: string, ward: string, via?: string): Subject {
+  const one = async (method: string | undefined, args: JsonObject): Promise<Answer> => {
+    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 as Answer;
+  };
+  return { tools: () => one(undefined, {}) as Promise<Blueprint | { error: string }>, call: (name, args) => one(name, args ?? {}), ears: new Set() };
+}
+
+export function pilotSide(dir: string, ward: string, transport: Transport, via?: string): Promise<Serving> {
+  return mcpSide(owner(dir, ward, via), transport);
+}