@nervur-org/dock 0.4.1 → 0.6.0

package/human/wake.ts

@@ -20,9 +20,8 @@
 import { isInvitation, isSilence, isWord } from 'nervur';
 import type { Invitation, JsonObject, Standing } from 'nervur';
 import type { Harbor } from 'nervur/harbor';
-import { DOCK, CONSOLE, NOTIFICATIONS, facultyOf, type Token } from '../dock/index.ts';
-import type { Notifications } from '../dock/notifications.ts';
-import { banner } from '../dock/push.ts';
+import { BOX, BOX_SEED, NOTIFICATIONS, Notifications, lent, type Token } from '../box/index.ts';
+import { banner } from '../box/ring.ts';
 import { localName, relations } from './worlds.ts';
 
 // The token a browser's push service hands a page: the endpoint, and the
@@ -54,7 +53,21 @@ const said = (out: unknown): JsonObject | null => (out === undefined || isSilenc
 // The box's own being, as the device's own code reaches its own object in
 // its own process. Nothing of this crosses an edge.
 const box = (harbor: Harbor): { standings: { knock(i: Invitation, m?: string, a?: JsonObject): Promise<unknown> } & Record<string, Standing | undefined> } | undefined =>
-  harbor.wards.get(DOCK)?.being(CONSOLE) as never;
+  harbor.wards.get(BOX_SEED)?.being(BOX) as never;
+
+// Why this device has no doorbell, one word per way it can fail to take
+// one. A closed set and never prose: it is read by the code that walks a
+// device and by a bench, never printed for a person, because a human who
+// has no doorbell is owed the one sentence her shell already writes and not
+// the move that did not happen.
+//
+// `unbuilt` is a build that names no bell. `unhoused` is a harbor with no
+// box ward or no box being, which is a device that has not stood up.
+// `unanswered` is a bell that said nothing at all: a dead tunnel, a refused
+// socket, a pk nothing answers on. `unmade` is a bell that answered and
+// handed out no way in, which is a porter out of room or a being who is not
+// a porter. `untaken` is a way in this ward did not come away holding.
+export type Why = 'unbuilt' | 'unhoused' | 'unanswered' | 'unmade' | 'untaken';
 
 // The doorbell this device holds, taken the first time and kept after that.
 // A stranger phone knocks the bell's public being, is booted a doorbell of
@@ -63,25 +76,32 @@ const box = (harbor: Harbor): { standings: { knock(i: Invitation, m?: string, a?
 //
 // Null is a device with no bell behind it, which is what a build that names
 // none looks like and what a bell that will not answer looks like. Each of
-// them works in every other way.
-export async function doorbell(harbor: Harbor, bell?: Bell): Promise<Held | null> {
-  if (!bell) return null;
-  const ward = harbor.wards.get(DOCK);
+// them works in every other way. The reason comes back beside the null, in
+// `note`, so a caller that wants to know which of them it is can ask and one
+// that does not passes nothing.
+export async function doorbell(harbor: Harbor, bell?: Bell, note?: { why?: Why }): Promise<Held | null> {
+  const no = (why: Why): null => {
+    if (note) note.why = why;
+    return null;
+  };
+  if (!bell) return no('unbuilt');
+  const ward = harbor.wards.get(BOX_SEED);
   const me = box(harbor);
-  if (!ward || !me) return null;
+  if (!ward || !me) return no('unhoused');
   if (!me.standings[DOORBELL]) {
-    const hello = said(await me.standings.knock({ ward: bell.pk } as Invitation, 'hello', {}));
-    const inv = hello?.invitation;
-    if (!isInvitation(inv)) return null;
+    const hello = said(await me.standings.knock({ ward: bell.pk }, 'hello', {}));
+    if (!hello) return no('unanswered');
+    const inv = hello.invitation;
+    if (!isInvitation(inv)) return no('unmade');
     // The ward's own knock, which knocks and takes in one act: an
     // invitation is taken only where it was answered, so the two halves are
     // never split.
-    const took = said(await ward.ask('knock', { being: CONSOLE, id: DOORBELL, invitation: inv }));
+    const took = said(await ward.ask('knock', { being: BOX, id: DOORBELL, invitation: inv }));
     await ward.save();
-    if (took?.taken !== DOORBELL) return null;
+    if (took?.taken !== DOORBELL) return no('untaken');
   }
   const mine = me.standings[DOORBELL];
-  if (!mine) return null;
+  if (!mine) return no('untaken');
   return {
     keep: async (token: Token) => {
       const out = said(await mine.ask('keep', { token }));
@@ -92,7 +112,7 @@ export async function doorbell(harbor: Harbor, bell?: Bell): Promise<Held | null
       // The banner key is minted on the first ask and kept, and a terrain
       // whose banners are drawn by a second process plants the secret half
       // where that process reads it while this is happening.
-      const keys = facultyOf<Notifications>(harbor, NOTIFICATIONS);
+      const keys = await lent<Notifications>(harbor, NOTIFICATIONS);
       const key = keys ? said(await keys.banner({}))?.banner : undefined;
       if (typeof key !== 'string') return null;
       const out = said(await mine.ask('admit', {}));

package/human/web.ts

@@ -32,7 +32,7 @@
 // server. The config crosses in a JSON script, which the policy allows.
 import type { Handler } from '../harbor/http.ts';
 import type { Hosted } from 'nervur/harbor';
-import { DOCK } from '../dock/index.ts';
+import { BOX_SEED } from '../box/index.ts';
 import { publicKey } from '../harbor/ward.ts';
 import { ANDROID, APPLE, association, type Apps } from './apps.ts';
 import { door } from './door.ts';
@@ -69,7 +69,7 @@ export type Folder = {
 
 // A world with nothing beside its wards: no design, no code of its own. It
 // is what a terrain hands the route when it holds no folder at all.
-export const BARE_FOLDER: Folder = {
+const BARE_FOLDER: Folder = {
   wearing: () => Promise.resolve({ tokens: false, fonts: false }),
   design: () => Promise.resolve(null),
   serving: () => Promise.resolve(false),
@@ -84,7 +84,7 @@ export type WebOptions = {
   code: { tab: string; worker: string };
   // what the world keeps beside its wards; a world that keeps nothing is bare
   folder?: Folder;
-  // the apps this world's links open, `app.json` in the harbor folder
+  // the apps this world's links open, the Dock's `apps` cell
   apps?: Apps | null;
   // the public half of this world's doorbell key, which a page subscribes
   // to a push service with. A world whose device holds no bell key sends
@@ -174,7 +174,7 @@ ${await design()}
   // public being still answers a proof and a link still knocks, but a hidden
   // ward's page is the plain door page and its root line is not written.
   const shown = o.shown ?? (() => true);
-  const wards = async () => Object.fromEntries(await Promise.all([...harbor.wards].filter(([n]) => n !== DOCK).map(async ([n, h]) => [n, { pk: h.pk, public: shown(n) && (await publicKey(h)) !== null }] as const)));
+  const wards = async () => Object.fromEntries(await Promise.all([...harbor.wards].filter(([n]) => n !== BOX_SEED).map(async ([n, h]) => [n, { pk: h.pk, public: shown(n) && (await publicKey(h)) !== null }] as const)));
   const config = async (ward?: string, being?: string): Promise<Config> => ({ quo: o.at.quo, web: o.at.web, wards: await wards(), beings: await folder.serving(), ...(o.bell ? { bell: o.bell } : {}), ...(ward ? { ward } : {}), ...(being ? { being } : {}) });
   const tab = async (ward?: string, being?: string) => {
     return `<script id="nervur" type="application/json">${JSON.stringify(await config(ward, being)).replace(/</g, '\\u003c')}</script><script type="module" src="${o.at.web}/tab.js"></script>`;