@nervur-org/dock 0.5.0 → 0.6.0

package/dist/harbor/browser.js

@@ -1,47 +1,46 @@
-import { User, Desk, Avatar, Presence, Courier } from '../beings/index.js';
+import { BEINGS } from '../beings/index.js';
 import { Harbor, dial } from 'nervur/harbor';
-import { FACULTY_CLASSES, settled, stand } from '../dock/index.js';
+import { BOX_SEED, harborageOver, keyed, settled, standHarbor } from '../box/index.js';
 import { Idb } from './idb.js';
-export const BUILT_IN = { User, Desk, Avatar, Presence, Courier, ...FACULTY_CLASSES };
 export class BrowserHarbor extends Harbor {
     name;
     dialers = [];
     #locked;
     #release;
-    // `lend` is what this box lends the beings of the wards it hosts: a name
-    // to an invitation on a being of its own ward. `stand` builds one; a bare
-    // tab hands none and every name answers null.
-    constructor(store = 'nervur', classes = {}, lend) {
+    constructor(store = 'nervur', classes = {}) {
         const s = typeof store === 'string' ? new Idb(store) : store;
-        super(s, async () => ({ ...BUILT_IN, ...classes }), lend);
+        super(s, async () => keyed({ ...BEINGS, classes }));
         this.name = typeof store === 'string' ? store : 'nervur';
         this.#locked = typeof store === 'string';
     }
-    // What this box lends, by name. A bare tab says nothing, stands no ward of
-    // its own and lends nothing.
-    lent;
-    // What this box lends is said before it boots, and standing the ward is
-    // part of booting: a being born in any other ward lends from her first
-    // line, and a ground that could not reach it yet would leave her holding
-    // nothing until her next birth.
-    async stand(lent) {
-        this.lent = lent;
+    // The classes this terrain brings to its own ward, as a tree. A bare tab
+    // brings none, stands no ward of its own and lends nothing.
+    faculties;
+    // What this harbor is to its faculties, up once it has booted.
+    box = harborageOver(() => this.wards.get(BOX_SEED)?.save() ?? Promise.resolve());
+    // What this box brings is said before it boots, and standing its own ward
+    // is act one of booting: a being born in any other ward takes the box at
+    // her ward's birth, and a box that was not standing yet would leave that
+    // ward holding nothing until its next boot.
+    async stand(faculties) {
+        this.faculties = faculties;
         if (this.wards.size > 0)
-            this.lend = await stand(this, lent);
+            await standHarbor(this, faculties, this.box);
     }
     // Take the lock and boot every ward kept here. A lock already held is
     // another tab's harbor over this seed, and this one refuses to boot.
     async boot() {
         if (this.#locked)
             await this.#lease();
-        if (this.lent)
-            this.lend = await stand(this, this.lent);
+        if (this.faculties)
+            await standHarbor(this, this.faculties, this.box);
         await super.boot();
         // Every being who takes what this box lends does it at her birth, and
         // birth is synchronous while taking a standing is not. A box is up when
         // they have landed, not before, here as on a daemon: a page painted
         // ahead of them shows a device that can do nothing.
-        await settled();
+        await settled(this);
+        await this.box.raise();
     }
     // Hold one socket to a world's quo. route.
     dial(url) {

package/dist/harbor/capacitor.d.ts

@@ -1,19 +1,19 @@
 import { Directory } from '@capacitor/filesystem';
 import type { BeingClass, JsonObject } from 'nervur';
-import { Location, Notifications, type Token, type Where } from '../dock/index.ts';
+import { Location, Notifications, type Token, type Where } from '../box/index.ts';
 import { BrowserHarbor } from './browser.ts';
 import { Sealed, type Files, type Secrets } from './sealed.ts';
 export declare class PhoneLocation extends Location {
+    static stands(): boolean;
     where(): Promise<Where | JsonObject>;
 }
 export declare class PhoneNotifications extends Notifications {
+    static stands(): boolean;
     notify(args: JsonObject): Promise<JsonObject>;
     protected plant(pair: {
         secret: Uint8Array;
     }): Promise<void>;
 }
-export declare const PHONE_FACULTIES: Record<string, BeingClass>;
-export declare const phoneLent: Record<string, string>;
 export declare function phoneEar(sandbox?: boolean, within?: number, named?: {
     bell?: string;
     app?: string;

package/dist/harbor/capacitor.js

@@ -16,7 +16,7 @@ import { SecureStorage, KeychainAccess } from '@aparajita/capacitor-secure-stora
 import { Geolocation } from '@capacitor/geolocation';
 import { LocalNotifications } from '@capacitor/local-notifications';
 import { PushNotifications } from '@capacitor/push-notifications';
-import { LOCATION, NOTIFICATIONS, Location, Notifications } from '../dock/index.js';
+import { Location, Notifications } from '../box/index.js';
 import { BrowserHarbor } from './browser.js';
 import { Sealed } from './sealed.js';
 // The phone's faculties, as its plugins give them: the two defaults extended,
@@ -31,6 +31,9 @@ const BANNER = 'banner';
 const asked = (what) => new Error(`the human is being asked to allow ${what} on this device; ask again`);
 const refused = (what) => new Error(`${what} is not allowed on this device`);
 export class PhoneLocation extends Location {
+    static stands() {
+        return Capacitor.isPluginAvailable('Geolocation');
+    }
     async where() {
         const { location } = await Geolocation.checkPermissions();
         if (location === 'prompt' || location === 'prompt-with-rationale') {
@@ -44,6 +47,9 @@ export class PhoneLocation extends Location {
     }
 }
 export class PhoneNotifications extends Notifications {
+    static stands() {
+        return Capacitor.isPluginAvailable('LocalNotifications');
+    }
     async notify(args) {
         const title = typeof args.title === 'string' ? args.title : '';
         const body = typeof args.body === 'string' ? args.body : '';
@@ -98,11 +104,6 @@ export class PhoneNotifications extends Notifications {
             await PushNotifications.requestPermissions().catch(() => ({ receive: 'denied' }));
     }
 }
-// What a phone lends: the two faculties above under the names every box
-// lends them under, and nothing a phone has not. The harbor holds these
-// class bodies for its own ward, and boots one being of each in it.
-export const PHONE_FACULTIES = { Location: PhoneLocation, Notifications: PhoneNotifications };
-export const phoneLent = { [LOCATION]: 'Location', [NOTIFICATIONS]: 'Notifications' };
 // The phone's ear, as `human/app.ts` asks for one: the token this device is
 // reachable at while it sleeps, or null.
 //
@@ -159,8 +160,8 @@ export function phoneEar(sandbox = false, within = 10_000, named = {}) {
 // told `wake` every time the app comes to the foreground, since a phone
 // asleep loses its sockets silently.
 export async function nativeHarbor(name = 'nervur', classes = {}) {
-    const h = new BrowserHarbor(await Native.open(name), { ...PHONE_FACULTIES, ...classes });
-    await h.stand(phoneLent);
+    const h = new BrowserHarbor(await Native.open(name), classes);
+    await h.stand({ harbor: { PhoneLocation, PhoneNotifications } });
     await h.boot();
     await App.addListener('appStateChange', ({ isActive }) => {
         if (isActive)

package/dist/harbor/disk.d.ts

@@ -1,21 +1,21 @@
-import type { BeingClass } from 'nervur';
-import { Harbor, type Hosted, type Lend } from 'nervur/harbor';
+import { Harbor, type Hosted } from 'nervur/harbor';
+import { type Tree } from '../box/index.ts';
 export type { Hosted, Bound } from 'nervur/harbor';
 export type { WardRecord } from 'nervur/harbor';
-export declare const BUILT_IN: Record<string, BeingClass>;
 export declare function defaultWard(marked: string[], hosted: string[]): string;
 export declare class DiskHarbor extends Harbor {
     #private;
     readonly dir: string;
     defaultWard: string;
-    static setDefault(dir: string, name: string): Promise<void>;
+    static say(dir: string, method: 'domain' | 'apps' | 'default', args: Record<string, unknown>): Promise<Record<string, unknown>>;
     static setShown(dir: string, name: string, shown: boolean): Promise<void>;
     static isShown(dir: string, name: string): boolean;
-    static marked(dir: string): Promise<string[]>;
-    static defaultOf(dir: string): Promise<string>;
-    constructor(dir: string, lend?: Lend, own?: Record<string, BeingClass>);
-    lent: Record<string, string> | undefined;
-    static init(dir: string, name?: string, user?: string, cls?: string, mark?: boolean, shown?: boolean): Promise<{
+    constructor(dir: string);
+    faculties: Tree | undefined;
+    readonly box: import("../box/box.ts").Harborage & {
+        raise(): Promise<void>;
+    };
+    static init(dir: string, name?: string, user?: string, cls?: string, shown?: boolean): Promise<{
         dir: string;
         name: string;
         pk: string;

package/dist/harbor/disk.js

@@ -10,9 +10,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // The node daemon's harbor: the core over a folder on disk. The store is
 // `files.ts`, one folder per ward; the class bodies come from a module the
 // ward record names, loaded from the folder; the lease is a pid file. The
-// estate's own beings, the user being, the front desk and the avatar, are
-// held by every harbor here: they are what every side needs, and a folder's
-// class source adds to them.
+// dock's beings are held by every harbor here under `beings/`, and a
+// folder's class source adds to them under the folder it sits in.
 //
 //   <dir>/
 //     lease                 pid of the one process that holds this harbor
@@ -24,21 +23,20 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //     reach.json            the directory's hints
 import { mkdir, readFile, writeFile, unlink, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { join, resolve, isAbsolute } from 'node:path';
+import { dirname, join, resolve, isAbsolute, relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { register } from 'node:module';
 import process from 'node:process';
-import { User, Desk, Avatar, Presence, Clock, Courier } from '../beings/index.js';
+import { BEINGS } from '../beings/index.js';
 import { setup } from '../beings/setup.js';
-import { Harbor, DEFAULT_CODE } from 'nervur/harbor';
-import { FACULTY_CLASSES, settled, stand } from '../dock/index.js';
+import { Harbor, DEFAULT_CODE, BOX_SEED } from 'nervur/harbor';
+import { BOX, harborageOver, keyed, settled, standHarbor } from '../box/index.js';
 import { Files } from './files.js';
-export const BUILT_IN = { User, Desk, Avatar, Presence, Clock, Courier, ...FACULTY_CLASSES };
 // The default ward, the one a caller means when naming none: the one marked,
 // or the one ward hosted when there is exactly one, which is every harbor an
 // adopter stands with one `nervur init`. Several wards and none marked is
 // refused by name, since agents and a door would otherwise hang off a
-// guess. The dock ward is furniture, never a candidate.
+// guess. The box ward is furniture, never a candidate.
 export function defaultWard(marked, hosted) {
     if (marked.length > 1)
         throw new Error(`this device marks ${marked.join(', ')} as default, and one at most may be`);
@@ -48,7 +46,7 @@ export function defaultWard(marked, hosted) {
             throw new Error(`this device says its default ward is ${one}, and hosts no such ward`);
         return one;
     }
-    const [first, ...more] = hosted.filter((n) => n !== 'dock');
+    const [first, ...more] = hosted.filter((n) => n !== BOX_SEED);
     if (first !== undefined && more.length === 0)
         return first;
     const names = first === undefined ? [] : [first, ...more];
@@ -96,20 +94,32 @@ export class DiskHarbor extends Harbor {
     // ward and nothing in Quo knows of it: a harbor is not a being and has no
     // self to be, so it can only point at one of its wards. Its agents boot
     // there, and its door answers for it when a caller names no ward. The one
-    // ward it hosts when there is one, the one marked otherwise, resolved by
-    // the daemon at boot; empty until then.
+    // ward it hosts when there is one, the one the Dock's cells say otherwise,
+    // placed by the root's `default` ask and resolved by the daemon at boot;
+    // empty until then.
     defaultWard = '';
-    // The mark is a file in the ward's own folder, `wards/<name>/default`, so
-    // it moves with the ward and nothing beside the wards says it. One at most:
-    // marking one takes the mark off every other.
-    static async setDefault(dir, name) {
+    // The root saying what the box is, with no daemon over the folder: the
+    // Dock's own asks, `domain`, `apps` and `default`, on the box ward stood
+    // alone, which the lease refuses while a daemon serves. The daemon reads
+    // what she keeps at its next boot, so a domain said is stop, say, start,
+    // like an init.
+    static async say(dir, method, args) {
         const h = new DiskHarbor(dir);
-        const names = await h.store.list();
-        if (!names.includes(name))
-            throw new Error(`no ward ${name} in ${h.dir}`);
-        for (const n of names)
-            await unlink(join(h.dir, 'wards', n, 'default')).catch(() => { });
-        await writeFile(join(h.dir, 'wards', name, 'default'), '');
+        h.faculties = {};
+        await h.boot();
+        try {
+            const ward = h.wards.get(BOX_SEED);
+            if (!ward)
+                throw new Error('this box stands no ward of its own');
+            const out = (await ward.ask('ask', { being: BOX, method, args }));
+            if (typeof out.error === 'string')
+                throw new Error(out.error);
+            await ward.save();
+            return out;
+        }
+        finally {
+            await h.close();
+        }
     }
     // Whether a ward is shown at the web route: listed at its root and its
     // public being's page painted for a stranger. Hidden, it is not listed
@@ -130,51 +140,44 @@ export class DiskHarbor extends Harbor {
     static isShown(dir, name) {
         return existsSync(join(resolve(dir), 'wards', name, 'shown'));
     }
-    static async marked(dir) {
-        const h = new DiskHarbor(dir);
-        return (await h.store.list()).filter((n) => existsSync(join(h.dir, 'wards', n, 'default')));
-    }
-    // The default ward read from the folder alone, for a command with no
-    // daemon in front of it and no `--ward` given.
-    static async defaultOf(dir) {
-        const h = new DiskHarbor(dir);
-        return defaultWard(await DiskHarbor.marked(dir), await h.store.list());
-    }
     #held = false;
-    // `lend` is what this box lends the beings of every ward here: a name to
-    // an invitation on a being of its own ward, which `stand` puts up. A
-    // folder booted by a command lends nothing.
-    // `own` are this terrain's own class bodies, the faculty subclasses a box
-    // has: they stand in front of the built-ins, so a daemon that can ring
-    // hands its own `Push` and the dock ward boots that one.
-    constructor(dir, lend, own = {}) {
+    constructor(dir) {
         const abs = resolve(dir);
         // The key the environment gives, the edge's name for it: from the
         // Keychain through the app that spawned this daemon, or nothing on a
         // droplet, whose folder stays plain under its file modes.
-        super(new Files(abs, process.env.NERVUR_SEED_KEY), async (rec) => ({ ...BUILT_IN, ...own, ...(await loadClasses(isAbsolute(rec.code) ? rec.code : join(abs, rec.code))) }), lend);
+        // A class is keyed where it lives: the dock's under `beings/`, the
+        // folder's under the folder its source sits in, `classes/Corpus`.
+        const lookup = async (rec) => {
+            const path = isAbsolute(rec.code) ? rec.code : join(abs, rec.code);
+            return keyed({ ...BEINGS, [relative(abs, dirname(path))]: await loadClasses(path) });
+        };
+        super(new Files(abs, process.env.NERVUR_SEED_KEY), lookup);
         this.dir = abs;
     }
-    // What this box lends, by name. Set before `boot` and read there; a box
-    // that says nothing stands no ward of its own and lends nothing.
-    lent;
+    // The classes this terrain brings to its own ward, as a tree. Set before
+    // `boot` and read there; a box that brings none stands no ward of its own
+    // and lends nothing. The folder's own classes join them under the folder
+    // they live in, so an estate's faculty stands beside the terrain's.
+    faculties;
+    // What this harbor is to its faculties. The terrain raises it once the box
+    // is up, which on a daemon is after its routes are mounted.
+    box = harborageOver(() => this.wards.get(BOX_SEED)?.save() ?? Promise.resolve());
     // Create a harbor folder with one ward, and the root's setup in it: the
     // front desk, public, and one user being, with the desk holding a standing
     // to her placed by the root's knock. Boots the ward once, with no lease, to
     // do that and to learn its pk, and writes the record. Refuses a folder that
     // has one.
-    static async init(dir, name = 'main', user = 'me', cls = 'User', mark = false, shown = false) {
+    static async init(dir, name = 'main', user = 'me', cls, shown = false) {
         const h = new DiskHarbor(dir);
         if ((await h.store.list()).includes(name))
             throw new Error(`ward ${name} already exists in ${h.dir}`);
         await mkdir(join(h.dir, 'classes'), { recursive: true });
         const classes = join(h.dir, DEFAULT_CODE);
         if (!existsSync(classes))
-            await writeFile(classes, '// The classes this harbor holds beside the built-in ones. Export each one by name.\nexport {};\n');
+            await writeFile(classes, "// The classes this harbor holds beside the dock's beings. Each export is classes/<its name>.\nexport {};\n");
         const hosted = await h.create(name, user);
-        await setup(hosted, user, cls);
-        if (mark)
-            await DiskHarbor.setDefault(h.dir, name);
+        await setup(hosted, user, cls ? { home: cls } : {});
         if (shown)
             await DiskHarbor.setShown(h.dir, name, true);
         return { dir: h.dir, name, pk: hosted.pk, user };
@@ -188,13 +191,15 @@ export class DiskHarbor extends Harbor {
     // it yet would leave her holding nothing until her next birth.
     async boot() {
         await this.#lease();
-        if (this.lent)
-            this.lend = await stand(this, this.lent);
+        if (this.faculties) {
+            const tree = { ...this.faculties, [dirname(DEFAULT_CODE)]: await loadClasses(join(this.dir, DEFAULT_CODE)) };
+            await standHarbor(this, tree, this.box);
+        }
         await super.boot();
         // Every being who takes what this box lends does it at her birth, and
         // birth is synchronous while taking a standing is not. A box is up when
         // they have landed, not before.
-        await settled();
+        await settled(this);
     }
     // Every ward's writing finished, then the lease. A ward says it wrote and
     // the harbor writes it after, so a close that only dropped the lease would

package/dist/harbor/edge/alarm.d.ts

@@ -1,10 +1,12 @@
-import { Timer } from '../../dock/index.ts';
+import type { Stance } from 'nervur';
+import { Timer, type Harborage } from '../../box/index.ts';
 import type { Storage } from './platform.d.ts';
 export type Alarms = (at: number | null) => Promise<void>;
 export declare const alarmsIn: (storage: Storage) => Alarms;
 export declare class Alarm extends Timer {
     #private;
-    alarms: Alarms | undefined;
+    readonly alarms: Alarms | undefined;
+    constructor(stance: Stance, box?: Harborage, alarms?: Alarms);
     get setting(): Promise<void>;
     protected arm(when: number | null): void;
 }

package/dist/harbor/edge/alarm.js

@@ -1,17 +1,4 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box's timer on this terrain. One method of hers knows a platform, the
-// arming, and this replaces it: the object's own storage alarm in place of a
-// `setTimeout` that would die with the request. Everything else about her is
-// the same class, the same door and the same suite, because when a box wakes
-// is a terrain's answer and what it does when it wakes is not.
-//
-// One harbor is one Durable Object, and every ward of it lives in that
-// object, so the alarm wakes the whole harbor and a tick from her to a home's
-// Clock is in-process here as it is on a disk. Only the object may set its
-// own alarm, so the two calls are handed to her after the box ward stands,
-// the way the grants are handed their save: a faculty is built by her ward
-// with a stance and nothing else.
-import { Timer } from '../../dock/index.js';
+import { Timer } from '../../box/index.js';
 export const alarmsIn = (storage) => async (at) => {
     if (at === null)
         await storage.deleteAlarm();
@@ -19,10 +6,14 @@ export const alarmsIn = (storage) => async (at) => {
         await storage.setAlarm(at);
 };
 export class Alarm extends Timer {
-    // Handed in after the box ward stands. A timer holding none arms nothing
-    // and wakes nobody, which is a harbor standing no box ward.
+    // Handed at birth by the object that brings her. A timer holding none arms
+    // nothing and wakes nobody.
     alarms;
     #setting = Promise.resolve();
+    constructor(stance, box, alarms) {
+        super(stance, box);
+        this.alarms = alarms;
+    }
     // The arming written, for the device's own code and a suite: on this
     // terrain an arming is a write to storage, and a reader of the alarm waits
     // for it. It crosses no door.
@@ -30,9 +21,8 @@ export class Alarm extends Timer {
         return this.#setting;
     }
     arm(when) {
-        // A faculty arms inside whatever ask learned the moment, and a write is
-        // not something that ask can answer for, so this is left to finish on its
-        // own. An alarm the platform refused is armed again by the next round.
+        // An arming is left to finish on its own; an alarm the platform refused is
+        // armed again by the next round.
         this.#setting = (this.alarms?.(when) ?? Promise.resolve()).catch(() => { });
     }
 }

package/dist/harbor/edge/edge.d.ts

@@ -1,13 +1,11 @@
-import type { BeingClass } from 'nervur';
 import { Harbor, Socket as Held } from 'nervur/harbor';
 import { type Folder } from '../../human/web.ts';
-import { Grants } from '../../dock/grants.ts';
+import { Grants, type Harborage, type Tree } from '../../box/index.ts';
 import { type Routes } from '../../mcp/route.ts';
 import { Exchange } from '../../mcp/allow.ts';
 import { DurableStorage, danceInStorage, wearInStorage } from './storage.ts';
 import { type Deployed, type Given, type SettingsStore } from './given.ts';
 import type { State, Env } from './platform.d.ts';
-export declare const BUILT_IN: Record<string, BeingClass>;
 export declare class EdgeHarbor extends Harbor {
     #private;
     readonly sockets: Set<Held>;
@@ -20,18 +18,21 @@ export declare class EdgeHarbor extends Harbor {
     static open(state: State, env: Env, deployed?: Deployed): Promise<EdgeHarbor>;
     constructor(store: DurableStorage, root: string | undefined, deployed?: Deployed);
     given(): Promise<Given>;
-    lent: Record<string, string> | undefined;
+    faculties: Tree | undefined;
+    readonly box: Harborage & {
+        raise(): Promise<void>;
+    };
     ready(): Promise<void>;
     boot(): Promise<void>;
     rang(): Promise<void>;
-    get grants(): Grants | undefined;
+    grants(): Promise<Grants | undefined>;
     web(request: Request, path: string, base: string): Promise<Response>;
     routes(base: string): Promise<Routes & {
         quo: string;
         api: string;
     }>;
     here(): string;
-    api(request: Request, path: string, base: string): Promise<Response>;
+    api(request: Request, path: string): Promise<Response>;
     mcp(request: Request, path: string, base: string): Promise<Response>;
     wellKnown(request: Request, path: string, base: string): Promise<Response>;
     exchange(base: string): Promise<Exchange | undefined>;