@lapxo/head 0.0.0-stage → 0.1.3

package/dist/src/ports/documents.js

@@ -0,0 +1,64 @@
+import { dirname, extname, join } from 'node:path';
+import { within } from "../core/answer.js";
+import { members, valueOf } from "../core/lock.js";
+import { sayIn } from "../core/surface.js";
+const limits = (context) => ['adapter/request/wait', 'adapter/request/document-bytes'].map((k) => Number(valueOf(context.lock, k).split('..')[1]));
+export const kindOf = (at, type = '') => (extname(URL.canParse(at) ? new URL(at).pathname : at).slice(1)
+    || (type.split(';')[0].split('/')[1] ?? '').split('+').at(-1).replace(/^x-/, '') || 'octet-stream').toLowerCase();
+/**
+ * A document the person names: a file inside the place or a folder the client shares, or an encrypted address read with
+ * nothing attached — signed or expiring as it may be — and, when its digest is named, followed wherever it moves to the
+ * bytes that digest names, and only to them. Anything else is not read. Its kind is named, never read for: its file's
+ * extension, its address's, or the media type it was served as; bytes that say none are octet-stream.
+ */
+export const documentOf = async (context, place, at, named = '') => {
+    const [wait, most] = limits(context), transport = URL.canParse(at) ? await context.adapter(at) : undefined;
+    if (URL.canParse(at))
+        return named ? ((bytes) => bytes && { bytes, kind: kindOf(at) })(await transport?.published(at, named, most, wait)) : ((got) => got && { bytes: got.bytes, kind: kindOf(at, got.type) })(await transport?.get(at, wait));
+    return ((bytes) => bytes && { bytes, kind: kindOf(at) })((await within(context, place, at)) ? context.files.take(at) : undefined);
+};
+/** A document read with the access a source the place connected holds: sent to that source's own origin alone, never redirected with it; a move is followed with nothing attached, only to the bytes its named digest names. */
+export const fetchedAs = async (context, at, via, got, named, accept) => {
+    const [say, [wait, most]] = [sayIn(context.lock), limits(context)];
+    if (!URL.canParse(at))
+        return { said: [say('document-unread', { document: at })] };
+    if (new URL(at).origin !== new URL(got.plan.origin).origin)
+        return { said: [say('fetch-cross-origin', { document: at, via })] };
+    const transport = await context.adapter(at), answer = transport ? await transport.fetched(at, got.attachment, accept, most, wait) : undefined;
+    if (answer?.kind !== 'got')
+        return { said: [say('document-unread', { document: at })] };
+    if (answer.status >= 300 && answer.status < 400 && answer.location !== undefined) {
+        if (!named)
+            return { said: [say('fetch-redirect', { document: at })] };
+        return ((bytes) => (bytes ? { bytes, kind: kindOf(at) } : { said: [say('document-unread', { document: at })] }))(await transport.published(new URL(answer.location, at).href, named, most, wait));
+    }
+    return answer.status < 300 ? { bytes: answer.bytes, kind: kindOf(at, answer.type) } : { said: [say('fetch-status', { document: at, via, status: String(answer.status) })] };
+};
+/**
+ * Every byte a package's lines name, by the path each names: read where a line of the same scope says — an encrypted
+ * address, signed or expiring, read with nothing attached and only to the bytes its digest names — or else beside the
+ * package's lock, in its folder or at its address. A path outside the package is never read. And what a place laid
+ * for a source it connected — its document and the overlay beside it — by the path the place keeps them at. And where
+ * an origin says its documents are: the catalog it publishes at its well-known address (RFC 9727), then the paths head's
+ * lock names, each once.
+ */
+export const besideOf = async (context, document, lines) => {
+    const [wait, most] = limits(context), read = new Map();
+    for (const l of lines.filter((one) => one.needs && one.measure === 'digest' && !one.needs.split('/').includes('..') && !one.needs.startsWith('/'))) {
+        const at = lines.find((o) => o.scope === l.scope && o.measure === 'id')?.value ?? (URL.canParse(document) ? new URL(l.needs, document).href : join(dirname(document), l.needs));
+        read.set(l.needs, URL.canParse(at) ? await (await context.adapter(at))?.published(at, l.value ?? '', most, wait) : context.files.take(at));
+    }
+    return read;
+};
+export const describedAt = async (context, origin) => {
+    const [wait] = limits(context), catalog = await (await context.adapter(origin))?.get(new URL(valueOf(context.lock, 'use/catalog'), origin).href, wait), rel = valueOf(context.lock, 'use/catalog-rel');
+    const listed = (() => { try {
+        return JSON.parse(new TextDecoder().decode(catalog?.bytes ?? new Uint8Array())).linkset?.flatMap((l) => (l[rel] ?? []).flatMap((d) => d.href ?? [])) ?? [];
+    }
+    catch {
+        return [];
+    } })();
+    return [...new Set([...listed, ...members(valueOf(context.lock, 'use/documents'))].flatMap((at) => (URL.canParse(at, origin) ? [new URL(at, origin).href] : [])))];
+};
+export const laidOf = (context, place, source) => ((at) => context.files.list(place, at).filter((f) => new RegExp(`^${source}\\.(overlay\\.)?[^.]+$`).test(f))
+    .map((f) => [`${at}/${f}`, context.files.take(join(place, at, f)) ?? new Uint8Array()]))(valueOf(context.lock, 'place/connected'));

package/dist/src/ports/keychain.d.ts

@@ -0,0 +1,8 @@
+export interface KeyStore {
+    readonly read: (account: string) => string | undefined;
+    readonly write: (account: string, secret: string) => void;
+    readonly made?: (account: string) => string | undefined;
+}
+export declare const plain: (word: string) => string;
+/** The secret store this host keeps head's keys in, by the name its lock gives the platform's: one adapter each, every secret crossing a command's stdin and stdout only; a key it is asked for by its account is made there once, and only its public half handed on. */
+export declare const keychain: (service: string, kind: string) => KeyStore;

package/dist/src/ports/keychain.js

@@ -0,0 +1,12 @@
+import { store as credentialManager } from "./stores/credential-manager.js";
+import { store as keychainOfMac } from "./stores/keychain.js";
+import { store as secretTool } from "./stores/secret-tool.js";
+import { newKey, publicOf } from "./keys.js";
+export const plain = (word) => { if (!/^[\w.@/+=-]+$/.test(word))
+    throw Error('REFUSE·keychain a name holds more than word characters'); return word; };
+/** The secret store this host keeps head's keys in, by the name its lock gives the platform's: one adapter each, every secret crossing a command's stdin and stdout only; a key it is asked for by its account is made there once, and only its public half handed on. */
+export const keychain = (service, kind) => ((made) => {
+    if (made === undefined)
+        throw Error(`REFUSE·keychain ${kind} is no store head carries`);
+    return ((store) => ({ ...store, made: (account) => ((secret) => secret && publicOf(secret))(store.read(account) ?? ((key) => { store.write(account, key.secret); return store.read(account) === key.secret ? key.secret : undefined; })(newKey())) }))(made(service));
+})({ keychain: keychainOfMac, 'secret-tool': secretTool, 'credential-manager': credentialManager }[kind]);

package/dist/src/ports/keys.d.ts

@@ -0,0 +1,14 @@
+export interface Key {
+    readonly secret: string;
+    readonly publicKey: string;
+}
+/** A new device key: its secret as base64 PKCS8 for the keychain to keep, its public half as base64 SPKI for a lock to admit. */
+export declare const newKey: () => Key;
+/**
+ * One signing lot answered as the signing-lot/1 contract asks: every line the lot carries, already the bytes a signature
+ * covers and named by this key alone, signed in order under the algorithm the host was told. A lot naming any other key,
+ * or bytes not in their canonical form, is refused whole: topos's own request reader decides, never this file.
+ */
+export declare const signLot: (input: string, secret: string, keyId: string, algorithm: string) => string;
+/** The public half of a kept secret, as a lock admits it. */
+export declare const publicOf: (secret: string) => string;

package/dist/src/ports/keys.js

@@ -0,0 +1,20 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign } from 'node:crypto';
+import { formatSignature, signerRequestBytes, signerResponseBytes } from '@lapxo/topos/wire';
+/** A new device key: its secret as base64 PKCS8 for the keychain to keep, its public half as base64 SPKI for a lock to admit. */
+export const newKey = () => ((pair) => ({
+    secret: pair.privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64'),
+    publicKey: pair.publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+}))(generateKeyPairSync('ed25519'));
+/**
+ * One signing lot answered as the signing-lot/1 contract asks: every line the lot carries, already the bytes a signature
+ * covers and named by this key alone, signed in order under the algorithm the host was told. A lot naming any other key,
+ * or bytes not in their canonical form, is refused whole: topos's own request reader decides, never this file.
+ */
+export const signLot = (input, secret, keyId, algorithm) => {
+    const bytes = input.endsWith('\n') ? input.slice(0, -1).split('\n') : [];
+    signerRequestBytes({ bytes, keyId, algorithm });
+    const key = createPrivateKey({ key: Buffer.from(secret, 'base64'), format: 'der', type: 'pkcs8' });
+    return signerResponseBytes(bytes.map((one) => ({ keyId, signature: formatSignature(algorithm, sign(null, Buffer.from(one, 'utf8'), key).toString('base64')) })));
+};
+/** The public half of a kept secret, as a lock admits it. */
+export const publicOf = (secret) => createPublicKey(createPrivateKey({ key: Buffer.from(secret, 'base64'), format: 'der', type: 'pkcs8' })).export({ type: 'spki', format: 'der' }).toString('base64');

package/dist/src/ports/place.d.ts

@@ -0,0 +1,11 @@
+import type { Said } from '../core/lock.ts';
+/** The lines head's own lock declares, decoded; a missing lock is an error, never an empty lock. */
+export declare const lockAt: (dir: string) => readonly Said[];
+/** A root the client shares, as the folder it names; a root that names no file folder is no place. */
+export declare const folderOf: (uri: string) => string | undefined;
+/** Bytes laid at a path inside a place, its folders made; a path outside the place is refused. */
+export declare const layAt: (place: string, rel: string, bytes: Uint8Array) => void;
+export declare const takeAt: (path: string) => Uint8Array | undefined;
+export declare const hasAt: (place: string, rel: string) => boolean;
+export declare const dropAt: (place: string, rel: string) => void;
+export declare const listAt: (place: string, rel: string) => readonly string[];

package/dist/src/ports/place.js

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LOCK } from '@lapxo/topos/wire';
+import { declaredOf } from "../core/lock.js";
+/** The lines head's own lock declares, decoded; a missing lock is an error, never an empty lock. */
+export const lockAt = (dir) => declaredOf(readFileSync(join(dir, LOCK), 'utf8'));
+/** A root the client shares, as the folder it names; a root that names no file folder is no place. */
+export const folderOf = (uri) => { try {
+    return fileURLToPath(uri);
+}
+catch {
+    return undefined;
+} };
+const inside = (place, rel) => ((at) => { if (!at.startsWith(`${resolve(place)}${sep}`))
+    throw Error('REFUSE·place a path outside its place'); return at; })(resolve(place, rel));
+/** Bytes laid at a path inside a place, its folders made; a path outside the place is refused. */
+export const layAt = (place, rel, bytes) => { const at = inside(place, rel); mkdirSync(dirname(at), { recursive: true }); writeFileSync(at, bytes); };
+export const takeAt = (path) => { try {
+    return readFileSync(path);
+}
+catch {
+    return undefined;
+} };
+export const hasAt = (place, rel) => existsSync(resolve(place, rel));
+export const dropAt = (place, rel) => rmSync(inside(place, rel), { force: true });
+export const listAt = (place, rel) => { try {
+    return readdirSync(inside(place, rel));
+}
+catch {
+    return [];
+} };

package/dist/src/ports/process.d.ts

@@ -0,0 +1,29 @@
+import type { ChildProcess } from 'node:child_process';
+export interface Printed {
+    readonly code: number;
+    readonly out: readonly string[];
+    readonly err: readonly string[];
+    readonly refusal?: Readonly<Record<string, string>>;
+}
+export interface Bounds {
+    readonly wait: number;
+    readonly most: number;
+    readonly signal?: AbortSignal;
+}
+/** A process head starts in a group of its own, so stopping it stops everything it started. */
+export declare const grouped: (command: string, args: readonly string[], at: {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}, pipes?: number) => ChildProcess;
+/**
+ * A process run beside head, never blocking it: what it printed, out and err, line by line, and its exit, which is
+ * transport and never the verdict. Its whole group is stopped when the wait runs out, when it prints more bytes than it
+ * may, when the asker cancels or when head exits; the exit is then -1 and the cause is err's last line.
+ */
+export declare const spawned: (command: string, args: readonly string[], at: {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly input?: string;
+}, bounds: Bounds) => Promise<Printed>;
+/** What a process head already started prints from now on, within the same bounds. */
+export declare const watched: (child: ChildProcess, bounds: Bounds) => Promise<Printed>;

package/dist/src/ports/process.js

@@ -0,0 +1,51 @@
+import { spawn } from 'node:child_process';
+const running = new Set();
+process.once('exit', () => { for (const stop of running)
+    stop(); });
+/** A process head starts in a group of its own, so stopping it stops everything it started. */
+export const grouped = (command, args, at, pipes = 3) => spawn(command, [...args], { cwd: at.cwd, env: at.env, stdio: Array(pipes).fill('pipe'), detached: process.platform !== 'win32', windowsHide: true });
+/**
+ * A process run beside head, never blocking it: what it printed, out and err, line by line, and its exit, which is
+ * transport and never the verdict. Its whole group is stopped when the wait runs out, when it prints more bytes than it
+ * may, when the asker cancels or when head exits; the exit is then -1 and the cause is err's last line.
+ */
+export const spawned = (command, args, at, bounds) => ((child) => { child.stdin.on('error', () => undefined).end(at.input ?? ''); return watched(child, bounds); })(grouped(command, args, at));
+/** What a process head already started prints from now on, within the same bounds. */
+export const watched = (child, bounds) => new Promise((resolve) => {
+    const [out, err] = [[], []];
+    let [printed, cause, done] = [0, undefined, false];
+    const kill = () => { try {
+        if (child.pid !== undefined && process.platform !== 'win32')
+            process.kill(-child.pid, 'SIGKILL');
+        else
+            child.kill('SIGKILL');
+    }
+    catch {
+        child.kill('SIGKILL');
+    } };
+    const stop = (why) => { cause ??= why; kill(); };
+    const signal = AbortSignal.any([...(bounds.wait > 0 ? [AbortSignal.timeout(bounds.wait)] : []), ...(bounds.signal ? [bounds.signal] : [])]);
+    const cancel = () => stop(bounds.signal?.aborted ? 'cancelled' : `waited ${bounds.wait} ms`);
+    const finish = (code) => {
+        if (done)
+            return;
+        done = true;
+        signal.removeEventListener('abort', cancel);
+        running.delete(kill);
+        const lines = (chunks) => Buffer.concat(chunks).toString('utf8').split('\n').filter(Boolean);
+        resolve({ code: cause === undefined ? code : -1, out: lines(out), err: [...lines(err), ...(cause === undefined ? [] : [cause])] });
+    };
+    const take = (into) => (chunk) => { printed += chunk.length; if (printed > bounds.most)
+        stop(`printed more than ${bounds.most} bytes`);
+    else
+        into.push(chunk); };
+    running.add(kill);
+    child.stdout.on('data', take(out));
+    child.stderr.on('data', take(err));
+    child.on('error', (error) => { cause ??= error.message; finish(-1); });
+    child.on('close', (code) => finish(code ?? -1));
+    if (signal.aborted)
+        cancel();
+    else
+        signal.addEventListener('abort', cancel, { once: true });
+});

package/dist/src/ports/signers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The host's registry bound reads to bind a declared signer name to a program: head's own signer, started by this node,
+ * told the keychain service, the account its secret is kept under, the key it signs as, the algorithm and the store this
+ * host keeps secrets in. It holds no secret; it lives beside nothing a repository ships.
+ */
+export declare const registryFor: (name: string, service: string, account: string, key: string, algorithm: string, store?: string) => string;

package/dist/src/ports/signers.js

@@ -0,0 +1,14 @@
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The host's registry bound reads to bind a declared signer name to a program: head's own signer, started by this node,
+ * told the keychain service, the account its secret is kept under, the key it signs as, the algorithm and the store this
+ * host keeps secrets in. It holds no secret; it lives beside nothing a repository ships.
+ */
+export const registryFor = (name, service, account, key, algorithm, store = 'keychain') => {
+    const at = join(mkdtempSync(join(tmpdir(), 'head-signers-')), 'signers.json');
+    writeFileSync(at, JSON.stringify({ [name]: { kind: 'command', executable: process.execPath, args: [fileURLToPath(new URL(`../signer${import.meta.url.slice(import.meta.url.lastIndexOf('.'))}`, import.meta.url)), service, account, key, algorithm, store] } }));
+    return at;
+};

package/dist/src/ports/spare.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/ports/spare.js

@@ -0,0 +1,33 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFileSync } from 'node:fs';
+import { Socket } from 'node:net';
+import { pathToFileURL } from 'node:url';
+/**
+ * A process started before it is asked: it loads what the program it will run imports, says it is ready on its fourth
+ * pipe, and waits there for one ask, the folder, the arguments and the variables a process started then would have been
+ * given. It takes them as its own, closes that pipe and runs the program once, as that process would have. An ask that
+ * never comes ends it.
+ */
+const [program] = process.argv.slice(2);
+const url = pathToFileURL(program), pipe = new Socket({ fd: 3, readable: true, writable: true });
+const asked = new Promise((resolve) => { let text = ''; pipe.setEncoding('utf8').on('data', (chunk) => { text += chunk; }).on('error', () => undefined).on('close', () => resolve(text)); });
+await Promise.all([...readFileSync(program, 'utf8').matchAll(/^import [^'"]*['"](\.{1,2}\/[^'"]+)['"];?$/gm)].map(([, path]) => import(__rewriteRelativeImportExtension(new URL(path, url).href)).catch(() => undefined)));
+pipe.write('ready\n');
+const text = await asked;
+if (!text)
+    process.exit(0);
+const { cwd, args, env } = JSON.parse(text);
+for (const name of Object.keys(process.env))
+    if (!(name in env))
+        delete process.env[name];
+Object.assign(process.env, env);
+process.chdir(cwd);
+process.argv = [process.argv[0], program, ...args];
+await import(__rewriteRelativeImportExtension(url.href));

package/dist/src/ports/stores/credential-manager.d.ts

@@ -0,0 +1,3 @@
+import type { KeyStore } from '../keychain.ts';
+/** The Windows Credential Manager: the secret travels inside the program head writes to PowerShell's stdin, base64, and comes back on its stdout; never an argument a process list shows. */
+export declare const store: (service: string) => KeyStore;

package/dist/src/ports/stores/credential-manager.js

@@ -0,0 +1,22 @@
+import { execFileSync } from 'node:child_process';
+import { plain } from "../keychain.js";
+/** Windows PowerShell, reading its whole program from stdin: the password vault of the Credential Manager, an entry by its resource and user. */
+const vault = (program) => execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', '-'], {
+    input: ['$ErrorActionPreference = \'Stop\'', '[void][Windows.Security.Credentials.PasswordVault, Windows.Security.Credentials, ContentType = WindowsRuntime]', '$v = New-Object Windows.Security.Credentials.PasswordVault', ...program, ''].join('\n'),
+    encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'],
+});
+/** The Windows Credential Manager: the secret travels inside the program head writes to PowerShell's stdin, base64, and comes back on its stdout; never an argument a process list shows. */
+export const store = (service) => ({
+    read: (account) => {
+        try {
+            return vault([`$r = '${plain(service)}'; $u = '${plain(account)}'`, 'try { $c = $v.Retrieve($r, $u); $c.RetrievePassword(); [Console]::Out.Write($c.Password) } catch { exit 1 }']).trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    write: (account, secret) => {
+        vault([`$r = '${plain(service)}'; $u = '${plain(account)}'; $b = '${Buffer.from(plain(secret)).toString('base64')}'`, 'try { $v.Remove($v.Retrieve($r, $u)) } catch { }',
+            '$v.Add((New-Object Windows.Security.Credentials.PasswordCredential($r, $u, [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b)))))']);
+    },
+});

package/dist/src/ports/stores/keychain.d.ts

@@ -0,0 +1,3 @@
+import type { KeyStore } from '../keychain.ts';
+/** The macOS keychain through the system's own command: a secret crosses its stdin and stdout only, never an argument a process list shows. */
+export declare const store: (service: string) => KeyStore;

package/dist/src/ports/stores/keychain.js

@@ -0,0 +1,16 @@
+import { execFileSync } from 'node:child_process';
+import { plain } from "../keychain.js";
+/** The macOS keychain through the system's own command: a secret crosses its stdin and stdout only, never an argument a process list shows. */
+export const store = (service) => ({
+    read: (account) => {
+        try {
+            return execFileSync('security', ['find-generic-password', '-a', plain(account), '-s', plain(service), '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    write: (account, secret) => {
+        execFileSync('security', ['-i'], { input: `add-generic-password -U -a ${plain(account)} -s ${plain(service)} -w ${plain(secret)}\n`, stdio: ['pipe', 'ignore', 'ignore'] });
+    },
+});

package/dist/src/ports/stores/secret-tool.d.ts

@@ -0,0 +1,3 @@
+import type { KeyStore } from '../keychain.ts';
+/** The Secret Service of a Linux session through libsecret's own command: an entry found by its service and account attributes, the secret crossing stdin and stdout only. */
+export declare const store: (service: string) => KeyStore;

package/dist/src/ports/stores/secret-tool.js

@@ -0,0 +1,16 @@
+import { execFileSync } from 'node:child_process';
+import { plain } from "../keychain.js";
+/** The Secret Service of a Linux session through libsecret's own command: an entry found by its service and account attributes, the secret crossing stdin and stdout only. */
+export const store = (service) => ({
+    read: (account) => {
+        try {
+            return execFileSync('secret-tool', ['lookup', 'service', plain(service), 'account', plain(account)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    write: (account, secret) => {
+        execFileSync('secret-tool', ['store', `--label=${plain(service)} ${plain(account)}`, 'service', plain(service), 'account', plain(account)], { input: plain(secret), stdio: ['pipe', 'ignore', 'ignore'] });
+    },
+});

package/dist/src/ports/surface.d.ts

@@ -0,0 +1,126 @@
+import type { Said } from '../core/lock.ts';
+export interface Field {
+    readonly name: string;
+    readonly about: string;
+    readonly type: string;
+    readonly required: boolean;
+}
+export interface Tool {
+    readonly name: string;
+    readonly about: string;
+    readonly fields: readonly Field[];
+    readonly hints: readonly string[];
+}
+export interface Resource {
+    readonly name: string;
+    readonly about: string;
+    readonly template: string;
+    readonly mime: string;
+}
+export interface Prompt {
+    readonly name: string;
+    readonly about: string;
+    readonly text: string;
+    readonly line: string;
+    readonly fields: readonly Field[];
+}
+export interface Surface {
+    readonly name: string;
+    readonly version: string;
+    readonly tools: readonly Tool[];
+    readonly resources: readonly Resource[];
+    readonly prompts: readonly Prompt[];
+}
+/** Everything a client is offered, read off the lock alone: its tools, resources and prompts, each with the words a model sees. */
+export declare const surfaceOf: (lock: readonly Said[]) => Surface;
+export declare const refusedOn: (lock: readonly Said[], platform: string) => string | undefined;
+/**
+ * The fields a URI gives a resource template, or none when it is not one of its URIs: {name} matches one path step,
+ * {?a,b} names query fields any of which may be absent, in any order, each decoded.
+ */
+export declare const matchTemplate: (template: string, uri: string) => Readonly<Record<string, string>> | undefined;
+export interface Cell {
+    readonly code: string;
+    readonly state: string;
+    readonly next: {
+        readonly tool: string;
+        readonly args: Readonly<Record<string, string>>;
+    } | {
+        readonly none: string;
+    };
+    readonly fields: Readonly<Record<string, string>>;
+    readonly head?: string;
+}
+/** A said code as the cell head answers with: its state and next from the lock, the next's arguments read from the cell's own fields; a bound refusal a field carries keeps bound's code, head's own beside it. */
+export declare const cellOf: (lock: readonly Said[], key: string, given: Readonly<Record<string, string | undefined>>) => Cell;
+export declare const cellLine: (cell: Cell) => string;
+/** An answer as cells and the lines bound printed beside them, read back from what head said: the shape every tool result has. */
+export declare const shapeOf: (answer: readonly string[]) => {
+    readonly cells: readonly Cell[];
+    readonly lines: readonly string[];
+};
+/** The one output schema every tool declares: cells in the states the lock names, and the lines bound printed. */
+export declare const shapeSchema: (lock: readonly Said[]) => {
+    type: "object";
+    required: string[];
+    properties: {
+        cells: {
+            type: string;
+            items: {
+                type: string;
+                required: string[];
+                properties: {
+                    code: {
+                        type: string;
+                    };
+                    state: {
+                        enum: string[];
+                    };
+                    head: {
+                        type: string;
+                    };
+                    next: {
+                        oneOf: ({
+                            type: string;
+                            required: string[];
+                            properties: {
+                                tool: {
+                                    type: string;
+                                };
+                                args: {
+                                    type: string;
+                                    additionalProperties: {
+                                        type: string;
+                                    };
+                                };
+                                none?: undefined;
+                            };
+                        } | {
+                            type: string;
+                            required: string[];
+                            properties: {
+                                none: {
+                                    type: string;
+                                };
+                                tool?: undefined;
+                                args?: undefined;
+                            };
+                        })[];
+                    };
+                    fields: {
+                        type: string;
+                        additionalProperties: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+        lines: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+    };
+};

package/dist/src/ports/surface.js

@@ -0,0 +1,48 @@
+import { aboutOf, below, members, valueOf } from "../core/lock.js";
+import { sayIn } from "../core/surface.js";
+const nameOf = (line) => line.scope.split('/')[1];
+const fieldsOf = (lock, scope) => ((required) => members(valueOf(lock, scope)).map((name) => ({
+    name, about: aboutOf(lock, `${scope}/${name}`), type: valueOf(lock, `${scope}/${name}`), required: required.includes(name)
+})))(members(valueOf(lock, `${scope}/required`)));
+/** Everything a client is offered, read off the lock alone: its tools, resources and prompts, each with the words a model sees. */
+export const surfaceOf = (lock) => ({
+    name: valueOf(lock, 'name'), version: valueOf(lock, 'version'),
+    tools: below(lock, 'tool').map((line) => ({ name: nameOf(line), about: line.about ?? '', fields: fieldsOf(lock, line.scope), hints: members(valueOf(lock, `${line.scope}/hints`)) })),
+    resources: below(lock, 'resource').map((line) => ({ name: nameOf(line), about: line.about ?? '', template: line.value ?? '', mime: valueOf(lock, `${line.scope}/mime`) })),
+    prompts: below(lock, 'prompt').map((line) => ({ name: nameOf(line), about: line.about ?? '', text: aboutOf(lock, `${line.scope}/text`), line: aboutOf(lock, `${line.scope}/line`), fields: fieldsOf(lock, line.scope) })),
+});
+export const refusedOn = (lock, platform) => ((supported) => (supported.includes(platform) ? undefined : sayIn(lock)('platform', { platform, supported: supported.join('|') })))(members(valueOf(lock, 'platform/supported')));
+/**
+ * The fields a URI gives a resource template, or none when it is not one of its URIs: {name} matches one path step,
+ * {?a,b} names query fields any of which may be absent, in any order, each decoded.
+ */
+export const matchTemplate = (template, uri) => {
+    const [path = '', query = ''] = template.split('{?');
+    const names = [...path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+    const pattern = new RegExp(`^${path.split(/\{\w+\}/).map((part) => part.replace(/[.*+?^$()|[\]\\]/g, '\\$&')).join('([^/?#]+)')}(?:\\?(.*))?$`);
+    const got = pattern.exec(uri);
+    if (got === null)
+        return undefined;
+    const params = new URLSearchParams(got[names.length + 1] ?? '');
+    return { ...Object.fromEntries(names.map((name, i) => [name, decodeURIComponent(got[i + 1])])),
+        ...Object.fromEntries(query.replace('}', '').split(',').filter(Boolean).flatMap((name) => ((v) => (v === null ? [] : [[name, v]]))(params.get(name)))) };
+};
+/** A said code as the cell head answers with: its state and next from the lock, the next's arguments read from the cell's own fields; a bound refusal a field carries keeps bound's code, head's own beside it. */
+export const cellOf = (lock, key, given) => {
+    const fields = Object.fromEntries(Object.entries(given).filter((e) => e[1] !== undefined)), bound = Object.values(fields).map((v) => /^REFUSE·[\w-]+/.exec(v)?.[0]).find(Boolean);
+    const [tool, args] = [valueOf(lock, `said/${key}/next`), members(valueOf(lock, `said/${key}/next/args`)).map((a) => ((k, v) => [k, v.startsWith('$') ? fields[v.slice(1)] ?? '' : v])(a.split(':')[0], a.slice(a.indexOf(':') + 1)))];
+    return { code: bound ?? `head/${key}`, state: valueOf(lock, `said/${key}/state`), next: tool === 'none' ? { none: aboutOf(lock, `said/${key}/next`) } : { tool, args: Object.fromEntries(args) }, fields, ...(bound ? { head: `head/${key}` } : {}) };
+};
+export const cellLine = (cell) => [`said/${cell.code} state=${cell.state}`, ...('tool' in cell.next ? [`next=${cell.next.tool}`, ...Object.entries(cell.next.args).map(([k, v]) => `next.${k}=${JSON.stringify(v)}`)] : ['next=none', `next.why=${JSON.stringify(cell.next.none)}`]),
+    ...(cell.head ? [`head=${JSON.stringify(cell.head)}`] : []), ...Object.entries(cell.fields).map(([k, v]) => `${k}=${JSON.stringify(v)}`)].join(' ');
+/** An answer as cells and the lines bound printed beside them, read back from what head said: the shape every tool result has. */
+export const shapeOf = (answer) => ({ lines: answer.filter((l) => !l.startsWith('said/')),
+    cells: answer.filter((l) => l.startsWith('said/')).map((l) => ((code, rest) => ((t) => ({ code, state: t['state'] ?? '', next: t['next'] === 'none' || t['next'] === undefined ? { none: t['next.why'] ?? '' } : { tool: t['next'], args: Object.fromEntries(Object.entries(t).filter(([k]) => k.startsWith('next.')).map(([k, v]) => [k.slice(5), v])) },
+        fields: Object.fromEntries(Object.entries(t).filter(([k]) => !['state', 'next', 'head'].includes(k) && !k.startsWith('next.'))), ...(t['head'] ? { head: t['head'] } : {}) }))(Object.fromEntries([...rest.matchAll(/(\S+?)=("(?:[^"\\]|\\.)*"|\S+)/g)].map((m) => [m[1], m[2].startsWith('"') ? JSON.parse(m[2]) : m[2]]))))(l.slice('said/'.length, l.indexOf(' ')), l.slice(l.indexOf(' ') + 1))) });
+/** The one output schema every tool declares: cells in the states the lock names, and the lines bound printed. */
+export const shapeSchema = (lock) => ({ type: 'object', required: ['cells', 'lines'], properties: {
+        cells: { type: 'array', items: { type: 'object', required: ['code', 'state', 'next', 'fields'], properties: { code: { type: 'string' }, state: { enum: [...members(valueOf(lock, 'shape/states'))] }, head: { type: 'string' },
+                    next: { oneOf: [{ type: 'object', required: ['tool', 'args'], properties: { tool: { type: 'string' }, args: { type: 'object', additionalProperties: { type: 'string' } } } }, { type: 'object', required: ['none'], properties: { none: { type: 'string' } } }] },
+                    fields: { type: 'object', additionalProperties: { type: 'string' } } } } },
+        lines: { type: 'array', items: { type: 'string' } }
+    } });

package/dist/src/ports/warm.d.ts

@@ -0,0 +1,19 @@
+import type { Bounds, Printed } from './process.ts';
+/** How many processes head keeps started ahead of each program while it answers a call, and the variables node reads as it starts: a process started under other values of them is never asked. */
+export declare const warmth: {
+    spares: number;
+    boot: readonly string[];
+};
+/** Keeps as many processes started ahead of a program as head's lock says; resolved when each has loaded what it runs. */
+export declare const kept: (program: string) => Promise<unknown>;
+/** Every process still waiting to be asked is stopped: head keeps none past the call it started them for. */
+export declare const cooled: () => void;
+/**
+ * A program run in a process started ahead under the same starting variables, handed the folder, arguments and
+ * variables a process started now would get, and watched within the same bounds; undefined when none is held ready,
+ * so the caller starts one as before and never waits on one still loading. Each process answers one ask and ends.
+ */
+export declare const warmed: (program: string, args: readonly string[], at: {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+}, bounds: Bounds) => Promise<Printed> | undefined;