@tapicker/bridge 1.0.0 → 1.1.0

package/src/cli.ts

@@ -1,1019 +0,0 @@
-#!/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,
-  type WorkflowStartInput,
-} from './protocol/schema.js'
-import { connectWorkflowWatch, waitForWorkflowStatus, workflowWatchWebSocketUrl } from './workflow-watch.js'
-import type { WorkflowStatusEvent } from './protocol/schema.js'
-import type { WorkflowWatchConnection } 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: string, options: BridgeStartOptions) => {
-    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: string, workflowId: string, options: WorkflowStartOptions) => {
-    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: string, tableId: string, options: DataCommandOptions) => {
-    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: McpOptions) => {
-    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)
-
-type CliHelpSection = { title?: string; body: string }
-
-const bridgeActions: Record<string, { summary: string; description: string; example: string }> = {
-  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: Record<string, { summary: string; description: string; example: string }> = {
-  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: Record<string, { summary: string; description: string; example: string }> = {
-  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: Record<string, string[][]> = {
-  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: Record<string, string[][]> = {
-  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: CliHelpSection[]): CliHelpSection[] {
-  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: CliHelpSection[] = 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: string[][]) {
-  const width = Math.max(...options.map(([name]) => name.length))
-  return options.map(([name, description]) => `  ${name.padEnd(width)}  ${description}`).join('\n')
-}
-
-type BridgeStartOptions = {
-  host: string
-  port?: string
-  token?: string
-  corsOrigin?: string
-  tlsKey?: string
-  tlsCert?: string
-  dataDir?: string
-  daemon?: boolean
-  refresh?: boolean
-}
-
-type WorkflowStartOptions = {
-  args: string
-  tab?: string
-  host: string
-  port: string
-  token?: string
-  clientId?: string
-  https?: boolean
-  watch?: boolean
-  timeout?: string
-}
-
-type DataCommandOptions = {
-  host: string
-  port: string
-  token?: string
-  clientId?: string
-  https?: boolean
-}
-
-type BridgeCommandOptions = Pick<DataCommandOptions, 'host' | 'port' | 'token' | 'clientId' | 'https'>
-
-type McpOptions = {
-  url: string
-  token?: string
-}
-
-type DaemonReadyMessage = {
-  type: 'ready'
-  pid: number
-  bridgeId: string
-  httpUrl: string
-  wsUrl: string
-  workflowWatchWsUrl: string
-  dataDir: string
-  logPath: string
-  pairingCode?: string
-  authenticationEnabled: boolean
-}
-
-async function startBridge(options: BridgeStartOptions) {
-  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: Awaited<ReturnType<typeof startBridgeControlServer>> | undefined
-  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<void>(() => undefined)
-}
-
-async function startBridgeInBackground(options: BridgeStartOptions) {
-  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: ReturnType<typeof fork>
-  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: DaemonReadyMessage
-  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: BridgeStartOptions) {
-  const dataDir = getDataDirectory(options)
-  const state = await readBridgeDaemonState(dataDir)
-
-  let result: { pid?: number }
-  try {
-    result = await sendBridgeControlRequest<{ pid?: number }>(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 as NodeJS.ErrnoException).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: BridgeStartOptions) {
-  const dataDir = getDataDirectory(options)
-  const result = await sendBridgeControlRequest<{ code?: string; locked: boolean }>(
-    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: BridgeStartOptions) {
-  const dataDir = getDataDirectory(options)
-  const extensions = await sendBridgeControlRequest<unknown[]>(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: BridgeStartOptions) {
-  return resolve(options.dataDir || process.env.TAPICKER_DATA_DIR || getDefaultBridgeDataDir())
-}
-
-function parseCorsOrigins(value: unknown = '*') {
-  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: ReturnType<typeof fork>, logPath: string) {
-  return new Promise<DaemonReadyMessage>((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: () => void) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timeout)
-      callback()
-    }
-
-    const fail = (error: Error) => finish(() => rejectReady(error))
-
-    child.on('message', (message: unknown) => {
-      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: unknown): value is DaemonReadyMessage {
-  if (!value || typeof value !== 'object') return false
-  const message = value as Partial<DaemonReadyMessage>
-  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: number, 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: { pid: number; bridgeId: string; httpUrl: string }) {
-  if (!isProcessRunning(state.pid)) return false
-
-  let response: 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: unknown
-  try {
-    health = await response.json()
-  } catch {
-    return false
-  }
-
-  if (!health || typeof health !== 'object') return false
-  return (health as { bridgeId?: unknown }).bridgeId === state.bridgeId
-}
-
-async function startWorkflow(workflowId: string, options: WorkflowStartOptions) {
-  let args: unknown
-  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: string, options: WorkflowStartOptions) {
-  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: string, options: WorkflowStartOptions) {
-  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: WorkflowWatchConnection,
-  onStatus: (event: WorkflowStatusEvent) => void,
-  onClose: (error: BridgeError) => void,
-) {
-  const removeStatusListener = connection.onStatus(onStatus)
-  const removeCloseListener = connection.onClose(onClose)
-  return () => {
-    removeStatusListener()
-    removeCloseListener()
-  }
-}
-
-function printWatchTimeout(result: { timedOut: boolean } & WorkflowStatusEvent) {
-  if (result.timedOut) {
-    console.log(JSON.stringify({ type: 'workflow.watch:res', data: { ok: true, data: result } }))
-  }
-}
-
-async function readWorkflowStatus(workflowId: string, clientId: string, options: WorkflowStartOptions) {
-  const result = await requestBridgeCommand('workflow.status', { workflowId }, { ...options, clientId })
-  const parsed = WorkflowStatusEventSchema.safeParse({ ...(result as object), 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: { clientId: string; workflowId: string; state: string; updatedAt: string }) {
-  console.log(JSON.stringify({ type: 'workflow.status', data: status }))
-}
-
-function parseWatchTimeout(value?: string) {
-  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?: string): WorkflowStartInput['tab'] | undefined {
-  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: 'pause' | 'resume' | 'stop' | 'status',
-  workflowId: string,
-  options: WorkflowStartOptions,
-) {
-  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: string, input: unknown, options: WorkflowStartOptions) {
-  const result = await requestBridgeCommand(command, input, options)
-  console.log(JSON.stringify(result, null, 2))
-  return result
-}
-
-async function sendDataCommand(command: string, input: unknown, options: DataCommandOptions) {
-  const result = await requestBridgeCommand(command, input, options)
-  console.log(JSON.stringify(result, null, 2))
-  return result
-}
-
-async function requestBridgeCommand(command: string, input: unknown, options: BridgeCommandOptions) {
-  const protocol = options.https ? 'https' : 'http'
-  const url = `${protocol}://${options.host}:${parsePort(options.port)}/v1/commands/${command}`
-  const headers: Record<string, string> = { '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: BridgeStartOptions) {
-  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: string) {
-  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: string) {
-  return host === '127.0.0.1' || host === 'localhost' || host === '::1'
-}
-
-async function readResponseBody(response: Response) {
-  const text = await response.text()
-  if (!text) {
-    return {}
-  }
-
-  try {
-    return JSON.parse(text) as {
-      data?: unknown
-      error?: { code?: string; message?: string; details?: unknown }
-    }
-  } 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()