nervur 0.22.2-6 → 0.22.2-8

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 the ground's
-  `recipe.ts` makes.
+- `Payments` is a faculty that charges money, which `recipe.ts` holds
+  by name.
 
 ## Words
 
@@ -31,7 +31,9 @@ The shop has three classes and one faculty.
 | role | a named test over the asker and her cells |
 | 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 their seeds, faculties and hands |
+| ground | the process houses run in, holding one key and sealing their seeds, faculties and secrets under it |
+| 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
 
@@ -587,7 +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 where a restart keeps 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>();
@@ -615,28 +618,31 @@ export class Payments {
 export const paymentsOffer = (payments: Payments): Offer => ({ blueprint: PaymentsBlueprint, object: payments, window: 7 * 86_400_000 });
 ```
 
-An offer is `{ blueprint, object, kinds?, window?, handler?, stop? }`.
-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. The ground's
-recipe makes each faculty by name, and `kinds` grants it to the classes
-it names. [Writing a faculty](FACULTIES.md) teaches the craft whole, with a
-faculty written in Python.
+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 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';
 
-export const faculties = () => ({
-  payments: paymentsOffer(new Payments()),
-});
+// A registry: the ground raises each faculty an entry names by its `up` here.
+export const faculties = {
+  payments: { up: () => paymentsOffer(new Payments()) },
+};
 ```
 
 ## A ground
 
 A ground is the process houses run in, and you write none. `nervur up`
-runs one on a folder: the recipe of its faculties, and a folder of code
-for each house. It keeps a record of its houses, and opens each on the
-bodies the record names.
+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.
 
 ### The shop's folder
 
@@ -676,11 +682,16 @@ 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. **Its own.** Its seeds and its record open.
-3. **Faculties.** The recipe makes each, in its order.
-4. **Houses.** Each house of the record opens on its bodies.
-5. **Hook.** The listeners, then the hand on its socket.
-6. **Ready.** It tells systemd it is up, where systemd waits.
+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.
 
@@ -693,26 +704,47 @@ It is set by its environment.
 | `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_KEYCHAIN` | a keychain service holding its seeds on macOS, in place of files |
+| `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 |
 
-The state holds each house's seed in a file its owner alone reads, and
-each house's ledger. A ledger appends every write and never rewrites
-one. Its witness keeps where it last stood, and a ledger behind its
-witness is refused. So a ledger restored alone cannot replay what a
-house already answered, though a whole state folder restored with its
-witnesses is not seen. A lost seed is a lost house.
+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
+ledger appends every write and never rewrites one. Its witness keeps
+where it last stood, and a ledger behind its witness is refused. So a
+ledger restored alone cannot replay what a house already answered,
+though a whole state folder restored with its witness is not seen. A
+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.
+
+```bash
+npx nervur faculties add name=recipe make=module args='{"at":"recipe.ts"}'
+```
+
+```bash
+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 memory='{"body":"ledger"}' classes='{"body":"folder","at":"classes"}' faculties='["payments"]'
+npx nervur houses add name=shop classes='{"faculty":"folder","at":"classes"}' faculties='["payments"]'
 ```
 
-`memory` and `classes` name the bodies the house is handed. `ledger` and
-`folder` are the ground's own, and a recipe may add more, a git registry
-or another store among them. `faculties` names what the house receives,
-and within it each offer's `kinds` names 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 `up` receives in `secrets`.
 
 ### The hand
 
@@ -774,7 +806,7 @@ with `loginctl enable-linger`. On macOS, the agent goes to
 
 ### In a page
 
-`BrowserGround.open({ recipe })` from `nervur/browser` runs the same
+`BrowserGround.open({ registry })` from `nervur/browser` runs the same
 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
@@ -782,12 +814,12 @@ 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.
 
-Its bodies are the browser's. Seeds are sealed under an AES key that
-IndexedDB holds unextractable, and memory is IndexedDB, named
-`indexeddb` in an entry. 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 recipe is the object you pass: its
-faculties, made by a function, and any custom body.
+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` 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
@@ -811,10 +843,10 @@ app's web view, on two interfaces the shell fills in native code:
   which lands every write only where each key in `expect` still holds
   what it names, and answers whether it landed.
 
-The library holds the rest. Each house's seed goes into the secret
-store, and each 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 recipe makes.
+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 holds.
 
 ## What the house guarantees
 
@@ -871,5 +903,9 @@ at her call, or where an ask arrives.
 - A send to a private address, unless its ground allows it.
 - A call on the house beside `House.open`, `door` and `ask`.
 - A faculty in a house's code. Faculties are the ground's.
-- A custom body for a ground's own custody or memory.
+- A drawer opened with a key that did not seal it.
+- 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.
 - A ground an owner must write. Each terrain's ships.

package/COMMAND.md

@@ -7,17 +7,21 @@ have read [the package's start](README.md), which runs a first ground.
 
 ## Starting a ground
 
-`nervur up` runs a NodeGround on a folder until it is stopped. The folder
-holds the ground's recipe, a folder of code for each house, and `state/`,
-where the ground keeps its seeds, its record and its hand.
+`nervur up` runs a NodeGround on a folder until it is stopped. The
+folder holds your code: a folder for each house, and each module or
+program your entries name. `state/` holds the ground's key, its ledger
+and its hand. The key is drawn on the first start, into a file your user
+alone reads.
 
 ```bash
 npx nervur up .
 ```
 
 The ground stops cleanly on an interrupt and on `SIGTERM`. It takes a
-lock on its folder, so a second `nervur up` on the same folder refuses to
-start.
+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.
 
 `nervur service` prints what keeps the ground running across reboots: a
 systemd unit on Linux, a launchd job on macOS. Nothing is installed; you
@@ -40,7 +44,7 @@ A ground reads its settings from the environment.
 | `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_KEYCHAIN` | on macOS, a keychain service that keeps the seeds in place of files |
+| `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 |
 
@@ -58,18 +62,24 @@ 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, and
-each house.
+`help` prints what the ground holds: 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. The ground's own `houses` faculty adds, removes and lists houses.
+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.
 
 ```bash
-npx nervur houses add name=main memory='{"body":"ledger"}' classes='{"body":"folder","at":"house"}'
+npx nervur faculties add name=recipe 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"]'
 ```
 
 `ask` asks a being of a house, as the house's owner. `--id <being>` names
@@ -101,6 +111,13 @@ JSON where it reads as JSON, and as text where it does not, so
 npx nervur ask main hello '{"name":"Ada"}'
 ```
 
+A lone `-` reads the one JSON object from standard input instead. So a
+secret never stands on a command line or in a shell's history.
+
+```bash
+npx nervur secrets set - < stripe-key.json
+```
+
 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,7 +125,7 @@ export const FaceBlueprint = need('face', {
  * asks to an agent as tools.
  */
 export class Api {
-  #context: FacultyContext | undefined;
+  #context: Calls | undefined;
   #signup = '';
   #calls = 0;
 
@@ -134,7 +135,12 @@ 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;
   }
@@ -179,8 +185,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
@@ -188,9 +194,11 @@ method the tool's name, its args schema the tool's input schema, and its
 hints the tool's annotations. A moved describe is a changed list of
 tools.
 
-## The recipe
+## The registry
 
-The ground makes the face from its recipe, as it makes any faculty. The
+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.
 
@@ -198,15 +206,23 @@ hands the face its signup.
 // recipe.ts
 import { Api, apiOffer } from './api.ts';
 
-export const faculties = () => ({
-  face: apiOffer(new Api()),
-});
+// A registry: the ground raises the face by its `up` when an entry names it.
+export const faculties = {
+  face: { up: () => apiOffer(new Api()) },
+};
+```
+
+```bash
+npx nervur faculties add name=recipe make=module args='{"at":"recipe.ts"}'
+npx nervur faculties add name=face from=recipe make=face
 ```
 
 ## Testing it
 
 A BenchGround answers a request with its faculties' handlers in turn, as
-a ground's one listener does, so the face is tested with no socket.
+a ground's one listener does, so the face is tested with no socket. The
+test hands the bench the registry, and stands the face through the
+ground's hand, as an owner does.
 
 ```ts
 // api.test.ts
@@ -217,8 +233,9 @@ import * as desk from './desk.ts';
 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 }, recipe: faculties });
+  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.add('desk', 'desk', { faculties: ['face'] });
   await ground.ask({ house: 'desk', method: 'arm' });
   const web = async (path: string, body?: unknown, token?: string) =>