nervur 0.23.0 → 0.24.0

package/COMMAND.md

@@ -1,179 +0,0 @@
-# The command
-
-`nervur` is the command the package installs. It holds no business of
-its own. Two words start things on your machine, and every other word is
-read from what the running ground says it holds. This guide assumes you
-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 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`. 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
-place what it prints.
-
-```bash
-npx nervur service /srv/shop
-```
-
-## Settings
-
-The environment names only what opens the ground's memory, its key and
-its hand.
-
-| Variable | What it names |
-| --- | --- |
-| `NERVUR_STATE` | the state folder, `state/` in the ground's folder where unset |
-| `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 |
-
-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.
-
-A socket's path fits 103 bytes on macOS and 107 on Linux, and a longer
-one refuses to start by name. A ground in a deep folder names a shorter
-path in `NERVUR_HAND`, such as `state/hand` run from the folder, and every
-command that reaches it names the same.
-
-## Asking the ground
-
-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: the asks of its dock, each faculty
-with its methods or why it is down, and each house.
-
-```bash
-npx nervur help
-```
-
-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 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"]'
-```
-
-`ask` asks a being of a house, as the house's owner. `--id <being>` names
-her, and with none it asks the steward. With no method, it prints what
-she shows.
-
-```bash
-npx nervur ask main
-```
-
-`--cells` reads a being's cells as they last landed, and asks nothing.
-Nothing but the hand reads cells, which makes it the tool for a test, a
-repair, or a look at what her asks do not show.
-
-```bash
-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.
-
-## Arguments and answers
-
-Arguments are one JSON object, or words `key=value`. A value is read as
-JSON where it reads as JSON, and as text where it does not, so
-`count=3` is a number and `name=Ada` is text.
-
-```bash
-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
-```
-
-`--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.
-
-| Exit | What it means |
-| --- | --- |
-| 0 | a result, or what she shows |
-| 1 | an error the ground or the being answered |
-| 2 | nothing was asked: a word the command does not know, or a hand that does not answer |
-
-So a script tells a refusal from a ground that is down.

package/FACES.md

@@ -1,280 +0,0 @@
-# Faces
-
-A face is how a person with no house of their own reaches a being: a
-site, an API, or a server of tools for an AI agent. It adds nothing new
-to the library. A face is a faculty with a handler on the ground's
-listener, and the person behind it is one occupant of one being. This
-guide writes one face that serves an API and tools together.
-[Writing for nervur](AUTHORING.md) teaches beings, and [Writing a
-faculty](FACULTIES.md) teaches faculties.
-
-## Doors and tokens
-
-**A person reaches a house in one of two ways.** Their own house holds a
-standing and asks over Quo, or a face asks for them with a token. Nothing
-else reaches a being.
-
-**A token is a door.** A being mints an occupant for the person. The face
-receives it as a token, since a face is a faculty, and a faculty calls a
-handle by its token. The face asks as that occupant, so the being's roles
-decide what the person may do, and the face decides nothing.
-
-**A token reads the describe, and asks by method.** Asked with no method,
-a token answers what its occupant may ask now, with each ask's schema. So
-an API face shows those asks as endpoints and a tool server as tools, and
-the owner writes the business once.
-
-**One ask gives every other door.** The person's being mints another
-occupant for a device, an agent or an API client, each under notes of its
-own. It lists its doors and lets any one go.
-
-## The desk
-
-The steward arms the face with a handle to her `signup`. Each person who
-signs up is a member being, and the face holds one door on her. A member
-declares the face as a need, so the ground's grant decides which classes
-a face reaches.
-
-```ts
-// desk.ts
-import { Being, need, s, type Args } from 'nervur/being';
-
-/** The face, as the steward arms it with a handle to her signup. */
-const Face = need('face', {
-  arm: { args: s.object({ signup: s.handle() }), hints: { idempotent: true } },
-});
-
-/** A member declares the face, so its doors reach her. */
-const Reached = need('face', {});
-
-export class Desk extends Being.of({
-  kind: 'com.example.desk',
-  needs: { face: Face },
-  asks: {
-    arm: { for: 'root', hints: { idempotent: true } },
-    signup: { for: 'handle', args: s.object({ name: s.string() }), result: s.object({ door: s.handle() }) },
-  },
-}) {
-  async arm() {
-    await this.face.arm({ signup: this.handle('signup') });
-  }
-
-  // Each person is one member, and the face holds one door on her.
-  signup({ name }: Args<Desk, 'signup'>) {
-    const id = `member-${name}`;
-    this.powers!.bear({ kind: 'com.example.member', id });
-    return { door: this.powers!.invite({ id, occupant: 'web', notes: { person: true } }) };
-  }
-}
-
-export class Member extends Being.of({
-  kind: 'com.example.member',
-  needs: { face: Reached },
-  cells: { visits: 0 },
-  roles: { person: (asker) => asker.steward.person === true },
-  asks: {
-    hello: { for: 'person', hints: { readOnly: true }, description: 'Greets the person.', result: s.string() },
-    visit: { for: 'person', description: 'Counts one visit.', result: s.integer() },
-    leave: { for: 'person', description: 'Lets this door go.' },
-  },
-}) {
-  hello() {
-    return `hello, ${this.id}`;
-  }
-
-  visit() {
-    this.cells.visits += 1;
-    return this.cells.visits;
-  }
-
-  leave() {
-    this.occupants.dismiss(this.asker.id);
-  }
-}
-
-export const steward = Desk;
-export const beings = [Member];
-```
-
-## The face
-
-The face keeps the context its `arm` was called with, and calls every
-token through it. Its handler answers the requests that are its own and
-passes on every other, so it shares the listener with Quo and any other
-face. Each call carries an id of the face's own, so a call the house
-tries again acts once.
-
-```ts
-// api.ts
-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', {
-  arm: { args: s.object({ signup: s.handle() }), hints: { idempotent: true } },
-});
-
-/**
- * One face, two ways in. `POST /signup` makes a person's door and answers
- * its token. With the token as a bearer, `GET /api` lists what the door
- * may ask, `POST /api/<ask>` asks it, and `POST /mcp` speaks the same
- * asks to an agent as tools.
- */
-export class Api {
-  #context: Calls | undefined;
-  #signup = '';
-
-  arm({ signup }: { signup: string }, context: FacultyContext): Promise<Answer> {
-    this.#context = context;
-    this.#signup = signup;
-    return Promise.resolve({ result: null });
-  }
-
-  // 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 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:${crypto.randomUUID()}` });
-  }
-
-  async #tools(token: string): Promise<Json> {
-    const described = await this.#held().describe({ token });
-    if (!('describe' in described)) return { error: described.error };
-    const asks = (described.describe as { asks: Entry[] }).asks;
-    return { tools: asks.map(({ method, description, args, hints }) => ({ name: method, description: description ?? '', inputSchema: args ?? { type: 'object' }, annotations: hints ?? {} })) };
-  }
-
-  readonly handler: Handler = {
-    fetch: async (request) => {
-      const path = new URL(request.url).pathname;
-      if (request.method === 'POST' && path === '/signup') {
-        const { name } = (await request.json()) as { name: string };
-        const answer = await this.#held().call({ token: this.#signup, args: { name }, id: `signup:${name}` });
-        return 'result' in answer ? Response.json({ token: (answer.result as { door: string }).door }) : Response.json(answer, { status: 400 });
-      }
-      const token = /^Bearer (\w+)$/.exec(request.headers.get('authorization') ?? '')?.[1];
-      if (path !== '/api' && !path.startsWith('/api/') && path !== '/mcp') return null;
-      if (token === undefined) return new Response(null, { status: 401 });
-      if (request.method === 'GET' && path === '/api') return Response.json(await this.#held().describe({ token }));
-      if (request.method === 'POST' && path.startsWith('/api/')) return Response.json(await this.#ask(token, path.slice('/api/'.length), (await request.json()) as Json));
-      if (request.method === 'POST' && path === '/mcp') {
-        const { id, method, params } = (await request.json()) as { id: number; method: string; params?: { name: string; arguments?: Json } };
-        if (method === 'tools/list') return Response.json({ jsonrpc: '2.0', id, result: await this.#tools(token) });
-        if (method === 'tools/call') {
-          const answer = await this.#ask(token, params?.name ?? '', params?.arguments ?? {});
-          const text = JSON.stringify('result' in answer ? (answer.result ?? null) : answer.error.message);
-          return Response.json({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }], isError: 'error' in answer } });
-        }
-        return Response.json({ jsonrpc: '2.0', id, error: { code: -32601, message: 'no such method' } });
-      }
-      return null;
-    },
-  };
-}
-
-/** 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
-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 registry
-
-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 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 from=folder 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. The
-test hands the bench the registry, and stands the face through the
-ground's hand, as an owner does.
-
-```ts
-// api.test.ts
-import assert from 'node:assert/strict';
-import { test } from 'node:test';
-import { BenchGround, FakeNetwork } from 'nervur/bench';
-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 }, registry: { faculties } });
-  t.after(() => ground.down());
-  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) =>
-    (await ground.fetch(
-      new Request(`https://desk.example${path}`, {
-        method: body === undefined ? 'GET' : 'POST',
-        headers: token === undefined ? {} : { authorization: `Bearer ${token}` },
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-      }),
-    )).json() as Promise<Record<string, unknown>>;
-
-  const { token } = (await web('/signup', { name: 'ada' })) as { token: string };
-  const { describe } = (await web('/api', undefined, token)) as { describe: { asks: { method: string }[] } };
-  assert.deepEqual(describe.asks.map(({ method }) => method).sort(), ['hello', 'leave', 'visit']);
-  assert.deepEqual(await web('/api/hello', {}, token), { result: 'hello, member-ada' });
-  assert.deepEqual(await web('/api/visit', {}, token), { result: 1 });
-
-  const { result } = (await web('/mcp', { jsonrpc: '2.0', id: 1, method: 'tools/list' }, token)) as { result: { tools: { name: string; annotations: { readOnly?: boolean } }[] } };
-  assert.equal(result.tools.find(({ name }) => name === 'hello')?.annotations.readOnly, true, 'a hint is an annotation');
-  const called = await web('/mcp', { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'visit' } }, token);
-  assert.deepEqual(called.result, { content: [{ type: 'text', text: '2' }], isError: false });
-
-  assert.deepEqual(await web('/api/leave', {}, token), { result: null });
-  assert.deepEqual(await web('/api/hello', {}, token), { error: { message: 'no such token' } }, 'a door let go is no door');
-});
-```
-
-## Further than one door
-
-**A watch reaches a page as events.** A token's call takes `after`, the
-answer the face holds, and makes a `readOnly` ask a watch. It answers the
-moment the answer changes, so a face streams it as server-sent events.
-
-**A door carried home leaves as an invitation.** A token's call takes
-`home: true`. The handles in its answer then reach the face as invitation
-bytes, never as tokens. The person carries them to a house of their own,
-which takes them. Their being, its cells and its history stay, and the old
-token is let go.
-
-**A session gives every other door.** A browser session is one door.
-Through it the person's being mints another for an agent or an API
-client, so an OAuth server is a face that turns that ask into its
-client's access token.