@omochi-ui/cli 0.0.0-stage → 0.1.0

package/dist/catalog-codegen.js

@@ -0,0 +1,185 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+const identifier = (value) => value.replace(/[^A-Za-z0-9]+(.)/g, (_, next) => next.toUpperCase()).replace(/^[^A-Za-z_]+/, '');
+const snake = (value) => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/[^A-Za-z0-9]+/g, '_').toLowerCase();
+function referenceType(ref, language) {
+    const name = ref.split('/').at(-1);
+    const maps = {
+        ts: { ComponentId: 'string', ChildList: 'string[] | { componentId: string; path: string }', DataBinding: 'DataBinding', FunctionCall: 'FunctionCall', DynamicValue: 'DynamicValue', DynamicString: 'DynamicString', DynamicNumber: 'DynamicNumber', DynamicBoolean: 'DynamicBoolean', DynamicStringList: 'DynamicStringList', AccessibilityAttributes: 'Accessibility', CheckRule: 'CheckRule', Action: 'WireAction' },
+        py: { ComponentId: 'str', ChildList: 'list[str] | dict[str, str]', DataBinding: 'DataBinding', FunctionCall: 'FunctionCall', DynamicValue: 'Any', DynamicString: 'DynamicString', DynamicNumber: 'DynamicNumber', DynamicBoolean: 'DynamicBoolean', DynamicStringList: 'DynamicStringList', AccessibilityAttributes: 'dict[str, DynamicString]', CheckRule: 'dict[str, Any]', Action: 'dict[str, Any]' },
+        rs: { ComponentId: 'String', ChildList: 'Value', DataBinding: 'Value', FunctionCall: 'Value', DynamicValue: 'Value', DynamicString: 'Value', DynamicNumber: 'Value', DynamicBoolean: 'Value', DynamicStringList: 'Value', AccessibilityAttributes: 'Value', CheckRule: 'Value', Action: 'Value' },
+    };
+    const value = maps[language][name];
+    if (!value)
+        throw new Error(`unsupported schema reference: ${ref}`);
+    return value;
+}
+function schemaType(schema, language) {
+    if (typeof schema.$ref === 'string')
+        return referenceType(schema.$ref, language);
+    if (Array.isArray(schema.allOf)) {
+        const values = schema.allOf.filter((item) => !item.if && !item.then).map((item) => schemaType(item, language));
+        if (values.length === 1)
+            return values[0];
+        return language === 'rs' ? 'Value' : values.join(' & ');
+    }
+    const union = (schema.anyOf ?? schema.oneOf);
+    if (union) {
+        const values = union.map((item) => schemaType(item, language));
+        return language === 'rs' ? 'Value' : values.join(' | ');
+    }
+    if (Array.isArray(schema.enum)) {
+        if (language === 'ts')
+            return schema.enum.map((value) => JSON.stringify(value)).join(' | ');
+        if (language === 'py')
+            return `Literal[${schema.enum.map((value) => JSON.stringify(value)).join(', ')}]`;
+        return 'String';
+    }
+    if (schema.type === 'string')
+        return language === 'ts' ? 'string' : language === 'py' ? 'str' : 'String';
+    if (schema.type === 'number' || schema.type === 'integer')
+        return language === 'ts' ? 'number' : language === 'py' ? 'float' : 'f64';
+    if (schema.type === 'boolean')
+        return language === 'ts' ? 'boolean' : language === 'py' ? 'bool' : 'bool';
+    if (schema.type === 'array') {
+        const item = schemaType(schema.items ?? {}, language);
+        return language === 'ts' ? `${item}[]` : language === 'py' ? `list[${item}]` : `Vec<${item}>`;
+    }
+    if (schema.type === 'object' && schema.properties) {
+        const entries = Object.entries(schema.properties);
+        if (language === 'ts')
+            return `{ ${entries.map(([key, value]) => `${JSON.stringify(key)}: ${schemaType(value, language)}`).join('; ')} }`;
+        return language === 'py' ? 'dict[str, Any]' : 'Value';
+    }
+    throw new Error(`unsupported schema fragment: ${JSON.stringify(schema)}`);
+}
+function pointer(document, fragment) {
+    if (!fragment || fragment === '#')
+        return document;
+    if (!fragment.startsWith('#/'))
+        throw new Error(`unsupported JSON Schema fragment: ${fragment}`);
+    return fragment.slice(2).split('/').reduce((value, part) => {
+        if (!value || typeof value !== 'object')
+            throw new Error(`unresolved JSON Schema fragment: ${fragment}`);
+        return value[part.replaceAll('~1', '/').replaceAll('~0', '~')];
+    }, document);
+}
+async function resolveLocalRefs(value, document, base, stack = new Set()) {
+    if (Array.isArray(value))
+        return Promise.all(value.map((item) => resolveLocalRefs(item, document, base, stack)));
+    if (!value || typeof value !== 'object')
+        return value;
+    const object = value;
+    if (typeof object.$ref === 'string' && !object.$ref.startsWith('http:') && !object.$ref.startsWith('https:')) {
+        const [filename, rawFragment = ''] = object.$ref.split('#', 2);
+        const fragment = `#${rawFragment}`;
+        const referenceKey = `${base}:${object.$ref}`;
+        if (stack.has(referenceKey))
+            throw new Error(`circular schema reference: ${object.$ref}`);
+        const nextStack = new Set(stack).add(referenceKey);
+        if (filename) {
+            const path = resolve(base, filename);
+            const external = JSON.parse(await readFile(path, 'utf8'));
+            const resolved = pointer(external, fragment);
+            return resolveLocalRefs({ ...resolved, ...Object.fromEntries(Object.entries(object).filter(([key]) => key !== '$ref')) }, external, dirname(path), nextStack);
+        }
+        const resolved = pointer(document, fragment);
+        return resolveLocalRefs({ ...resolved, ...Object.fromEntries(Object.entries(object).filter(([key]) => key !== '$ref')) }, document, base, nextStack);
+    }
+    return Object.fromEntries(await Promise.all(Object.entries(object).map(async ([key, item]) => [key, await resolveLocalRefs(item, document, base, stack)])));
+}
+function normalize(raw, requestedName, sourceHash) {
+    const catalog = JSON.parse(raw);
+    if (!catalog.components || typeof catalog.components !== 'object')
+        throw new Error('catalog must contain a components object');
+    const title = requestedName ?? (typeof catalog.title === 'string' ? catalog.title : 'GeneratedCatalog');
+    const name = identifier(title);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        throw new Error(`catalog name is not a valid identifier: ${title}`);
+    const components = Object.entries(catalog.components).map(([componentName, schema]) => {
+        const layers = Array.isArray(schema.allOf) ? schema.allOf : [schema];
+        const properties = new Map();
+        const required = new Set();
+        for (const layer of layers) {
+            if (typeof layer.$ref === 'string') {
+                if (layer.$ref.endsWith('/ComponentCommon'))
+                    properties.set('accessibility', { $ref: 'https://a2ui.org/specification/v0_9/common_types.json#/$defs/AccessibilityAttributes' });
+                else if (layer.$ref.endsWith('/Checkable')) {
+                    properties.set('checks', { type: 'array', items: { $ref: 'https://a2ui.org/specification/v0_9/common_types.json#/$defs/CheckRule' } });
+                    properties.set('isValid', { type: 'boolean' });
+                    properties.set('validationErrors', { type: 'array', items: { type: 'string' } });
+                }
+                else if (layer.$ref === '#/$defs/CatalogComponentCommon')
+                    properties.set('weight', { type: 'number' });
+                else
+                    throw new Error(`unsupported component mixin: ${layer.$ref}`);
+            }
+            for (const [key, value] of Object.entries(layer.properties ?? {}))
+                if (key !== 'component' && key !== 'id')
+                    properties.set(key, value);
+            for (const key of layer.required ?? [])
+                if (key !== 'component' && key !== 'id')
+                    required.add(key);
+        }
+        return { name: componentName, properties: [...properties].map(([propertyName, propertySchema]) => ({ name: propertyName, type: JSON.stringify(propertySchema), required: required.has(propertyName) })) };
+    });
+    return { id: String(catalog.catalogId ?? catalog.$id ?? ''), name, hash: sourceHash ?? createHash('sha256').update(raw).digest('hex'), components };
+}
+const propertyType = (property, language) => schemaType(JSON.parse(property.type), language);
+const header = (model, comment) => `${comment} Generated by omochi-ui from catalog ${model.id}\n${comment} Source SHA-256: ${model.hash}\n`;
+function typescript(model) {
+    const body = model.components.map((component) => `export interface ${component.name}Props {\n${component.properties.map((property) => `  ${JSON.stringify(property.name)}${property.required ? '' : '?'}: ${propertyType(property, 'ts')}`).join('\n')}\n}`).join('\n\n');
+    const map = model.components.map((component) => `  ${JSON.stringify(component.name)}: ${component.name}Props`).join('\n');
+    const knownTypes = ['Accessibility', 'CheckRule', 'DataBinding', 'DynamicBoolean', 'DynamicNumber', 'DynamicString', 'DynamicStringList', 'DynamicValue', 'FunctionCall', 'WireAction'];
+    const imports = ['CatalogDefinition', ...knownTypes.filter((name) => body.includes(name))];
+    return `${header(model, '//')}import type { ${imports.join(', ')} } from '@omochi-ui/sdk'\n\n${body}\n\nexport interface ${model.name}ComponentMap {\n${map}\n}\n\nexport const ${model.name.toUpperCase()}: CatalogDefinition<${model.name}ComponentMap> = { id: ${JSON.stringify(model.id)}, name: ${JSON.stringify(model.name)} }\n`;
+}
+function python(model) {
+    const body = model.components.map((component) => `class ${component.name}Props(TypedDict, total=False):\n${component.properties.map((property) => `    ${property.name}: ${property.required ? 'Required[' : ''}${propertyType(property, 'py')}${property.required ? ']' : ''}`).join('\n') || '    pass'}`).join('\n\n');
+    const overloads = model.components.map((component) => `    @overload\n    def component(self, component: Literal[${JSON.stringify(component.name)}], *, key: str, **props: Unpack[${component.name}Props]) -> None: ...`).join('\n');
+    return `${header(model, '#')}from typing import Any, Literal, Required, TypedDict, Unpack, overload\nfrom omochi_ui import Catalog, UI\nfrom omochi_ui.catalog import DataBinding, DynamicBoolean, DynamicNumber, DynamicString, DynamicStringList, FunctionCall\n\n${body}\n\nclass ${model.name}UI(UI):\n${overloads}\n    def component(self, component: str, *, key: str, **props: Any) -> None:\n        super().component(component, key=key, **props)\n\n${model.name.toUpperCase()} = Catalog(id=${JSON.stringify(model.id)}, name=${JSON.stringify(model.name)}, ui_type=${model.name}UI)\n`;
+}
+function rust(model) {
+    const enumName = (component, property) => `${identifier(component.name)}${identifier(property.name[0].toUpperCase() + property.name.slice(1))}`;
+    const enums = model.components.flatMap((component) => component.properties.flatMap((property) => {
+        const values = JSON.parse(property.type).enum;
+        if (!Array.isArray(values))
+            return [];
+        const variants = values.map((value) => {
+            const raw = String(value);
+            const variant = identifier(raw[0].toUpperCase() + raw.slice(1)) || 'Value';
+            return `    #[serde(rename = ${JSON.stringify(raw)})]\n    ${/^\d/.test(variant) ? `Value${variant}` : variant},`;
+        }).join('\n');
+        return [`#[derive(Clone, Debug, Serialize)]\npub enum ${enumName(component, property)} {\n${variants}\n}`];
+    })).join('\n\n');
+    const body = model.components.map((component) => `#[derive(Clone, Debug, Serialize)]\n#[serde(rename_all = "camelCase")]\npub struct ${component.name}Props {\n${component.properties.map((property) => {
+        const schema = JSON.parse(property.type);
+        const type = Array.isArray(schema.enum) ? enumName(component, property) : propertyType(property, 'rs');
+        return `${property.required ? '' : '    #[serde(skip_serializing_if = "Option::is_none")]\n'}    pub ${snake(property.name)}: ${property.required ? type : `Option<${type}>`},`;
+    }).join('\n')}\n}\nimpl ComponentProps for ${component.name}Props {\n    const NAME: &'static str = ${JSON.stringify(component.name)};\n    fn into_props(self) -> JsonObject { serde_json::to_value(self).unwrap().as_object().unwrap().clone() }\n}`).join('\n\n');
+    return `${header(model, '//')}use omochi_ui::{ComponentProps, JsonObject};\nuse serde::Serialize;\nuse serde_json::Value;\n\npub const CATALOG_ID: &str = ${JSON.stringify(model.id)};\n\n${enums}${enums ? '\n\n' : ''}${body}\n`;
+}
+async function output(path, content, check) {
+    const current = await readFile(path, 'utf8').catch(() => null);
+    if (check) {
+        if (current !== content)
+            throw new Error(`generated catalog is stale: ${path}`);
+        return;
+    }
+    if (current !== content)
+        await writeFile(path, content);
+}
+export async function generateCatalog(options) {
+    if (!options.typescript && !options.python && !options.rust)
+        throw new Error('at least one output flag is required');
+    const raw = await readFile(options.catalog, 'utf8');
+    const parsed = JSON.parse(raw);
+    const resolved = await resolveLocalRefs(parsed, parsed, dirname(resolve(options.catalog)));
+    const model = normalize(JSON.stringify(resolved), options.name, createHash('sha256').update(raw).digest('hex'));
+    await Promise.all([
+        options.typescript ? output(options.typescript, typescript(model), Boolean(options.check)) : undefined,
+        options.python ? output(options.python, python(model), Boolean(options.check)) : undefined,
+        options.rust ? output(options.rust, rust(model), Boolean(options.check)) : undefined,
+    ]);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,454 @@
+#!/usr/bin/env bun
+import { hostname, networkInterfaces } from 'node:os';
+import process from 'node:process';
+import { createStaticLocator, gatewayEndpointKey, loadNodeIdentity, omochiConfigRoot, openTrustStore, pairWithGateway, parseGatewayTarget, startGateway, } from '@omochi-ui/discovery';
+import { generateCatalog } from './catalog-codegen.js';
+import { helpText, helpTopic } from './help.js';
+import { startHub } from './hub/hub.js';
+import { startSshGateway, validateSshTarget } from './hub/ssh-gateway.js';
+import { startStdioWebSocketBridge } from './stdio-websocket-bridge.js';
+import { loadComposition, openBrowser, startCompositionServices } from './up.js';
+/**
+ * An address another machine could actually dial.
+ *
+ * A wildcard bind is what the gateway listens on, not somewhere anyone can connect to,
+ * so printing it back would send a person to `0.0.0.0`.
+ */
+function reachableHost(bound) {
+    if (bound !== '0.0.0.0' && bound !== '::' && bound !== '')
+        return bound;
+    for (const addresses of Object.values(networkInterfaces())) {
+        for (const address of addresses ?? []) {
+            if (address.family === 'IPv4' && !address.internal)
+                return address.address;
+        }
+    }
+    return hostname();
+}
+function usage(message = 'Invalid or incomplete arguments.') {
+    process.stderr.write(`[omochi-ui] ${message}\n\n${helpText(topic) ?? helpText()}`);
+    process.exit(2);
+}
+const args = process.argv.slice(2);
+// Stop scanning at -- so e.g. `dev -- python app.py --help` reaches the app.
+const separatorIndex = args.indexOf('--');
+const ownArgs = separatorIndex < 0 ? args : args.slice(0, separatorIndex);
+const explicitHelp = ownArgs[0] === 'help';
+const helpArgs = explicitHelp ? ownArgs.slice(1) : ownArgs;
+const topic = helpTopic(helpArgs.filter((arg) => arg !== '--help' && arg !== '-h'));
+if (!args.length || explicitHelp || ownArgs.some((arg) => arg === '--help' || arg === '-h')) {
+    const text = helpText(topic);
+    if (text === undefined || (explicitHelp && helpArgs.length > (topic.includes(' ') ? 2 : 1))) {
+        usage(`Unknown help topic: ${helpArgs.join(' ')}`);
+    }
+    process.stdout.write(text);
+    process.exit(0);
+}
+const commandName = args.shift();
+if (commandName === 'generate') {
+    if (args.shift() !== 'catalog')
+        usage();
+    const options = { catalog: '' };
+    while (args.length) {
+        const option = args.shift();
+        if (option === '--check') {
+            options.check = true;
+            continue;
+        }
+        const value = args.shift();
+        if (!value)
+            usage();
+        if (option === '--catalog')
+            options.catalog = value;
+        else if (option === '--name')
+            options.name = value;
+        else if (option === '--typescript')
+            options.typescript = value;
+        else if (option === '--python')
+            options.python = value;
+        else if (option === '--rust')
+            options.rust = value;
+        else
+            usage();
+    }
+    if (!options.catalog)
+        usage();
+    await generateCatalog(options);
+    process.exit(0);
+}
+if (commandName === 'id') {
+    let nodeName;
+    while (args.length) {
+        const option = args.shift();
+        const value = args.shift();
+        if (!value || option !== '--node-name')
+            usage();
+        nodeName = value;
+    }
+    const identity = await loadNodeIdentity(nodeName === undefined ? {} : { name: nodeName });
+    process.stdout.write(`${identity.nodeId}\t${identity.name}\n`);
+    process.stderr.write(`[omochi-ui] identity stored in ${omochiConfigRoot()}\n`);
+    process.exit(0);
+}
+if (commandName === 'pair') {
+    const target = args.shift();
+    if (!target)
+        usage();
+    const parsed = parseGatewayTarget(target);
+    if (!parsed || parsed.endpoint.kind !== 'tcp')
+        usage();
+    let code;
+    while (args.length) {
+        const option = args.shift();
+        const value = args.shift();
+        if (!value || option !== '--code')
+            usage();
+        code = value;
+    }
+    // Reading the code from stdin keeps it out of shell history.
+    if (code === undefined) {
+        process.stderr.write('[omochi-ui] pairing code: ');
+        code = await new Promise((resolvePromise) => {
+            let typed = '';
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (chunk) => {
+                typed += chunk;
+                const line = typed.indexOf('\n');
+                if (line >= 0) {
+                    process.stdin.pause();
+                    resolvePromise(typed.slice(0, line));
+                }
+            });
+            process.stdin.on('end', () => resolvePromise(typed));
+        });
+    }
+    const identity = await loadNodeIdentity();
+    const trust = await openTrustStore();
+    try {
+        const peer = await pairWithGateway(parsed.endpoint, { identity, trust, code });
+        process.stderr.write(`[omochi-ui] paired with ${peer.nodeId} (${peer.name})\n`);
+        process.stderr.write(`[omochi-ui] reach it with: omochi-ui hub --gateway ${peer.nodeId}@${peer.addresses[0]}\n`);
+        process.exit(0);
+    }
+    catch (error) {
+        process.stderr.write(`[omochi-ui] ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    }
+}
+if (commandName === 'trust') {
+    const action = args.shift();
+    if (action !== 'list' && action !== 'forget')
+        usage('Expected trust list or trust forget <nodeId>.');
+    if (action === 'list' && args.length !== 0)
+        usage('trust list takes no arguments.');
+    if (action === 'forget' && args.length !== 1)
+        usage('trust forget requires exactly one node ID.');
+    const store = await openTrustStore();
+    if (action === 'list') {
+        const peers = store.list();
+        if (store.legacy)
+            process.stderr.write('[omochi-ui] old TLS-PSK pairings are unsupported; pair devices again\n');
+        if (!peers.length)
+            process.stderr.write(`[omochi-ui] no paired peers in ${store.file}\n`);
+        for (const peer of peers) {
+            const seen = peer.lastSeenAt ? ` last seen ${peer.lastSeenAt}` : '';
+            process.stdout.write(`${peer.nodeId}\t${peer.role}\t${peer.name}\tpaired ${peer.pairedAt}${seen}\n`);
+        }
+        process.exit(0);
+    }
+    if (action === 'forget') {
+        const nodeId = args.shift();
+        if (!nodeId)
+            usage();
+        const forgotten = await store.forget(nodeId);
+        process.stderr.write(forgotten
+            ? `[omochi-ui] forgot ${nodeId}\n`
+            : `[omochi-ui] no paired peer ${nodeId}\n`);
+        process.exit(forgotten ? 0 : 1);
+    }
+    usage();
+}
+if (commandName === 'gateway') {
+    let root;
+    let socketPath;
+    let nodeName;
+    let listen;
+    let pairing;
+    let advertise = false;
+    while (args.length) {
+        const option = args.shift();
+        // `--lan` is sugar; accepting hubs and advertising stay separate switches.
+        if (option === '--lan') {
+            listen = { host: '0.0.0.0', port: 5556 };
+            advertise = true;
+            continue;
+        }
+        if (option === '--advertise') {
+            advertise = true;
+            continue;
+        }
+        if (option === '--pair') {
+            pairing = {};
+            continue;
+        }
+        const value = args.shift();
+        if (!value)
+            usage();
+        if (option === '--root')
+            root = value;
+        else if (option === '--socket')
+            socketPath = value;
+        else if (option === '--node-name')
+            nodeName = value;
+        else if (option === '--listen') {
+            const target = parseGatewayTarget(value);
+            if (!target || target.endpoint.kind !== 'tcp')
+                usage();
+            listen = { host: target.endpoint.host, port: target.endpoint.port };
+        }
+        else
+            usage();
+    }
+    if ((pairing || advertise) && !listen)
+        usage('--pair and --advertise require --listen HOST:PORT or --lan.');
+    const gateway = await startGateway({ root, socketPath, name: nodeName, listen, pairing, advertise })
+        .catch((error) => {
+        // Two gateways on one machine is the common mistake here, and a stack trace is a
+        // poor way to say so.
+        if (error.code === 'EADDRINUSE' && listen) {
+            process.stderr.write(`[omochi-ui] ${listen.host}:${listen.port} is already in use; another gateway may be running\n`);
+            process.exit(1);
+        }
+        if (error.code === 'EADDRINUSE') {
+            process.stderr.write('[omochi-ui] a gateway is already listening on this machine\n');
+            process.exit(1);
+        }
+        throw error;
+    });
+    process.stderr.write(`[omochi-ui] gateway ${gateway.nodeId} (${gateway.name})\n[omochi-ui] publishing services from ${gateway.root}\n[omochi-ui] listening on ${gateway.socketPath}\n`);
+    if (gateway.address) {
+        const peers = (await openTrustStore()).list().filter((peer) => peer.role === 'hub').length;
+        process.stderr.write(`[omochi-ui] reachable from the local network on ${gateway.address.host}:${gateway.address.port}; ${peers} hub(s) paired\n`);
+        if (advertise)
+            process.stderr.write(`[omochi-ui] advertising as _${'omochi-ui'}._tcp\n`);
+    }
+    if (gateway.pairing) {
+        const seconds = Math.round((gateway.pairing.expiresAt - Date.now()) / 1000);
+        process.stderr.write([
+            `[omochi-ui] pairing code: ${gateway.pairing.display}   (valid ${seconds}s, one use)`,
+            `[omochi-ui] on the other machine: omochi-ui pair ${reachableHost(gateway.pairingAddress.host)}:${gateway.pairingAddress.port}`,
+            '',
+        ].join('\n'));
+        void gateway.pairing.ended.then((reason) => {
+            // The gateway keeps running either way; only the window is over.
+            process.stderr.write(`[omochi-ui] pairing window closed: ${reason}\n`);
+        });
+    }
+    const stop = () => void gateway.close().then(() => process.exit(0));
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+}
+else if (commandName === 'up') {
+    let host = '127.0.0.1';
+    let port = 5555;
+    let shouldOpen = false;
+    const allowOrigins = [];
+    let file = 'omochi.toml';
+    let foundFile = false;
+    while (args.length) {
+        const option = args.shift();
+        if (option === '--open') {
+            shouldOpen = true;
+            continue;
+        }
+        if (!option.startsWith('-')) {
+            if (foundFile)
+                usage('up accepts at most one composition file.');
+            file = option;
+            foundFile = true;
+            continue;
+        }
+        const value = args.shift();
+        if (!value)
+            usage();
+        if (option === '--host')
+            host = value;
+        else if (option === '--port' && Number.isInteger(Number(value)))
+            port = Number(value);
+        else if (option === '--allow-origin')
+            allowOrigins.push(value);
+        else
+            usage();
+    }
+    if (port < 0 || port > 65535)
+        usage('--port must be an integer from 0 to 65535.');
+    let services;
+    let hub;
+    let shutdown;
+    const stop = (code = 0) => shutdown ??= (async () => {
+        await services?.close();
+        await hub?.close();
+        process.exit(code);
+    })();
+    process.on('SIGINT', () => { void stop(130); });
+    process.on('SIGTERM', () => { void stop(143); });
+    try {
+        const identity = await loadNodeIdentity();
+        const composition = await loadComposition(file, identity.nodeId);
+        services = startCompositionServices(composition.services);
+        hub = await startHub({ host, port, allowOrigins, presets: [composition.preset] });
+        const url = new URL(hub.httpUrl);
+        url.searchParams.set('preset', composition.id);
+        process.stderr.write(`[omochi-ui] composition ${composition.id}: ${composition.services.length} services\n[omochi-ui] ${url.toString()}\n`);
+        if (shouldOpen) {
+            if (['0.0.0.0', '::'].includes(url.hostname))
+                url.hostname = '127.0.0.1';
+            openBrowser(url.toString());
+        }
+    }
+    catch (error) {
+        process.stderr.write(`[omochi-ui] ${error instanceof Error ? error.message : String(error)}\n`);
+        await services?.close();
+        await hub?.close();
+        process.exit(1);
+    }
+}
+else if (commandName === 'hub') {
+    let host = '127.0.0.1';
+    let port = 5555;
+    let autoGateway = true;
+    let discoverLan = false;
+    let sshHost;
+    let sshSocket;
+    const peers = [];
+    const peerIds = new Map();
+    const allowOrigins = [];
+    while (args.length) {
+        const option = args.shift();
+        if (option === '--no-auto-gateway') {
+            autoGateway = false;
+            continue;
+        }
+        if (option === '--discover-lan') {
+            discoverLan = true;
+            continue;
+        }
+        const value = args.shift();
+        if (!value)
+            usage();
+        if (option === '--host')
+            host = value;
+        else if (option === '--port' && Number.isInteger(Number(value)))
+            port = Number(value);
+        else if (option === '--ssh') {
+            if (sshHost !== undefined)
+                usage();
+            sshHost = value;
+        }
+        else if (option === '--ssh-socket') {
+            if (sshSocket !== undefined)
+                usage();
+            sshSocket = value;
+        }
+        else if (option === '--gateway') {
+            const target = parseGatewayTarget(value);
+            if (!target)
+                usage();
+            peers.push(target.endpoint);
+            if (target.nodeId)
+                peerIds.set(gatewayEndpointKey(target.endpoint), target.nodeId);
+        }
+        else if (option === '--allow-origin')
+            allowOrigins.push(value);
+        else
+            usage();
+    }
+    // Naming a gateway replaces the default, so `--gateway` can point at another machine
+    // without also picking up whatever happens to be running locally.
+    if (sshSocket !== undefined && sshHost === undefined)
+        usage();
+    if (port < 0 || port > 65535)
+        usage('--port must be an integer from 0 to 65535.');
+    let tunnel;
+    let hub;
+    const abort = new AbortController();
+    let stopping = false;
+    let pending;
+    let shutdown;
+    const stop = (code = 0) => shutdown ??= (async () => {
+        stopping = true;
+        abort.abort();
+        await pending?.catch(() => { });
+        await hub?.close();
+        await tunnel?.close();
+        process.exit(code);
+    })();
+    // Install these before SSH can prompt, so cancellation also cleans partial startup.
+    process.on('SIGINT', () => { void stop(130); });
+    process.on('SIGTERM', () => { void stop(143); });
+    try {
+        if (sshHost !== undefined) {
+            validateSshTarget(sshHost, sshSocket);
+            tunnel = await (pending = startSshGateway({ host: sshHost, remoteSocket: sshSocket, signal: abort.signal }));
+            peers.push({ kind: 'unix', socketPath: tunnel.socketPath });
+        }
+        const gateways = peers.length ? [createStaticLocator(peers, peerIds)] : undefined;
+        hub = await (pending = startHub({ host, port, allowOrigins, gateways, discoverLan, autoGateway: autoGateway && !peers.length }));
+        if (tunnel)
+            void tunnel.exited.then((error) => {
+                if (!stopping) {
+                    process.stderr.write(`[omochi-ui] ${error.message}\n`);
+                    void stop(1);
+                }
+            });
+    }
+    catch (error) {
+        process.stderr.write(`[omochi-ui] ${error instanceof Error ? error.message : error}\n`);
+        await stop(1);
+        process.exit(1);
+    }
+    // Connections are still being established, so name the targets rather than count them.
+    const named = peers.length
+        ? peers.map((peer) => (peer.kind === 'unix' ? peer.socketPath : `${peer.host}:${peer.port}`)).join(', ')
+        : 'the local gateway';
+    const targets = discoverLan ? `${named} and any gateway on the local link` : named;
+    process.stderr.write(`[omochi-ui] merging ${targets}\n[omochi-ui] ${hub.httpUrl}\nA2UI endpoint: ${hub.url}\n`);
+    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+        process.stderr.write('[omochi-ui] warning: hub has no authentication or TLS\n');
+    }
+}
+else {
+    if (commandName !== 'dev')
+        usage(`Unknown command: ${commandName}`);
+    const separator = args.indexOf('--');
+    if (separator < 0)
+        usage('dev requires -- followed by the application command.');
+    const optionArgs = args.slice(0, separator);
+    const childCommand = args.slice(separator + 1);
+    let host = '127.0.0.1';
+    let port = 5555;
+    for (let index = 0; index < optionArgs.length; index += 1) {
+        const option = optionArgs[index];
+        const value = optionArgs[index + 1];
+        if (option === '--host' && value)
+            host = value;
+        else if (option === '--port' && value && Number.isInteger(Number(value)))
+            port = Number(value);
+        else
+            usage();
+        index += 1;
+    }
+    if (!childCommand.length)
+        usage();
+    if (port < 0 || port > 65535)
+        usage('--port must be an integer from 0 to 65535.');
+    const handle = await startStdioWebSocketBridge({ command: childCommand, host, port });
+    process.stderr.write(`[omochi-ui] bridge: ${handle.url}\nStart the browser preview in another terminal: bun run --filter @omochi-ui/dev-server dev\nOpen: http://127.0.0.1:5173/?ws=${encodeURIComponent(handle.url)}\n`);
+    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1')
+        process.stderr.write('[omochi-ui] warning: bridge has no authentication or TLS\n');
+    const forward = (signal) => { if (handle.child.exitCode === null)
+        handle.child.kill(signal); };
+    process.on('SIGINT', forward);
+    process.on('SIGTERM', forward);
+    process.exitCode = await handle.exited;
+}

package/dist/help.d.ts

@@ -0,0 +1,3 @@
+export declare function helpText(topic?: string): string | undefined;
+/** Only command words select a topic; options and child arguments never do. */
+export declare function helpTopic(args: string[]): string;