@tapicker/bridge 1.0.0

package/dist/cli.js

@@ -0,0 +1,835 @@
+#!/usr/bin/env node
+import { cac } from 'cac';
+import { chmodSync, closeSync, openSync, readFileSync } from 'node:fs';
+import { fork } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { DEFAULT_HOST, DEFAULT_PORT, VERSION } from './constants.js';
+import { BridgeError, serializeBridgeError } from './errors.js';
+import { createHttpMcpApi, createTapickerMcpServer } from './mcp.js';
+import { DataInputSchema, WorkflowControlInputSchema, WorkflowStartInputSchema, WorkflowStatusEventSchema, } from './protocol/schema.js';
+import { connectWorkflowWatch, waitForWorkflowStatus, workflowWatchWebSocketUrl } from './workflow-watch.js';
+import { BridgeServer } from './server.js';
+import { getDefaultBridgeDataDir } from './bridge/pairing-state.js';
+import { sendBridgeControlRequest, startBridgeControlServer } from './bridge/control.js';
+import { getBridgeDaemonLogPath, isProcessRunning, readBridgeDaemonState, removeBridgeDaemonState, writeBridgeDaemonState, } from './bridge/daemon.js';
+const DAEMON_CHILD_ENV = 'TAPICKER_BRIDGE_DAEMON_CHILD';
+const cli = cac('tapicker');
+cli
+    .command('bridge <action>', 'Manage Bridge: start/stop it, view the pairing code, or list connected Extensions')
+    .option('--host <host>', 'Host to bind', { default: DEFAULT_HOST })
+    .option('--port <port>', 'Port to bind; defaults to the first available port from 9520 to 9530')
+    .option('--token <token>', 'Bearer token for HTTP command clients')
+    .option('--cors-origin <origins>', 'Comma-separated allowed HTTP origins (default: *)', { default: '*' })
+    .option('--tls-key <path>', 'TLS private key path')
+    .option('--tls-cert <path>', 'TLS certificate path')
+    .option('--data-dir <path>', 'Directory for Bridge state and logs')
+    .option('--daemon', 'Run Bridge as a daemon')
+    .option('--refresh', 'Rotate the pairing code and unlock pairing')
+    .action(async (action, options) => {
+    if (action === 'start') {
+        if (options.daemon && process.env[DAEMON_CHILD_ENV] !== '1') {
+            await startBridgeInBackground(options);
+        }
+        else {
+            await startBridge(options);
+        }
+        return;
+    }
+    if (action === 'stop') {
+        await stopBridge(options);
+        return;
+    }
+    if (action === 'code') {
+        await showPairingCode(options);
+        return;
+    }
+    if (action === 'extensions') {
+        await showExtensions(options);
+        return;
+    }
+    throw new BridgeError('CommandNotFound', `Unsupported bridge action: ${action}`, { status: 404 });
+});
+cli
+    .command('workflow <action> <workflowId>', 'Start, pause, resume, stop, query, or watch a Workflow')
+    .option('--args <json>', 'Workflow input as a JSON object (start only)', { default: '{}' })
+    .option('--tab <target>', 'Target tab: active, new, or id:<tabId> (start only)')
+    .option('--host <host>', 'Bridge host', { default: DEFAULT_HOST })
+    .option('--port <port>', 'Bridge port', { default: String(DEFAULT_PORT) })
+    .option('--token <token>', 'Bridge Bearer token')
+    .option('--client-id <clientId>', 'Target Extension clientId when multiple Extensions are connected')
+    .option('--https', 'Use HTTPS when calling the Bridge')
+    .option('--watch', 'After start, stream status updates until the Workflow reaches a terminal state')
+    .option('--timeout <milliseconds>', 'Maximum watch duration; does not stop the Workflow')
+    .action(async (action, workflowId, options) => {
+    if (action === 'start') {
+        await startWorkflow(workflowId, options);
+        return;
+    }
+    if (action === 'pause' || action === 'resume' || action === 'stop' || action === 'status') {
+        await controlWorkflow(action, workflowId, options);
+        return;
+    }
+    if (action === 'watch') {
+        await watchWorkflow(workflowId, options);
+        return;
+    }
+    throw new BridgeError('CommandNotFound', `Unsupported workflow action: ${action}`, { status: 404 });
+});
+cli
+    .command('data <action> <tableId>', 'Get or delete an extracted data table by its ID')
+    .option('--host <host>', 'Bridge host', { default: DEFAULT_HOST })
+    .option('--port <port>', 'Bridge port', { default: String(DEFAULT_PORT) })
+    .option('--token <token>', 'Bridge Bearer token')
+    .option('--client-id <clientId>', 'Target Extension clientId when multiple Extensions are connected')
+    .option('--https', 'Use HTTPS when calling the Bridge')
+    .action(async (action, tableId, options) => {
+    if (action !== 'get' && action !== 'delete') {
+        throw new BridgeError('CommandNotFound', `Unsupported data action: ${action}`, { status: 404 });
+    }
+    const parsed = DataInputSchema.safeParse({ tableId });
+    if (!parsed.success) {
+        throw new BridgeError('InvalidArguments', `Invalid data ${action} arguments`, {
+            status: 400,
+            details: parsed.error.issues,
+        });
+    }
+    await sendDataCommand(`data.${action}`, parsed.data, options);
+});
+cli
+    .command('mcp', 'Expose a running Tapicker Bridge to an MCP client over stdio')
+    .option('--url <url>', 'Bridge HTTP(S) URL', {
+    default: process.env.TAPICKER_BRIDGE_URL || `http://${DEFAULT_HOST}:${DEFAULT_PORT}`,
+})
+    .option('--token <token>', 'Bridge Bearer token; prefer TAPICKER_BRIDGE_TOKEN for MCP host configuration')
+    .example('tapicker mcp')
+    .example('tapicker mcp --url https://bridge.example.com --token <token>')
+    .action((options) => {
+    const token = options.token || process.env.TAPICKER_BRIDGE_TOKEN;
+    const api = createHttpMcpApi(options.url, token);
+    serveStdio(() => createTapickerMcpServer(api), {
+        onerror: (error) => console.error('Tapicker MCP stdio error:', error),
+    });
+});
+cli.help((sections) => formatCliHelp(sections));
+cli.version(VERSION);
+const bridgeActions = {
+    start: {
+        summary: 'Start the Bridge server in the foreground or as a daemon.',
+        description: 'Start the Bridge server. It runs in the foreground unless --daemon is set. The startup output includes the address and pairing code.',
+        example: 'tapicker bridge start [--daemon] [options]',
+    },
+    stop: {
+        summary: 'Stop a running Bridge.',
+        description: 'Stop a running Bridge. Use the same --data-dir used when it was started, if customized.',
+        example: 'tapicker bridge stop [--data-dir <path>]',
+    },
+    code: {
+        summary: 'Show or rotate the Extension pairing code.',
+        description: 'Show the current Extension pairing code. Add --refresh to rotate the code and unlock pairing after rate limiting.',
+        example: 'tapicker bridge code [--refresh] [--data-dir <path>]',
+    },
+    extensions: {
+        summary: 'List connected Extension clients.',
+        description: 'List Extensions currently connected to the Bridge, including connections that have not finished pairing.',
+        example: 'tapicker bridge extensions [--data-dir <path>]',
+    },
+};
+const workflowActions = {
+    start: {
+        summary: 'Start one Workflow instance; optionally stream its status with --watch.',
+        description: 'Start the specified Workflow and return its workflowId, full workflowName, and selected clientId. A Workflow supports one active instance at a time. By default this returns after the start response; add --watch to stream status until it completes, stops, or fails.',
+        example: `tapicker workflow start <workflowId> [--args '{"name":"Tom"}'] [--tab active|new|id:<tabId>] [--watch]`,
+    },
+    pause: {
+        summary: 'Pause the active instance of a Workflow.',
+        description: 'Pause the active instance of the specified Workflow.',
+        example: 'tapicker workflow pause <workflowId>',
+    },
+    resume: {
+        summary: 'Resume a paused Workflow instance.',
+        description: 'Resume a paused instance of the specified Workflow.',
+        example: 'tapicker workflow resume <workflowId>',
+    },
+    stop: {
+        summary: 'Stop the active instance of a Workflow.',
+        description: 'Stop the active instance of the specified Workflow.',
+        example: 'tapicker workflow stop <workflowId>',
+    },
+    status: {
+        summary: 'Fetch one current Workflow status snapshot.',
+        description: 'Fetch a single current-state snapshot. Use watch to receive ongoing updates without polling.',
+        example: 'tapicker workflow status <workflowId>',
+    },
+    watch: {
+        summary: 'Stream Workflow status until it completes, stops, or fails.',
+        description: 'Listen for status updates until the Workflow reaches completed, stopped, or failed. Timeout or Ctrl+C ends only the watch; it does not stop the Workflow.',
+        example: 'tapicker workflow watch <workflowId> [--timeout <milliseconds>]',
+    },
+};
+const dataActions = {
+    get: {
+        summary: 'Get all rows from an extracted data table; consumes export quota.',
+        description: 'Retrieve the complete data table identified by tableId. The row count is charged against the connected Extension account export quota.',
+        example: 'tapicker data get <tableId>',
+    },
+    delete: {
+        summary: 'Delete an extracted data table.',
+        description: 'Delete the data table identified by tableId and remove it from Tapicker Data.',
+        example: 'tapicker data delete <tableId>',
+    },
+};
+const workflowCommonOptions = [
+    ['--host <host>', `Bridge host (default: ${DEFAULT_HOST})`],
+    ['--port <port>', `Bridge port (default: ${DEFAULT_PORT})`],
+    ['--token <token>', 'Bridge Bearer token'],
+    ['--client-id <clientId>', 'Select an Extension; required when multiple are ready'],
+    ['--https', 'Use HTTPS/WSS instead of HTTP/WS'],
+];
+const dataCommonOptions = [
+    ['--host <host>', `Bridge host (default: ${DEFAULT_HOST})`],
+    ['--port <port>', `Bridge port (default: ${DEFAULT_PORT})`],
+    ['--token <token>', 'Bridge Bearer token'],
+    ['--client-id <clientId>', 'Select an Extension; required when multiple are ready'],
+    ['--https', 'Use HTTPS instead of HTTP'],
+];
+const workflowActionOptions = {
+    start: [
+        ['--args <json>', 'Workflow input object (default: {})'],
+        ['--tab <target>', 'Target tab: active (default), new, or id:<positive-tabId>'],
+        ['--watch', 'Stream status updates after starting, until a terminal state'],
+        ['--timeout <milliseconds>', 'Limit the --watch duration; does not stop the Workflow'],
+    ],
+    pause: [],
+    resume: [],
+    stop: [],
+    status: [],
+    watch: [['--timeout <milliseconds>', 'Limit how long to wait; does not stop the Workflow']],
+};
+const workflowGeneralOptions = [
+    ...workflowCommonOptions,
+    ['--args <json>', 'Workflow input object (default: {}; start only)'],
+    ['--tab <target>', 'Target tab: active (default), new, or id:<positive-tabId> (start only)'],
+    ['--watch', 'Stream status after start until a terminal state (start only)'],
+    ['--timeout <milliseconds>', 'Limit watch duration (watch or start --watch); does not stop the Workflow'],
+];
+const bridgeCommonOptions = [['--data-dir <path>', 'Bridge state directory (TAPICKER_DATA_DIR or ~/.tapicker)']];
+const bridgeActionOptions = {
+    start: [
+        ['--host <host>', `Bind address (default: ${DEFAULT_HOST}); remote binding requires token and TLS`],
+        ['--port <port>', 'Listen port (default: first available from 9520 to 9530)'],
+        ['--token <token>', 'HTTP Bearer token (or TAPICKER_BRIDGE_TOKEN)'],
+        ['--cors-origin <origins>', 'Comma-separated CORS allowlist (default: *)'],
+        ['--tls-key <path>', 'TLS private key; required with --tls-cert for remote binding'],
+        ['--tls-cert <path>', 'TLS certificate; required with --tls-key for remote binding'],
+        ['--daemon', 'Run in the background'],
+    ],
+    stop: [],
+    code: [['--refresh', 'Rotate the pairing code and unlock pairing after rate limiting']],
+    extensions: [],
+};
+function formatCliHelp(sections) {
+    const command = cli.matchedCommandName;
+    if (command === 'mcp') {
+        const usage = sections.find((section) => section.title === 'Usage');
+        if (usage)
+            usage.body = '  $ tapicker mcp [options]';
+        const usageIndex = sections.findIndex((section) => section.title === 'Usage');
+        sections.splice(usageIndex + 1, 0, {
+            title: 'Description',
+            body: '  Start an MCP stdio server that connects to an already-running Tapicker Bridge. This does not start the Bridge itself.',
+        });
+        return sections;
+    }
+    if (command !== 'workflow' && command !== 'bridge' && command !== 'data')
+        return sections;
+    const action = cli.args[0];
+    const actionMap = command === 'workflow' ? workflowActions : command === 'bridge' ? bridgeActions : dataActions;
+    const actionInfo = actionMap[action];
+    const actionOptions = command === 'workflow' ? workflowActionOptions : command === 'bridge' ? bridgeActionOptions : {};
+    const commonOptions = command === 'workflow' ? workflowCommonOptions : command === 'bridge' ? bridgeCommonOptions : dataCommonOptions;
+    const usage = sections.find((section) => section.title === 'Usage');
+    if (usage) {
+        if (actionInfo && command === 'workflow') {
+            usage.body = `  $ tapicker workflow ${action} <workflowId> [options]`;
+        }
+        else if (actionInfo && command === 'data') {
+            usage.body = `  $ tapicker data ${action} <tableId> [options]`;
+        }
+        else if (actionInfo) {
+            usage.body = `  $ tapicker bridge ${action} [options]`;
+        }
+        else {
+            const target = command === 'workflow' ? ' <workflowId>' : command === 'data' ? ' <tableId>' : '';
+            usage.body = `  $ tapicker ${command} <action>${target} [options]`;
+        }
+    }
+    const options = actionInfo
+        ? [...commonOptions, ...(actionOptions[action] || [])]
+        : command === 'workflow'
+            ? workflowGeneralOptions
+            : command === 'bridge'
+                ? [
+                    ...commonOptions,
+                    ...Object.entries(actionOptions).flatMap(([name, entries]) => entries.map(([option, description]) => [option, `${description} (${name} only)`])),
+                ]
+                : commonOptions;
+    const optionsSection = sections.find((section) => section.title === 'Options');
+    if (optionsSection)
+        optionsSection.body = formatOptionRows(options);
+    const detailSections = actionInfo
+        ? [
+            { title: 'Description', body: `  ${actionInfo.description}` },
+            { title: 'Example', body: `  ${actionInfo.example}` },
+        ]
+        : [
+            {
+                title: 'Actions',
+                body: Object.entries(actionMap)
+                    .map(([name, info]) => `  ${name.padEnd(12)} ${info.summary}`)
+                    .join('\n'),
+            },
+            {
+                title: 'Examples',
+                body: Object.entries(actionMap)
+                    .map(([, info]) => `  ${info.example}`)
+                    .join('\n'),
+            },
+        ];
+    const usageIndex = sections.findIndex((section) => section.title === 'Usage');
+    sections.splice(usageIndex + 1, 0, ...detailSections);
+    return sections;
+}
+function formatOptionRows(options) {
+    const width = Math.max(...options.map(([name]) => name.length));
+    return options.map(([name, description]) => `  ${name.padEnd(width)}  ${description}`).join('\n');
+}
+async function startBridge(options) {
+    const token = options.token || process.env.TAPICKER_BRIDGE_TOKEN;
+    const host = options.host || DEFAULT_HOST;
+    const port = options.port === undefined ? undefined : parsePort(options.port);
+    const tls = resolveTls(options);
+    const dataDir = getDataDirectory(options);
+    const isDaemonChild = process.env[DAEMON_CHILD_ENV] === '1';
+    if (!isLoopback(host) && (!token || !tls)) {
+        throw new BridgeError('InsecureRemoteBinding', 'Non-loopback Bridge binding requires --token, --tls-key and --tls-cert', {
+            status: 400,
+        });
+    }
+    const server = new BridgeServer({
+        host,
+        port,
+        token,
+        corsOrigins: parseCorsOrigins(options.corsOrigin),
+        tls,
+        dataDir,
+    });
+    const address = await server.start();
+    let controlServer;
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        await controlServer?.close();
+        await server.close();
+        if (isDaemonChild) {
+            await removeBridgeDaemonState(dataDir, process.pid);
+        }
+        process.exit(0);
+    };
+    process.once('SIGINT', () => void shutdown());
+    process.once('SIGTERM', () => void shutdown());
+    try {
+        controlServer = await startBridgeControlServer(dataDir, async (action) => {
+            if (action === 'code.get') {
+                const code = server.getPairingCode();
+                return { code, locked: code === undefined };
+            }
+            if (action === 'code.refresh') {
+                return { code: server.refreshPairingCode(), locked: false };
+            }
+            if (action === 'extensions.list') {
+                return server.bridge.getExtensionStatuses();
+            }
+            setTimeout(() => void shutdown(), 50);
+            return { pid: process.pid, bridgeId: server.bridgeId };
+        });
+        if (isDaemonChild) {
+            await writeBridgeDaemonState(dataDir, {
+                pid: process.pid,
+                bridgeId: server.bridgeId,
+                httpUrl: address.httpUrl,
+                startedAt: Date.now(),
+            });
+        }
+    }
+    catch (error) {
+        await controlServer?.close();
+        await server.close();
+        throw error;
+    }
+    console.log(`Tapicker Bridge ${VERSION} is running`);
+    console.log(`HTTP: ${address.httpUrl}`);
+    console.log(`WebSocket: ${address.wsUrl}`);
+    console.log(`MCP Server: ${address.mcpUrl}`);
+    console.log(`Data Directory: ${dataDir}`);
+    const pairingCode = server.getPairingCode();
+    if (pairingCode) {
+        console.log(`Pairing Code: ${pairingCode}`);
+    }
+    else {
+        console.log('Pairing is locked; run `tapicker bridge code --refresh` locally to unlock it');
+    }
+    const connectedExtensions = server.bridge.getExtensionStatuses().filter((extension) => extension.ready).length;
+    console.log(`Extensions: ${connectedExtensions} connected`);
+    if (token) {
+        console.log('Authentication: enabled');
+    }
+    else {
+        console.warn('Authentication: disabled (loopback mode only)');
+    }
+    if (isDaemonChild && process.send) {
+        process.send({
+            type: 'ready',
+            pid: process.pid,
+            bridgeId: server.bridgeId,
+            httpUrl: address.httpUrl,
+            wsUrl: address.wsUrl,
+            workflowWatchWsUrl: address.workflowWatchWsUrl,
+            dataDir,
+            logPath: getBridgeDaemonLogPath(dataDir),
+            pairingCode,
+            authenticationEnabled: Boolean(token),
+        });
+    }
+    await new Promise(() => undefined);
+}
+async function startBridgeInBackground(options) {
+    const dataDir = getDataDirectory(options);
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    const existingState = await readBridgeDaemonState(dataDir);
+    if (existingState) {
+        if (await isManagedBridgeRunning(existingState)) {
+            throw new BridgeError('BridgeAlreadyRunning', `Tapicker Bridge is already running (PID ${existingState.pid})`, {
+                status: 409,
+            });
+        }
+        await removeBridgeDaemonState(dataDir, existingState.pid);
+    }
+    const logPath = getBridgeDaemonLogPath(dataDir);
+    const logFile = openSync(logPath, 'a', 0o600);
+    let child;
+    try {
+        chmodSync(logPath, 0o600);
+        const entryPoint = process.argv[1];
+        if (!entryPoint) {
+            throw new BridgeError('InvalidCliEntryPoint', 'Unable to determine the Tapicker Bridge CLI entry point', {
+                status: 500,
+            });
+        }
+        const childArgs = process.argv.slice(2).filter((argument) => argument !== '--daemon');
+        child = fork(entryPoint, childArgs, {
+            detached: true,
+            env: { ...process.env, [DAEMON_CHILD_ENV]: '1' },
+            stdio: ['ignore', logFile, logFile, 'ipc'],
+        });
+    }
+    finally {
+        closeSync(logFile);
+    }
+    let ready;
+    try {
+        ready = await waitForDaemonReady(child, logPath);
+    }
+    catch (error) {
+        if (child.connected)
+            child.disconnect();
+        child.kill('SIGTERM');
+        child.unref();
+        throw error;
+    }
+    if (child.connected)
+        child.disconnect();
+    child.unref();
+    console.log(`Tapicker Bridge ${VERSION} started as a daemon (PID ${ready.pid})`);
+    console.log(`HTTP: ${ready.httpUrl}`);
+    console.log(`WebSocket: ${ready.wsUrl}`);
+    console.log(`MCP Server: ${new URL(ready.httpUrl).origin}/mcp`);
+    console.log(`Data Directory: ${ready.dataDir}`);
+    console.log(`Log: ${ready.logPath}`);
+    if (ready.pairingCode) {
+        console.log(`Pairing Code: ${ready.pairingCode}`);
+    }
+    else {
+        console.log('Pairing is locked; run `tapicker bridge code --refresh` locally to unlock it');
+    }
+    console.log(`Authentication: ${ready.authenticationEnabled ? 'enabled' : 'disabled (loopback mode only)'}`);
+}
+async function stopBridge(options) {
+    const dataDir = getDataDirectory(options);
+    const state = await readBridgeDaemonState(dataDir);
+    let result;
+    try {
+        result = await sendBridgeControlRequest(dataDir, 'bridge.stop');
+    }
+    catch (error) {
+        if (!(error instanceof BridgeError) || error.code !== 'BridgeControlUnavailable')
+            throw error;
+        if (!state) {
+            console.log('No Tapicker Bridge is running.');
+            return;
+        }
+        if (!isProcessRunning(state.pid)) {
+            await removeBridgeDaemonState(dataDir, state.pid);
+            console.log('Tapicker Bridge daemon was not running; removed the stale process file.');
+            return;
+        }
+        if (!(await isManagedBridgeRunning(state))) {
+            await removeBridgeDaemonState(dataDir, state.pid);
+            console.log('Tapicker Bridge daemon was not running; removed the stale process file.');
+            return;
+        }
+        try {
+            process.kill(state.pid, 'SIGTERM');
+        }
+        catch (signalError) {
+            if (signalError.code !== 'ESRCH')
+                throw signalError;
+        }
+        const stopped = await waitForProcessExit(state.pid);
+        if (!stopped) {
+            throw new BridgeError('BridgeStopTimeout', `Tapicker Bridge (PID ${state.pid}) did not stop in time`, {
+                status: 500,
+                cause: error,
+            });
+        }
+        await removeBridgeDaemonState(dataDir, state.pid);
+        console.log(`Tapicker Bridge stopped (PID ${state.pid}; verified PID fallback)`);
+        return;
+    }
+    const pid = result.pid ?? state?.pid;
+    if (pid === undefined) {
+        console.log('Tapicker Bridge shutdown requested.');
+        return;
+    }
+    const stopped = await waitForProcessExit(pid);
+    if (!stopped) {
+        throw new BridgeError('BridgeStopTimeout', `Tapicker Bridge (PID ${pid}) did not stop in time`, {
+            status: 500,
+        });
+    }
+    await removeBridgeDaemonState(dataDir, pid);
+    console.log(`Tapicker Bridge stopped (PID ${pid})`);
+}
+async function showPairingCode(options) {
+    const dataDir = getDataDirectory(options);
+    const result = await sendBridgeControlRequest(dataDir, options.refresh ? 'code.refresh' : 'code.get');
+    if (!result.code || result.locked) {
+        throw new BridgeError('PairingRateLimited', 'Pairing is locked; run `tapicker bridge code --refresh` to rotate the code and unlock pairing', { status: 429 });
+    }
+    console.log(`Pairing Code: ${result.code}`);
+}
+async function showExtensions(options) {
+    const dataDir = getDataDirectory(options);
+    const extensions = await sendBridgeControlRequest(dataDir, 'extensions.list');
+    if (extensions.length === 0) {
+        console.log('No Extensions are currently connected.');
+        return;
+    }
+    console.log(JSON.stringify(extensions, null, 2));
+}
+function getDataDirectory(options) {
+    return resolve(options.dataDir || process.env.TAPICKER_DATA_DIR || getDefaultBridgeDataDir());
+}
+function parseCorsOrigins(value = '*') {
+    if (typeof value !== 'string') {
+        throw new BridgeError('InvalidCorsOrigins', 'Pass multiple CORS origins as one comma-separated --cors-origin value', {
+            status: 400,
+        });
+    }
+    const origins = value.split(',').map((origin) => origin.trim());
+    if (origins.some((origin) => !origin)) {
+        throw new BridgeError('InvalidCorsOrigins', '--cors-origin must contain one or more non-empty origins', {
+            status: 400,
+        });
+    }
+    return origins;
+}
+function waitForDaemonReady(child, logPath) {
+    return new Promise((resolveReady, rejectReady) => {
+        let settled = false;
+        const timeout = setTimeout(() => {
+            fail(new BridgeError('BridgeStartTimeout', `Timed out waiting for Bridge startup; see ${logPath}`, { status: 504 }));
+        }, 15_000);
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            callback();
+        };
+        const fail = (error) => finish(() => rejectReady(error));
+        child.on('message', (message) => {
+            if (!isDaemonReadyMessage(message))
+                return;
+            finish(() => resolveReady(message));
+        });
+        child.once('error', (error) => fail(error));
+        child.once('exit', (code, signal) => {
+            fail(new BridgeError('BridgeStartFailed', `Tapicker Bridge exited before startup completed (${signal || `code ${code}`}); see ${logPath}`, { status: 500 }));
+        });
+    });
+}
+function isDaemonReadyMessage(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const message = value;
+    return (message.type === 'ready' &&
+        typeof message.pid === 'number' &&
+        typeof message.bridgeId === 'string' &&
+        typeof message.httpUrl === 'string' &&
+        typeof message.wsUrl === 'string' &&
+        typeof message.workflowWatchWsUrl === 'string' &&
+        typeof message.dataDir === 'string' &&
+        typeof message.logPath === 'string' &&
+        typeof message.authenticationEnabled === 'boolean');
+}
+async function waitForProcessExit(pid, timeoutMs = 10_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (isProcessRunning(pid) && Date.now() < deadline) {
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, 100));
+    }
+    return !isProcessRunning(pid);
+}
+async function isManagedBridgeRunning(state) {
+    if (!isProcessRunning(state.pid))
+        return false;
+    let response;
+    try {
+        response = await fetch(`${state.httpUrl}/v1/health`, { signal: AbortSignal.timeout(2_000) });
+    }
+    catch (cause) {
+        throw new BridgeError('BridgeProcessUnverified', 'Could not verify the saved Bridge process; refusing to signal it', {
+            status: 503,
+            cause,
+        });
+    }
+    if (!response.ok)
+        return false;
+    let health;
+    try {
+        health = await response.json();
+    }
+    catch {
+        return false;
+    }
+    if (!health || typeof health !== 'object')
+        return false;
+    return health.bridgeId === state.bridgeId;
+}
+async function startWorkflow(workflowId, options) {
+    let args;
+    try {
+        args = JSON.parse(options.args);
+    }
+    catch (error) {
+        throw new BridgeError('InvalidArguments', '--args must be valid JSON', { status: 400, cause: error });
+    }
+    const parsed = WorkflowStartInputSchema.safeParse({ workflowId, args, tab: parseTabTarget(options.tab) });
+    if (!parsed.success) {
+        throw new BridgeError('InvalidArguments', 'Invalid Workflow start arguments', {
+            status: 400,
+            details: parsed.error.issues,
+        });
+    }
+    if (!options.watch) {
+        await sendWorkflowCommand('workflow.start', parsed.data, options);
+        return;
+    }
+    const timeoutMs = parseWatchTimeout(options.timeout);
+    const connection = await openWorkflowWatch(workflowId, options);
+    try {
+        const startResult = await requestBridgeCommand('workflow.start', parsed.data, {
+            ...options,
+            clientId: connection.clientId,
+        });
+        console.log(JSON.stringify({ type: 'workflow.start', data: startResult }));
+        const result = await waitForWorkflowStatus({
+            clientId: connection.clientId,
+            workflowId,
+            subscribe: (onStatus, onClose) => subscribeToWorkflowWatch(connection, onStatus, onClose),
+            readStatus: () => readWorkflowStatus(workflowId, connection.clientId, options),
+            onStatus: printWorkflowStatus,
+            timeoutMs,
+        });
+        printWatchTimeout(result);
+    }
+    finally {
+        connection.close();
+    }
+}
+async function watchWorkflow(workflowId, options) {
+    const timeoutMs = parseWatchTimeout(options.timeout);
+    const connection = await openWorkflowWatch(workflowId, options);
+    try {
+        const result = await waitForWorkflowStatus({
+            clientId: connection.clientId,
+            workflowId,
+            subscribe: (onStatus, onClose) => subscribeToWorkflowWatch(connection, onStatus, onClose),
+            readStatus: () => readWorkflowStatus(workflowId, connection.clientId, options),
+            onStatus: printWorkflowStatus,
+            timeoutMs,
+        });
+        printWatchTimeout(result);
+    }
+    finally {
+        connection.close();
+    }
+}
+async function openWorkflowWatch(workflowId, options) {
+    const protocol = options.https ? 'https' : 'http';
+    const bridgeUrl = new URL(`${protocol}://${options.host}:${parsePort(options.port)}`);
+    return connectWorkflowWatch(workflowWatchWebSocketUrl(bridgeUrl), { clientId: options.clientId, workflowId }, options.token);
+}
+function subscribeToWorkflowWatch(connection, onStatus, onClose) {
+    const removeStatusListener = connection.onStatus(onStatus);
+    const removeCloseListener = connection.onClose(onClose);
+    return () => {
+        removeStatusListener();
+        removeCloseListener();
+    };
+}
+function printWatchTimeout(result) {
+    if (result.timedOut) {
+        console.log(JSON.stringify({ type: 'workflow.watch:res', data: { ok: true, data: result } }));
+    }
+}
+async function readWorkflowStatus(workflowId, clientId, options) {
+    const result = await requestBridgeCommand('workflow.status', { workflowId }, { ...options, clientId });
+    const parsed = WorkflowStatusEventSchema.safeParse({ ...result, clientId });
+    if (!parsed.success || parsed.data.workflowId !== workflowId) {
+        throw new BridgeError('InvalidBridgeResponse', 'Bridge returned an invalid Workflow status response', {
+            status: 502,
+            details: parsed.success ? undefined : parsed.error.issues,
+        });
+    }
+    return parsed.data;
+}
+function printWorkflowStatus(status) {
+    console.log(JSON.stringify({ type: 'workflow.status', data: status }));
+}
+function parseWatchTimeout(value) {
+    if (value === undefined)
+        return undefined;
+    const timeoutMs = Number(value);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new BridgeError('InvalidArguments', '--timeout must be a positive integer no greater than 2147483647', {
+            status: 400,
+        });
+    }
+    return timeoutMs;
+}
+function parseTabTarget(value) {
+    if (value === undefined || value === 'active') {
+        return undefined;
+    }
+    if (value === 'new') {
+        return { mode: 'new' };
+    }
+    const match = /^id:(\d+)$/.exec(value);
+    const tabId = match ? Number(match[1]) : Number.NaN;
+    if (!Number.isSafeInteger(tabId) || tabId <= 0) {
+        throw new BridgeError('InvalidArguments', '--tab must be "active", "new", or "id:<positive-tabId>"', {
+            status: 400,
+        });
+    }
+    return { mode: 'id', tabId };
+}
+async function controlWorkflow(action, workflowId, options) {
+    const parsed = WorkflowControlInputSchema.safeParse({ workflowId });
+    if (!parsed.success) {
+        throw new BridgeError('InvalidArguments', `Invalid Workflow ${action} arguments`, {
+            status: 400,
+            details: parsed.error.issues,
+        });
+    }
+    await sendWorkflowCommand(`workflow.${action}`, parsed.data, options);
+}
+async function sendWorkflowCommand(command, input, options) {
+    const result = await requestBridgeCommand(command, input, options);
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+}
+async function sendDataCommand(command, input, options) {
+    const result = await requestBridgeCommand(command, input, options);
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+}
+async function requestBridgeCommand(command, input, options) {
+    const protocol = options.https ? 'https' : 'http';
+    const url = `${protocol}://${options.host}:${parsePort(options.port)}/v1/commands/${command}`;
+    const headers = { 'Content-Type': 'application/json' };
+    if (options.token) {
+        headers.Authorization = `Bearer ${options.token}`;
+    }
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ clientId: options.clientId, input }),
+    });
+    const body = await readResponseBody(response);
+    if (!response.ok) {
+        throw new BridgeError(body.error?.code || 'BridgeRequestFailed', body.error?.message || response.statusText, {
+            status: response.status,
+            details: body.error?.details,
+        });
+    }
+    return body.data ?? body;
+}
+function resolveTls(options) {
+    if (!options.tlsKey && !options.tlsCert) {
+        return undefined;
+    }
+    if (!options.tlsKey || !options.tlsCert) {
+        throw new BridgeError('InvalidTlsOptions', '--tls-key and --tls-cert must be provided together', { status: 400 });
+    }
+    readFileSync(options.tlsKey);
+    readFileSync(options.tlsCert);
+    return { key: options.tlsKey, cert: options.tlsCert };
+}
+function parsePort(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new BridgeError('InvalidPort', `Invalid port: ${value}`, { status: 400 });
+    }
+    return port;
+}
+function isLoopback(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text) {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { error: { message: text } };
+    }
+}
+async function main() {
+    try {
+        cli.parse(process.argv, { run: false });
+        await cli.runMatchedCommand();
+    }
+    catch (error) {
+        console.error(JSON.stringify({ ok: false, error: serializeBridgeError(error) }, null, 2));
+        process.exitCode = 1;
+    }
+}
+void main();
+//# sourceMappingURL=cli.js.map