@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/cli/commands/doctor.js

@@ -0,0 +1,365 @@
+/**
+ * `boombot doctor` — environment health checks.
+ *
+ * Every check is pure/async-testable via `runDoctor()`; printing and the
+ * process exit code live in `printDoctorReport()` / the bin entrypoint.
+ * No secret values are ever printed — only their presence.
+ */
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ConfigError, configHasSecrets, expandTilde, fileModeBits, loadConfig, resolveConfigPath, validateConfig, } from "../config-file.js";
+import { resolveMasterKeyPath } from "../master-key.js";
+import { resolveWebAssets } from "../web-assets.js";
+const HEALTH_TIMEOUT_MS = 5000;
+/** SQLite is unflagged from Node 22.13; newer supported runtime line starts at 24. */
+export const MIN_NODE_MAJOR = 22;
+/** Real provider store written by `boombot setup` (keys encrypted at rest). */
+export function providerStorePath(dataDir) {
+    return path.join(expandTilde(dataDir), 'providers.json');
+}
+function healthzUrl(config) {
+    return `http://${config.host}:${config.port}/healthz`;
+}
+function checkNodeVersion() {
+    const raw = process.versions.node;
+    const [major = 0, minor = 0] = raw.split('.').map(Number);
+    if ((major === MIN_NODE_MAJOR && minor >= 13) || major >= 24) {
+        return { name: 'node version', status: 'pass', detail: `node v${raw} (22.13+ or 24+)` };
+    }
+    return {
+        name: 'node version',
+        status: 'fail',
+        detail: `node v${raw} is unsupported — BoomBot needs 22.13+ (22.x) or 24+`,
+        fix: 'install a supported Node.js version: https://nodejs.org/en/download',
+    };
+}
+function checkPythonRuntime() {
+    const sourceVenv = fileURLToPath(new URL(process.platform === 'win32'
+        ? '../../../../agent-core-python/.venv/Scripts/python.exe'
+        : '../../../../agent-core-python/.venv/bin/python', import.meta.url));
+    const python = process.env['BOOMBOT_PYTHON']
+        ?? (existsSync(sourceVenv) ? sourceVenv : process.platform === 'win32' ? 'python' : 'python3');
+    const probe = spawnSync(python, ['-c', 'import grpc, google.protobuf, sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")'], { encoding: 'utf8', timeout: 5_000, windowsHide: true });
+    const version = probe.stdout?.trim() ?? '';
+    if (probe.status === 0 && /^(?:3\.(?:1[1-9]|[2-9]\d)|[4-9]\d)\b/u.test(version)) {
+        return { name: 'python agent core', status: 'pass', detail: `python ${version} with gRPC` };
+    }
+    return {
+        name: 'python agent core',
+        status: 'fail',
+        detail: probe.error?.message ?? (probe.stderr?.trim() || 'Python 3.11+ with grpcio is unavailable'),
+        fix: 'install Python 3.11+ with grpcio/protobuf; source checkouts run `pnpm python:sync`, or set BOOMBOT_PYTHON',
+    };
+}
+function checkMasterKey(configPath) {
+    const fromEnv = process.env['BOOMBOT_MASTER_KEY'];
+    if (fromEnv !== undefined && fromEnv !== '') {
+        return { name: 'master key', status: 'pass', detail: 'provided via BOOMBOT_MASTER_KEY' };
+    }
+    const keyPath = resolveMasterKeyPath(configPath);
+    if (existsSync(keyPath)) {
+        return { name: 'master key', status: 'pass', detail: `found at ${keyPath}` };
+    }
+    return {
+        name: 'master key',
+        status: 'fail',
+        detail: `no master key at ${keyPath} — provider API keys are stored encrypted and need one`,
+        fix: 'run `boombot setup` to generate one, or set BOOMBOT_MASTER_KEY',
+    };
+}
+/** Try to bind `host:port` briefly. Resolves when the port is free. */
+function tryBind(host, port) {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.once('error', (err) => {
+            srv.close(() => reject(err));
+        });
+        srv.listen(port, host, () => {
+            srv.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    });
+}
+async function checkPort(host, port) {
+    try {
+        await tryBind(host, port);
+        return { name: 'port', status: 'pass', detail: `port ${port} on ${host} is free` };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EADDRINUSE') {
+            return {
+                name: 'port',
+                status: 'fail',
+                detail: `port ${port} on ${host} is already in use (and it is not our gateway)`,
+                fix: 'stop the other process, or pick another port in `boombot setup`',
+            };
+        }
+        return {
+            name: 'port',
+            status: 'fail',
+            detail: `cannot bind ${host}:${port}: ${err.message}`,
+            fix: 'check the host/port in your config',
+        };
+    }
+}
+/** Read `<dataDir>/providers.json`; `null` when absent/unreadable/invalid. */
+function readProviderStore(dataDir) {
+    let raw;
+    try {
+        raw = readFileSync(providerStorePath(dataDir), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.providers))
+            return { count: 0, active: 0 };
+        const providers = parsed.providers;
+        return {
+            count: providers.length,
+            active: providers.filter((p) => p.active === true).length,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function checkWebAssets() {
+    const web = resolveWebAssets();
+    if (web.found) {
+        return { name: 'web assets', status: 'pass', detail: `web UI found at ${web.path}` };
+    }
+    if (web.isDistLayout) {
+        // A global `npm i -g` install must ship dist/web — its absence is a broken install.
+        return {
+            name: 'web assets',
+            status: 'fail',
+            detail: 'bundled web UI is missing from this install (the gateway would run API-only)',
+            fix: 'reinstall: npm i -g @boombot/cli',
+        };
+    }
+    return {
+        name: 'web assets',
+        status: 'warn',
+        detail: 'web UI not built — the gateway will run API-only',
+        fix: 'build it with `pnpm --filter @boombot/web build` (or run the web dev server)',
+    };
+}
+export async function runDoctor(options = {}) {
+    const checks = [];
+    const configPath = options.configPath ?? resolveConfigPath();
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.healthTimeoutMs ?? HEALTH_TIMEOUT_MS;
+    // 0. Node.js version.
+    checks.push(checkNodeVersion());
+    checks.push(checkPythonRuntime());
+    // 1. Config file exists and is valid.
+    let config = null;
+    try {
+        config = loadConfig(configPath);
+    }
+    catch (err) {
+        checks.push({
+            name: 'config file',
+            status: 'fail',
+            detail: err instanceof ConfigError ? err.message : `unexpected error: ${err.message}`,
+            fix: 'run `boombot setup` to create a fresh config, or fix the JSON by hand',
+        });
+    }
+    if (config === null) {
+        checks.push({
+            name: 'config file',
+            status: 'fail',
+            detail: `not found at ${configPath}`,
+            fix: 'run `boombot setup` to create it',
+        });
+    }
+    else {
+        const problems = validateConfig(config);
+        checks.push(problems.length === 0
+            ? { name: 'config file', status: 'pass', detail: `${configPath} is valid` }
+            : {
+                name: 'config file',
+                status: 'fail',
+                detail: problems.join('; '),
+                fix: 'run `boombot setup` again or edit the file',
+            });
+        // 2. File permissions when secrets are present.
+        const bits = fileModeBits(configPath);
+        if (configHasSecrets(config)) {
+            if (process.platform === 'win32') {
+                // chmod 0600 is a no-op on Windows (no POSIX permission bits), so
+                // a PASS here would lie. Report WARN: secrets are NOT OS-protected.
+                checks.push({
+                    name: 'config permissions',
+                    status: 'warn',
+                    detail: `${configPath} holds secrets but permission bits are not enforced on Windows ` +
+                        `(chmod is a no-op there) — restrict the file via Windows ACLs`,
+                    fix: 'use `icacls` to remove access for other users, or keep the machine single-user (see SECURITY.md §5)',
+                });
+            }
+            else if (bits === 0o600) {
+                checks.push({
+                    name: 'config permissions',
+                    status: 'pass',
+                    detail: `${configPath} is 0600 (secrets protected)`,
+                });
+            }
+            else {
+                checks.push({
+                    name: 'config permissions',
+                    status: 'fail',
+                    detail: `config contains secrets but ${configPath} has mode ${bits === null ? 'unknown' : '0o' + bits.toString(8)}`,
+                    fix: `run \`chmod 600 ${configPath}\``,
+                });
+            }
+        }
+        else {
+            checks.push({
+                name: 'config permissions',
+                status: 'pass',
+                detail: 'no secrets in config file — permissions not critical',
+            });
+        }
+        // 3. dataDir writable.
+        const dataDir = expandTilde(config.dataDir);
+        try {
+            mkdirSync(dataDir, { recursive: true });
+            accessSync(dataDir, constants.W_OK);
+            checks.push({ name: 'data dir', status: 'pass', detail: `${dataDir} is writable` });
+        }
+        catch (err) {
+            checks.push({
+                name: 'data dir',
+                status: 'fail',
+                detail: `${dataDir}: ${err.message}`,
+                fix: 'check directory ownership and permissions',
+            });
+        }
+        // 4. Master key for provider-key encryption.
+        checks.push(checkMasterKey(configPath));
+        // 5. Gateway reachable.
+        const url = healthzUrl(config);
+        let gatewayOk = false;
+        try {
+            const res = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+            if (res.ok) {
+                gatewayOk = true;
+                checks.push({ name: 'gateway', status: 'pass', detail: `GET ${url} → ${res.status}` });
+            }
+            else {
+                checks.push({
+                    name: 'gateway',
+                    status: 'fail',
+                    detail: `GET ${url} → ${res.status} (expected 2xx)`,
+                    fix: 'start it with `boombot gateway`',
+                });
+            }
+        }
+        catch (err) {
+            checks.push({
+                name: 'gateway',
+                status: 'fail',
+                detail: `GET ${url} failed: ${err.message}`,
+                fix: 'start it with `boombot gateway`',
+            });
+        }
+        // 6. Port bindable — only when the gateway is NOT already answering
+        // (a running gateway legitimately holds the port).
+        if (!gatewayOk) {
+            checks.push(await checkPort(config.host, config.port));
+        }
+        // 7. Provider configured in the real encrypted store.
+        const store = readProviderStore(config.dataDir);
+        if (store !== null && store.count > 0) {
+            checks.push({
+                name: 'provider',
+                status: 'pass',
+                detail: `${store.count} provider(s) in ${providerStorePath(config.dataDir)} (${store.active} active)`,
+            });
+        }
+        else {
+            checks.push({
+                name: 'provider',
+                status: 'fail',
+                detail: 'no default provider configured',
+                fix: 'run `boombot setup` and choose a provider',
+            });
+        }
+        // 8. Web UI assets the gateway would serve.
+        checks.push(checkWebAssets());
+        // 9. Channel tokens present (names only — never the token values).
+        const present = [];
+        const empty = [];
+        const sections = [
+            ['telegram', config.telegram?.botToken],
+            ['discord', config.discord?.botToken],
+            ['slack', config.slack?.botToken],
+            ['whatsapp', config.whatsapp?.accessToken],
+        ];
+        for (const [name, token] of sections) {
+            if (token !== undefined && token !== '')
+                present.push(name);
+            else
+                empty.push(name);
+        }
+        if (present.length > 0) {
+            checks.push({
+                name: 'channels',
+                status: 'pass',
+                detail: `configured: ${present.join(', ')}; not configured: ${empty.length > 0 ? empty.join(', ') : 'none'}`,
+            });
+        }
+        else if (empty.some((name) => hasChannelSection(config, name))) {
+            checks.push({
+                name: 'channels',
+                status: 'fail',
+                detail: 'channel section exists but its token is empty',
+                fix: 'run `boombot setup` again and paste the token, or remove the empty section',
+            });
+        }
+        else {
+            checks.push({
+                name: 'channels',
+                status: 'pass',
+                detail: 'no channels configured (optional — chat via web UI still works)',
+            });
+        }
+    }
+    return { checks, ok: checks.every((c) => c.status !== 'fail') };
+}
+function hasChannelSection(config, name) {
+    switch (name) {
+        case 'telegram':
+            return config.telegram !== undefined;
+        case 'discord':
+            return config.discord !== undefined;
+        case 'slack':
+            return config.slack !== undefined;
+        case 'whatsapp':
+            return config.whatsapp !== undefined;
+        default:
+            return false;
+    }
+}
+/** Print a report in `PASS`/`WARN`/`FAIL` lines. Returns the exit code (0 when nothing failed). */
+export function printDoctorReport(report) {
+    for (const check of report.checks) {
+        const tag = check.status === 'pass' ? 'PASS' : check.status === 'warn' ? 'WARN' : 'FAIL';
+        console.log(`${tag}  ${check.name}: ${check.detail}`);
+        if (check.status !== 'pass' && check.fix !== undefined) {
+            console.log(`      fix: ${check.fix}`);
+        }
+    }
+    console.log(report.ok ? '\nAll checks passed.' : '\nSome checks failed — see fixes above.');
+    return report.ok ? 0 : 1;
+}

package/dist/cli/commands/gateway.js

@@ -0,0 +1,290 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * `boombot gateway` — boot the gateway in-process.
+ *
+ * The gateway entry is owned by the coordinator: `agent-worker/src/index.ts`
+ * MUST export `startGateway(): Promise<void>`. This launcher resolves that
+ * entry relative to THIS file (override with `BOOMBOT_GATEWAY_ENTRY`),
+ * dynamic-imports it, and hands over control.
+ *
+ * Layouts handled (first existing file wins):
+ * - npm dist, bundled CLI:  `dist/bin/boombot.js`     → `dist/gateway/index.js`
+ * - npm dist, per-file tsc: `dist/bin/commands/*.js` → `dist/gateway/index.js`
+ * - monorepo build:         `apps/cli/…`              → `agent-worker/dist/index.js`
+ *
+ * Only the npm-dist bundle is runnable by plain `node`: its workspace deps are
+ * vendored as compiled JS under `dist/node_modules/@boombot/*`. The monorepo
+ * candidate is a last resort — it resolves `@boombot/*` through the
+ * workspace symlink to TypeScript sources whose relative `./x.js` specifiers
+ * do not resolve outside vitest, so it is listed last and never preferred.
+ * Source-tree runs must use `BOOMBOT_GATEWAY_ENTRY`.
+ *
+ * Before booting, the provider master key is loaded into
+ * `BOOMBOT_MASTER_KEY` (the gateway refuses to boot without it). After the
+ * server is listening, the UI URL is printed and opened in the browser
+ * (best-effort; `BOOMBOT_NO_BROWSER=1` or `--no-browser` skips it).
+ *
+ * The browser is handed the stored gateway API key in the URL fragment
+ * (`#k=…`, see `withApiKey`) — that is what lets the web UI connect on its own
+ * instead of opening on a form asking for a secret the user has no way to look
+ * up. The URL that gets PRINTED never carries the key: it must not reach a
+ * terminal, a log, or a pasted bug report.
+ *
+ * NOTE for the coordinator: please make sure `startGateway` exists and
+ * resolves when the gateway is up (it should keep the process alive via its
+ * server/scheduler, like `src/main.ts` does today once wired).
+ */
+import { existsSync } from 'node:fs';
+import { isIP } from 'node:net';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { apiKeyMatchesHash, effectiveApiKey, ensureApiKey, resolveApiKeyPath } from "../api-key.js";
+import { loadConfig, resolveConfigPath, saveConfig } from "../config-file.js";
+import { ensureMasterKey, ensureMasterKeyEnv, hasMasterKey, resolveMasterKeyPath } from "../master-key.js";
+import { openBrowser } from "../open-browser.js";
+/**
+ * The `apps/cli` package root, derived from this file's own location.
+ * Exported for tests.
+ *
+ * Uses `fileURLToPath` — NOT `new URL(import.meta.url).pathname`: on
+ * Windows a file URL looks like `file:///C:/...` and `.pathname` keeps the
+ * bogus leading `/C:/`, which `path.resolve` then mangles into `\C:\...`.
+ */
+export function cliPackageRoot() {
+    // src/commands/gateway.ts → apps/cli/
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+/** Directory containing this module file (`dist/bin[/commands]` in the npm layout). */
+function moduleDir() {
+    return path.dirname(fileURLToPath(import.meta.url));
+}
+function resolveGatewayEntry() {
+    const override = process.env['BOOMBOT_GATEWAY_ENTRY'];
+    if (override !== undefined && override !== '')
+        return override;
+    const dir = moduleDir();
+    // Order matters: the npm-dist bundle is the ONLY candidate plain `node` can
+    // load (see the header note). The monorepo paths point at TS sources whose
+    // `.js` specifiers never resolve outside vitest, so they must never shadow a
+    // real bundle — listing them first is what made a working install crash.
+    const candidates = [
+        // npm dist layout (bundled CLI): dist/bin/boombot.js → dist/gateway/index.js
+        path.join(dir, '..', 'gateway', 'index.js'),
+        path.join(dir, '..', 'gateway', 'main.js'),
+        // npm dist layout (per-file tsc): dist/bin/commands/gateway.js → dist/gateway/index.js
+        path.join(dir, '..', '..', 'gateway', 'index.js'),
+        // Monorepo build layout — last resort only (not runnable under plain node).
+        path.join(cliPackageRoot(), '..', '..', 'agent-worker', 'dist', 'index.js'),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error('gateway entry not found — expected dist/gateway/index.js next to the CLI ' +
+        '(npm layout) or agent-worker/dist/index.js (monorepo layout, which plain ' +
+        'node cannot load). Reinstall so dist/gateway/ ships, or point ' +
+        'BOOMBOT_GATEWAY_ENTRY=<path> at a runnable bundle.');
+}
+/** Gateway host/port from the CLI config (safe defaults when unreadable). */
+function gatewayHostPort() {
+    try {
+        const config = loadConfig(resolveConfigPath());
+        const host = process.env['BOOMBOT_HOST']?.trim() || config?.host || '127.0.0.1';
+        const port = Number.parseInt(process.env['BOOMBOT_PORT']?.trim() || String(config?.port ?? 8787), 10);
+        return { host, port: Number.isInteger(port) && port > 0 && port <= 65535 ? port : 8787 };
+    }
+    catch {
+        return { host: '127.0.0.1', port: 8787 };
+    }
+}
+/** Public URL for the browser: 0.0.0.0/:: mean "this machine". Exported for tests. */
+export function gatewayPublicUrl() {
+    const { host, port } = gatewayHostPort();
+    const browserHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
+    return `http://${isIP(browserHost) === 6 ? `[${browserHost}]` : browserHost}:${port}`;
+}
+/**
+ * The URL to hand the browser, with the stored API key in the fragment.
+ *
+ * The fragment is deliberate: browsers never transmit it to the server, so the
+ * key cannot land in an access log or a `Referer` header, and it is never baked
+ * into the served HTML — where any script on the origin could read it.
+ *
+ * Returns `url` unchanged when no key is stored. A gateway on another machine is
+ * not this CLI's to vouch for, and the UI's manual form is the right path there.
+ * Exported for tests.
+ */
+export function withApiKey(url, keyPath = resolveApiKeyPath()) {
+    const key = effectiveApiKey(keyPath);
+    if (key === null)
+        return url;
+    const target = new URL(url);
+    target.hash = `k=${encodeURIComponent(key)}`;
+    return target.href;
+}
+/** First launch only: local defaults and recoverable keys, never reset an existing install. */
+export function initializeGateway(configPath = resolveConfigPath()) {
+    if (loadConfig(configPath) !== null)
+        return false;
+    const dataDir = path.resolve(process.env['BOOMBOT_DATA_DIR']?.trim() || path.join(path.dirname(path.resolve(configPath)), 'data'));
+    const masterKeyPath = resolveMasterKeyPath(configPath);
+    if (!hasMasterKey(masterKeyPath)) {
+        if (existsSync(path.join(dataDir, 'providers.json'))) {
+            throw new Error('Existing provider data has no master key. Restore master.key before starting; no keys were changed.');
+        }
+        ensureMasterKey(masterKeyPath);
+    }
+    const { apiKeyHash } = ensureApiKey(resolveApiKeyPath(configPath));
+    saveConfig({ host: '127.0.0.1', port: 8787, dataDir, apiKeyHash }, configPath, 'wx');
+    return true;
+}
+/**
+ * Say so when the stored key cannot authenticate, instead of letting the UI open
+ * on a silent UNAUTHORIZED that reads like a broken gateway.
+ *
+ * Three ways to end up there, in the order they are checked: no hash in
+ * `config.json` at all (the gateway fails closed on every request), no key left
+ * to hand over, or a key that no longer hashes to the stored one — an old
+ * `api.key` beside a config rewritten by a later `boombot setup`.
+ */
+function warnOnApiKeyDrift() {
+    let hash;
+    try {
+        hash = loadConfig(resolveConfigPath())?.apiKeyHash;
+    }
+    catch {
+        return; // unreadable config — the gateway's own error is clearer than ours
+    }
+    if (hash === undefined) {
+        console.log('⚠ config.json has no apiKeyHash — the gateway rejects every request.\n' +
+            '  Run `boombot setup` to generate one.');
+        return;
+    }
+    if (effectiveApiKey() === null) {
+        // The state every install predating `api.key` is in: config.json keeps the
+        // hash, the plaintext is gone, and no arithmetic brings it back. Say so —
+        // the UI otherwise just shows a form asking for a secret that does not exist.
+        console.log(`⚠ config.json has an apiKeyHash but ${resolveApiKeyPath()} is missing, so there is\n` +
+            '  no key left to sign the browser in with — a hash cannot be turned back into\n' +
+            '  the key it came from. Re-run `boombot setup` to rotate it (the old key stops\n' +
+            '  working), or restore that file if you still have the key.');
+        return;
+    }
+    if (apiKeyMatchesHash(hash) === false) {
+        console.log(`⚠ ${resolveApiKeyPath()} does not match config.json's apiKeyHash — the browser\n` +
+            '  would be signed in with a key the gateway rejects. Delete that file and\n' +
+            '  re-run `boombot setup` to rotate the key.');
+    }
+}
+/**
+ * Run the gateway from a statically-bundled module (Bun `--compile` binary).
+ * Mirrors the tail of `runGateway()` below: starts the gateway, wires up
+ * the shutdown IPC handshake, prints the URL.
+ */
+async function runBundledGateway(mod, options) {
+    const firstRun = initializeGateway();
+    ensureMasterKeyEnv();
+    const start = mod.startGatewayManaged ?? mod.startGateway;
+    if (typeof start !== 'function') {
+        throw new Error('bundled gateway does not export startGateway(): Promise<void>.');
+    }
+    try {
+        const stop = await start();
+        if (typeof stop === 'function' && typeof process.send === 'function') {
+            process.on('message', (message) => {
+                if (typeof message === 'object' &&
+                    message !== null &&
+                    message.type === 'shutdown') {
+                    void stop().finally(() => process.exit(0));
+                }
+            });
+        }
+    }
+    catch (err) {
+        if (err.code === 'EADDRINUSE') {
+            const { port } = gatewayHostPort();
+            throw new Error(`port ${port} is already in use — is another gateway running? ` +
+                `Stop it, or pick another port in ${resolveConfigPath()}.`);
+        }
+        throw err;
+    }
+    const url = gatewayPublicUrl();
+    console.log(`\n🦉 BoomBot is running — open ${url} in your browser\n`);
+    warnOnApiKeyDrift();
+    if (firstRun) {
+        console.log('Local setup complete. Choose your AI provider in Settings → Connection. Keep this terminal open; Ctrl+C stops BoomBot.');
+    }
+    if (!options.noBrowser && process.env['BOOMBOT_NO_BROWSER'] !== '1') {
+        await openBrowser(url);
+    }
+}
+export async function runGateway(options = {}) {
+    // Bun-compiled standalone binary: the gateway is bundled via a static import
+    // (see src/bin-bun.ts). Check for it before the dynamic-import path below.
+    const bundled = globalThis.__BOOMBOT_BUNDLED_GATEWAY__;
+    if (bundled && (typeof bundled.startGatewayManaged === 'function' || typeof bundled.startGateway === 'function')) {
+        await runBundledGateway(bundled, options);
+        return;
+    }
+    const entry = resolveGatewayEntry();
+    const firstRun = initializeGateway();
+    // The gateway needs BOOMBOT_MASTER_KEY to decrypt provider keys; load the
+    // key `boombot setup` generated so a fresh install just works.
+    ensureMasterKeyEnv();
+    let mod;
+    try {
+        mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href)));
+    }
+    catch (err) {
+        throw new Error(`failed to import gateway entry ${entry}: ${err.message}`);
+    }
+    const start = mod.startGatewayManaged ?? mod.startGateway;
+    if (typeof start !== 'function') {
+        throw new Error(`gateway entry ${entry} does not export startGateway(): Promise<void> ` +
+            '(coordinator: please add this export).');
+    }
+    try {
+        const stop = await start();
+        if (typeof stop === 'function' && typeof process.send === 'function') {
+            process.on('message', (message) => {
+                if (typeof message === 'object' &&
+                    message !== null &&
+                    message.type === 'shutdown') {
+                    void stop().finally(() => process.exit(0));
+                }
+            });
+        }
+    }
+    catch (err) {
+        if (err.code === 'EADDRINUSE') {
+            const { port } = gatewayHostPort();
+            throw new Error(`port ${port} is already in use — is another gateway running? ` +
+                `Stop it, or pick another port in ${resolveConfigPath()}.`);
+        }
+        throw err;
+    }
+    // startGateway resolves once the server is listening.
+    const url = gatewayPublicUrl();
+    console.log(`\n🦉 BoomBot is running — open ${url} in your browser\n`);
+    warnOnApiKeyDrift();
+    if (firstRun) {
+        console.log('Local setup complete. Choose your AI provider in Settings → Connection. Keep this terminal open; Ctrl+C stops BoomBot.');
+    }
+    if (options.noBrowser !== true) {
+        // The fragment carries the API key to the browser. Browsers never send a
+        // fragment to the server, so the key reaches neither the static file server
+        // nor any access log, and it is not baked into the served HTML. The web app
+        // persists it and rewrites the URL to drop it again.
+        const opened = await openBrowser(withApiKey(firstRun ? `${url}/settings/connection` : url));
+        if (!opened) {
+            console.log('(could not open a browser automatically — headless? open the URL above yourself)');
+        }
+    }
+}