@quo-systems/dock 0.1.0 → 0.2.1

package/README.md

@@ -8,10 +8,17 @@ built on the dock, on Quo.
 
 ```bash
 npm install @quo-systems/dock
-npx quo init
-npx quo serve
+npx quo estate my-estate --domain example.com
+npx quo init --dir my-estate/droplet
+npx quo serve --dir my-estate/droplet
 ```
 
+`quo estate` writes an estate folder: one folder per harbor, the first a
+droplet's quo directory with its routes under your domain, its unit and
+its Caddyfile, and a package file that depends on the dock and nothing
+else. Add your beings to `droplet/classes/`, and your placement to the
+routes and agents files.
+
 `beings/quo-dock.md` is the truth of this package and the trunk of its four
 documents; read it first. It knows nothing the spec of Quo does not say,
 and adds no word to harbor, ward or being.

package/beings/avatar.ts

@@ -51,8 +51,11 @@ export class Avatar extends Being {
     return this.join(inv as unknown as Invitation);
   }
 
-  // Knock with an invitation, hand the user being one back so she can push,
-  // and take her as `user`. The only moment a standing is born here.
+  // Knock with an invitation, hand the far being one back so she can push,
+  // and take her as `user`. The only moment a standing is born here. A being
+  // who answers the hello with an error object is a being who answered: she
+  // is taken all the same, and the way back she did not take is dropped, so
+  // any world's public being may admit a guest, hello or not.
   async join(invitation: Invitation): Promise<Blueprint | { error: string }> {
     if (this.standings[USER]) return this.tools();
     const mine = await this.invite(PUSHER);
@@ -62,6 +65,7 @@ export class Avatar extends Being {
       this.occupants.remove(PUSHER);
       return { error: isSilence(out) ? 'silence' : wordOf(out) };
     }
+    if (out !== null && typeof out === 'object' && !Array.isArray(out) && 'error' in out) this.occupants.remove(PUSHER);
     await this.take(USER, invitation);
     return this.tools();
   }

package/beings/carry.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier: a being who shows the asks of the standings she holds as asks
+// of her own, and forwards. Whoever she carries for sees, in one describe,
+// what she can be asked and what every being she holds can be asked, each
+// under that standing's name; asking one is an ask on that standing, in her
+// name, so the far being sees her and never who is behind her. A user being
+// carries acme for the human's devices; a house being could carry its
+// rooms; nothing here knows what she is.
+//
+// A carried ask is `<id>-<name>`, and the mapping back is kept in her cells
+// and never parsed from the name, so an id with a dash in it is no trouble.
+// The notes say which asks are whose, `standings: { id: { asks, look? } }`,
+// so a screen draws one section per standing and a model side keeps the
+// flat list it needs. Her own asks come first and are never shadowed: a
+// carried name that collides with one of hers is dropped.
+//
+// She asks a standing's describe again when its digest moved, and its
+// `look` once per digest, and keeps both in her cells. So a describe of
+// hers may cost one ask per stale standing, which is the price of a page
+// that is never more than one ask behind.
+import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import type { Asker, Blueprint, JsonObject, OccupantRecord, Reply } from '@quo-systems/quo';
+import { sanitise, type Look } from './look.ts';
+
+type Carried = Record<string, { id: string; ask: string }>;
+type Looks = Record<string, { digest: string | null; look: Look }>;
+
+export class Carrier extends Being {
+  // Who sees what she carries. Nobody, until a subclass says who.
+  static carries(_occupant: OccupantRecord | undefined, _asker: Asker): boolean {
+    return false;
+  }
+  // Standings she never carries: a way back to a device is one, by the
+  // dock's own convention, and a subclass may name more.
+  static hidden(id: string): boolean {
+    return id.startsWith('to:');
+  }
+
+  private get carried(): Carried {
+    return ((this.cells.carried as Carried | undefined) ??= {});
+  }
+  private get looks(): Looks {
+    return ((this.cells.looks as Looks | undefined) ??= {});
+  }
+
+  // Her describe with her standings carried into it, for an asker who may
+  // see them. Every other asker gets her describe alone.
+  async blueprint(asker: Asker): Promise<Blueprint> {
+    const C = this.constructor as typeof Carrier;
+    const bp = this.describe(asker);
+    if (!C.carries(this.occupant(asker), asker)) return bp;
+    const own = new Set(bp.asks.map((a) => a.name));
+    const carried: Carried = {};
+    const groups: Record<string, { asks: string[]; look?: Look }> = {};
+    for (const [id, rec] of Object.entries(this.cells.standings)) {
+      if (C.hidden(id)) continue;
+      const st = this.standings[id];
+      if (!st) continue;
+      if (!rec.blueprint || rec.seen !== rec.digest) await st.ask(); // her ward writes the record
+      if (!rec.blueprint) continue;
+      const names: string[] = [];
+      for (const a of rec.blueprint.asks) {
+        if (a.name === 'look') continue;
+        const name = `${id}-${a.name}`;
+        if (own.has(name)) continue;
+        carried[name] = { id, ask: a.name };
+        names.push(name);
+        bp.asks.push({ ...a, name });
+      }
+      const group: { asks: string[]; look?: Look } = { asks: names };
+      if (rec.blueprint.asks.some((a) => a.name === 'look')) {
+        const kept = this.looks[id];
+        if (!kept || kept.digest !== rec.digest) {
+          const l = await st.ask('look');
+          this.looks[id] = { digest: rec.digest, look: isSilence(l) || isWord(l) ? {} : sanitise(l) };
+        }
+        group.look = this.looks[id]!.look;
+      }
+      groups[id] = group;
+    }
+    for (const id of Object.keys(this.looks)) if (!(id in groups)) delete this.looks[id];
+    this.cells.carried = carried;
+    const notes = bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) ? bp.notes : {};
+    return { asks: bp.asks, notes: { ...notes, standings: groups as unknown as JsonObject } };
+  }
+
+  override async answer(asker: Asker, method?: string, args: JsonObject = {}): Promise<Reply> {
+    if (method === undefined) return this.blueprint(asker);
+    const C = this.constructor as typeof Carrier;
+    const to = Object.hasOwn(this.carried, method) ? this.carried[method] : undefined;
+    if (to && C.carries(this.occupant(asker), asker)) {
+      const st = this.standings[to.id];
+      if (!st) return { error: 'unknown ask' };
+      const out = await st.ask(to.ask, args);
+      if (isSilence(out)) return out;
+      if (isWord(out)) return { error: wordOf(out) };
+      return out;
+    }
+    return super.answer(asker, method, args);
+  }
+}

package/beings/desk.ts

@@ -12,7 +12,7 @@ import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
 import type { Asker, Json, JsonObject } from '@quo-systems/quo';
 
 export type Proof = { kind: string; [more: string]: Json };
-export type Verified = { user: string; client: string; wake?: boolean };
+export type Verified = { user: string; client: string; wake?: boolean; reach?: boolean };
 export type Verifier = (proof: Proof) => Promise<Verified | null> | Verified | null;
 
 export class Desk extends Being {
@@ -38,7 +38,7 @@ export class Desk extends Being {
     if (!who) return { error: 'refused' };
     const user = this.standings[`user:${who.user}`];
     if (!user) return { error: 'no such user' };
-    const inv = await user.ask('device', who.wake === true ? { client: who.client, wake: true } : { client: who.client });
+    const inv = await user.ask('device', { client: who.client, ...(who.wake === true ? { wake: true } : {}), ...(who.reach === true ? { reach: true } : {}) });
     if (isSilence(inv)) return { error: 'silence' };
     if (isWord(inv)) return { error: wordOf(inv) };
     return inv;

package/beings/index.ts

@@ -3,3 +3,5 @@
 export { User, DESK } from './user.ts';
 export { Desk, type Proof, type Verified, type Verifier } from './desk.ts';
 export { Avatar, USER, PUSHER } from './avatar.ts';
+export { Carrier } from './carry.ts';
+export { sanitise, hint, hintFor, groups, type Look, type Hint } from './look.ts';

package/beings/link.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+// A link: a world's page with an invitation in the fragment. The page is the
+// hint, where the world lives; the fragment is the invitation, which never
+// leaves the browser: a query string reaches the server, its logs and every
+// referer, and an invitation is a capability. One reserved key, `quo`, the
+// one word no page uses for anything else, and the value is the invitation
+// compact: `ward.heir.secret`, three hex strings, or `ward` alone for a
+// world's public being. The dock's human module reads it, strips it before
+// any page code runs, and joins.
+import type { Invitation } from '@quo-systems/quo';
+
+export const KEY = 'quo';
+const HEX = (n: number) => `[0-9a-f]{${n}}`;
+const FULL = new RegExp(`^(${HEX(128)})\\.(${HEX(64)})\\.(${HEX(64)})$`);
+const PUBLIC = new RegExp(`^${HEX(128)}$`);
+
+export function format(inv: Invitation): string {
+  return inv.heir && inv.secret ? `${inv.ward}.${inv.heir}.${inv.secret}` : inv.ward;
+}
+
+// The invitation in a fragment, or null. Anything else in the fragment is
+// the page's own and is left alone.
+export function parse(hash: string): Invitation | null {
+  const m = /(?:^#|&)quo=([^&]+)/.exec(hash.startsWith('#') ? hash : `#${hash}`);
+  if (!m) return null;
+  const v = decodeURIComponent(m[1]!);
+  const full = FULL.exec(v);
+  if (full) return { ward: full[1]!, heir: full[2]!, secret: full[3]! };
+  return PUBLIC.test(v) ? { ward: v } : null;
+}
+
+// The fragment without the invitation, so the page keeps whatever else it
+// put there and the capability is gone from the address bar.
+export function strip(hash: string): string {
+  const rest = (hash.startsWith('#') ? hash.slice(1) : hash)
+    .split('&')
+    .filter((p) => !p.startsWith(`${KEY}=`))
+    .join('&');
+  return rest ? `#${rest}` : '';
+}
+
+export function link(page: string, inv: Invitation): string {
+  return `${page}#${KEY}=${format(inv)}`;
+}
+
+// Whether an answer is an invitation: a ward pk, and a heir with its secret
+// or neither. What a guest's form answers with to be let in.
+export function 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' || !PUBLIC.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));
+}

package/beings/look.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// A look: what a being may say about how she is presented, as values and
+// no more. One optional ask, `look`, answers it, and every side reads the
+// part it understands: a screen reads the tokens and paints her section, a
+// model side reads the hints per ask and writes them as tool annotations.
+// Nothing here is capability, so nothing here is in a blueprint or a digest,
+// and Quo never sees it. The vocabulary is closed: a token that is not
+// listed does not exist, and one that fails its shape is dropped, not
+// fixed. A being cannot paint outside her section or reach a server
+// through a look, because no token can carry a URL, a stylesheet or code.
+import type { Blueprint, Json, JsonObject } from '@quo-systems/quo';
+
+// What a side may do with one ask. `title` is a human label instead of the
+// name; `readOnly` says the ask changes nothing, so a screen may run it on
+// its own and a model side marks it so; `destructive` asks for care;
+// `idempotent` says asking twice is asking once; `icon` is one short string
+// for a button. A being who marks an ask read-only and then writes has lied
+// to her own page, and nothing enforces it, the way nothing enforces that
+// her empty ask is safe to repeat.
+export type Hint = { title?: string; readOnly?: boolean; destructive?: boolean; idempotent?: boolean; icon?: string };
+export type Look = {
+  name?: string;
+  logo?: string; // an image as a data URI, never a URL
+  accent?: string; // hex colours
+  background?: string;
+  foreground?: string;
+  font?: string; // a font stack, plain characters
+  radius?: number; // 0 to 40, in px
+  order?: string[]; // her asks in the order she wants them shown
+  asks?: Record<string, Hint>;
+};
+
+const COLOUR = /^#[0-9a-fA-F]{3,8}$/;
+const FONT = /^[\w\s,'"-]{1,80}$/;
+const LOGO = /^data:image\/(svg\+xml|png|jpeg|webp);base64,[A-Za-z0-9+/=]{1,40000}$/;
+const NAME = /^[^<>&]{1,60}$/;
+const ICON = /^[^<>&"']{1,8}$/;
+
+const str = (v: Json | undefined, re: RegExp): string | undefined => (typeof v === 'string' && re.test(v) ? v : undefined);
+
+// The look as a side may use it: every token held to its shape, everything
+// else gone. A value that is not an object is no look at all.
+export function sanitise(v: Json | undefined): Look {
+  if (v === null || v === undefined || typeof v !== 'object' || Array.isArray(v)) return {};
+  const l: Look = {};
+  const name = str(v.name, NAME);
+  if (name !== undefined) l.name = name;
+  const logo = str(v.logo, LOGO);
+  if (logo !== undefined) l.logo = logo;
+  for (const k of ['accent', 'background', 'foreground'] as const) {
+    const c = str(v[k], COLOUR);
+    if (c !== undefined) l[k] = c;
+  }
+  const font = str(v.font, FONT);
+  if (font !== undefined) l.font = font;
+  if (typeof v.radius === 'number' && Number.isFinite(v.radius) && v.radius >= 0 && v.radius <= 40) l.radius = Math.round(v.radius);
+  if (Array.isArray(v.order)) l.order = v.order.filter((x): x is string => typeof x === 'string');
+  if (v.asks !== null && typeof v.asks === 'object' && !Array.isArray(v.asks)) {
+    const asks: Record<string, Hint> = {};
+    for (const [ask, h] of Object.entries(v.asks as JsonObject)) {
+      if (h === null || typeof h !== 'object' || Array.isArray(h)) continue;
+      const hint: Hint = {};
+      const title = str(h.title, NAME);
+      if (title !== undefined) hint.title = title;
+      const icon = str(h.icon, ICON);
+      if (icon !== undefined) hint.icon = icon;
+      for (const k of ['readOnly', 'destructive', 'idempotent'] as const) if (typeof h[k] === 'boolean') hint[k] = h[k];
+      if (Object.keys(hint).length) asks[ask] = hint;
+    }
+    if (Object.keys(asks).length) l.asks = asks;
+  }
+  return l;
+}
+
+// The one hint a side reads first: whether this ask is in the look at all.
+export const hint = (l: Look | undefined, name: string): Hint => l?.asks?.[name] ?? {};
+
+// A carrier's notes say which asks are a standing's, and how she looks:
+// `standings: { id: { asks: [name], look? } }`. Every side reads them here.
+export type Group = { asks?: string[]; look?: Json };
+export function groups(bp: Blueprint | null): Record<string, Group> {
+  const n = bp?.notes;
+  const g = n !== null && n !== undefined && typeof n === 'object' && !Array.isArray(n) ? n.standings : undefined;
+  return g !== null && g !== undefined && typeof g === 'object' && !Array.isArray(g) ? (g as Record<string, Group>) : {};
+}
+
+// The hint for one ask, hers or a standing's: a carried ask is looked up
+// under its bare name in that standing's look.
+export function hintFor(bp: Blueprint | null, mine: Look, name: string): Hint {
+  for (const [id, g] of Object.entries(groups(bp))) {
+    if (!g.asks?.includes(name)) continue;
+    const prefix = `${id}-`;
+    return hint(sanitise(g.look), name.startsWith(prefix) ? name.slice(prefix.length) : name);
+  }
+  return hint(mine, name);
+}