@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/client/admin-cli.js

@@ -0,0 +1,370 @@
+// The operator's admin commands (#124, #142, #143): each builds root's messages (admin.ts, plan.ts), signs
+// them in this process with the operator's key (SKEIN_OPERATOR_KEY, default $SKEIN_HOME/operator.key;
+// hostenv.ts) and delivers them (target.ts) — no other process, no wallet command.
+//
+//   skein install <catalog-name | url#commit | dir> <where> [--config <file.json>] [--dry-run]
+//   skein uninstall <app> <where> [--dry-run]
+//   skein routes add|remove [--transport t] [--prefix] [--filters f,g] [--fn f] [--settings json] <address> [<handler>] <where> [--dry-run]
+//   skein grant add|remove <key> [--role root|<app>.<role>] <where> [--dry-run]
+//   skein peers add <key> <address> [--transport mailbox|libp2p|local] [--handle h@d] <where> [--dry-run]
+//   skein peers remove <key> <where> [--dry-run]
+//   skein host add|remove (<host-key> --x sats [--rates json] | --from <host origin>) <where> [--dry-run]
+//   skein claim [--messagebox url] [--handle h@d] <where> [--dry-run]
+//   skein deploy <dir> [--only glob,glob | --all] <where> [--dry-run]
+//
+// <where> is the instance: `--instance <handle>` (on this host machine: host.db's row, its store read
+// read-only, the messages over the running host's control socket), or its origin `<url>` (one BRC-104
+// session: the messages, and the explorer's reads — the owner's), or `--store <runtime.db>` (its store
+// file, read-only: planned and printed, nothing sent). `--dry-run` prints the prompt and the messages
+// (their `/sendMessage` JSON, one a line) and sends nothing.
+//
+// `install` of a catalog name or `<url>#<commit>` sends one message to the instance's git app — `git.clone
+// {url, hash}`: the VM fetches that commit by hash and keeps its tree (#91) — reads the answer, plans the
+// install from the stored tree, and sends the head, the rows and the start: nothing of the app's tree or
+// modules crosses from here. A catalog name is looked up in the instance's own site tree
+// (www/catalog.json). A directory is read here and its objects sent (what the instance lacks); installing
+// a tree the instance holds already (an app installed before, an image's app) sends only what changes:
+// the owner's rows after a claim. `--dry-run` with a clone still sends the clone (the tree is read from the
+// instance), then sends nothing more.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { appHead, readStoredApp } from "../host/plan.js";
+import { identityOf, operatorKey } from "../host/hostenv.js";
+import { keyWallet } from "../wallet.js";
+import { catalogOf, messageJson, planClaim, planDeploy, planGrant, planHost, planInstallApp, planPeers, planRoute, planUninstallApp } from "./admin.js";
+import { localTarget, remoteTarget, stdoutOf } from "./target.js";
+export const ADMIN_USAGE = `usage (the operator's messages, signed with SKEIN_OPERATOR_KEY, default $SKEIN_HOME/operator.key):
+  skein install <catalog-name | url#commit | dir> <where> [--config <file.json>] [--dry-run]
+                                                     an app (docs/APPS.md §3): a name from the instance's catalog or a repository
+                                                     and commit, cloned by the instance's git app; head <app>/app, its rows, start
+  skein uninstall <app> <where> [--dry-run]          its stop, then its routes removed (the heads are left)
+  skein routes add [--transport mailbox|event|http|libp2p] [--prefix] [--filters f,g] [--fn f] [--settings json] <address> [<handler>] <where> [--dry-run]
+                                                     root's own route (#143): <handler> a program record CID, a genesis program,
+                                                     or <app>.<role>; an http route with --filters and no handler is a read route
+                                                     (the site at /: routes add --prefix --filters site.get --settings '{"root":"www"}' /)
+  skein routes remove [--transport t] [--prefix] <address> <where> [--dry-run]
+  skein grant add|remove <key> [--role root|<app>.<role>] <where> [--dry-run]     a grant (#143; root by default)
+  skein peers add <key> <address> [--transport mailbox|libp2p|local] [--handle h@d] <where> [--dry-run]
+  skein peers remove <key> <where> [--dry-run]      an address-book entry (#70)
+  skein host add|remove (<host-key> --x sats [--rates json] | --from <host origin>) <where> [--dry-run]
+                                                     the host row (#130)
+  skein claim [--messagebox url] [--handle h@d] <where> [--dry-run]               an image's claim (#127, #143): root to the key that sends it
+  skein deploy <dir> [--only glob,glob | --all] <where> [--dry-run]               a directory into main (objects, head)
+<where>: --instance <handle> (this host machine: over its control socket) | <origin> (one BRC-104 session)
+         | --store <runtime.db> (read only: planned and printed, nothing sent)`;
+export const ADMIN_COMMANDS = ["install", "uninstall", "routes", "grant", "peers", "host", "claim", "deploy"];
+const where = { instance: { type: "string" }, store: { type: "string" }, "dry-run": { type: "boolean" } };
+const isUrl = (s) => /^https?:\/\/[^/]/.test(s);
+async function sessionOf(v, origin, env) {
+    const given = [v.instance !== undefined, origin !== undefined, v.store !== undefined].filter(Boolean).length;
+    if (given !== 1)
+        throw new Error("where is the instance: --instance <handle>, its origin <url>, or --store <runtime.db> (one)");
+    if (v.store !== undefined) {
+        const { openStoreFile, storeExists } = await import("../host/stores.js");
+        if (!storeExists(v.store))
+            throw new Error(`--store ${v.store}: no such file (or LMDB set, lmdb:<env dir>#<set>)`);
+        const { instanceView } = await import("../host/install.js");
+        const s = openStoreFile(v.store, { readOnly: true });
+        let view;
+        try {
+            view = await instanceView(s);
+        }
+        catch (e) {
+            s.close();
+            throw e;
+        }
+        return { view: async () => view, identity: async () => view.identity, dry: true, close: async () => s.close() };
+    }
+    const key = operatorKey(env.vars).key;
+    const wallet = keyWallet(key);
+    const target = v.instance !== undefined ? localTarget(env.vars, v.instance, wallet) : await remoteTarget(origin, wallet);
+    return { target, view: () => target.view(), identity: async () => target.identity, dry: !!v["dry-run"], close: () => target.close(), signer: key.toPublicKey().toString() };
+}
+/** The origin among the positionals: the last one when it is a URL and the command takes one more than it needs. */
+function splitOrigin(positionals, needs) {
+    if (positionals.length === needs + 1 && isUrl(positionals.at(-1)))
+        return { args: positionals.slice(0, -1), origin: positionals.at(-1) };
+    return { args: positionals };
+}
+const json = (what, text) => {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch {
+        v = undefined;
+    }
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw new Error(`${what}: a JSON object`);
+    return v;
+};
+/** Print the plan; unless it is a dry run, send its messages in order (signed here, over the target). */
+async function deliver(p, s, env) {
+    for (const l of p.prompt)
+        env.out(l);
+    if (s.dry || !s.target) {
+        for (const m of p.messages)
+            env.out(messageJson(p.recipient, m));
+        env.out(`${p.messages.length} message${p.messages.length === 1 ? "" : "s"} to ${p.recipient} (not sent)`);
+        return 0;
+    }
+    const t0 = Date.now();
+    for (const m of p.messages)
+        await s.target.send(m.box, m.body);
+    env.out(`${s.target.where}: ${p.messages.length} message${p.messages.length === 1 ? "" : "s"} sent (${Date.now() - t0} ms)`);
+    return 0;
+}
+/** `skein <command> …` for the admin commands. */
+export async function adminMain(cmd, argv, env) {
+    let s;
+    try {
+        switch (cmd) {
+            case "install": {
+                const { values: v, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { ...where, config: { type: "string" } } });
+                const { args: [spec, ...more], origin } = splitOrigin(positionals, 1);
+                if (!spec || more.length) {
+                    env.err(ADMIN_USAGE);
+                    return 2;
+                }
+                const config = v.config !== undefined ? json(`--config ${v.config}`, readFileSync(v.config, "utf8")) : undefined;
+                s = await sessionOf(v, origin, env);
+                return await install(spec, s, config, env);
+            }
+            case "uninstall": {
+                const { values: v, positionals } = parseArgs({ args: argv, allowPositionals: true, options: where });
+                const { args: [app, ...more], origin } = splitOrigin(positionals, 1);
+                if (!app || more.length) {
+                    env.err(ADMIN_USAGE);
+                    return 2;
+                }
+                s = await sessionOf(v, origin, env);
+                return await deliver(await planUninstallApp(app, await s.view()), s, env);
+            }
+            case "routes": {
+                const { values: v, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { ...where, transport: { type: "string" }, prefix: { type: "boolean" }, filters: { type: "string" }, fn: { type: "string" }, settings: { type: "string" } } });
+                const origin = positionals.length > 1 && isUrl(positionals.at(-1)) ? positionals.at(-1) : undefined;
+                const [op, address, handler, ...more] = origin ? positionals.slice(0, -1) : positionals;
+                if (!address || more.length || (op !== "add" && op !== "remove") || (op === "remove" && handler !== undefined)) {
+                    env.err(ADMIN_USAGE);
+                    return 2;
+                }
+                const settings = v.settings !== undefined ? json("skein routes --settings", v.settings) : undefined;
+                const filters = v.filters !== undefined ? v.filters.split(",").map((x) => x.trim()).filter(Boolean) : undefined;
+                s = await sessionOf(v, origin, env);
+                const programs = handler ? await handlerPrograms(s, handler) : {};
+                return await deliver(await planRoute(await s.view(), { op, address, ...(v.transport ? { transport: v.transport } : {}), ...(v.prefix ? { prefix: true } : {}), ...(filters ? { filters } : {}), ...(handler ? { handler } : {}), ...(v.fn ? { fn: v.fn } : {}), ...(settings ? { settings } : {}) }, programs), s, env);
+            }
+            case "grant": {
+                const { values: v, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { ...where, role: { type: "string" } } });
+                const { args: [op, key, ...more], origin } = splitOrigin(positionals, 2);
+                if (!key || more.length || (op !== "add" && op !== "remove")) {
+                    env.err(ADMIN_USAGE);
+                    return 2;
+                }
+                s = await sessionOf(v, origin, env);
+                return await deliver(await planGrant(await s.view(), key, { ...(v.role ? { role: v.role } : {}), ...(op === "remove" ? { remove: true } : {}) }), s, env);
+            }
+            case "peers": {
+                const { values: v, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { ...where, transport: { type: "string" }, handle: { type: "string" } } });
+                const op = positionals[0];
+                const { args: [, key, address, ...more], origin } = splitOrigin(positionals, op === "remove" ? 2 : 3);
+                const shape = op === "remove" ? !!key && !address : op === "add" ? !!key && !!address : false;
+                if (more.length || !shape || ((v.transport ?? v.handle) !== undefined && op !== "add")) {
+                    env.err(ADMIN_USAGE);
+                    return 2;
+                }
+                const transport = (v.transport ?? "mailbox");
+                if (!["mailbox", "libp2p", "local"].includes(transport)) {
+                    env.err("skein peers: --transport is mailbox, libp2p or local");
+                    return 2;
+                }
+                if (op === "add" && transport === "mailbox" && !isUrl(address)) {
+                    env.err(`skein peers: ${address} is not an http(s) URL`);
+                    return 2;
+                }
+                const named = v.handle !== undefined ? handleOf(v.handle) : {};
+                const change = op === "add" ? { op: "add", key: key, transport, address: address, ...named } : { op: "remove", key: key };
+                s = await sessionOf(v, origin, env);
+                return await deliver(planPeers(await s.identity(), [change]), s, env);
+            }
+            case "claim": {
+                const { values: v, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { ...where, messagebox: { type: "string" }, handle: { type: "string" } } });
+                const { args: more, origin } = splitOrigin(positionals, 0);
+                if (more.length) {
+                    env.err(ADMIN_USAGE);
+                    return 2;
+                }
+                if (v.messagebox !== undefined && !isUrl(v.messagebox)) {
+                    env.err(`skein claim: ${v.messagebox} is not an http(s) URL`);
+                    return 2;
+                }
+                const named = v.handle !== undefined ? handleOf(v.handle) : {};
+                s = await sessionOf(v, origin, env);
+                const p = planClaim(await s.identity(), { messagebox: v.messagebox, ...named });
+                if (s.dry || !s.target)
+                    return await deliver(p, s, env);
+                for (const l of p.prompt)
+                    env.out(l);
+                await s.target.claim(p.messages[0].body);
+                env.out(`${s.target.where}: the claim sent`);
+                return 0;
+            }
+            case "host": {
+                const { values: v, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { ...where, x: { type: "string" }, rates: { type: "string" }, from: { type: "string" } } });
+                const { args: [op, key, ...more], origin } = splitOrigin(positionals, v.from !== undefined ? 1 : 2);
+                if (more.length || (op !== "add" && op !== "remove") || (!key && v.from === undefined) || (key && v.from !== undefined)) {
+                    env.err(ADMIN_USAGE);
+                    return 2;
+                }
+                let terms;
+                if (v.from !== undefined) {
+                    const r = await fetch(new URL("/.well-known/skein-host", v.from));
+                    const b = (await r.json()).billing;
+                    if (!r.ok || !b)
+                        throw new Error(`${v.from}: no billing terms at /.well-known/skein-host`);
+                    terms = { key: b.key, x: b.x, rates: b.rates };
+                }
+                else {
+                    const rates = v.rates !== undefined ? json("skein host --rates", v.rates) : undefined;
+                    terms = { key: key, x: Number(v.x ?? (op === "remove" ? 1 : NaN)), ...(rates ? { rates } : {}) };
+                }
+                s = await sessionOf(v, origin, env);
+                return await deliver(planHost(await s.identity(), op, terms), s, env);
+            }
+            case "deploy": {
+                const { values: v, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { ...where, only: { type: "string" }, all: { type: "boolean" } } });
+                const { args: [dir, ...more], origin } = splitOrigin(positionals, 1);
+                if (!dir || more.length || (v.all && v.only !== undefined)) {
+                    env.err(ADMIN_USAGE);
+                    return 2;
+                }
+                const only = v.all ? [] : v.only !== undefined ? v.only.split(",").map((x) => x.trim()).filter(Boolean) : undefined;
+                s = await sessionOf(v, origin, env);
+                return await deliver(await planDeploy(resolve(dir), await s.view(), { only }), s, env);
+            }
+            default:
+                env.err(ADMIN_USAGE);
+                return 2;
+        }
+    }
+    catch (e) {
+        env.err(`skein ${cmd}: ${e.message}`);
+        return 1;
+    }
+    finally {
+        await s?.close();
+    }
+}
+function handleOf(given) {
+    const h = given.replace(/^@/, "");
+    const at = h.lastIndexOf("@");
+    const named = at > 0 ? { handle: h.slice(0, at), domain: h.slice(at + 1) } : { handle: h };
+    if (!named.handle || (at > 0 && !named.domain))
+        throw new Error(`--handle ${given}: want handle@domain`);
+    return named;
+}
+/** The programs a handler may name (#125): the genesis's by name, and `<app>.<role>` — the installed app's. */
+async function handlerPrograms(s, handler) {
+    const role = /^([a-z0-9][a-z0-9-]*)\.([A-Za-z0-9_-]+)$/.exec(handler);
+    const needsView = !!role || !/^baf/.test(handler);
+    if (!needsView)
+        return {};
+    const view = await s.view();
+    const programs = { ...view.programs };
+    if (role && !programs[handler]) {
+        const { appRecordIn } = await import("../host/plan.js");
+        const app = await appRecordIn(view, role[1]);
+        if (!app)
+            throw new Error(`handler ${handler}: no app ${role[1]} installed (no head ${role[1]}/app)`);
+        const cid = app.record.programs[role[2]];
+        if (!cid)
+            throw new Error(`handler ${handler}: app ${role[1]} has no program ${role[2]} (${Object.keys(app.record.programs).join(", ")})`);
+        programs[handler] = cid;
+    }
+    return programs;
+}
+const hexOf = (k) => (k instanceof Uint8Array ? Buffer.from(k).toString("hex") : typeof k === "string" ? k : "");
+/**
+ * `skein install`: the tree — a directory read here, or a commit the instance's git app clones by hash (a
+ * catalog name gives the URL and the commit) — then the plan from it, printed, and its messages sent.
+ */
+async function install(spec, s, config, env) {
+    const { wasmDirObjects, WASM_DIR } = await import("../host/boot.js");
+    let view = await s.view();
+    let tree;
+    let cloned;
+    if (existsSync(spec) && statSync(spec).isDirectory()) {
+        const { readApp } = await import("../host/install.js");
+        tree = await readApp(resolve(spec));
+    }
+    else {
+        let url, hash;
+        const m = /^(.+)#([0-9a-fA-F]{40})$/.exec(spec);
+        if (m) {
+            url = m[1];
+            hash = m[2].toLowerCase();
+        }
+        else if (/^[a-z0-9][a-z0-9-]*$/.test(spec)) {
+            const cat = await catalogOf(view);
+            const e = cat.find((x) => x.name === spec);
+            if (!e)
+                throw new Error(`${spec}: not in the instance's catalog (it names ${cat.map((x) => x.name).join(", ") || "nothing"}); give <url>#<commit>`);
+            url = e.url;
+            hash = e.hash.toLowerCase();
+            env.out(`catalog: ${e.name}${e.version ? ` ${e.version}` : ""} = ${url}#${hash}`);
+        }
+        else
+            throw new Error(`${spec}: a catalog name, <url>#<40-hex commit>, or a directory`);
+        if (!s.target)
+            throw new Error("--store reads a store file: it cannot ask the instance's git app to clone (give a directory, or --instance / an origin)");
+        // #143: the git app's box is a route; its function is gated by root (git's roles) — the gate judges the sender.
+        const gitRoute = view.dispatch.find((r) => r.transport === "mailbox" && r.address === "git");
+        if (!gitRoute) {
+            throw new Error(`the instance has no route to box git${view.heads.some((h) => h.name === appHead("git")) ? "" : " (no git app installed)"}`);
+        }
+        // The gate, read before anything is sent (the kernel's own check runs on the message; a refused one runs nothing).
+        const { gatePasses } = await import("./admin.js");
+        const gate = await gatePasses(view, gitRoute, s.signer);
+        if (!gate.pass)
+            throw new Error(`box git is gated (${gate.roles.join(", ")}) and ${s.signer.slice(0, 10)}… holds none of those roles: nothing sent`);
+        const t0 = Date.now();
+        const id = await s.target.send("git", { fn: "git.clone", args: { url, hash } });
+        const end = await s.target.answer(id);
+        if (end.state === "errored")
+            throw new Error(`git.clone: the git app's thread errored: ${JSON.stringify(end.error ?? {})}`);
+        const out = stdoutOf(end);
+        if (out?.error)
+            throw new Error(`git.clone: ${out.error.code}: ${out.error.message}`);
+        if (!out?.result?.tree || !out.result.app)
+            throw new Error(`git.clone: no {tree, app} in the answer (${JSON.stringify(out)})`);
+        cloned = { tree: out.result.tree, app: out.result.app };
+        env.out(`git.clone ${url}#${hash}: tree ${cloned.tree} · app record ${cloned.app} (${Date.now() - t0} ms, in the instance)`);
+        view = await s.view();
+        tree = await readStoredApp(view.store, cloned.tree);
+    }
+    const p = await planInstallApp(tree, view, { config, modules: wasmDirObjects(WASM_DIR) });
+    if (cloned && !config && !p.recordCid.equals(cloned.app))
+        p.prompt.push(`  note      the plan's app record ${p.recordCid} is not the git app's ${cloned.app}`);
+    await deliver(p, s, env);
+    if (s.dry || !s.target)
+        return 0;
+    // Installed when its head names the record (the kernel takes the messages in order).
+    // Its start may move the head on at once (the app's `state`): the record without `state` is what counts.
+    const { encode } = await import("../runtime/cid.js");
+    const bare = (r) => { const { state: _s, ...rest } = r; void _s; return encode(rest).cid; };
+    const want = bare(p.record);
+    const deadline = Date.now() + 120_000;
+    for (;;) {
+        const v = await s.view();
+        const root = v.heads.find((h) => h.name === appHead(p.app))?.root;
+        const rec = root ? await v.store.get(root).catch(() => undefined) : undefined;
+        if (rec && bare(rec).equals(want))
+            break;
+        if (Date.now() > deadline)
+            throw new Error(`${p.app}: head ${appHead(p.app)} does not name ${p.recordCid} after 120 s (the instance's log says why)`);
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    env.out(`installed ${p.app} ${p.version} into ${s.target.where}`);
+    return 0;
+}

package/dist/client/admin.d.ts

@@ -0,0 +1,139 @@
+import type { CID } from "multiformats/cid";
+import { type DispatchRow } from "../runtime/dispatch.ts";
+import { type AddressEntry } from "../host/deploy.ts";
+import { type AppRecord, type AppTree, type InstanceView } from "../host/plan.ts";
+import type { Objects } from "../host/boot.ts";
+/** One admin message: the box and the body (a record value: what the kernel's operation takes). */
+export interface AdminMessage {
+    box: string;
+    body: unknown;
+}
+/** What the admin commands build: the prompt (what the messages do, as the page shows it), the recipient, the messages in order. */
+export interface AdminPlan {
+    prompt: string[];
+    recipient: string;
+    messages: AdminMessage[];
+}
+/** A message as the `/sendMessage` JSON body. */
+export declare function messageJson(recipient: string, m: AdminMessage): string;
+/**
+ * Install (or upgrade) the app `tree` into the instance `view` reads (docs/APPS.md §3): objects (≤ 1 MiB
+ * bundles), the head `<app>/app`, a dispatch message per row that changes, the start. `config` is merged
+ * over the manifest's (one level deep per program). `modules`: where a `bin/<x>.cid` module the instance
+ * lacks is found (this repo's wasm/ directory, boot.ts wasmDirObjects).
+ */
+export declare function planInstallApp(tree: AppTree, view: InstanceView, o?: {
+    config?: Record<string, unknown>;
+    modules?: Objects;
+}): Promise<AdminPlan & {
+    app: string;
+    version: string;
+    recordCid: CID;
+    record: AppRecord;
+}>;
+/** Uninstall: the app's `stop`, then every route the table holds for it removed; its heads are left. */
+export declare function planUninstallApp(name: string, view: InstanceView): Promise<AdminPlan>;
+/** One of root's own routes as `skein routes` takes it (#143). */
+export interface RouteArgs {
+    op: "add" | "remove";
+    transport?: "mailbox" | "event" | "http" | "libp2p";
+    address: string;
+    prefix?: boolean;
+    filters?: string[];
+    /** A program record CID, a genesis program's name, or `<app>.<role>` (resolved by the caller into `programs`); none: an http read route. */
+    handler?: string;
+    fn?: string;
+    settings?: Record<string, unknown>;
+}
+/**
+ * Root's own route (#125, #143; `skein routes`): one `dispatch` add or remove of a route with no `app` —
+ * an app's upgrade or uninstall leaves it. A mailbox or event route at a box, an http route at a path
+ * (with `filters` and a handler's `fn`, or filters only: a read route — the site at `/`: filters
+ * ["site.get"], settings {root: "www"}), a libp2p route at a topic. No sender (#143). A remove names the
+ * key (transport, address, prefix) only.
+ */
+export declare function planRoute(view: InstanceView, a: RouteArgs, programs?: Record<string, CID>): Promise<AdminPlan>;
+/**
+ * The claim (#89, #127, #143): one message in box `claim` to an image (its claim route takes anyone) —
+ * its sender (the wallet that sends it) is granted root; the body carries only the claimant's
+ * mailbox entry, if any.
+ */
+export declare function planClaim(recipient: string, o?: {
+    messagebox?: string;
+    handle?: string;
+    domain?: string;
+}): AdminPlan;
+/** The host's terms as it publishes them (/.well-known/skein-host `billing`, #130). */
+export interface HostTerms {
+    key: string;
+    x: number;
+    rates?: Record<string, number>;
+}
+/**
+ * The host row (#130): root's choice of a host and its rates — one `dispatch` message adding (or
+ * removing) the kernel route {mailbox, billing, host: <the host's key>, kernel, tick, x, rates} (#143:
+ * the host's key a setting, no sender). The first such route is the host's; the kernel bills by it,
+ * the host ticks it. Removing it ends billing.
+ */
+export declare function planHost(recipient: string, op: "add" | "remove", t: HostTerms): AdminPlan;
+export type PeerChange = ({
+    op: "add";
+} & AddressEntry) | {
+    op: "remove";
+    key: string;
+};
+/** Address-book changes (#40, #70): one message to `peers` each. */
+export declare function planPeers(recipient: string, changes: PeerChange[]): AdminPlan;
+/**
+ * A directory into the instance's `main` (#23): its git objects in ≤ 1 MiB bundles to `objects`, the root
+ * on the last (the kernel sets `main` when there is none), then `head {name: "main", tree}` when `main` is
+ * another tree. `only` filters the directory (deploy.ts onlyIgnore; default DEFAULT_ONLY; [] for all of it).
+ * Records the view's store has are not sent. With no view (`recipient` alone) everything is sent, and the head.
+ */
+export declare function planDeploy(dir: string, target: InstanceView | {
+    identity: string;
+}, o?: {
+    only?: string[];
+}): Promise<AdminPlan & {
+    root: CID;
+}>;
+/**
+ * A read of the instance's explorer (`/explore…`; root's, #121, #143): the answer DAG-JSON decoded, undefined
+ * for a 404 — the client's on its BRC-104 session (target.ts remoteTarget).
+ */
+export type ExplorerRead = (path: string) => Promise<unknown>;
+/**
+ * The instance as the install plan reads it (plan.ts InstanceView), from its explorer: heads, the genesis
+ * (identity, programs), the address book, the route table, and the store by CID —
+ * what the management page's view reads (shruggr/skein-site www/app.js `Skein.view`).
+ */
+export declare function explorerView(read: ExplorerRead): Promise<InstanceView>;
+/**
+ * A grant (#142, #143; `skein-host grant`): the kernel's `grant` operation — `role` (root by default,
+ * or an app's `<app>.<role>`) to `key`, or with `remove` from it. One message to box `grant`, sent by
+ * root. Nothing is sent when the grants already say so.
+ */
+export declare function planGrant(view: InstanceView, key: string, o?: {
+    role?: string;
+    remove?: boolean;
+}): Promise<AdminPlan>;
+/** One app the management page offers (the site's www/catalog.json): a repository and a commit. */
+export interface CatalogEntry {
+    name: string;
+    version?: string;
+    url: string;
+    hash: string;
+    image?: string;
+    description?: string;
+}
+/** The catalog in the instance's own site tree (its app `site`: www/catalog.json), and the names in it. */
+export declare function catalogOf(view: InstanceView): Promise<CatalogEntry[]>;
+/**
+ * The kernel's gate (#143, kernel-zig/src/grants.zig), read from the instance's view: the roles that
+ * gate a route's handler (its app's `roles` for its fn; a kernel admin box's is root) and whether
+ * `key` passes them. Root passes anything; `user` passes any key; no gating roles: open.
+ */
+export declare function gatePasses(view: InstanceView, row: DispatchRow, key: string): Promise<{
+    pass: boolean;
+    roles: string[];
+}>;