kubun 0.11.0 → 0.12.1

package/lib/commands/graph.js

@@ -9,8 +9,10 @@ function parseVariables(value) {
     }
     try {
         return JSON.parse(value);
-    } catch  {
-        throw new Error(`--variables is not valid JSON: ${value}`);
+    } catch (cause) {
+        throw new Error(`--variables is not valid JSON: ${value}`, {
+            cause
+        });
     }
 }
 function createMutateCommand() {

package/lib/commands/hub.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createHubCommand(): Command;

package/lib/commands/hub.js

@@ -0,0 +1,105 @@
+import { getKubunLogger } from '@kubun/logger';
+import { configureSync, getConsoleSink } from '@logtape/logtape';
+import { Command } from 'commander';
+import { startHub } from '../hub.js';
+import { withAllowedOrigin, withLogLevel, withPort, withPrivateKey } from '../options.js';
+import { renderNotice, withSpinner } from '../ui.js';
+/**
+ * Resolve who the relay accepts. Exactly one of the two flags is required: a
+ * hub started with neither would run refusing every DID, which looks like a
+ * broken hub rather than a missing decision.
+ */ function resolveHubAuth(opts) {
+    if (opts.acceptDid != null && opts.acceptAll) {
+        throw new Error('--accept-did and --accept-all are mutually exclusive');
+    }
+    if (opts.acceptDid == null && !opts.acceptAll) {
+        throw new Error('one of --accept-did or --accept-all is required');
+    }
+    if (opts.acceptAll) {
+        return {
+            mode: 'open'
+        };
+    }
+    const allowedDIDs = (opts.acceptDid ?? '').split(',').map((did)=>did.trim()).filter(Boolean);
+    if (allowedDIDs.length === 0) {
+        throw new Error('--accept-did lists no DID');
+    }
+    // A wildcard in the list would match no issuer and quietly deny everyone, so
+    // the operator asking for open is sent to the flag that means it.
+    if (allowedDIDs.includes('*')) {
+        throw new Error('--accept-did takes DIDs, not a wildcard. Use --accept-all to accept any DID.');
+    }
+    return {
+        mode: 'allowlist',
+        allowedDIDs
+    };
+}
+export function createHubCommand() {
+    const cmd = new Command('hub').description('Start a blind relay hub for groups this process is not a member of').option('--accept-did <dids>', 'comma-separated DIDs allowed to use the relay').option('--accept-all', 'accept every signed DID (development only)').option('--db <path>', 'path to the hub database');
+    withAllowedOrigin(cmd);
+    withLogLevel(cmd);
+    withPort(cmd);
+    withPrivateKey(cmd);
+    cmd.action(async (opts)=>{
+        const auth = resolveHubAuth(opts);
+        configureSync({
+            reset: true,
+            sinks: {
+                console: getConsoleSink()
+            },
+            loggers: [
+                {
+                    category: [
+                        'logtape',
+                        'meta'
+                    ],
+                    lowestLevel: 'error',
+                    sinks: [
+                        'console'
+                    ]
+                },
+                {
+                    category: [
+                        'kubun'
+                    ],
+                    lowestLevel: opts.logLevel ?? 'warning',
+                    sinks: [
+                        'console'
+                    ]
+                }
+            ]
+        });
+        if (auth.mode === 'open') {
+            const logger = getKubunLogger('cli');
+            logger.warn('================================================================');
+            logger.warn('  RELAY AUTH IS OPEN — --accept-all');
+            logger.warn('  Any signed token from any DID will be accepted.');
+            logger.warn('  Never use this setting in production.');
+            logger.warn('================================================================');
+        }
+        const port = opts.port == null ? undefined : typeof opts.port === 'number' ? opts.port : Number.parseInt(opts.port, 10);
+        const hub = await withSpinner('Starting the hub...', ()=>startHub({
+                auth,
+                ...opts.db == null ? {} : {
+                    db: opts.db
+                },
+                ...opts.privateKey == null ? {} : {
+                    privateKey: opts.privateKey
+                },
+                ...opts.allowedOrigin == null ? {} : {
+                    allowedOrigin: opts.allowedOrigin
+                },
+                ...port == null ? {} : {
+                    port
+                }
+            }));
+        const accepted = auth.mode === 'open' ? 'any signed DID' : `${auth.allowedDIDs?.length ?? 0} DID(s)`;
+        renderNotice('success', `Hub relay listening at ${hub.url}\n  DID: ${hub.did}\n  Accepting: ${accepted}`);
+        await new Promise((resolve)=>{
+            process.once('SIGINT', resolve);
+            process.once('SIGTERM', resolve);
+        });
+        await hub.dispose();
+    });
+    return cmd;
+}

package/lib/commands/model.js

@@ -5,8 +5,10 @@ import { renderNotice } from '../ui.js';
 function parseJSON(label, value) {
     try {
         return JSON.parse(value);
-    } catch  {
-        throw new Error(`${label} is not valid JSON: ${value}`);
+    } catch (cause) {
+        throw new Error(`${label} is not valid JSON: ${value}`, {
+            cause
+        });
     }
 }
 function createClusterCommand() {

package/lib/commands/peer.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createPeerCommand(): Command;

package/lib/commands/peer.js

@@ -0,0 +1,275 @@
+import { getKubunLogger } from '@kubun/logger';
+import { Command } from 'commander';
+import { announceSelf, buildEngine, createAdapter, deployPeerGraph } from '../engine.js';
+import { resolveIdentity } from '../identity.js';
+import { withLogLevel, withPrivateKey } from '../options.js';
+import { renderNotice } from '../ui.js';
+const PREPARE_JOIN_REQUEST = 'mutation { prepareJoinRequest { joinRequest } }';
+const COMPLETE_JOIN = `mutation($invitePayload: String!, $send: ShareInput, $receive: ShareReceiveInput) {
+  completeJoin(invitePayload: $invitePayload, send: $send, receive: $receive) { group { id name } }
+}`;
+const CREATE_GROUP = `mutation($name: String!, $url: URL!) {
+  createGroup(input: { name: $name, hubs: [{ url: $url }] }) { group { id name } }
+}`;
+const ADMIT = `mutation($groupID: ID!, $joinRequest: String!, $send: ShareInput, $receive: ShareReceiveInput) {
+  admitJoinRequest(groupID: $groupID, joinRequest: $joinRequest, send: $send, receive: $receive) {
+    peerDID
+    invitePayload
+  }
+}`;
+const GROUPS = '{ groups { id name } }';
+const PEER_DEVICES = `query($groupID: ID!) {
+  peerDevices(groupID: $groupID) { peerDID label availability }
+}`;
+const SYNC_PEER = `mutation($groupID: ID!, $peerDID: ID!) {
+  syncPeer(groupID: $groupID, peerDID: $peerDID) {
+    messagesSent
+    messagesReceived
+    divergentBuckets
+  }
+}`;
+/** `--send a,b` as the `ShareInput` the admission mutations take, or null for none. */ function shareInput(models) {
+    if (models == null) return null;
+    const list = models.split(',').map((entry)=>entry.trim()).filter(Boolean);
+    return {
+        models: list
+    };
+}
+/**
+ * Run one p2p mutation against a local device and stop.
+ *
+ * Both halves of the offline exchange are one-shot, but they must land in the
+ * SAME database: `peer request` writes the key material `peer join` consumes,
+ * so a default in-memory adapter would make the pair silently unusable.
+ */ async function withPeerDevice(opts, run) {
+    if (opts.db == null) {
+        throw new Error('--db is required: the join exchange spans two commands and must persist');
+    }
+    const logger = getKubunLogger('cli');
+    const { engine } = buildEngine({
+        identity: resolveIdentity({
+            ...opts,
+            p2p: true
+        }, logger),
+        adapter: createAdapter(opts.db),
+        p2p: {}
+    });
+    const execute = async (kind, id, text, variables)=>{
+        const params = {
+            id,
+            text,
+            ...variables == null ? {} : {
+                variables
+            }
+        };
+        const result = kind === 'mutate' ? await engine.mutateGraph(params) : await engine.queryGraph(params);
+        if (result.errors != null) {
+            throw new Error(result.errors.map((error)=>error.message).join('; '));
+        }
+        if (result.data == null) {
+            throw new Error(`${kind} returned no data`);
+        }
+        return result.data;
+    };
+    try {
+        const id = await deployPeerGraph(engine);
+        return await run({
+            mutate: (text, variables)=>execute('mutate', id, text, variables),
+            query: (text, variables)=>execute('query', id, text, variables),
+            engine,
+            hubReady: async ()=>{
+                const api = await engine.getAPI('p2p');
+                await api.hubReady;
+                return api;
+            }
+        });
+    } finally{
+        await engine.dispose();
+    }
+}
+function withPeerOptions(cmd) {
+    cmd.option('--db <path>', 'path to the local SQLite database');
+    withLogLevel(cmd);
+    withPrivateKey(cmd, {
+        required: true
+    });
+    return cmd;
+}
+export function createPeerCommand() {
+    const cmd = new Command('peer').description('Pair devices, advertise this one, and sync with them');
+    const request = new Command('request').description('Print a join request for another device to admit');
+    withPeerOptions(request);
+    request.action(async (opts)=>{
+        const data = await withPeerDevice(opts, async ({ mutate })=>{
+            return await mutate(PREPARE_JOIN_REQUEST);
+        });
+        // The payload goes to stdout alone so it can be piped; everything else this
+        // command says goes to stderr.
+        process.stdout.write(`${data.prepareJoinRequest.joinRequest}\n`);
+    });
+    const join = new Command('join').description('Complete a join from an invite payload');
+    join.requiredOption('--invite <payload>', 'invite payload minted by the admitting device');
+    // Each device declares its OWN half in the call it already makes. Without
+    // `--send` this device grants nothing back, so the admitter can never pull
+    // what this one authors and the pair syncs one way while looking bidirectional.
+    join.option('--send <models>', 'comma-separated model ids this device shares back');
+    join.option('--receive', 'activate the seeded catalog, so this device pulls the share scope');
+    withPeerOptions(join);
+    join.action(async (opts)=>{
+        const data = await withPeerDevice(opts, async ({ mutate })=>{
+            return await mutate(COMPLETE_JOIN, {
+                invitePayload: opts.invite,
+                send: shareInput(opts.send),
+                receive: opts.receive === true ? {
+                    activate: true
+                } : null
+            });
+        });
+        renderNotice('success', `Joined ${data.completeJoin.group.name}\n  Group: ${data.completeJoin.group.id}`);
+    });
+    const createGroup = new Command('create-group').description('Create a group on this device and bind it to a hub');
+    createGroup.requiredOption('--name <name>', 'group name');
+    createGroup.requiredOption('--hub <url>', 'hub relay URL the group publishes through');
+    withPeerOptions(createGroup);
+    createGroup.action(async (opts)=>{
+        const data = await withPeerDevice(opts, async ({ mutate, hubReady })=>{
+            // Before the group's first commit, not after: the creation commit rides
+            // the relay, and a one-shot process that dials before its relay exists
+            // reports an empty group rather than an unreachable one.
+            await hubReady();
+            return await mutate(CREATE_GROUP, {
+                name: opts.name,
+                url: opts.hub
+            });
+        });
+        renderNotice('success', `Created ${data.createGroup.group.name}\n  Group: ${data.createGroup.group.id}`);
+    });
+    const admit = new Command('admit').description('Admit a join request into a group and print the invite payload');
+    admit.requiredOption('--group <id>', 'group to admit into');
+    admit.requiredOption('--request <payload>', 'join request printed by `peer request`');
+    admit.option('--send <models>', 'comma-separated model ids to share with the admitted device');
+    admit.option('--receive', 'activate the created catalog, so this device pulls the share scope');
+    withPeerOptions(admit);
+    admit.action(async (opts)=>{
+        const data = await withPeerDevice(opts, async ({ mutate, hubReady })=>{
+            // An admission drives an MLS commit whose fan-out to the group's EXISTING
+            // members rides the relay, and `withPeerDevice` disposes the engine the
+            // moment this returns. Without the wait, a group with a third member is a
+            // plausible silently-dropped commit.
+            await hubReady();
+            return await mutate(ADMIT, {
+                groupID: opts.group,
+                joinRequest: opts.request,
+                send: shareInput(opts.send),
+                receive: opts.receive === true ? {
+                    activate: true
+                } : null
+            });
+        });
+        process.stderr.write(`  Admitted: ${data.admitJoinRequest.peerDID}\n`);
+        // The payload alone on stdout, as `peer request` does, so it can be piped.
+        process.stdout.write(`${data.admitJoinRequest.invitePayload}\n`);
+    });
+    const profile = new Command('profile').description('Declare what this device is, so co-members can see it at all');
+    profile.requiredOption('--label <label>', 'display name shown to co-members');
+    profile.option('--availability <tier>', 'always-on | interactive | mobile (default: always-on)', 'always-on');
+    withPeerOptions(profile);
+    profile.action(async (opts)=>{
+        // Commander enforces `--label`, so this only fires if the option is ever
+        // made optional — a cast would go on compiling and announce `undefined`.
+        const label = opts.label;
+        if (label == null) {
+            throw new Error('--label is required');
+        }
+        const availability = opts.availability ?? 'always-on';
+        if (availability !== 'always-on' && availability !== 'interactive' && availability !== 'mobile') {
+            throw new Error(`--availability must be always-on, interactive or mobile, got ${availability}`);
+        }
+        await withPeerDevice(opts, async ({ engine, hubReady })=>{
+            // The announce publishes on each joined group's lane, so the relay has to
+            // be up first or this device advertises only to its own store.
+            await hubReady();
+            await announceSelf(engine, {
+                label,
+                availability
+            });
+        });
+        renderNotice('success', `Announced as ${label} (${availability})`);
+    });
+    const list = new Command('list').description("This group's other devices, and who answered");
+    list.option('--group <id>', 'group to list (default: every joined group)');
+    withPeerOptions(list);
+    list.action(async (opts)=>{
+        const rows = await withPeerDevice(opts, async ({ query, engine, hubReady })=>{
+            const api = await hubReady();
+            // Every announce seeds this device's OWN row, and a device never answers
+            // its own gather — so leaving it in prints this machine as `silent`, which
+            // is both useless and wrong.
+            const selfDID = engine.identity.id;
+            // Named from the store even when `--group` picks one, so the column reads
+            // as a name in both modes rather than as an id in one of them.
+            const joined = (await query(GROUPS)).groups;
+            const groups = opts.group == null ? joined : joined.filter((group)=>group.id === opts.group);
+            if (opts.group != null && groups.length === 0) {
+                throw new Error(`this device has not joined group ${opts.group}`);
+            }
+            const out = [];
+            for (const group of groups){
+                // Announce then gather, as the app's device list does: a device that has
+                // gone quiet should hear this one is here in the same round trip it is
+                // asked to answer.
+                const answered = await api.refreshPeerPresence(group.id);
+                const live = new Set(answered.map((peer)=>peer.peerDID));
+                const devices = await query(PEER_DEVICES, {
+                    groupID: group.id
+                });
+                for (const device of devices.peerDevices){
+                    if (device.peerDID === selfDID) continue;
+                    out.push({
+                        group: group.name,
+                        did: device.peerDID,
+                        label: `${device.label} (${device.availability})`,
+                        live: live.has(device.peerDID)
+                    });
+                }
+            }
+            return out;
+        });
+        if (rows.length === 0) {
+            // Never "no devices": a device that has not announced is invisible here,
+            // which is a different fact from not existing.
+            renderNotice('info', 'No devices have answered yet');
+            return;
+        }
+        for (const row of rows){
+            // "answered" and "silent", never "online"/"offline": the gather reports who
+            // replied inside its window, and asleep is indistinguishable from gone.
+            process.stdout.write(`${row.live ? 'answered' : 'silent  '}  ${row.label}  ${row.did}  [${row.group}]\n`);
+        }
+    });
+    const sync = new Command('sync').description('Catch up with one named device now');
+    sync.argument('<peerDID>', 'the device to sync with');
+    sync.requiredOption('--group <id>', 'group whose hub tunnel routes the session');
+    withPeerOptions(sync);
+    sync.action(async (peerDID, opts)=>{
+        const data = await withPeerDevice(opts, async ({ mutate, hubReady })=>{
+            await hubReady();
+            return await mutate(SYNC_PEER, {
+                groupID: opts.group,
+                peerDID
+            });
+        });
+        const synced = data.syncPeer;
+        // All-zero is a real outcome, not a failure: a device with no ACTIVE catalog
+        // resolving to a concrete owner short-circuits before choosing a direction.
+        renderNotice('success', `Synced with ${peerDID}\n  Messages: ${synced.messagesReceived} in, ${synced.messagesSent} out\n  Divergent buckets: ${synced.divergentBuckets}`);
+    });
+    cmd.addCommand(request);
+    cmd.addCommand(join);
+    cmd.addCommand(createGroup);
+    cmd.addCommand(admit);
+    cmd.addCommand(profile);
+    cmd.addCommand(list);
+    cmd.addCommand(sync);
+    return cmd;
+}

package/lib/commands/serve.js

@@ -1,18 +1,12 @@
-import { NodeSQLiteAdapter } from '@kubun/db-node-sqlite';
-import { PostgresAdapter } from '@kubun/db-postgres';
-import { KubunEngine } from '@kubun/engine';
 import { getKubunLogger } from '@kubun/logger';
-import { createHTTPPlugin } from '@kubun/plugin-http';
-import { createP2PPlugin } from '@kubun/plugin-p2p';
-import { createRPCPlugin } from '@kubun/plugin-rpc';
 import { configureSync, getConsoleSink } from '@logtape/logtape';
 import { Command } from 'commander';
-import { resolvePath } from '../fs.js';
+import { createAdapter, startNode } from '../engine.js';
 import { resolveIdentity } from '../identity.js';
 import { withAllowedOrigin, withLogLevel, withPort, withPrivateKey } from '../options.js';
 import { renderNotice, withSpinner } from '../ui.js';
 export function createServeCommand() {
-    const cmd = new Command('serve').description('Start a local Kubun server').option('--auto-accept-peers <dids>', 'comma-separated DIDs to auto-accept for peer join flows').option('--db <path>', 'path to the local SQLite database').option('--id <id>', 'server ID').option('--p2p', 'enable P2P mode with sync and graph protocols over HTTP');
+    const cmd = new Command('serve').description('Start a local Kubun server').option('--auto-accept-peers <dids>', 'comma-separated DIDs to auto-accept for peer join flows').option('--db <path>', 'path to the local SQLite database').option('--id <id>', 'server ID').option('--label <label>', 'display name advertised to co-members (default: the host name)').option('--no-http', 'run as a hub-only peer, binding no HTTP listener (requires --p2p)').option('--p2p', 'enable P2P mode with sync and graph protocols');
     withAllowedOrigin(cmd);
     withLogLevel(cmd);
     withPort(cmd);
@@ -24,6 +18,9 @@ export function createServeCommand() {
         if (opts.autoAcceptPeers != null && !opts.p2p) {
             throw new Error('--auto-accept-peers requires --p2p');
         }
+        if (!opts.http && !opts.p2p) {
+            throw new Error('--no-http requires --p2p: without either there is nothing to reach');
+        }
         configureSync({
             reset: true,
             sinks: {
@@ -53,56 +50,29 @@ export function createServeCommand() {
         });
         const logger = getKubunLogger('cli');
         const identity = resolveIdentity(opts, logger);
-        const adapter = opts.db == null || opts.db === ':memory:' ? new NodeSQLiteAdapter({
-            database: ':memory:'
-        }) : opts.db.startsWith('postgres://') || opts.db.startsWith('postgresql://') ? new PostgresAdapter({
-            url: opts.db
-        }) : new NodeSQLiteAdapter({
-            database: resolvePath(opts.db)
-        });
         const autoAcceptPeers = opts.autoAcceptPeers ? opts.autoAcceptPeers.split(',').map((s)=>s.trim()) : undefined;
-        const rpcAccessRules = autoAcceptPeers != null ? {
-            '*': {
-                allow: [
-                    identity.id,
-                    ...autoAcceptPeers
-                ]
-            }
-        } : undefined;
         const port = opts.port == null ? undefined : typeof opts.port === 'number' ? opts.port : Number.parseInt(opts.port, 10);
-        const plugins = [
-            createRPCPlugin({
-                ...rpcAccessRules != null ? {
-                    accessRules: rpcAccessRules
+        const { engine, url } = await withSpinner('Starting the server...', async ()=>{
+            return await startNode({
+                identity,
+                adapter: createAdapter(opts.db),
+                ...opts.label != null ? {
+                    label: opts.label
                 } : undefined,
-                allowDelegatedMutations: opts.p2p
-            }),
-            createHTTPPlugin({
-                port,
-                allowedOrigin: opts.allowedOrigin
-            })
-        ];
-        if (opts.p2p) {
-            plugins.push(createP2PPlugin({
-                http: true,
-                autoAcceptPeers
-            }));
-        }
-        const engine = new KubunEngine({
-            db: adapter,
-            identity,
-            plugins
-        });
-        const http = await withSpinner('Starting the server...', async ()=>{
-            const api = await engine.getAPI('http');
-            await api.listening;
-            if (opts.p2p) {
-                const p2p = await engine.getAPI('p2p');
-                await p2p.syncReady;
-            }
-            return api;
+                ...opts.http ? {
+                    http: {
+                        port,
+                        allowedOrigin: opts.allowedOrigin
+                    }
+                } : undefined,
+                ...opts.p2p ? {
+                    p2p: autoAcceptPeers == null ? {} : {
+                        autoAcceptPeers
+                    }
+                } : undefined
+            });
         });
-        renderNotice('success', `HTTP server listening at ${http.getURL()}\n  DID: ${identity.id}`);
+        renderNotice('success', url == null ? `Hub-only peer running, no HTTP listener\n  DID: ${identity.id}` : `HTTP server listening at ${url}\n  DID: ${identity.id}`);
         if (opts.p2p && autoAcceptPeers) {
             process.stderr.write(`  Auto-accept peers: ${autoAcceptPeers.length} DID(s)\n`);
         }

package/lib/engine.d.ts

@@ -0,0 +1,74 @@
+import type { Identity, OwnIdentity } from '@kokuin/token';
+import { KubunDB } from '@kubun/db';
+import { NodeSQLiteAdapter } from '@kubun/db-node-sqlite';
+import { PostgresAdapter } from '@kubun/db-postgres';
+import { KubunEngine } from '@kubun/engine';
+/**
+ * The graph a peer device serves its own p2p surface from.
+ *
+ * Deployed with no clusters: a headless peer learns a model from whichever
+ * device already has it (the negotiate response carries the cluster), so
+ * requiring the operator to supply model definitions up front would be asking
+ * for something sync provides.
+ */
+export declare const PEER_GRAPH_ID = "kubun-peer";
+/** The adapters a CLI device can run on, kept concrete so `@kubun/db-adapter` stays out of the manifest. */
+export type PeerAdapter = NodeSQLiteAdapter | PostgresAdapter;
+export declare function createAdapter(db?: string): PeerAdapter;
+export type BuildEngineParams = {
+    identity: Identity | OwnIdentity;
+    adapter: PeerAdapter;
+    /** Omit to bind no HTTP listener at all — the hub-only participant. */
+    http?: {
+        port?: number;
+        allowedOrigin?: string;
+    };
+    p2p?: {
+        autoAcceptPeers?: Array<string>;
+    };
+};
+/**
+ * The engine every command builds, with or without an HTTP listener.
+ *
+ * With `http` omitted the p2p plugin also drops its HTTP sync transport, so the
+ * device is reachable only through a group's hub tunnel. That is the whole
+ * difference between the two topologies: hub relay and tunnel dialling are
+ * always wired, and the hub client factory defaults to HTTP on its own.
+ */
+export declare function buildEngine(params: BuildEngineParams): {
+    engine: KubunEngine;
+    db: KubunDB;
+};
+/** Deploy the peer graph, which is what carries the p2p mutations. */
+export declare function deployPeerGraph(engine: KubunEngine): Promise<string>;
+/**
+ * Advertise this device to its co-members.
+ *
+ * Presence is opt-in — a device with no local profile publishes nothing and
+ * never appears in another device's projection, so without this call a headless
+ * peer is running and unselectable.
+ */
+export declare function announceSelf(engine: KubunEngine, params: {
+    label: string;
+    availability: 'always-on' | 'interactive' | 'mobile';
+}): Promise<void>;
+export type StartNodeParams = BuildEngineParams & {
+    label?: string;
+};
+export type StartedNode = {
+    engine: KubunEngine;
+    /** The device's stores, so a caller can read what the engine wrote. */
+    db: KubunDB;
+    /** The peer graph's id, or null when p2p is off and none was deployed. */
+    deployID: string | null;
+    /** Null for a hub-only peer, which binds no listener. */
+    url: string | null;
+};
+/**
+ * Bring a device up: the engine, its peer graph, and its advertisement.
+ *
+ * `serve` is a thin wrapper over this so a test can start the same device
+ * without a process to signal — the alternative is a test that re-types the
+ * startup and then agrees with itself.
+ */
+export declare function startNode(params: StartNodeParams): Promise<StartedNode>;

package/lib/engine.js

@@ -0,0 +1,154 @@
+import { hostname } from 'node:os';
+import { KubunDB } from '@kubun/db';
+import { NodeSQLiteAdapter } from '@kubun/db-node-sqlite';
+import { PostgresAdapter } from '@kubun/db-postgres';
+import { KubunEngine } from '@kubun/engine';
+import { createHTTPPlugin } from '@kubun/plugin-http';
+import { createP2PPlugin, MERKLE_SYNC_PROTOCOL } from '@kubun/plugin-p2p';
+import { createRPCPlugin } from '@kubun/plugin-rpc';
+import { resolvePath } from './fs.js';
+/**
+ * The graph a peer device serves its own p2p surface from.
+ *
+ * Deployed with no clusters: a headless peer learns a model from whichever
+ * device already has it (the negotiate response carries the cluster), so
+ * requiring the operator to supply model definitions up front would be asking
+ * for something sync provides.
+ */ export const PEER_GRAPH_ID = 'kubun-peer';
+export function createAdapter(db) {
+    if (db == null || db === ':memory:') {
+        return new NodeSQLiteAdapter({
+            database: ':memory:'
+        });
+    }
+    if (db.startsWith('postgres://') || db.startsWith('postgresql://')) {
+        return new PostgresAdapter({
+            url: db
+        });
+    }
+    return new NodeSQLiteAdapter({
+        database: resolvePath(db)
+    });
+}
+/**
+ * The engine every command builds, with or without an HTTP listener.
+ *
+ * With `http` omitted the p2p plugin also drops its HTTP sync transport, so the
+ * device is reachable only through a group's hub tunnel. That is the whole
+ * difference between the two topologies: hub relay and tunnel dialling are
+ * always wired, and the hub client factory defaults to HTTP on its own.
+ */ export function buildEngine(params) {
+    const { adapter, identity, http, p2p } = params;
+    const plugins = [
+        createRPCPlugin({
+            ...p2p?.autoAcceptPeers != null ? {
+                accessRules: {
+                    '*': {
+                        allow: [
+                            identity.id,
+                            ...p2p.autoAcceptPeers
+                        ]
+                    }
+                }
+            } : undefined,
+            allowDelegatedMutations: p2p != null
+        })
+    ];
+    if (http != null) {
+        plugins.push(createHTTPPlugin({
+            port: http.port,
+            allowedOrigin: http.allowedOrigin
+        }));
+    }
+    if (p2p != null) {
+        plugins.push(createP2PPlugin({
+            ...http != null ? {
+                http: true
+            } : undefined,
+            ...p2p.autoAcceptPeers != null ? {
+                autoAcceptPeers: p2p.autoAcceptPeers
+            } : undefined
+        }));
+    }
+    const db = new KubunDB({
+        adapter
+    });
+    return {
+        engine: new KubunEngine({
+            db,
+            identity,
+            plugins
+        }),
+        db
+    };
+}
+/** Deploy the peer graph, which is what carries the p2p mutations. */ export async function deployPeerGraph(engine) {
+    const deployed = await engine.deployGraph({
+        id: PEER_GRAPH_ID,
+        name: 'Kubun peer',
+        clusters: [],
+        plugins: {
+            p2p: {}
+        }
+    });
+    return deployed.id;
+}
+/**
+ * Advertise this device to its co-members.
+ *
+ * Presence is opt-in — a device with no local profile publishes nothing and
+ * never appears in another device's projection, so without this call a headless
+ * peer is running and unselectable.
+ */ export async function announceSelf(engine, params) {
+    const p2p = await engine.getAPI('p2p');
+    await p2p.setLocalPeerProfile({
+        label: params.label,
+        availability: params.availability,
+        capabilities: [
+            {
+                protocol: MERKLE_SYNC_PROTOCOL,
+                version: 1,
+                transports: null
+            }
+        ]
+    });
+}
+/**
+ * Bring a device up: the engine, its peer graph, and its advertisement.
+ *
+ * `serve` is a thin wrapper over this so a test can start the same device
+ * without a process to signal — the alternative is a test that re-types the
+ * startup and then agrees with itself.
+ */ export async function startNode(params) {
+    const { engine, db } = buildEngine(params);
+    let deployID = null;
+    if (params.p2p != null) {
+        const p2p = await engine.getAPI('p2p');
+        await p2p.syncReady;
+        // The p2p mutations live on a deployed graph, and a hub-only peer has no
+        // client to deploy one for it.
+        deployID = await deployPeerGraph(engine);
+        await announceSelf(engine, {
+            label: params.label ?? hostname(),
+            // A process meant to be left running is exactly what selection should
+            // prefer, and this is the only place that claim can be made honestly.
+            availability: params.http == null ? 'always-on' : 'interactive'
+        });
+    }
+    if (params.http == null) {
+        return {
+            engine,
+            db,
+            deployID,
+            url: null
+        };
+    }
+    const api = await engine.getAPI('http');
+    await api.listening;
+    return {
+        engine,
+        db,
+        deployID,
+        url: api.getURL()
+    };
+}

package/lib/hub.d.ts

@@ -0,0 +1,38 @@
+import { type HubAuthConfig, type Relay, type RelayObservers } from '@kubun/hub';
+export type StartHubParams = {
+    /**
+     * Who may use the relay. Required: an unset `auth` would leave `createRelay`
+     * with no access rules at all, which refuses every DID without saying so.
+     */
+    auth: HubAuthConfig;
+    /** SQLite path, `:memory:`, or a postgres URL. Defaults to `:memory:`. */
+    db?: string;
+    /**
+     * Base64 private key for the hub's signing identity. Absent generates an
+     * ephemeral one — every client holding the old DID then has to rediscover it
+     * from `/info`, which is why `resolveIdentity` warns about it.
+     */
+    privateKey?: string;
+    allowedOrigin?: string;
+    /** Bind port. Absent probes for a free one, preferring {@link DEFAULT_HUB_PORT}. */
+    port?: number;
+    /** Relay diagnostics — auth refusals, stores, fetches. */
+    observers?: RelayObservers;
+};
+export type StartedHub = {
+    /** The relay endpoint a device binds a group to. */
+    url: string;
+    /** The hub's DID — the audience of every token it accepts, served at `/info`. */
+    did: string;
+    relay: Relay;
+    dispose: () => Promise<void>;
+};
+/**
+ * Serve a blind relay hub over HTTP.
+ *
+ * The hub holds no group state and is a member of nothing: it stores encrypted
+ * envelopes and serves topic subscriptions for groups it cannot read. Its only
+ * authentication is `auth`, checked against the issuer of each signed Enkaku
+ * envelope — there is nothing to check at the HTTP layer.
+ */
+export declare function startHub(params: StartHubParams): Promise<StartedHub>;

package/lib/hub.js

@@ -0,0 +1,109 @@
+import { serve } from '@hono/node-server';
+import { NodeSQLiteAdapter } from '@kubun/db-node-sqlite';
+import { PostgresAdapter } from '@kubun/db-postgres';
+import { createRelay } from '@kubun/hub';
+import { getKubunLogger } from '@kubun/logger';
+import { getPort } from '@tejika/env';
+import { resolvePath } from './fs.js';
+import { resolveIdentity } from './identity.js';
+/**
+ * Where the relay's Enkaku transport is mounted. The relay is path-agnostic —
+ * it is one transport behind a `fetch` — so this prefix is ours to pick, and it
+ * is the URL a device binds a group to.
+ */ const RELAY_PATH = '/relay';
+/**
+ * The name `/info` advertises the relay mount under, mirroring how a device's
+ * HTTP surface advertises its own protocols. A device binds the mount path
+ * directly, so this is discovery for a reader that has only the origin.
+ */ const RELAY_PROTOCOL_NAME = 'relay';
+/** Preferred port when none is given; a taken one yields another free port. */ const DEFAULT_HUB_PORT = 4321;
+/**
+ * Serve a blind relay hub over HTTP.
+ *
+ * The hub holds no group state and is a member of nothing: it stores encrypted
+ * envelopes and serves topic subscriptions for groups it cannot read. Its only
+ * authentication is `auth`, checked against the issuer of each signed Enkaku
+ * envelope — there is nothing to check at the HTTP layer.
+ */ export async function startHub(params) {
+    const logger = getKubunLogger('cli');
+    // No `--id` counterpart here: the relay signs its own response tokens, so an
+    // identity that cannot sign is not a hub identity.
+    const identity = resolveIdentity({
+        privateKey: params.privateKey
+    }, logger);
+    const adapter = params.db == null || params.db === ':memory:' ? new NodeSQLiteAdapter({
+        database: ':memory:'
+    }) : params.db.startsWith('postgres://') || params.db.startsWith('postgresql://') ? new PostgresAdapter({
+        url: params.db
+    }) : new NodeSQLiteAdapter({
+        database: resolvePath(params.db)
+    });
+    const relay = await createRelay({
+        db: adapter,
+        identity,
+        auth: params.auth,
+        retention: {
+            olderThanSeconds: 30 * 24 * 60 * 60
+        },
+        ...params.allowedOrigin == null ? {} : {
+            allowedOrigin: params.allowedOrigin
+        },
+        ...params.observers == null ? {} : {
+            observers: params.observers
+        }
+    });
+    // OPTIONS is served alongside POST: the relay answers the CORS preflight
+    // itself, and a POST-only mount leaves a browser client unable to reach it.
+    const handler = async (request)=>{
+        const { pathname } = new URL(request.url);
+        if (pathname === RELAY_PATH || pathname.startsWith(`${RELAY_PATH}/`)) {
+            return request.method === 'POST' || request.method === 'OPTIONS' ? await relay.fetch(request) : new Response(null, {
+                status: 405
+            });
+        }
+        if (request.method === 'GET' && pathname === '/health') {
+            return Response.json({
+                status: 'ok'
+            });
+        }
+        // Discovery, in the shape a device already reads from another device's
+        // `/info`: the DID every token addressed to this hub must name, plus where
+        // the relay is mounted. A hub advertising a DID it cannot sign with is
+        // simply unreachable — its own server refuses the audience — so nothing
+        // here has to be verified by the reader.
+        if (request.method === 'GET' && pathname === '/info') {
+            return Response.json({
+                did: identity.id,
+                protocols: {
+                    [RELAY_PROTOCOL_NAME]: RELAY_PATH
+                }
+            });
+        }
+        return new Response(null, {
+            status: 404
+        });
+    };
+    const port = params.port ?? await getPort('kubun', {
+        default: DEFAULT_HUB_PORT
+    });
+    const httpServer = await new Promise((resolve)=>{
+        const server = serve({
+            fetch: handler,
+            port
+        }, ()=>resolve(server));
+    });
+    return {
+        url: `http://localhost:${port}${RELAY_PATH}`,
+        did: identity.id,
+        relay,
+        dispose: async ()=>{
+            await new Promise((resolve, reject)=>{
+                httpServer.close((error)=>{
+                    if (error == null) resolve();
+                    else reject(error);
+                });
+            });
+            await relay.dispose();
+        }
+    };
+}

package/lib/identity.d.ts

@@ -1,10 +1,10 @@
-import type { Identity, OwnIdentity } from '@kokuin/token';
+import type { DIDString, Identity, OwnIdentity } from '@kokuin/token';
 type Logger = {
     warn: (message: string, properties?: Record<string, unknown>) => void;
 };
 export type IdentityOptions = {
     privateKey?: string;
-    id?: string;
+    id?: DIDString;
     p2p?: boolean;
 };
 /**

package/lib/program.js

@@ -5,8 +5,10 @@ import { buildProgram as tejikaBuildProgram } from '@tejika/cli';
 import { createAccountCommand } from './commands/account.js';
 import { createGraphCommand } from './commands/graph.js';
 import { createGraphQLCommand } from './commands/graphql.js';
+import { createHubCommand } from './commands/hub.js';
 import { createMCPCommand } from './commands/mcp.js';
 import { createModelCommand } from './commands/model.js';
+import { createPeerCommand } from './commands/peer.js';
 import { createServeCommand } from './commands/serve.js';
 const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), '../package.json');
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
@@ -18,8 +20,10 @@ export function buildProgram() {
             createAccountCommand(),
             createGraphCommand(),
             createGraphQLCommand(),
+            createHubCommand(),
             createModelCommand(),
             createMCPCommand(),
+            createPeerCommand(),
             createServeCommand()
         ]
     });

package/lib/ui.js

@@ -8,7 +8,13 @@ const renderToStderr = {
     const { unmount } = render(/*#__PURE__*/ _jsx(SystemNotice, {
         variant: variant,
         text: text
-    }), renderToStderr);
+    }), {
+        ...renderToStderr,
+        // Nothing to protect from interleaved logs: this mounts and unmounts in one
+        // turn. Patching the global console for that costs a process-wide side
+        // effect, and throws outright wherever `console` is already a stand-in.
+        patchConsole: false
+    });
     unmount();
 }
 /** Show a live spinner on stderr for the duration of `fn`, then unmount. */ export async function withSpinner(label, fn) {

package/package.json

@@ -1,59 +1,68 @@
 {
   "name": "kubun",
-  "version": "0.11.0",
-  "license": "see LICENSE.md",
+  "version": "0.12.1",
   "description": "Kubun CLI",
   "keywords": [],
+  "license": "see LICENSE.md",
   "type": "module",
-  "engines": {
-    "node": ">=22.0.0"
-  },
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "bin": {
+    "kubun": "./bin/run.js"
+  },
   "files": [
     "/bin",
     "/lib"
   ],
-  "bin": {
-    "kubun": "./bin/run.js"
-  },
   "dependencies": {
-    "@kokuin/token": "^0.1.1",
-    "@logtape/logtape": "^2.2.3",
-    "@mokei/context-server": "^0.8.0",
-    "@sozai/codec": "^0.1.0",
-    "@tejika/cli": "^0.1.0",
-    "@tejika/env": "^0.1.0",
-    "@tejika/ui": "^0.1.0",
+    "@hono/node-server": "^2.1.0",
+    "@kokuin/token": "^0.4.0",
+    "@logtape/logtape": "^2.3.0",
+    "@mokei/context-server": "^0.12.0",
+    "@sozai/codec": "^0.4.0",
+    "@tejika/cli": "^0.4.1",
+    "@tejika/env": "^0.5.0",
+    "@tejika/ui": "^0.4.1",
     "commander": "^15.0.0",
     "graphql": "^16.14.2",
-    "ink": "^7.1.0",
+    "ink": "^7.1.1",
     "react": "19.2.3",
-    "@kubun/client": "^0.11.0",
-    "@kubun/engine": "^0.11.0",
-    "@kubun/db-node-sqlite": "^0.11.0",
-    "@kubun/http-client": "^0.11.0",
-    "@kubun/mcp": "^0.11.0",
-    "@kubun/graphql": "^0.11.0",
-    "@kubun/db-postgres": "^0.11.0",
-    "@kubun/logger": "^0.11.0",
-    "@kubun/plugin-p2p": "^0.11.0",
-    "@kubun/plugin-rpc": "^0.11.0",
-    "@kubun/plugin-http": "^0.11.0",
-    "@kubun/protocol": "^0.11.0"
+    "@kubun/client": "^0.12.1",
+    "@kubun/db-postgres": "^0.12.1",
+    "@kubun/db": "^0.12.1",
+    "@kubun/db-node-sqlite": "^0.12.1",
+    "@kubun/engine": "^0.12.1",
+    "@kubun/graphql": "^0.13.0",
+    "@kubun/http-client": "^0.12.1",
+    "@kubun/logger": "^0.12.0",
+    "@kubun/mcp": "^0.12.1",
+    "@kubun/plugin-http": "^0.12.1",
+    "@kubun/hub": "^0.12.1",
+    "@kubun/plugin-p2p": "^0.12.1",
+    "@kubun/protocol": "^0.13.0",
+    "@kubun/plugin-rpc": "^0.12.1"
   },
   "devDependencies": {
-    "ink-testing-library": "^4.0.0"
+    "ink-testing-library": "^4.0.0",
+    "@kubun/id": "^0.12.0",
+    "@kubun/store-graph": "^0.13.0",
+    "@kubun/store-p2p": "^0.12.1"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
-    "kubun": "./bin/dev.js",
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
     "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
-    "test:types": "tsc --noEmit --skipLibCheck",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "kubun": "./bin/dev.js",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
   }
 }