nervur 0.22.2-7 → 0.23.0

package/AUTHORING.md

@@ -11,8 +11,8 @@ The shop has three classes and one faculty.
 - `Order` is one order, from its first item to its shipping.
 - `Shop` is the steward, the being that runs the house.
 - `Lobby` is the public being, which strangers may ask.
-- `Payments` is a faculty that charges money, which a maker in
-  `recipe.ts` makes.
+- `Payments` is a faculty that charges money, which `recipe.ts` holds
+  by name.
 
 ## Words
 
@@ -32,7 +32,8 @@ The shop has three classes and one faculty.
 | state | a name read from her cells that decides which asks exist |
 | house | what holds beings, keeps their cells, and seals every ask |
 | ground | the process houses run in, holding one key and sealing their seeds, faculties and secrets under it |
-| registry | code that makes faculties and bodies by name, for the ground to stand |
+| registry | code that holds faculties by name, for the ground to stand |
+| body | a faculty stood: the living instance houses and bodies use |
 
 ## A being
 
@@ -588,8 +589,8 @@ type Answer = { result: { pending: boolean } } | { error: { message: string } };
 /**
  * A payment provider in the ground's process. It answers a call id it has
  * seen with the answer it gave, so an effect sent twice charges once. A
- * provider that changes the world keeps these in the memory its maker
- * receives, where a restart and a move keep them.
+ * provider that changes the world keeps these in the memory its faculty's
+ * `up` receives, where a restart and a move keep them.
  */
 export class Payments {
   readonly #answered = new Map<string, Answer>();
@@ -619,19 +620,19 @@ export const paymentsOffer = (payments: Payments): Offer => ({ blueprint: Paymen
 
 An offer is `{ blueprint, object, kinds?, window? }`. The object answers
 each call with its call id, and one that changes the world answers a
-call id it has seen with the answer it gave. A registry holds a maker
-for each faculty by name. The ground stands a faculty when an entry names
-its maker, and the entry's `kinds` grants it to the classes it names.
-[Writing a faculty](FACULTIES.md) teaches the craft whole, with a faculty
-written in Python.
+call id it has seen with the answer it gave. A registry holds each
+faculty by name, as `{ up, install? }`. The ground raises a faculty by
+its `up` when an entry names it, and the entry's `kinds` grants it to
+the classes it names. [Writing a faculty](FACULTIES.md) teaches the
+craft whole, with a faculty written in Python.
 
 ```ts
 // recipe.ts
 import { Payments, paymentsOffer } from './payments.ts';
 
-// A registry: the ground makes each faculty an entry names, by its maker here.
+// A registry: the ground raises each faculty an entry names by its `up` here.
 export const faculties = {
-  payments: () => paymentsOffer(new Payments()),
+  payments: { up: () => paymentsOffer(new Payments()) },
 };
 ```
 
@@ -640,8 +641,8 @@ export const faculties = {
 A ground is the process houses run in, and you write none. `nervur up`
 runs one on a folder of code: a folder for each house, and each module
 your entries name. It holds one key in `state/`, and keeps every entry
-sealed in its drawer: which faculties stand, and which houses open on
-which bodies.
+sealed as the cells of its dock's beings: which faculties stand, and
+which houses open on which bodies.
 
 ### The shop's folder
 
@@ -680,29 +681,44 @@ npx nervur up .
 The ground boots in one order, and a stop is that order reversed, on an
 interrupt and on `SIGTERM`.
 
-1. **Lock.** One ground to its state.
-2. **Key.** Its key is read from `state/key`, drawn there on the first
-   start.
-3. **Drawer.** Its ledger opens, and the key opens its drawer.
-4. **Ladder.** Each faculty its drawer names stands on its registry. One
-   that fails stays down, and says why.
-5. **Houses.** Each house of the drawer opens on its bodies.
-6. **Hook.** The listeners, then the hand on its socket.
-7. **Ready.** It tells systemd it is up, where systemd waits.
-
-It is set by its environment.
-
-| Setting | What it sets |
+1. **Primordial.** Its ledger goes up and takes the lock on its state,
+   so one ground runs on it. Its unlock, crypto and tools go up. Its key
+   is read from `state/key`, drawn there on the first start.
+2. **The ground's work.** The library's `ground` faculty goes up, which
+   the dock alone reaches.
+3. **Dock.** The ground's own house opens in the ledger, under a seed
+   its key derives. Its beings hold every entry, seed, secret and
+   setting as their cells.
+4. **Ladder.** The dock's steward joins your entries to the defaults its
+   code fixes, yours winning by name. Each entry is held to what its
+   faculty takes. Each body is installed where its entry is new, and
+   goes up. One that fails stays down, and says why.
+5. **Houses.** Each house opens on its bodies, and its door joins the
+   carry.
+6. **Hand.** The hand takes its socket, and the ground tells systemd it
+   is up.
+
+Its environment names what opens its memory, its key and its hand, and
+nothing else.
+
+| Variable | What it names |
 | --- | --- |
-| `NERVUR_TCP_PORT` | its TCP port, 9110 where unset |
-| `NERVUR_HTTP_PORT` | its HTTP port, for Quo over the web and every handler; no HTTP where unset |
-| `NERVUR_ADDRESSES` | the public addresses it writes into invitations, by commas: `tcp`, `https`, `http`, `wss` or `ws` |
-| `NERVUR_ORIGINS` | the pages of other origins it answers on the web, by commas; a page of its own host needs none |
-| `NERVUR_ALLOW_PRIVATE` | `1` to dial private and loopback addresses, as two grounds on one machine do |
-| `NERVUR_BIND` | the address it listens on, `0.0.0.0` where unset |
 | `NERVUR_STATE` | its state, `state/` in its folder where unset |
 | `NERVUR_UNLOCK` | `keychain:<account>` keeps its key in the macOS keychain, in place of `state/key` |
-| `NERVUR_WAIT` | its bound on every ask, in milliseconds |
+| `NERVUR_HAND` | its hand's socket, `state/hand` where unset |
+
+Every other setting is an arg of an entry its dock keeps, set through
+the hand. Its `tcp` entry listens on every address at 9110. Its `web`
+entry serves the ground's one listener over HTTP, for Quo over the web
+and every handler, once its args name a `port`. It names that listener
+in its `faculties`. Both take `bind`, the public `addresses` written
+into invitations, and `allowPrivate` to dial loopback addresses, as two
+grounds on one machine do. `web` also takes the `origins` of pages it
+answers. `wait set` keeps its bound on every ask.
+
+```bash
+npx nervur faculties update name=web make=web faculties='["listener"]' args='{"port":8080}'
+```
 
 The state holds the key in a file its owner alone reads, and the
 ground's ledger. Every house keeps its rows in that ledger, sealed. A
@@ -714,10 +730,11 @@ lost key is a lost ground.
 
 The ladder stands once, and the ground stands it again at every start.
 The first entry stands the folder's `recipe.ts` as a registry, by the
-ground's own maker `module`. The second makes the payments from it.
+faculty `module` the folder's registry holds. The second raises the
+payments from it. An entry names only faculties that stand already.
 
 ```bash
-npx nervur faculties add name=recipe make=module args='{"at":"recipe.ts"}'
+npx nervur faculties add name=recipe from=folder make=module args='{"at":"recipe.ts"}'
 ```
 
 ```bash
@@ -727,19 +744,21 @@ npx nervur faculties add name=payments from=recipe make=payments
 A house is added once, and the ground opens it again at every start.
 
 ```bash
-npx nervur houses add name=shop classes='{"body":"folder","at":"classes"}' faculties='["payments"]'
+npx nervur houses add name=shop classes='{"faculty":"folder","at":"classes"}' faculties='["payments"]'
 ```
 
-`classes` names the body of the house's code. `folder` is the ground's
-own, and a registry may add more, a git repository among them. A house
-keeps its rows in the ground's ledger unless its entry names a `memory`
-body. `faculties` names what the house receives, and within it each
-faculty's entry names in `kinds` the classes that hold it.
+`classes` names the faculty whose body serves the house's code. `folder`
+is the ground's own, and a registry may add more, a git repository among
+them. A house keeps its rows in the ground's ledger unless its entry
+names a `memory` faculty. `faculties` names what the house receives, and
+within it each faculty's entry names in `kinds` the classes that hold
+it. `houses update` and `faculties update` land a new entry in one
+write, and `faculties restart` takes a body down and up again.
 
 A secret reaches a faculty the same way, and never through the
 environment. `npx nervur secrets set -` reads `{ name, value }` from
-standard input into the ground's sealed drawer. A faculty's entry names
-the secrets its maker receives in `secrets`.
+standard input into a being of the dock, whose cells no one reads. A
+faculty's entry names the secrets its `up` receives in `secrets`.
 
 ### The hand
 
@@ -751,8 +770,10 @@ describes.
 npx nervur help
 ```
 
-A faculty's method is called as its owner calls it, and a faculty named
-alone shows its methods. Args are one JSON object, or words `key=value`.
+Two words ask the dock, the ground's own steward, so `houses list` asks
+her `housesList`. A faculty named alone shows its methods, and a method
+after it is called through the dock. Args are one JSON object, or words
+`key=value`.
 
 ```bash
 npx nervur houses list
@@ -805,16 +826,17 @@ with `loginctl enable-linger`. On macOS, the agent goes to
 houses in a page. Every tab and the service worker of one origin share
 one ground: the one holding the Web Lock runs it, and the others reach
 its hand over a `BroadcastChannel`. When it closes, the next opens the
-ground from the same storage. `hand` answers the same three requests
-the command sends: `describe`, a faculty's method, and an ask of a being
-in a named house.
+ground from the same storage. `hand` takes the same requests the
+command sends: `describe`, and an ask of a being in a named house. A
+request that names no house asks the dock's steward, as
+`{ method: 'housesList' }`.
 
 Its bodies are the browser's. The ground's key is sealed under an AES
 key that IndexedDB holds unextractable, and its memory is IndexedDB.
-Classes load from the page's own origin through the `origin` body, `{
-body: 'origin', at: '/house/index.js' }`, and a path off the origin is
-refused. The registry is the object you pass: makers of faculties, and
-of any custom body, beside the terrain's own.
+Classes load from the page's own origin through the `origin` faculty, `{
+faculty: 'origin', at: '/house/index.js' }`, and a path off the origin
+is refused. The registry is the object you pass: faculties by name,
+foundation and custom alike, beside the terrain's own.
 
 Any script on the origin can use the ground's keys, so the ground is
 whoever serves the origin's script. Give it an origin of its own, serve
@@ -841,7 +863,7 @@ app's web view, on two interfaces the shell fills in native code:
 The library holds the rest. The ground's key goes into the secret store,
 and its memory into the native store, which the system never evicts as
 it may a web view's storage. A push token reaches the ground through a
-faculty your registry makes.
+faculty your registry holds.
 
 ## What the house guarantees
 
@@ -899,7 +921,15 @@ at her call, or where an ask arrives.
 - A call on the house beside `House.open`, `door` and `ask`.
 - A faculty in a house's code. Faculties are the ground's.
 - A drawer opened with a key that did not seal it.
-- A secret read by a being, a describe or anyone but a maker its entry
-  names.
-- A faculty entry for `secrets` or `moves`, which the hand alone reaches.
+- A secret read by a being, a describe or anyone but a faculty whose
+  entry names it.
+- A faculty raised any way but its `up`, foundation or custom.
+- An entry named `dock`, for a house or a faculty. The dock is the
+  library's.
+- A secret or a move asked by anyone but the hand.
+- A grant naming a faculty or a secret the ground does not hold.
+- A secret's cells read through the hand.
+- An entry naming, making or granting `ground` or `shell`. Both are the
+  dock's alone.
+- A second ground on the state one runs on.
 - A ground an owner must write. Each terrain's ships.

package/COMMAND.md

@@ -17,11 +17,11 @@ alone reads.
 npx nervur up .
 ```
 
-The ground stops cleanly on an interrupt and on `SIGTERM`. It takes a
-lock on its state, so a second `nervur up` on the same folder refuses to
-start. Keep `state/` as you keep an ssh key: whoever holds its key and
-its ledger holds the ground, and without the key the ledger opens
-nothing.
+The ground stops cleanly on an interrupt and on `SIGTERM`. Its ledger
+holds a lock on its state while it stands, so a second `nervur up` on
+the same folder refuses to start. Keep `state/` as you keep an ssh key:
+whoever holds its key and its ledger holds the ground, and without the
+key the ledger opens nothing.
 
 `nervur service` prints what keeps the ground running across reboots: a
 systemd unit on Linux, a launchd job on macOS. Nothing is installed; you
@@ -33,20 +33,38 @@ npx nervur service /srv/shop
 
 ## Settings
 
-A ground reads its settings from the environment.
+The environment names only what opens the ground's memory, its key and
+its hand.
 
-| Setting | What it sets |
+| Variable | What it names |
 | --- | --- |
 | `NERVUR_STATE` | the state folder, `state/` in the ground's folder where unset |
-| `NERVUR_TCP_PORT` | the TCP port Quo listens on, 9110 where unset |
-| `NERVUR_HTTP_PORT` | the port of the web listener, which faces and Quo over the web share; none where unset |
-| `NERVUR_BIND` | the address both listen on, every interface where unset |
-| `NERVUR_ADDRESSES` | the public addresses written into invitations, by commas |
-| `NERVUR_ORIGINS` | the page origins the web listener answers, by commas |
-| `NERVUR_ALLOW_PRIVATE` | `1` to let the ground dial a private or loopback address |
 | `NERVUR_UNLOCK` | on macOS, `keychain:<account>` keeps the key in the keychain in place of `state/key` |
 | `NERVUR_HAND` | where the hand's socket is, `state/hand` where unset; a relative path is read from where the command runs |
-| `NERVUR_WAIT` | the longest any ask may run, in milliseconds |
+
+Every other setting is an entry the ground's dock keeps, set through the
+hand and kept across a restart. The `tcp` entry listens on the loopback
+at 9110 until you name another bind, and the `web` entry listens on no
+port until one is named. The web serves the ground's one listener,
+which its entry names in `faculties`.
+
+| Arg | Of | What it sets |
+| --- | --- | --- |
+| `port` | `tcp`, `web` | the port it listens on; with none, it only dials |
+| `bind` | `tcp`, `web` | the address it listens on, every interface where unset |
+| `addresses` | `tcp`, `web` | the public addresses written into invitations |
+| `origins` | `web` | the page origins the web listener answers |
+| `allowPrivate` | `tcp`, `web` | `true` to let the ground dial a private or loopback address |
+
+```bash
+npx nervur faculties update name=web make=web faculties='["listener"]' args='{"port":8080,"addresses":["https://shop.example/quo"]}'
+npx nervur wait set wait=30000
+```
+
+`faculties catalog` prints every faculty the ground can raise and what
+each takes, so an entry it refuses says which arg failed. `wait set`
+keeps the longest any ask may run, in milliseconds, and `wait show`
+prints it.
 
 A ground that people reach names its public addresses. Without them, it
 writes only the addresses it listens on, which a stranger cannot reach.
@@ -62,22 +80,31 @@ Every other word goes to the ground's hand, a socket in `state/` that
 your user alone may open. Run the command in the ground's folder, or
 name the socket with `--at <socket>` or `NERVUR_HAND`.
 
-`help` prints what the ground holds: each faculty with its methods, or
-why it is down, and each house.
+`help` prints what the ground holds: the asks of its dock, each faculty
+with its methods or why it is down, and each house.
 
 ```bash
 npx nervur help
 ```
 
-A faculty is called by its name and a method. Named alone, it prints its
-methods. Four faculties are the ground's own. `secrets` keeps a secret
-in the ground's sealed drawer. `faculties` stands a faculty on the maker
-its entry names, and `houses` opens a house on its entry.
+The dock is the ground's own house, and its steward changes the ground.
+Two words ask her, so `houses add` asks `housesAdd`. One word alone
+prints the asks it begins. `secrets set` keeps a secret in a being of
+the dock, whose cells no one reads. `faculties add` raises a faculty by
+the `up` its entry names, and `houses add` opens a house on its entry.
+Each answers why the body is down or the house closed, where it is.
+Each `update` lands a new entry in one write, and `faculties restart`
+takes a body down and up again. A faculty named with a method is called
+through the dock, and named alone it prints its methods.
+
+An entry names only faculties and secrets the ground holds already. A
+module and a program stand on the folder's registry, so their entries
+say `from=folder`.
 
 ```bash
-npx nervur faculties add name=recipe make=module args='{"at":"recipe.ts"}'
+npx nervur faculties add name=recipe from=folder make=module args='{"at":"recipe.ts"}'
 npx nervur faculties add name=payments from=recipe make=payments secrets='["stripe-key"]'
-npx nervur houses add name=main classes='{"body":"folder","at":"house"}' faculties='["payments"]'
+npx nervur houses add name=main classes='{"faculty":"folder","at":"house"}' faculties='["payments"]'
 ```
 
 `ask` asks a being of a house, as the house's owner. `--id <being>` names
@@ -96,6 +123,22 @@ repair, or a look at what her asks do not show.
 npx nervur ask main --cells
 ```
 
+`ask dock` asks the dock's own beings, since no house takes that name.
+`faculty.<name>`, `house.<name>` and the steward hold every entry, seed
+and setting, and a secret's cells are shown to no one.
+
+```bash
+npx nervur ask dock --id faculty.web --cells
+```
+
+`shell run` runs a command on the ground's machine, in its code folder,
+and prints its exit code and what it printed. The words after `--` are
+the command line. Its environment holds nothing of the ground's.
+
+```bash
+npx nervur shell run -- git status
+```
+
 The command asks no watch. A watch is held by a being on her standing,
 or by a page through a face, where something waits on its answer.
 
@@ -116,6 +159,14 @@ secret never stands on a command line or in a shell's history.
 npx nervur secrets set - < stripe-key.json
 ```
 
+`--call <id>`, before the words, names the ask's call id. The same ask
+sent again with the same id answers what the first answered, and runs
+nothing twice. So a script that lost an answer sends its ask again.
+
+```bash
+npx nervur --call deploy-42 houses update name=main classes='{"faculty":"folder","at":"house"}'
+```
+
 Each word prints one JSON value, the answer, and its exit code says what
 came back.
 

package/FACES.md

@@ -106,11 +106,12 @@ tries again acts once.
 
 ```ts
 // api.ts
-import type { Faculty, FacultyContext, Handler } from 'nervur';
+import type { Body, FacultyContext, Handler } from 'nervur';
 import { need, s, type Json } from 'nervur/being';
 
 type Answer = Awaited<ReturnType<FacultyContext['call']>>;
 type Entry = { method: string; description?: string; args?: Json; hints?: Json };
+type Calls = Pick<FacultyContext, 'call' | 'describe'>;
 
 /** What the steward arms the face with. */
 export const FaceBlueprint = need('face', {
@@ -124,9 +125,8 @@ export const FaceBlueprint = need('face', {
  * asks to an agent as tools.
  */
 export class Api {
-  #context: FacultyContext | undefined;
+  #context: Calls | undefined;
   #signup = '';
-  #calls = 0;
 
   arm({ signup }: { signup: string }, context: FacultyContext): Promise<Answer> {
     this.#context = context;
@@ -134,14 +134,19 @@ export class Api {
     return Promise.resolve({ result: null });
   }
 
-  #held(): FacultyContext {
+  // Told its house opened: every door's token answers from the first request, after any restart.
+  opened(context: Calls): void {
+    this.#context = context;
+  }
+
+  #held(): Calls {
     if (this.#context === undefined) throw new Error('the face is not armed');
     return this.#context;
   }
 
-  // Each call its own id, so a call the house retries acts once.
+  // Each call an id drawn afresh, so no life of the face repeats one.
   #ask(token: string, method: string, args: Json): Promise<Answer> {
-    return this.#held().call({ token, method, args, id: `api:${++this.#calls}` });
+    return this.#held().call({ token, method, args, id: `api:${crypto.randomUUID()}` });
   }
 
   async #tools(token: string): Promise<Json> {
@@ -179,8 +184,8 @@ export class Api {
   };
 }
 
-/** The offer a ground hands: the blueprint, the object, and its handler on the ground's listener. */
-export const apiOffer = (api: Api): Faculty => ({ blueprint: FaceBlueprint, object: api, handler: api.handler });
+/** The face as a body. */
+export const apiOffer = (api: Api): Body => ({ blueprint: FaceBlueprint, object: api, handler: api.handler, opened: (context) => api.opened(context) });
 ```
 
 **The describe maps onto tools by renaming.** An ask is a tool, its
@@ -190,24 +195,24 @@ tools.
 
 ## The registry
 
-The ground makes the face from a registry, as it makes any faculty. A
-NodeGround stands the module below with the maker `module`, and the
-face from it by an entry that names `from`. The house's entry names
-`face` among its faculties, and the steward's `arm` hands the face its
-signup.
+The ground raises the face from a registry by its `up`, as it raises any
+faculty. A NodeGround stands the module below with the faculty
+`module`, and the face from it by an entry that names `from`. The
+house's entry names `face` among its faculties, and the steward's `arm`
+hands the face its signup.
 
 ```ts
 // recipe.ts
 import { Api, apiOffer } from './api.ts';
 
-// A registry: the ground makes the face when an entry names its maker.
+// A registry: the ground raises the face by its `up` when an entry names it.
 export const faculties = {
-  face: () => apiOffer(new Api()),
+  face: { up: () => apiOffer(new Api()) },
 };
 ```
 
 ```bash
-npx nervur faculties add name=recipe make=module args='{"at":"recipe.ts"}'
+npx nervur faculties add name=recipe from=folder make=module args='{"at":"recipe.ts"}'
 npx nervur faculties add name=face from=recipe make=face
 ```
 
@@ -229,7 +234,7 @@ import { faculties } from './recipe.ts';
 test('A person signs up at the face, and reaches their member as an API and as tools', async (t) => {
   const ground = await BenchGround.open({ network: new FakeNetwork(), host: 'desk', modules: { desk }, registry: { faculties } });
   t.after(() => ground.down());
-  await ground.hand({ faculty: 'faculties', method: 'add', args: { name: 'face', make: 'face' } });
+  await ground.hand({ method: 'facultiesAdd', args: { name: 'face', make: 'face' } });
   await ground.add('desk', 'desk', { faculties: ['face'] });
   await ground.ask({ house: 'desk', method: 'arm' });
   const web = async (path: string, body?: unknown, token?: string) =>