kubun 0.10.0 → 0.12.0

package/lib/commands/model.js

@@ -0,0 +1,71 @@
+import { ClusterBuilder } from '@kubun/protocol';
+import { Command, Option } from 'commander';
+import { writeJSON } from '../fs.js';
+import { renderNotice } from '../ui.js';
+function parseJSON(label, value) {
+    try {
+        return JSON.parse(value);
+    } catch (cause) {
+        throw new Error(`${label} is not valid JSON: ${value}`, {
+            cause
+        });
+    }
+}
+function createClusterCommand() {
+    const cmd = new Command('cluster').description('Create a documents cluster model').requiredOption('-m, --model <json...>', 'document model as JSON string (repeatable)').option('-o, --output <file>', 'output file for the cluster');
+    cmd.action(async (opts)=>{
+        const builder = new ClusterBuilder();
+        builder.addAll(opts.model.map((model)=>parseJSON('--model', model)));
+        const cluster = builder.build();
+        if (opts.output == null) {
+            renderNotice('success', 'Cluster model created');
+            console.log(JSON.stringify(cluster));
+        } else {
+            await writeJSON(opts.output, cluster);
+            renderNotice('success', `Cluster model written to ${opts.output}`);
+        }
+    });
+    return cmd;
+}
+function createCreateCommand() {
+    const cmd = new Command('create').description('Create a document model').argument('<name>', 'document model name').argument('<schema>', 'document schema as JSON string').addOption(new Option('-b, --behavior <behavior>', 'behavior of the document').choices([
+        'default',
+        'interface',
+        'unique'
+    ]).default('default')).option('-c, --cluster', 'create a cluster model instead of a document model').option('-o, --output <file>', 'output file').option('-u, --unique-field <field...>', 'unique field of the document when behavior is "unique" (repeatable)');
+    cmd.action(async (name, schema, opts)=>{
+        const model = {
+            name,
+            behavior: opts.behavior,
+            schema: parseJSON('<schema>', schema)
+        };
+        if (opts.behavior === 'unique') {
+            model.uniqueFields = opts.uniqueField;
+        }
+        const builder = new ClusterBuilder();
+        builder.add(model);
+        if (opts.cluster) {
+            const cluster = builder.build();
+            if (opts.output == null) {
+                renderNotice('success', 'Cluster model created');
+                console.log(JSON.stringify(cluster));
+            } else {
+                await writeJSON(opts.output, cluster);
+                renderNotice('success', `Cluster model written to ${opts.output}`);
+            }
+            return;
+        }
+        const document = builder.cluster[0];
+        if (opts.output == null) {
+            renderNotice('success', 'Document model created');
+            console.log(JSON.stringify(document));
+        } else {
+            await writeJSON(opts.output, document);
+            renderNotice('success', `Document model written to ${opts.output}`);
+        }
+    });
+    return cmd;
+}
+export function createModelCommand() {
+    return new Command('model').description('Model commands').addCommand(createClusterCommand()).addCommand(createCreateCommand());
+}

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.d.ts

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

package/lib/commands/serve.js

@@ -0,0 +1,86 @@
+import { getKubunLogger } from '@kubun/logger';
+import { configureSync, getConsoleSink } from '@logtape/logtape';
+import { Command } from 'commander';
+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('--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);
+    withPrivateKey(cmd);
+    cmd.action(async (opts)=>{
+        if (opts.id != null && opts.privateKey != null) {
+            throw new Error('--id and --private-key are mutually exclusive');
+        }
+        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: {
+                console: getConsoleSink()
+            },
+            loggers: [
+                {
+                    category: [
+                        'logtape',
+                        'meta'
+                    ],
+                    lowestLevel: 'error',
+                    sinks: [
+                        'console'
+                    ]
+                },
+                {
+                    category: [
+                        'kubun'
+                    ],
+                    lowestLevel: opts.logLevel ?? 'warning',
+                    sinks: [
+                        'console'
+                    ]
+                }
+            ]
+        });
+        const logger = getKubunLogger('cli');
+        const identity = resolveIdentity(opts, logger);
+        const autoAcceptPeers = opts.autoAcceptPeers ? opts.autoAcceptPeers.split(',').map((s)=>s.trim()) : undefined;
+        const port = opts.port == null ? undefined : typeof opts.port === 'number' ? opts.port : Number.parseInt(opts.port, 10);
+        const { engine, url } = await withSpinner('Starting the server...', async ()=>{
+            return await startNode({
+                identity,
+                adapter: createAdapter(opts.db),
+                ...opts.label != null ? {
+                    label: opts.label
+                } : undefined,
+                ...opts.http ? {
+                    http: {
+                        port,
+                        allowedOrigin: opts.allowedOrigin
+                    }
+                } : undefined,
+                ...opts.p2p ? {
+                    p2p: autoAcceptPeers == null ? {} : {
+                        autoAcceptPeers
+                    }
+                } : undefined
+            });
+        });
+        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`);
+        }
+        await new Promise((resolve)=>{
+            process.once('SIGINT', resolve);
+            process.once('SIGTERM', resolve);
+        });
+        await engine.dispose();
+    });
+    return cmd;
+}

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/fs.d.ts

@@ -0,0 +1,4 @@
+export declare function resolvePath(value: string): string;
+export declare function readJSON<T = unknown>(path: string): Promise<T>;
+export declare function writeFile(path: string, value: string): Promise<void>;
+export declare function writeJSON(path: string, value: unknown, format?: boolean): Promise<void>;