nervur 0.20.0 → 0.20.1

package/README.md

@@ -23,9 +23,12 @@ a disk and needs Node's file system.
 ```js
 import { Being, Faculty, World } from 'nervur';
 
-// A contract, and a faculty that fulfils it.
-class Clock extends Faculty {}
+// A contract, and a faculty that fulfils it. Every class names its kind.
+class Clock extends Faculty {
+  static kind = 'org.example.clock';
+}
 class SystemTime extends Clock {
+  static kind = 'org.example.system-time';
   static asks = { now: {} };
   now() {
     return { now: Date.now() };
@@ -34,6 +37,7 @@ class SystemTime extends Clock {
 
 // A being, who lends a clock by its contract.
 class Greeter extends Being {
+  static kind = 'org.example.greeter';
   static asks = { hello: {} };
   async hello(args, asker) {
     if (!this.stance.standings.get('clock')) await this.stance.lend(Clock, 'clock');
@@ -42,42 +46,125 @@ class Greeter extends Being {
   }
 }
 
+// The module these classes are: its name, its version, its classes.
+const greetings = { module: 'org.example.greetings', version: '1.0.0', classes: [SystemTime, Greeter] };
+
+// A harbor whose terrain can load that module, and whose catalogue runs it.
 const world = new World();
-const harbor = await world.harbor('home', [SystemTime, Greeter]);
-await harbor.root('open', { key: 'clock', class: 'SystemTime' });
+const harbor = await world.harbor('home', [greetings]);
+await harbor.root('ask', { being: 'catalogue', method: 'add', args: { from: 'org.example.greetings' } });
+await harbor.root('open', { key: 'clock', class: 'org.example.system-time' });
 await harbor.root('host', { ward: 'alice' });
-await harbor.ward('alice').root('boot', { key: 'greeter', class: 'Greeter' });
+await harbor.ward('alice').root('boot', { key: 'greeter', class: 'org.example.greeter' });
 ```
 
 A second harbor in the same world takes an invitation on the greeter and
 asks it through the world, sealed as Quo's bytes. `world.restart('home')`
 opens the harbor again from what its memory kept.
 
+## Kinds
+
+A row keeps the kind of the class a being is born of, and a being lends
+by a contract's kind. A kind is declared on the class, because a bundler
+renames classes. It is a domain you own, reversed, then a name, as Apple
+and Matrix name things: `com.acme.shop`. Every segment is lowercase
+letters, digits and `-`, and there are three at least. Each class
+declares its own: a subclass that stands, and every contract between a
+faculty and `Faculty`. `org.nervur.` is the kit's, and `org.example.` is
+for examples like the one above. A module's classes stand under its own
+domain: `com.acme.shop` stands `com.acme.*` kinds. A harbor refuses a
+module in which one kind names two classes or two contracts, or names a
+class and a contract.
+
+## Modules
+
+Your classes come in modules: `{ module, version, classes }`, a module
+named as a kind is. A harbor's catalogue is a faculty of its own, and her
+cells name the modules the harbor runs. `add { from }` runs the module
+the terrain's loader finds there, and `remove { module }` stops one no
+being stands on. A restart loads every module she names and refuses to
+stand when one is missing. A module found at a new version wakes, and
+`modules` shows the version kept and the version running.
+
 ## The onion
 
-1. The terrain gives the box ward's seed and memory.
-2. The box ward unpacks, its ward-being the dock.
-3. Its faculties are born from their rows.
-4. Every ward the dock hosts unpacks.
-5. In every ward, the ward-being first, then each being from her row.
+A harbor is one package. Only the seed and the terrain's bodies, its
+loader among them, stand outside it.
+
+1. The terrain gives the harbor's seed, which opens its memory. The
+   terrain keeps that memory as sealed bytes and reads none of it.
+2. The box ward unpacks under the seed, its ward-being the dock.
+3. The catalogue wakes, and loads every module she names.
+4. The other faculties are born from their rows.
+5. The routes the dock keeps are handed to the carrier.
+6. Every ward the dock hosts unpacks, under the seed the dock keeps for it.
+7. In every ward, the ward-being first, then each being from her row.
 
-Cells decide what stands. The classes you hand a harbor only resolve a
-name a row keeps. Opening a harbor on empty memory is its genesis, and
-the root's asks write the rest: `open`, `host`, and `boot` on a ward.
+Cells decide what stands. The modules only resolve a kind a row keeps.
+Opening a harbor on empty memory is its genesis: the dock stands the
+catalogue, and the root's asks write the rest: `add` on the catalogue,
+`open`, `host`, `route`, and `boot` on a ward. `host { ward, seed? }`
+stands a ward under a seed you name, or a drawn one.
 
 ## What it holds
 
 - **Being, Faculty.** What you extend. A faculty's contract is its class
   and every class between it and `Faculty`.
-- **Entropy, Clock, Custody, Memory, Carrier.** The contracts a terrain
-  fulfils. Each has one suite, and every body that fulfils it passes it.
-- **Harbor, Terrain, Registry, Dock, WardBeing.** The onion.
-- **World, PointerTerrain** and the pointer bodies. A whole world with
-  this package alone.
+- **Entropy, Clock, Custody, Memory, Carrier, Loader.** The contracts a
+  terrain fulfils. Each has one suite, and every body that fulfils it
+  passes it.
+- **Harbor, Terrain, Dock, Catalogue, Registry, WardBeing.** The onion.
+- **World, PointerTerrain** and the pointer bodies, `HeldLoader` among
+  them. A whole world with this package alone.
 - **FolderMemory, FolderCustody**, from `nervur/folder`.
+- **TcpCarrier, TcpListener**, from `nervur/tcp`: Quo over TCP. Route a
+  ward pk to `host:port` on the carrier, hand the listener your harbor,
+  and harbors in two processes, or a harbor and another kit, speak.
+
+Other carriers, storage beyond a folder, key custody, and every screen
+are `@nervur-org/dock`'s, as classes fulfilling these contracts.
+
+## The command
+
+`nervur` stands a harbor on this machine: its seed and sealed memory in a
+folder, Quo over TCP as its carrier. A module is a file that exports
+`module`, `version` and `classes`.
+
+```sh
+nervur init  --dir ./harbor
+nervur module add ./greetings.js --dir ./harbor
+nervur serve --dir ./harbor --port 7000
+nervur host alice --dir ./harbor
+nervur boot --ward alice greeter org.example.greeter --dir ./harbor
+nervur route <ward pk> host:port --dir ./harbor
+nervur ask --ward alice greeter hello --dir ./harbor
+```
+
+`init` makes the harbor and prints its pk and an owner invitation. `serve`
+listens for Quo on TCP and for the root's asks on a local socket, open to
+you alone. Every other command is one root ask, sent to the served
+harbor, or answered from the folder when none is served. Each prints one
+JSON line. `--dir` defaults to `$NERVUR_DIR`, then `~/.nervur`. The
+catalogue keeps a module by its file's absolute path, and routes live in
+the harbor like everything else, so a restart finds both. `nervur
+modules` shows what runs, and `nervur module remove <module>` stops one.
+
+A harbor elsewhere is piloted with the owner invitation its `init`
+printed, from a harbor of your own:
+
+```sh
+nervur pilot far '<owner invitation>' host:port --dir ./mine
+nervur host shop --via far --dir ./mine
+```
+
+`pilot` boots an `org.nervur.pilot` being in your harbor that holds the
+invitation as an ordinary Quo relation, kept in your harbor's memory. With
+`--via far`, any command is asked of the far harbor as its owner, sealed
+over TCP, except `own` and `disown`, which stay the far root's.
+`nervur unboot far` lets it go.
 
-Carriers over a network, storage beyond a folder, key custody, and every
-screen are `@nervur-org/dock`'s, as classes fulfilling these contracts.
+`rootLine(harbor, request)` is the same request in code, for any other
+front: `{ ward?, method?, args? }` in, one JSON answer out.
 
 ## License
 

package/dist/being/being.d.ts

@@ -5,6 +5,7 @@ export type AskSpec = {
     readonly for?: (asker: Asker, notes: JsonObject | undefined) => boolean;
 };
 export declare class Being {
+    static readonly kind: string;
     static cells: JsonObject;
     static asks: Record<string, AskSpec>;
     readonly stance: Stance;

package/dist/being/being.js

@@ -9,8 +9,12 @@ const wrote = (self, name) => {
     return false;
 };
 // A subclass's statics replace its parent's and never merge: her blueprint
-// is what the class in front of you declares, in its order.
+// is what the class in front of you declares, in its order. Her kind is
+// never inherited: see `kind.ts`.
 export class Being {
+    // The name her row keeps for this class. Every class that stands declares
+    // its own.
+    static kind = 'org.nervur.being';
     // Her cells' defaults, written at birth only where a key is missing.
     static cells = {};
     static asks = {};

package/dist/being/faculty.d.ts

@@ -2,6 +2,7 @@ import { Being } from './being.ts';
 import { type Asker, type Blueprint, type JsonObject, type Reply } from './types.ts';
 export declare class Faculty extends Being {
     #private;
+    static readonly kind: string;
     static contracts(C: abstract new (...args: never[]) => unknown): string[];
     static fulfils(C: unknown): C is typeof Faculty;
     describe(asker: Asker): Blueprint;

package/dist/being/faculty.js

@@ -2,23 +2,29 @@
 // A faculty: a being of the box ward that fulfils a contract. A contract is
 // a class between `Faculty` and the class that stands, usually abstract:
 //
-//   abstract class Timer extends Faculty { ... }     the contract
-//   class IntervalTimer extends Timer { ... }        one class that fulfils it
+//   abstract class Timer extends Faculty {           the contract
+//     static override kind = 'com.acme.timer' }
+//   class IntervalTimer extends Timer {              one class that fulfils it
+//     static override kind = 'com.acme.interval-timer' }
 //
-// A being lends by the contract and never learns the class. Two asks are the
+// A being lends by the contract's kind and never learns the class. Every
+// class between the faculty and `Faculty` is a contract and declares its
+// own kind, and a faculty fulfils each of them and her own. Two asks are the
 // faculty's own and answered to the ward-being that opened her alone:
 // `offer`, an invitation on herself for a ward the dock vouches for, and
 // `retract`, an offer that was not taken.
 import { Being } from './being.js';
+import { kindOf } from './kind.js';
 import { WARD } from './types.js';
 export class Faculty extends Being {
+    static kind = 'org.nervur.faculty';
     // The contracts a class fulfils: itself and every class between it and
-    // `Faculty`, by name.
+    // `Faculty`, by kind. A class among them with no kind of its own throws.
     static contracts(C) {
-        const names = [];
+        const kinds = [];
         for (let c = C; typeof c === 'function' && c !== Faculty; c = Object.getPrototypeOf(c))
-            names.push(c.name);
-        return names;
+            kinds.push(kindOf(c));
+        return kinds;
     }
     static fulfils(C) {
         return typeof C === 'function' && C.prototype instanceof Faculty;

package/dist/being/index.d.ts

@@ -1,5 +1,6 @@
 export { Being, type AskSpec } from './being.ts';
 export { canonical, digest } from './digest.ts';
 export { Faculty } from './faculty.ts';
+export { isKind, KIT, kindOf, ownKind } from './kind.ts';
 export { OWNER, WARD, type Answer, type Ask, type Asker, type BeingClass, type BeingLike, type Blueprint, type Invitation, type Json, type JsonObject, type Occupants, type Reply, type Schema, type Stance, type Standing, type Standings, type Wanted } from './types.ts';
 export { isSilence, isWord, silence, told, word, type Silence, type Word, type WordName } from './words.ts';

package/dist/being/index.js

@@ -3,5 +3,6 @@
 export { Being } from './being.js';
 export { canonical, digest } from './digest.js';
 export { Faculty } from './faculty.js';
+export { isKind, KIT, kindOf, ownKind } from './kind.js';
 export { OWNER, WARD } from './types.js';
 export { isSilence, isWord, silence, told, word } from './words.js';

package/dist/being/kind.d.ts

@@ -0,0 +1,4 @@
+export declare const KIT = "org.nervur.";
+export declare const isKind: (text: unknown) => text is string;
+export declare const ownKind: (C: unknown) => string | undefined;
+export declare const kindOf: (C: unknown) => string;

package/dist/being/kind.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// A kind: the name a row keeps for the class a being is born of, and the
+// name a contract is lent by. It is declared on the class, never taken from
+// the name the language gives it, because a bundler renames classes.
+//
+//   static kind = 'com.acme.shop'
+//
+// A kind is a reversed domain its author owns, then a name: at least three
+// segments joined by `.`, each lowercase letters, digits and `-`, starting
+// with a letter or digit. `org.nervur.` is the kit's own. A class declares
+// its own kind: one it inherits names its parent, so it is none.
+export const KIT = 'org.nervur.';
+const KIND = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*){2,}$/;
+export const isKind = (text) => typeof text === 'string' && KIND.test(text);
+// The kind a class declares on itself, or undefined.
+export const ownKind = (C) => {
+    if (typeof C !== 'function' || !Object.hasOwn(C, 'kind'))
+        return undefined;
+    const kind = C.kind;
+    return isKind(kind) ? kind : undefined;
+};
+// The kind a class declares on itself, or a throw naming the class.
+export const kindOf = (C) => {
+    const kind = ownKind(C);
+    if (kind === undefined)
+        throw new Error(`class ${typeof C === 'function' ? C.name : String(C)} declares no kind of its own`);
+    return kind;
+};

package/dist/being/types.d.ts

@@ -48,10 +48,8 @@ export interface Stance {
     readonly cells: JsonObject;
     readonly occupants: Occupants;
     readonly standings: Standings;
-    boot(className: string, key: string, id?: string): Promise<string | null>;
-    lend(contract: {
-        readonly name: string;
-    }, id: string): Promise<string | null>;
+    boot(kind: string, key: string, id?: string): Promise<string | null>;
+    lend(contract: abstract new (...args: never[]) => unknown, id: string): Promise<string | null>;
 }
 export interface BeingLike {
     answer(asker: Asker, method: string | undefined, args: JsonObject): Reply | Promise<Reply>;
@@ -59,4 +57,5 @@ export interface BeingLike {
 }
 export type BeingClass = (new (stance: Stance) => BeingLike) & {
     readonly name: string;
+    readonly kind: string;
 };

package/dist/cli/command.d.ts

@@ -0,0 +1,13 @@
+import type { JsonObject } from '../being/index.ts';
+import type { RootRequest } from '../harbor/index.ts';
+export declare const parse: (argv: string[]) => {
+    command?: string;
+    words: string[];
+    flags: Record<string, string>;
+};
+export declare const requestOf: (command: string, words: string[], flags: Record<string, string>) => RootRequest;
+export declare const main: (argv: string[], env: Record<string, string | undefined>, print: (line: string) => void) => Promise<number>;
+export declare const pilotRequests: (name: string, invitation: JsonObject, at: string) => RootRequest[];
+export declare const via: (pilot: string, far: RootRequest) => RootRequest;
+export declare const farAnswer: (local: JsonObject) => JsonObject;
+export declare const SERVING = -1;

package/dist/cli/command.js

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur`: a harbor on this machine. Each command is one root request, the
+// same the root line carries from any front, printed as one JSON line.
+//
+//   nervur init   [--dir D]                         the harbor made: its seed drawn,
+//                                                   its catalogue stood, and an owner
+//                                                   invitation for whoever made it
+//   nervur serve  [--dir D] [--host H] [--port P]   the harbor served: Quo over TCP,
+//                                                   and the root line on its socket
+//   nervur module add <file>                        a module the catalogue runs
+//   nervur module remove <module>                   a module it runs no more
+//   nervur modules                                  what the catalogue runs
+//   nervur census [--ward W]                        the empty ask
+//   nervur open   <key> <kind>                      a faculty stands in the box ward
+//   nervur host   <ward> [--seed S]                 a hosted ward stands
+//   nervur route  <ward pk> <host:port | none>      where a ward is reached
+//   nervur boot   [--ward W] <key> <kind>           a being stands
+//   nervur unboot [--ward W] <being>                a being goes
+//   nervur public [--ward W] <key | none>           the being a stranger reaches
+//   nervur invite [--ward W] <being> <id>           an invitation on a being
+//   nervur ask    [--ward W] [being] [method] [args] a being, asked as the owner
+//   nervur own    [--ward W] <id>                   an invitation for an owner
+//   nervur disown [--ward W] <id>                   an owner no more
+//   nervur pilot  <name> <invitation> <host:port>   a far ward held as its owner, by a
+//                                                   pilot being of the box ward
+//   nervur <command> --via <name> ...               the command asked of the far ward
+//                                                   that pilot holds, as its owner
+//
+// D is --dir, then $NERVUR_DIR, then ~/.nervur. A module file is named from
+// where the command runs and kept by its absolute path. No --ward is the box
+// ward, and a pilot holds one ward, so --via takes no --ward. The exit is 1
+// when the answer is an error.
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { open, request, serve } from './harbor.js';
+const USAGE = 'usage: nervur <init|serve|module|modules|census|open|host|route|boot|unboot|public|invite|ask|own|disown|pilot> [args] [--dir D] [--ward W] [--via V] [--seed S] [--host H] [--port P]';
+const FLAGS = new Set(['dir', 'ward', 'via', 'seed', 'host', 'port']);
+export const parse = (argv) => {
+    const flags = {};
+    const words = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const name = arg.startsWith('--') ? arg.slice(2) : undefined;
+        if (name === undefined)
+            words.push(arg);
+        else if (!FLAGS.has(name) || argv[i + 1] === undefined)
+            throw new Error(`--${name} is no flag with a value`);
+        else
+            flags[name] = argv[(i += 1)];
+    }
+    const [command, ...rest] = words;
+    return { ...(command === undefined ? {} : { command }), words: rest, flags };
+};
+const none = (word) => (word === 'none' ? null : word);
+const json = (word) => (word === undefined ? undefined : JSON.parse(word));
+const catalogue = (method, args = {}) => ({ method: 'ask', args: { being: 'catalogue', method, args } });
+// The root request a command names, or a throw saying what it lacks.
+export const requestOf = (command, words, flags) => {
+    const need = (n) => {
+        if (words.length !== n)
+            throw new Error(`${command} takes ${n} argument${n === 1 ? '' : 's'}`);
+        return words;
+    };
+    const at = flags.ward === undefined ? {} : { ward: flags.ward };
+    switch (command) {
+        case 'module': {
+            const [verb, what] = need(2);
+            if (verb === 'add')
+                return catalogue('add', { from: resolve(what) });
+            if (verb === 'remove')
+                return catalogue('remove', { module: what });
+            throw new Error('module is add or remove');
+        }
+        case 'modules':
+            return (need(0), catalogue('modules'));
+        case 'census':
+            return (need(0), at);
+        case 'open': {
+            const [key, kind] = need(2);
+            return { method: 'open', args: { key: key, class: kind } };
+        }
+        case 'host': {
+            const [ward] = need(1);
+            return { method: 'host', args: { ward: ward, ...(flags.seed === undefined ? {} : { seed: flags.seed }) } };
+        }
+        case 'route': {
+            const [ward, where] = need(2);
+            return { method: 'route', args: { ward: ward, at: none(where) } };
+        }
+        case 'boot': {
+            const [key, kind] = need(2);
+            return { ...at, method: 'boot', args: { key: key, class: kind } };
+        }
+        case 'unboot':
+            return { ...at, method: 'unboot', args: { being: need(1)[0] } };
+        case 'public':
+            return { ...at, method: 'public', args: { key: none(need(1)[0]) } };
+        case 'invite': {
+            const [being, id] = need(2);
+            return { ...at, method: 'invite', args: { being: being, id: id } };
+        }
+        case 'ask': {
+            if (words.length > 3)
+                throw new Error('ask takes at most a being, a method and its args');
+            const [being, method, args] = words;
+            return { ...at, method: 'ask', args: { ...(being === undefined ? {} : { being }), ...(method === undefined ? {} : { method }), ...(args === undefined ? {} : { args: json(args) }) } };
+        }
+        case 'own':
+        case 'disown':
+            return { ...at, method: command, args: { id: need(1)[0] } };
+        default:
+            throw new Error(USAGE);
+    }
+};
+// An error answer at any depth the root line or an ask carries it.
+const failed = (answer) => {
+    if (typeof answer !== 'object' || answer === null)
+        return false;
+    const a = answer;
+    return 'error' in a || failed(a.answer);
+};
+export const main = async (argv, env, print) => {
+    const { command, words, flags } = parse(argv);
+    if (command === undefined)
+        throw new Error(USAGE);
+    const dir = flags.dir ?? env.NERVUR_DIR ?? join(homedir(), '.nervur');
+    const out = (answer) => {
+        print(JSON.stringify(answer));
+        return failed(answer) ? 1 : 0;
+    };
+    if (command === 'init') {
+        if (words.length > 0)
+            throw new Error('init takes no argument');
+        if (existsSync(join(dir, 'seed')))
+            return out({ error: `a harbor stands at ${dir}` });
+        const { harbor, carrier } = await open(dir);
+        try {
+            const owner = await harbor.root('own', { id: 'owner' });
+            return out({ pk: harbor.box.pk, owner: owner });
+        }
+        finally {
+            await carrier.close();
+        }
+    }
+    if (command === 'serve') {
+        if (words.length > 0)
+            throw new Error('serve takes no argument');
+        const served = await serve(dir, flags.host, flags.port === undefined ? undefined : Number(flags.port));
+        const stop = () => void served.close().then(() => process.exit(0));
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        print(JSON.stringify({ pk: served.pk, at: served.at, root: served.root }));
+        return SERVING;
+    }
+    if (command === 'pilot') {
+        if (words.length !== 3)
+            throw new Error('pilot takes 3 arguments');
+        const [name, invitation, at] = words;
+        const held = JSON.parse(invitation);
+        for (const req of pilotRequests(name, held, at)) {
+            const answer = await request(dir, req);
+            if (!failed(answer))
+                continue;
+            if (req.method === 'ask')
+                await request(dir, { method: 'unboot', args: { being: name } });
+            return out(answer);
+        }
+        return out({ piloting: name, ward: held.ward });
+    }
+    if (flags.via === undefined)
+        return out(await request(dir, requestOf(command, words, flags)));
+    if (flags.ward !== undefined)
+        throw new Error('--via takes no --ward');
+    return out(farAnswer(await request(dir, via(flags.via, requestOf(command, words, flags)))));
+};
+// The root requests that hold a far ward: its route, the pilot, the take.
+export const pilotRequests = (name, invitation, at) => [
+    { method: 'route', args: { ward: invitation.ward ?? null, at } },
+    { method: 'boot', args: { key: name, class: 'org.nervur.pilot' } },
+    { method: 'ask', args: { being: name, method: 'hold', args: { invitation } } },
+];
+// A root request, asked of the far ward a pilot holds.
+export const via = (pilot, far) => ({
+    method: 'ask',
+    args: { being: pilot, method: 'pilot', args: { ...(far.method === undefined ? {} : { method: far.method }), ...(far.args === undefined ? {} : { args: far.args }) } },
+});
+// The far ward-being's answer out of the pilot's, or the local error.
+export const farAnswer = (local) => {
+    const inner = local.answer?.answer;
+    return typeof inner === 'object' && inner !== null && !Array.isArray(inner) ? inner : local;
+};
+// What `main` answers for a harbor it keeps serving: no exit yet.
+export const SERVING = -1;

package/dist/cli/harbor.d.ts

@@ -0,0 +1,21 @@
+import type { JsonObject } from '../being/index.ts';
+import { Loader, type Loaded } from '../contract/index.ts';
+import { Harbor, type RootRequest } from '../harbor/index.ts';
+import { TcpCarrier } from '../tcp/index.ts';
+export declare const socketOf: (dir: string) => string;
+export declare class ImportLoader extends Loader {
+    load(from: string): Promise<Loaded | null>;
+}
+export type Opened = {
+    harbor: Harbor;
+    carrier: TcpCarrier;
+};
+export declare const open: (dir: string) => Promise<Opened>;
+export declare const request: (dir: string, req: RootRequest) => Promise<JsonObject>;
+export type Served = {
+    pk: string;
+    at: string;
+    root: string;
+    close(): Promise<void>;
+};
+export declare const serve: (dir: string, host?: string, port?: number) => Promise<Served>;