@bbigbang/server-ops 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+type JoinOptions = {
+    hubUrl: string;
+    token: string;
+    serverId: string;
+    serverSlug: string;
+    serverName: string;
+    version: string;
+    installPackages: string[];
+    port: number;
+    service: 'systemd' | 'tmux' | 'none';
+    dryRun: boolean;
+};
+type BridgeOptions = {
+    hubUrl: string;
+    token: string;
+    credentialPath: string;
+    serverId: string;
+    serverSlug: string;
+    serverName: string;
+    version: string;
+    coreUrl: string;
+};
+export declare function joinServer(options: JoinOptions): Promise<void>;
+export declare function runBridge(options: BridgeOptions): Promise<void>;
+export {};

package/dist/index.js

@@ -0,0 +1,591 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import WebSocket from 'ws';
+const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/u;
+const MAX_BRIDGE_HTTP_BODY_BYTES = 25 * 1024 * 1024;
+async function main(argv = process.argv.slice(2)) {
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        printUsage();
+        return;
+    }
+    const [scope, command, ...rest] = argv;
+    if (scope === 'server' && command === 'join') {
+        await joinServer(parseJoinOptions(rest));
+        return;
+    }
+    if (scope === 'server' && command === 'bridge') {
+        await runBridge(parseBridgeOptions(rest));
+        return;
+    }
+    {
+        throw new Error(`Unknown command: ${argv.join(' ')}`);
+    }
+}
+export async function joinServer(options) {
+    validateJoinOptions(options);
+    const home = os.homedir();
+    const coreHome = process.env.BIGBANG_HOME?.trim() || path.join(home, '.bigbang');
+    const nodeHome = process.env.BIGBANG_NODE_HOME?.trim() || path.join(home, '.bigbang-node');
+    const coreConfigPath = path.join(coreHome, 'config.json');
+    const nodeEnvPath = path.join(nodeHome, 'server.env');
+    const legacyNodeEnvPath = path.join(home, '.bigbang-node.env');
+    const bridgeEnvPath = path.join(coreHome, 'bridge.env');
+    const bridgeCredentialPath = path.join(coreHome, 'bridge-credential.json');
+    const coreWsUrl = `ws://127.0.0.1:${options.port}`;
+    const coreHttpUrl = `http://127.0.0.1:${options.port}`;
+    const coreConfig = {
+        serverId: options.serverId,
+        serverSlug: options.serverSlug,
+        serverName: options.serverName,
+        publicServerUrl: stripTrailingSlash(options.hubUrl),
+        publicBasePath: `/s/${options.serverSlug}`,
+        agentBridgeServerUrl: coreHttpUrl,
+        webHost: '127.0.0.1',
+        webPort: options.port,
+        workspaceRoot: path.join(coreHome, 'workspace'),
+        dbPath: path.join(coreHome, 'data', 'gateway.db'),
+        internalAgentAuthToken: cryptoRandomToken(),
+        nodeDispatchAckTimeoutMs: 5_000,
+    };
+    const nodeEnv = [
+        envLine('CORE_URL', coreWsUrl),
+        envLine('NODE_ID', `${options.serverSlug}-node-1`),
+        envLine('NODE_HOSTNAME', os.hostname()),
+        envLine('DB_PATH', path.join(nodeHome, 'db.sqlite')),
+        envLine('WORKSPACE_ROOT', path.join(nodeHome, 'workspace')),
+        '',
+    ].join('\n');
+    const bridgeEnv = [
+        envLine('HUB_URL', stripTrailingSlash(options.hubUrl)),
+        envLine('TOKEN', options.token),
+        envLine('BRIDGE_CREDENTIAL_PATH', bridgeCredentialPath),
+        envLine('SERVER_ID', options.serverId),
+        envLine('SERVER_SLUG', options.serverSlug),
+        envLine('SERVER_NAME', options.serverName),
+        envLine('VERSION', options.version),
+        envLine('CORE_URL', coreHttpUrl),
+        '',
+    ].join('\n');
+    if (options.dryRun) {
+        console.log(JSON.stringify({
+            action: 'dry-run',
+            installPackages: packageInstallList(options),
+            coreConfigPath,
+            coreConfig,
+            nodeEnvPath,
+            legacyNodeEnvPath,
+            nodeEnv,
+            bridgeEnvPath,
+            bridgeEnv,
+            service: options.service,
+            bridgeUrl: buildBridgeUrl(options.hubUrl, options.token),
+        }, null, 2));
+        return;
+    }
+    run('npm', ['install', '-g', ...packageInstallList(options)]);
+    fs.mkdirSync(path.dirname(coreConfigPath), { recursive: true });
+    fs.mkdirSync(path.dirname(nodeEnvPath), { recursive: true });
+    fs.writeFileSync(coreConfigPath, `${JSON.stringify(coreConfig, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(nodeEnvPath, nodeEnv, 'utf8');
+    fs.writeFileSync(legacyNodeEnvPath, nodeEnv, 'utf8');
+    fs.writeFileSync(bridgeEnvPath, bridgeEnv, 'utf8');
+    await startServices(options, { coreHome, nodeEnvPath, bridgeEnvPath });
+    console.log(JSON.stringify({
+        ok: true,
+        status: 'services-started',
+        registration: 'pending-bridge-connection',
+        serverSlug: options.serverSlug,
+        bridge: buildBridgeUrl(options.hubUrl, options.token),
+        bridgeCredentialPath,
+    }, null, 2));
+}
+function parseJoinOptions(argv) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith('--'))
+            throw new Error(`Unexpected argument: ${arg}`);
+        if (arg === '--dry-run') {
+            values.set('dry-run', true);
+            continue;
+        }
+        const value = argv[index + 1];
+        if (!value || value.startsWith('--'))
+            throw new Error(`${arg} requires a value.`);
+        values.set(arg.slice(2), value);
+        index += 1;
+    }
+    return {
+        hubUrl: readString(values, 'hub-url', true),
+        token: readString(values, 'token', true),
+        serverId: readString(values, 'server-id', true),
+        serverSlug: readString(values, 'server-slug', true),
+        serverName: readString(values, 'server-name', true),
+        version: readString(values, 'version', true),
+        installPackages: parseInstallPackages(readString(values, 'install-packages', false)),
+        port: Number(readString(values, 'port', false) || '3100'),
+        service: normalizeService(readString(values, 'service', false) || 'systemd'),
+        dryRun: values.get('dry-run') === true,
+    };
+}
+function parseBridgeOptions(argv) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith('--'))
+            throw new Error(`Unexpected argument: ${arg}`);
+        const value = argv[index + 1];
+        if (!value || value.startsWith('--'))
+            throw new Error(`${arg} requires a value.`);
+        values.set(arg.slice(2), value);
+        index += 1;
+    }
+    const options = {
+        hubUrl: readString(values, 'hub-url', false) || process.env.HUB_URL?.trim() || '',
+        token: readString(values, 'token', false) || process.env.TOKEN?.trim() || '',
+        credentialPath: readString(values, 'credential-path', false) || process.env.BRIDGE_CREDENTIAL_PATH?.trim() || path.join(os.homedir(), '.bigbang', 'bridge-credential.json'),
+        serverId: readString(values, 'server-id', false) || process.env.SERVER_ID?.trim() || '',
+        serverSlug: readString(values, 'server-slug', false) || process.env.SERVER_SLUG?.trim() || '',
+        serverName: readString(values, 'server-name', false) || process.env.SERVER_NAME?.trim() || '',
+        version: readString(values, 'version', false) || process.env.VERSION?.trim() || '',
+        coreUrl: readString(values, 'core-url', false) || process.env.CORE_URL?.trim() || 'http://127.0.0.1:3100',
+    };
+    validateBridgeOptions(options);
+    return options;
+}
+function readString(values, key, required) {
+    const value = values.get(key);
+    if (typeof value === 'string' && value.trim())
+        return value.trim();
+    if (required)
+        throw new Error(`--${key} is required.`);
+    return '';
+}
+function normalizeService(value) {
+    if (value === 'systemd' || value === 'tmux' || value === 'none')
+        return value;
+    throw new Error('--service must be systemd, tmux, or none.');
+}
+function validateJoinOptions(options) {
+    if (!SLUG_RE.test(options.serverSlug))
+        throw new Error('--server-slug must be a safe path segment.');
+    if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535)
+        throw new Error('--port must be 1..65535.');
+    normalizeHttpUrl(options.hubUrl, '--hub-url');
+}
+function validateBridgeOptions(options) {
+    if (!SLUG_RE.test(options.serverSlug))
+        throw new Error('--server-slug must be a safe path segment.');
+    for (const field of ['hubUrl', 'token', 'serverId', 'serverName', 'version']) {
+        if (!options[field])
+            throw new Error(`--${field.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`)} is required.`);
+    }
+    normalizeHttpUrl(options.hubUrl, '--hub-url');
+    normalizeHttpUrl(options.coreUrl, '--core-url');
+}
+function parseInstallPackages(value) {
+    if (!value.trim())
+        return [];
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function packageInstallList(options) {
+    if (options.installPackages.length > 0)
+        return [...options.installPackages];
+    return [
+        `@bbigbang/cli@${options.version}`,
+        `@bbigbang/core@${options.version}`,
+        `@bbigbang/agent-node@${options.version}`,
+    ];
+}
+async function startServices(options, paths) {
+    if (options.service === 'none')
+        return;
+    if (options.service === 'systemd') {
+        try {
+            installSystemdServices(paths);
+            run('systemctl', ['--user', 'daemon-reload']);
+            run('systemctl', ['--user', 'enable', '--now', 'bigbang-core.service', 'bigbang-node.service', 'bigbang-bridge.service']);
+            return;
+        }
+        catch (error) {
+            console.warn(`systemd setup failed; falling back to tmux: ${String(error?.message ?? error)}`);
+            cleanupSystemdServices();
+        }
+    }
+    startTmuxServices(paths);
+}
+function installSystemdServices(paths) {
+    const dir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'bigbang-core.service'), [
+        '[Unit]',
+        'Description=Bigbang Core',
+        '',
+        '[Service]',
+        `Environment=BIGBANG_HOME=${paths.coreHome}`,
+        'ExecStart=bigbang-core',
+        'Restart=always',
+        'RestartSec=3',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+        '',
+    ].join('\n'), 'utf8');
+    fs.writeFileSync(path.join(dir, 'bigbang-node.service'), [
+        '[Unit]',
+        'Description=Bigbang Agent Node',
+        'After=bigbang-core.service',
+        '',
+        '[Service]',
+        `EnvironmentFile=${paths.nodeEnvPath}`,
+        'ExecStart=bigbang-node',
+        'Restart=always',
+        'RestartSec=3',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+        '',
+    ].join('\n'), 'utf8');
+    fs.writeFileSync(path.join(dir, 'bigbang-bridge.service'), [
+        '[Unit]',
+        'Description=Bigbang Hub Bridge',
+        'After=bigbang-core.service',
+        '',
+        '[Service]',
+        `EnvironmentFile=${paths.bridgeEnvPath}`,
+        'ExecStart=bigbang server bridge',
+        'Restart=always',
+        'RestartSec=3',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+        '',
+    ].join('\n'), 'utf8');
+}
+function cleanupSystemdServices() {
+    spawnSync('systemctl', ['--user', 'disable', '--now', 'bigbang-core.service', 'bigbang-node.service', 'bigbang-bridge.service'], { stdio: 'ignore' });
+    const dir = path.join(os.homedir(), '.config', 'systemd', 'user');
+    fs.rmSync(path.join(dir, 'bigbang-core.service'), { force: true });
+    fs.rmSync(path.join(dir, 'bigbang-node.service'), { force: true });
+    fs.rmSync(path.join(dir, 'bigbang-bridge.service'), { force: true });
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+}
+function startTmuxServices(paths) {
+    const session = 'bigbang-server';
+    spawnSync('tmux', ['kill-session', '-t', session], { stdio: 'ignore' });
+    run('tmux', ['new-session', '-d', '-s', session, `BIGBANG_HOME=${shellQuote(paths.coreHome)} bigbang-core`]);
+    run('tmux', ['new-window', '-t', session, '-n', 'node', `set -a; . ${shellQuote(paths.nodeEnvPath)}; set +a; bigbang-node`]);
+    run('tmux', ['new-window', '-t', session, '-n', 'bridge', `set -a; . ${shellQuote(paths.bridgeEnvPath)}; set +a; bigbang server bridge`]);
+}
+export async function runBridge(options) {
+    const sockets = new Map();
+    let reconnectDelayMs = 1000;
+    let currentToken = readPersistedBridgeToken(options.credentialPath) ?? options.token;
+    for (;;) {
+        const fatalError = await new Promise((resolve) => {
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(error);
+            };
+            const ws = new WebSocket(buildBridgeUrl(options.hubUrl, currentToken));
+            const send = (message) => {
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.send(JSON.stringify(message));
+            };
+            ws.once('open', () => {
+                reconnectDelayMs = 1000;
+                send({
+                    type: 'hello',
+                    token: currentToken,
+                    serverId: options.serverId,
+                    serverSlug: options.serverSlug,
+                    serverName: options.serverName,
+                    version: options.version,
+                });
+            });
+            ws.on('message', (raw) => {
+                const message = parseHubMessage(raw);
+                if (!message)
+                    return;
+                if (message.type === 'hello_ack') {
+                    if (message.bridgeToken) {
+                        currentToken = message.bridgeToken;
+                        writePersistedBridgeToken(options.credentialPath, message.bridgeToken);
+                    }
+                    console.log(`[bridge] connected ${message.serverSlug}`);
+                    return;
+                }
+                if (message.type === 'hello_error') {
+                    console.error(`[bridge] rejected: ${message.error}`);
+                    finish(new Error(message.error));
+                    ws.close();
+                    return;
+                }
+                if (message.type === 'http_request') {
+                    void handleBridgeHttpRequest(options, message, send);
+                    return;
+                }
+                if (message.type === 'ws_open') {
+                    openBridgeWebSocket(options, message, send, sockets);
+                    return;
+                }
+                if (message.type === 'ws_data') {
+                    sockets.get(message.requestId)?.write(Buffer.from(message.bodyBase64, 'base64'));
+                    return;
+                }
+                if (message.type === 'ws_close') {
+                    const socket = sockets.get(message.requestId);
+                    sockets.delete(message.requestId);
+                    socket?.destroy();
+                    return;
+                }
+                if (message.type === 'ping')
+                    send({ type: 'pong' });
+            });
+            ws.once('close', () => {
+                for (const socket of sockets.values())
+                    socket.destroy();
+                sockets.clear();
+                finish(null);
+            });
+            ws.once('error', (error) => {
+                console.error(`[bridge] connection error: ${String(error.message ?? error)}`);
+            });
+        });
+        if (fatalError)
+            throw fatalError;
+        await sleep(reconnectDelayMs);
+        reconnectDelayMs = Math.min(reconnectDelayMs * 2, 30_000);
+    }
+}
+async function handleBridgeHttpRequest(options, message, send) {
+    try {
+        const response = await fetch(new URL(message.path, `${stripTrailingSlash(options.coreUrl)}/`), {
+            method: message.method,
+            headers: message.headers,
+            body: message.bodyBase64 ? Buffer.from(message.bodyBase64, 'base64') : undefined,
+        });
+        const body = await readResponseBodyLimited(response, MAX_BRIDGE_HTTP_BODY_BYTES);
+        send({
+            type: 'http_response',
+            requestId: message.requestId,
+            statusCode: response.status,
+            headers: headersToRecord(response.headers),
+            bodyBase64: body.length > 0 ? body.toString('base64') : undefined,
+        });
+    }
+    catch (error) {
+        if (error instanceof BridgeBodyTooLargeError) {
+            send({
+                type: 'http_response',
+                requestId: message.requestId,
+                statusCode: 413,
+                headers: { 'content-type': 'application/json; charset=utf-8' },
+                bodyBase64: Buffer.from(JSON.stringify({ error: error.message })).toString('base64'),
+            });
+            return;
+        }
+        send({ type: 'http_error', requestId: message.requestId, error: String(error.message ?? error) });
+    }
+}
+class BridgeBodyTooLargeError extends Error {
+}
+async function readResponseBodyLimited(response, maxBytes) {
+    const contentLength = response.headers.get('content-length');
+    if (contentLength && Number(contentLength) > maxBytes) {
+        throw new BridgeBodyTooLargeError('Bridge HTTP response body is too large.');
+    }
+    if (!response.body)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        const buffer = Buffer.from(value);
+        totalBytes += buffer.length;
+        if (totalBytes > maxBytes) {
+            await reader.cancel();
+            throw new BridgeBodyTooLargeError('Bridge HTTP response body is too large.');
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+function openBridgeWebSocket(options, message, send, sockets) {
+    const coreUrl = new URL(options.coreUrl);
+    const socket = net.connect(Number(coreUrl.port || 80), coreUrl.hostname);
+    sockets.set(message.requestId, socket);
+    let handshake = Buffer.alloc(0);
+    let opened = false;
+    socket.once('connect', () => {
+        socket.write(buildLocalUpgradeRequest(message.path, coreUrl.host, message.headers));
+    });
+    socket.on('data', (chunk) => {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        if (!opened) {
+            handshake = Buffer.concat([handshake, buffer]);
+            const headerEnd = handshake.indexOf('\r\n\r\n');
+            if (headerEnd < 0)
+                return;
+            const headerText = handshake.subarray(0, headerEnd).toString('latin1');
+            const statusCode = parseStatusCode(headerText) ?? 502;
+            opened = statusCode === 101;
+            send({ type: 'ws_opened', requestId: message.requestId, statusCode, headers: parseHeaders(headerText) });
+            const rest = handshake.subarray(headerEnd + 4);
+            if (rest.length > 0)
+                send({ type: 'ws_data', requestId: message.requestId, bodyBase64: rest.toString('base64') });
+            if (!opened) {
+                sockets.delete(message.requestId);
+                socket.destroy();
+            }
+            return;
+        }
+        send({ type: 'ws_data', requestId: message.requestId, bodyBase64: buffer.toString('base64') });
+    });
+    socket.once('close', () => {
+        sockets.delete(message.requestId);
+        send({ type: 'ws_close', requestId: message.requestId, reason: 'local core closed' });
+    });
+    socket.once('error', (error) => {
+        sockets.delete(message.requestId);
+        send({ type: 'ws_error', requestId: message.requestId, error: String(error.message ?? error) });
+    });
+}
+function parseHubMessage(raw) {
+    try {
+        const text = Array.isArray(raw) ? Buffer.concat(raw).toString('utf8') : Buffer.from(raw).toString('utf8');
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && typeof parsed.type === 'string' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildLocalUpgradeRequest(pathname, host, headers) {
+    const lines = [`GET ${pathname} HTTP/1.1`];
+    const next = { ...headers, host, connection: 'Upgrade', upgrade: 'websocket' };
+    for (const [name, value] of Object.entries(next)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                lines.push(`${name}: ${item}`);
+        }
+        else {
+            lines.push(`${name}: ${value}`);
+        }
+    }
+    lines.push('', '');
+    return lines.join('\r\n');
+}
+function parseStatusCode(headerText) {
+    const match = /^HTTP\/\d(?:\.\d)?\s+(\d{3})(?:\s|$)/u.exec(headerText);
+    return match ? Number(match[1]) : null;
+}
+function parseHeaders(headerText) {
+    const headers = {};
+    for (const line of headerText.split('\r\n').slice(1)) {
+        const separator = line.indexOf(':');
+        if (separator < 0)
+            continue;
+        const name = line.slice(0, separator).trim();
+        const value = line.slice(separator + 1).trim();
+        const existing = headers[name];
+        if (Array.isArray(existing))
+            existing.push(value);
+        else if (typeof existing === 'string')
+            headers[name] = [existing, value];
+        else
+            headers[name] = value;
+    }
+    return headers;
+}
+function headersToRecord(headers) {
+    const record = {};
+    headers.forEach((value, key) => {
+        record[key] = value;
+    });
+    return record;
+}
+function buildBridgeUrl(hubUrl, token) {
+    const url = new URL('api/hub/server-bridge/ws', `${stripTrailingSlash(hubUrl)}/`);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    url.searchParams.set('token', token);
+    return url.toString();
+}
+function normalizeHttpUrl(value, name) {
+    try {
+        const parsed = new URL(value);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            throw new Error('bad protocol');
+    }
+    catch {
+        throw new Error(`${name} must be an http(s) URL.`);
+    }
+}
+function run(command, args) {
+    const result = spawnSync(command, args, { stdio: 'inherit' });
+    if (result.status !== 0)
+        throw new Error(`${command} ${args.join(' ')} failed with exit code ${result.status ?? 'unknown'}`);
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/u, '');
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function cryptoRandomToken() {
+    return `internal-${randomUUID()}`;
+}
+function readPersistedBridgeToken(credentialPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(credentialPath, 'utf8'));
+        return typeof parsed.bridgeToken === 'string' && parsed.bridgeToken.trim() ? parsed.bridgeToken.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writePersistedBridgeToken(credentialPath, bridgeToken) {
+    fs.mkdirSync(path.dirname(credentialPath), { recursive: true });
+    const tempPath = `${credentialPath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tempPath, `${JSON.stringify({ bridgeToken }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tempPath, credentialPath);
+}
+function envLine(key, value) {
+    return `${key}=${shellQuote(value)}`;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+function printUsage() {
+    console.log(`Usage:
+  bigbang server join --hub-url <url> --token <token> --server-id <id> --server-slug <slug> --server-name <name> --version <semver> [options]
+  bigbang server bridge --hub-url <url> --token <token> --server-id <id> --server-slug <slug> --server-name <name> --version <semver> [--core-url <url>]
+
+Options:
+  --port <n>               Local core port. Defaults to 3100.
+  --service <kind>         systemd, tmux, or none. Defaults to systemd.
+  --install-packages <csv> Comma-separated package specs for core/node/CLI installs.
+  --dry-run                Print planned actions without writing files or starting services.
+`);
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bbigbang/server-ops",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Bigbang server join and bridge operations",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/__tests__/**",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ws": "^8.18.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}