nervur 0.22.2-8 → 0.23.0

package/AUTHORING.md

@@ -641,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
 
@@ -681,31 +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. **Primordial.** Its unlock, its ledger, crypto and tools go up. Its
-   key is read from `state/key`, drawn there on the first start.
-3. **Drawer.** The key opens its drawer in the ledger.
-4. **Entries.** The drawer's entries join the defaults its environment
-   gives, the drawer's winning by name.
-5. **Ladder.** Each body is installed where its entry is new, and goes
-   up. One that fails stays down, and says why.
-6. **Houses.** Each house of the drawer opens on its bodies, and its
-   door joins the carry.
-7. **Ready.** The hand takes its socket, and it tells systemd it is up.
-
-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
@@ -717,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 faculty `module`. The second raises 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
@@ -743,8 +757,8 @@ 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 `up` 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
 
@@ -756,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
@@ -810,9 +826,10 @@ 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.
@@ -907,5 +924,12 @@ at her call, or where an ask arrives.
 - 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.
-- A faculty entry for `secrets` or `moves`, which the hand alone reaches.
+- 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,29 @@ 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` raises a faculty by the `up`
-its entry names, and `houses` opens a house on its entry. Each takes
-`update` to land a new entry in one write, and `faculties restart`
-takes a body down and up again.
+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='{"faculty":"folder","at":"house"}' faculties='["payments"]'
 ```
@@ -98,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.
 
@@ -118,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

@@ -127,7 +127,6 @@ export const FaceBlueprint = need('face', {
 export class Api {
   #context: Calls | undefined;
   #signup = '';
-  #calls = 0;
 
   arm({ signup }: { signup: string }, context: FacultyContext): Promise<Answer> {
     this.#context = context;
@@ -145,9 +144,9 @@ export class Api {
     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> {
@@ -213,7 +212,7 @@ export const faculties = {
 ```
 
 ```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
 ```
 
@@ -235,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) =>

package/FACULTIES.md

@@ -15,16 +15,22 @@ the package's own tests run.
 ## What a faculty owes
 
 A faculty answers a blueprint: a name, and methods with their schemas.
-A registry holds it by name as `{ up, install? }`. The ground raises it
-by its `up` into a body, and hands the body to its houses as an offer,
-with the kinds its entry grants.
+A registry holds it by name as `{ takes?, up, install? }`. The ground
+raises it by its `up` into a body, and hands the body to its houses as
+an offer, with the kinds its entry grants.
 
 ```text
-faculty = { install?, up }
+faculty = { takes?, install?, up }
+takes   = { args?: schema, secrets?: { [name]: what it holds } }
 body    = { blueprint?, object?, window?, handler?, registry?, down? }
 offer   = { blueprint, object, kinds?, window? }
 ```
 
+- **It declares what it takes.** `takes.args` is a schema built with
+  `s` from `nervur/being`, which its entry's args meet. `takes.secrets`
+  names each secret its entry must name, with a line saying what it
+  holds. The hand refuses an entry that fails either, before it lands,
+  and `facultiesCatalog` shows it to whoever writes the entry.
 - **The object has the blueprint's methods.** Each takes one args object
   and a context, and answers `{ result }` or `{ error: { message } }`.
 - **An error is final, and a throw is not.** An error reaches the being
@@ -93,7 +99,8 @@ receives four things beside the faculty's name.
 
 - **`args`** are its entry's, as the owner wrote them.
 - **`secrets`** are the secrets its entry names, set through the hand
-  and kept sealed in the ground's drawer. No other code reads them.
+  and kept sealed in a being of the ground's dock. No other code reads
+  them.
 - **`memory`** is the faculty's own, a view of the ground's memory
   sealed under a key the ground derives for it. Its call ids live there,
   so they move with the ground.
@@ -378,11 +385,11 @@ it later, once.
 
 The Pi's folder holds the program and a folder of classes for its
 house, and no code of the ground's. The relay stands from its entry,
-raised by the NodeGround's own faculty `bridge`, and granted to the
-twin's class alone.
+raised by the faculty `bridge` of the NodeGround's folder, and granted
+to the twin's class alone.
 
 ```bash
-npx nervur faculties add name=relay make=bridge args='{"command":"python3","args":["relay.py"]}' kinds='["org.example.garage"]'
+npx nervur faculties add name=relay from=folder make=bridge args='{"command":"python3","args":["relay.py"]}' kinds='["org.example.garage"]'
 ```
 
 The house is added once, and names the relay among the faculties it
@@ -392,8 +399,8 @@ receives.
 npx nervur houses add name=garage classes='{"faculty":"folder","at":"classes"}' faculties='["relay"]'
 ```
 
-Both entries rest sealed in the ground's drawer, so the ground stands
-the relay again at every start.
+Both entries rest sealed as cells of the ground's dock, so the ground
+stands the relay again at every start.
 
 ## In JavaScript
 
@@ -493,7 +500,7 @@ test('Each tap on the phone pulses the relay once, whatever fails between', { ti
   });
   t.after(() => garage.down());
   // The relay, granted to the twin's class alone.
-  await garage.hand({ faculty: 'faculties', method: 'add', args: { name: 'relay', make: 'bridge', kinds: ['org.example.garage'] } });
+  await garage.hand({ method: 'facultiesAdd', args: { name: 'relay', make: 'bridge', kinds: ['org.example.garage'] } });
   await garage.add('garage', 'pi', { faculties: ['relay'] });
   await garage.ask({ house: 'garage', method: 'bear', args: { kind: 'org.example.garage', id: 'door' } });