@nervur-org/dock 0.5.0 → 0.6.0

package/cli/nervur.ts

@@ -10,14 +10,15 @@
 // device holds for the daemon is either: the unit, the unix user, the home
 // and the environment file all say nervur.
 //
-//   nervur 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
+//   nervur 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, beings/User unless said; --default marks it the default ward; --show shows it at the web route; --domain writes the four routes under DOM
 //   nervur 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
 //   nervur 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
-//   nervur domain [--dir D] <domain>            write routes.json by the convention: mcp., web., quo. and api. under the domain, over https
-//   nervur 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
+//   nervur domain [--dir D] <domain>            say the four routes by the convention, mcp., web., quo. and api. under the domain over https, a cell of the Dock
+//   nervur apps   [--dir D] <json>              say the apps this box's links open, { apple, android }, a cell of the Dock; {} forgets them
+//   nervur serve  [--dir D] [--http PORT] [--host ADDR]  the daemon: harbor from disk, the two sockets, the HTTP door on ADDR, 127.0.0.1 unless said, a socket held to every route the dialers faculty keeps
 //   nervur census [--dir D] [--ward W] [--via S]        the empty ask: pk and every being
 //   nervur boot   [--dir D] [--ward W] [--via S] <json> { key, class, public? }
-//   nervur invite [--dir D] [--ward W] [--via S] <json> { being, id }; with routes.json naming web., the answer carries the link
+//   nervur invite [--dir D] [--ward W] [--via S] <json> { being, id }; with the box's routes naming web., the answer carries the link
 //   nervur knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
 //   nervur remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
 //   nervur unboot [--dir D] [--ward W] [--via S] <json> { being }: a being out of the ward, with every relation she holds
@@ -29,7 +30,9 @@
 //   nervur estate <dir> --domain D              an estate folder of the shape every estate has: a droplet's harbor directory, unit and Caddyfile, a Mac's launchd agent, on this dock
 //
 // D defaults to $NERVUR_DIR, then ~/.nervur. W defaults to the default ward, and
-// init names a new ward main when none is given. init takes
+// init names a new ward main when none is given. serve takes the HTTP port
+// as --http or $NERVUR_HTTP and the address it binds as --host or
+// $NERVUR_HOST, 127.0.0.1 when neither says one. init takes
 // --user NAME for the user being, defaulting to the device's user. run
 // takes the model's base URL as --url or $NERVUR_MODEL_URL, its name as
 // --model or $NERVUR_MODEL, a bearer from $NERVUR_MODEL_KEY, read here and never
@@ -42,7 +45,8 @@ import { join } from 'node:path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { isInvitation } from 'nervur';
 import { DiskHarbor } from '../harbor/disk.ts';
-import { serve, readRoutes, writeRoutes } from './daemon.ts';
+import { serve } from './daemon.ts';
+import { BOX, BOX_SEED, type Routes } from '../box/index.ts';
 import { ask, askBeing, side, reach, type Run } from './client.ts';
 import { link } from '../beings/link.ts';
 import { pilotSide } from './pilot.ts';
@@ -57,7 +61,7 @@ function parse(argv: string[]) {
     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]!;
+    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;
@@ -69,8 +73,10 @@ const print = (v: unknown) => console.log(JSON.stringify(v, null, 2));
 async function main(argv: string[]): Promise<number> {
   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);
+    const made = await DiskHarbor.init(dir, flags.ward, flags.user ?? userInfo().username, flags.class, 'show' in flags);
+    // the box's own cells, said to the Dock with no daemon over the folder
+    if ('default' in flags) await DiskHarbor.say(dir, 'default', { ward: made.name });
+    print(flags.domain ? { ...made, ...(await DiskHarbor.say(dir, 'domain', { domain: flags.domain })) } : made);
     return 0;
   }
   if (cmd === 'default') {
@@ -78,8 +84,15 @@ async function main(argv: string[]): Promise<number> {
       console.error('nervur default <ward>');
       return 2;
     }
-    await DiskHarbor.setDefault(dir, json);
-    print({ default: json });
+    print(await DiskHarbor.say(dir, 'default', { ward: json }));
+    return 0;
+  }
+  if (cmd === 'apps') {
+    if (!json) {
+      console.error('nervur apps <json>  { apple: [...], android: [{ package, fingerprints }] }; {} forgets them');
+      return 2;
+    }
+    print(await DiskHarbor.say(dir, 'apps', JSON.parse(json) as Record<string, unknown>));
     return 0;
   }
   if (cmd === 'show' || cmd === 'hide') {
@@ -96,13 +109,12 @@ async function main(argv: string[]): Promise<number> {
       console.error('nervur domain <domain>');
       return 2;
     }
-    print({ routes: await writeRoutes(dir, json) });
+    print(await DiskHarbor.say(dir, 'domain', { domain: 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));
+  // default, which the daemon resolves for a request naming none.
+  const wardOf = () => flags.ward;
   if (cmd === 'side' || cmd === 'run') {
     if (!flags.as) {
       console.error(`nervur ${cmd} needs --as NAME`);
@@ -124,11 +136,11 @@ async function main(argv: string[]): Promise<number> {
       }
       run = { url, model, ...(key ? { key } : {}), ...(turns !== undefined ? { turns } : {}) };
     }
-    await side(dir, flags.as, await wardOf(), run); // stdio to the daemon, until one end closes
+    await side(dir, flags.as, wardOf(), run); // stdio to the daemon, until one end closes
     return -1;
   }
   if (cmd === 'pilot') {
-    const ward = await wardOf();
+    const ward = 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)));
@@ -136,7 +148,11 @@ async function main(argv: string[]): Promise<number> {
   }
   if (cmd === 'serve') {
     const port = flags.http ?? process.env.NERVUR_HTTP;
-    const s = await serve(dir, port !== undefined ? { http: { port: Number(port) } } : {});
+    // Loopback unless an address is said. A daemon reachable from the
+    // network is the operator's own word and never a default, so the flag
+    // exists and is never filled in for him.
+    const host = flags.host || process.env.NERVUR_HOST;
+    const s = await serve(dir, port !== undefined ? { http: { port: Number(port), ...(host ? { host } : {}) } } : {});
     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);
@@ -160,7 +176,7 @@ async function main(argv: string[]): Promise<number> {
       console.error('nervur ask needs <being> [method] [json]');
       return 2;
     }
-    const out = await askBeing(dir, json, more, third ? (JSON.parse(third) as Record<string, unknown>) : {}, await wardOf());
+    const out = await askBeing(dir, json, more, third ? (JSON.parse(third) as Record<string, unknown>) : {}, 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;
@@ -176,25 +192,28 @@ async function main(argv: string[]): Promise<number> {
   }
   if (cmd === 'census' || (cmd !== undefined && OWNER_ASKS.has(cmd))) {
     const args = json ? (JSON.parse(json) as Record<string, unknown>) : {};
-    const ward = await wardOf();
+    const ward = 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
+    // an invitation minted here is handed on as a link when the box'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
+    // the fragment, one string to send to the person it is for. The routes
+    // are the Dock's cells, asked of her through the daemon.
     const minted = cmd === 'invite' && !via && 'result' in out && isInvitation(out.result) ? out.result : null;
-    const routes = minted ? await readRoutes(dir) : null;
+    const box = minted ? await askBeing(dir, BOX, 'box', {}, BOX_SEED) : null;
+    const routes = box && 'result' in box ? ((box.result as { routes?: Routes | null }).routes ?? null) : null;
+    const on = ('ward' in out ? out.ward : undefined) ?? ward ?? '';
     // 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) });
+    if (minted && routes) print({ ...minted, link: link(`${routes.web}/${encodeURIComponent(on)}`, 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: nervur 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]');
+  console.error('usage: nervur init|default|show|hide|domain|apps|serve|census|boot|public|invite|knock|remove|unboot|ask|side|run|pilot|reach|estate [--dir D] [--ward W] [--via S] [--as NAME] [--http PORT] [--host ADDR] [--url URL --model NAME] [json]');
   return 2;
 }
 

package/cli/stand.ts

@@ -89,7 +89,7 @@ const ward = (h: Wards, name: string, why: string) => h.wards.get(name) ?? fail(
 // 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: Harbor | Wards, decl: Stand): Promise<{ booted: string[]; wired: string[]; already: string[] }> {
+async function standUp(harbor: Harbor | Wards, decl: Stand): Promise<{ booted: string[]; wired: string[]; already: string[] }> {
   const h = harbor as Wards;
   const booted: string[] = [];
   for (const b of decl.boot ?? []) {

package/dist/api/route.d.ts

@@ -1,7 +1,7 @@
 import type { Handler } from '../harbor/http.ts';
 import type { Hosted } from 'nervur/harbor';
 import type { Avatar } from '../beings/avatar.ts';
-import type { Grants } from '../dock/grants.ts';
+import type { Bearers as Grants } from '../box/grants.ts';
 import { type Invitation } from 'nervur';
 export type Held = {
     wards: ReadonlyMap<string, Hosted>;
@@ -16,6 +16,5 @@ export type Options = {
     join: (identity: string, invitation: Invitation, ward: string) => Promise<{
         error?: string;
     }>;
-    web?: string;
 };
 export declare function apiRoute(harbor: Held, o: Options): Handler;

package/dist/api/route.js

@@ -1,35 +1,12 @@
 import { readText } from '../harbor/http.js';
 import { invitationOf } from '../beings/link.js';
-import { landed, POLICY } from '../human/door.js';
-import { CSS } from '../human/style.js';
+import { isIdentity } from '../beings/join.js';
 import { isInvitation, isSilence, isWord, wordOf } from 'nervur';
 const open = { 'access-control-allow-origin': '*', 'access-control-allow-methods': 'GET, POST, OPTIONS', 'access-control-allow-headers': 'content-type, authorization' };
 const word = (s) => (typeof s === 'string' && /^[\w.-]{1,40}$/.test(s) ? s : null);
 export function apiRoute(harbor, o) {
     return async (req, rest) => {
         const json = (status, body) => Response.json(body, { status, headers: open });
-        // The one page this road serves, and it wears the one stylesheet every
-        // screen wears. No cross-origin header on it: a page is for the browser
-        // that was sent here and never for a script somewhere else. Its policy
-        // is the allow page's, and for the same reason: a page that runs no
-        // script of its own should be allowed none.
-        const page = (status, body) => new Response(`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>nervur</title>\n<style>${CSS}</style>\n</head><body>${body}</body></html>`, {
-            status,
-            headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': POLICY, 'referrer-policy': 'no-referrer' },
-        });
-        // Where this world lives, as the daemon was told and not as the request
-        // said: a Host header is the caller's to write, and a page that printed
-        // one would print whatever a caller wanted a human to read. Falling back
-        // to it is for a box configured with no web address at all, where the
-        // request is the only thing that knows.
-        const hostOf = (r) => {
-            try {
-                return o.web === undefined ? (r.headers.get('host') ?? '') : new URL(o.web).host;
-            }
-            catch {
-                return r.headers.get('host') ?? '';
-            }
-        };
         if (req.method === 'OPTIONS')
             return new Response(null, { status: 204, headers: open });
         if (req.method !== 'GET' && req.method !== 'POST')
@@ -64,8 +41,8 @@ export function apiRoute(harbor, o) {
                 return json(400, { error: 'that invitation is for a world that does not live here' });
             const [ward, hosted] = world;
             const identity = word(b.identity);
-            if (identity === null || identity === hosted.record.user || identity === 'desk')
-                return json(400, { error: 'an identity is one word, and not the user or the desk' });
+            if (!isIdentity(hosted, identity))
+                return json(400, { error: 'an identity is one word, and not a being of the ward' });
             // Nobody at a page vouches for a program, so a trade is a knock that
             // spends: an identity already in refreshes, or is removed at the user
             // being and invited again, and never re-enters on a spent invitation.
@@ -81,57 +58,8 @@ export function apiRoute(harbor, o) {
         // device's, and its door answers for it.
         const [, named = '', ask = '', ...more] = rest.split('/');
         const ward = named === '' ? harbor.here() : named;
-        // The delivery: a vendor's webhook to an envoy, `/api/<ward>/<being>/deliver`.
-        // Not a stranger's ask and not an occupant's: the owner asking her
-        // `deliver` with the raw bytes and the headers, and nothing else. The
-        // body is read as a string and never parsed here, since the vendor
-        // signed the bytes and a reparsed body fails her check; no bearer is
-        // read, since the rung is not the caller's to prove. She answers `{ ok }`
-        // or her error object, and the route carries it.
-        // A GET on the same path is the same ask with an empty body: where an
-        // OAuth redirect lands, the code in the query. The query crosses inside
-        // the headers under `:query`, a name no header on the wire can have, so
-        // her one ask in stays one.
-        if (more.length === 1 && more[0] === 'deliver') {
-            if (req.method !== 'POST' && req.method !== 'GET')
-                return json(405, { error: 'POST, or GET for a redirect' });
-            const hosted = harbor.wards.get(ward);
-            if (!hosted || !/^[\w-]+$/.test(ask))
-                return json(404, { error: 'no such world' });
-            const raw = req.method === 'GET' ? '' : await readText(req);
-            if (raw === undefined)
-                return json(413, { error: 'too big' });
-            const headers = {};
-            req.headers.forEach((v, k) => (headers[k] = v));
-            const query = new URL(req.url).search.slice(1);
-            if (query)
-                headers[':query'] = query;
-            const out = await hosted.ask('ask', { being: ask, method: 'deliver', args: { body: raw, headers } });
-            await hosted.save();
-            // A GET here is a browser and a browser is a human: a vendor a world
-            // sent her to has opened this URL in her tab, so what she is looking
-            // at is whatever the envoy answered a machine. She gets a page
-            // instead, and only she does; a vendor asking for JSON is answered in
-            // JSON as it always was, and so is a GET that says nothing about what
-            // it wants.
-            const wants = req.method === 'GET' && (req.headers.get('accept') ?? '').includes('text/html');
-            if (wants) {
-                const ok = out !== null && typeof out === 'object' && !Array.isArray(out) && typeof out.error !== 'string';
-                return page(ok ? 200 : 400, landed({ world: ward, host: hostOf(req), ...(o.web ? { at: `${o.web.replace(/\/$/, '')}/${encodeURIComponent(ward)}` } : {}), ok }));
-            }
-            if (isSilence(out) || out === null || typeof out !== 'object' || Array.isArray(out))
-                return json(503, { error: 'silence' });
-            const said = out.error;
-            if (said === 'no such being' || said === 'unknown ask')
-                return json(404, { error: 'no such envoy' });
-            if (said === 'silence' || said === 'threw' || said === 'late')
-                return json(503, { error: 'silence' });
-            if (typeof said === 'string')
-                return json(400, out);
-            return json(200, out);
-        }
         if (!/^[\w.-]+$/.test(ward) || more.length > 0 || (ask !== '' && !/^[\w-]+$/.test(ask)))
-            return json(404, { error: 'GET /api for the device’s ward, GET /api/<ward> for the describe, GET or POST /api/<ward>/<ask> for one ask, POST /api/<ward>/<being>/deliver for a delivery' });
+            return json(404, { error: 'GET /api for the device’s ward, GET /api/<ward> for the describe, GET or POST /api/<ward>/<ask> for one ask' });
         const hosted = harbor.wards.get(ward);
         if (!hosted)
             return json(404, { error: 'no such world' });

package/dist/beings/avatar.d.ts

@@ -1,8 +1,8 @@
-import type { Answer, Blueprint, Invitation, JsonObject, OccupantRecord, Wanted } from 'nervur';
-import { Carrier } from './carry.ts';
+import { Being } from 'nervur';
+import type { Answer, Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Reply, Wanted } from 'nervur';
 export declare const USER = "user";
 export declare const PUSHER = "user:push";
-export declare class Avatar extends Carrier {
+export declare class Avatar extends Being {
     static cells: {
         inbox: JsonObject[];
     };
@@ -15,6 +15,7 @@ export declare class Avatar extends Carrier {
             for: (occ: OccupantRecord | undefined) => boolean;
         };
     };
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
     readonly ears: Set<(object: JsonObject) => void>;
     notify(args: JsonObject): {
         notified: boolean;

package/dist/beings/avatar.js

@@ -7,21 +7,24 @@
 // calls the four methods below: one of the two ways in, `enter` behind a
 // route's proof or `join` with an invitation, then `tools` and `call`.
 // Nothing of a side is in her cells.
-import { isSilence, isWord, wordOf } from 'nervur';
-import { Carrier } from './carry.js';
+import { Being, isSilence, isWord, wordOf } from 'nervur';
+import { carry } from './carry.js';
 // Her one standing, and the id under which the user being pushes to her.
 // Two ids for one far being, because standings and occupants share one
 // namespace and a record holds one or the other.
 export const USER = 'user';
 export const PUSHER = 'user:push';
-// A carrier who carries for nobody, until a subclass says who: the presence
-// being carries the box's faculties to her user being, and a bare avatar
-// holds one standing and shows nothing of it.
-export class Avatar extends Carrier {
+// She carries for nobody, until a subclass says who: the presence being
+// carries the box's faculties to her user being, and a bare avatar holds
+// one standing and shows nothing of it.
+export class Avatar extends Being {
     static cells = { inbox: [] };
     static asks = {
         notify: { description: 'a push from the user being', input: { type: 'object' }, for: (occ) => occ?.id === PUSHER },
     };
+    answer(asker, method, args = {}) {
+        return carry(this, asker, method, args, (a, m, g) => super.answer(a, m, g));
+    }
     // Her sides' ears. One identity is one avatar for life, and two sessions
     // of that identity are two sides on her at once, so a push goes to every
     // ear present; each side adds its own on open and removes it on close.

package/dist/beings/carry.d.ts

@@ -1,12 +1,10 @@
-import { Being } from 'nervur';
-import type { Asker, Blueprint, JsonObject, OccupantRecord, Reply } from 'nervur';
-export declare class Carrier extends Being {
-    static carries(_occupant: OccupantRecord | undefined, _asker: Asker): boolean;
-    static hidden(id: string): boolean;
-    static skips(_id: string): boolean;
-    static shows(_id: string, _occupant: OccupantRecord | undefined, _asker: Asker): boolean;
-    private get carried();
-    private get looks();
-    blueprint(asker: Asker): Promise<Blueprint>;
-    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
-}
+import type { Asker, Being, Blueprint, JsonObject, OccupantRecord, Reply } from 'nervur';
+export type Carrying = {
+    carries(occupant: OccupantRecord | undefined, asker: Asker): boolean;
+    hidden(id: string): boolean;
+    skips(id: string): boolean;
+    shows(id: string, occupant: OccupantRecord | undefined, asker: Asker): boolean;
+};
+export declare const CARRIES: Carrying;
+export declare function blueprint(self: Being, asker: Asker): Promise<Blueprint>;
+export declare function carry(self: Being, asker: Asker, method: string | undefined, args: JsonObject, own: (asker: Asker, method: string, args: JsonObject) => Promise<Reply>): Promise<Reply>;