chrome-cli-bridge 0.1.0

package/bin/chrome-bridge.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline'
+import { getClient } from '../src/client.js'
+import { outLine } from '../src/output.js'
+
+// ── Pipe mode ───────────────────────────────────────────────────────────────
+// Activated when stdin is not a TTY or --pipe flag is present
+
+const forcePipe = process.argv.includes('--pipe')
+const isPipeMode = forcePipe || !process.stdin.isTTY
+
+if (isPipeMode) {
+  // Remove --pipe flag from args so yargs doesn't complain
+  const idx = process.argv.indexOf('--pipe')
+  if (idx !== -1) process.argv.splice(idx, 1)
+
+  runPipeMode()
+} else {
+  runCLI()
+}
+
+async function runPipeMode() {
+  const portArg = process.argv.indexOf('--port')
+  const port = portArg !== -1 ? parseInt(process.argv[portArg + 1], 10) : 9876
+
+  let client
+  try {
+    client = await getClient(port)
+  } catch (e) {
+    process.stderr.write(JSON.stringify({ error: 'connection_failed', message: e.message }) + '\n')
+    process.exit(1)
+  }
+
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity })
+
+  rl.on('line', async (line) => {
+    const trimmed = line.trim()
+    if (!trimmed) return
+
+    let msg
+    try {
+      msg = JSON.parse(trimmed)
+    } catch {
+      outLine({ error: 'invalid_input', message: `Invalid JSON: ${trimmed.slice(0, 80)}` })
+      return
+    }
+
+    const { command, ...params } = msg
+    if (!command) {
+      outLine({ error: 'invalid_input', message: 'Missing "command" field' })
+      return
+    }
+
+    const methodMap = {
+      tabs:        'tabs.list',
+      select:      'tabs.select',
+      query:       'page.query',
+      exec:        'page.exec',
+      logs:        'page.logs',
+      network:     'page.network',
+      trigger:     'page.trigger',
+      screenshot:  'page.screenshot',
+      navigate:    'page.navigate',
+      storage:     'page.storage',
+      wait:        'page.wait',
+      inject:      'page.inject',
+      snapshot:    'page.snapshot',
+      type:        'page.type',
+      click:       'page.click',
+      hover:       'page.hover',
+    }
+
+    const method = methodMap[command]
+    if (!method) {
+      outLine({ error: 'unknown_command', message: `Unknown command: ${command}` })
+      return
+    }
+
+    try {
+      const result = await client.call(method, params)
+      outLine({ result })
+    } catch (e) {
+      outLine({ error: e.message, code: e.code, ...(e.data && { data: e.data }) })
+    }
+  })
+
+  rl.on('close', () => {
+    client.close()
+    process.exit(0)
+  })
+}
+
+async function runCLI() {
+  const yargs = (await import('yargs')).default
+  const { hideBin } = await import('yargs/helpers')
+
+  // commandDir() is not supported in ESM — import commands explicitly
+  const [start, stop, status, tabs, query, exec, logs, trigger,
+         screenshot, navigate, storage, wait, inject, snapshot,
+         type, click, hover, repl, devtools] = await Promise.all([
+    import('../src/commands/start.js'),
+    import('../src/commands/stop.js'),
+    import('../src/commands/status.js'),
+    import('../src/commands/tabs.js'),
+    import('../src/commands/query.js'),
+    import('../src/commands/exec.js'),
+    import('../src/commands/logs.js'),
+    import('../src/commands/trigger.js'),
+    import('../src/commands/screenshot.js'),
+    import('../src/commands/navigate.js'),
+    import('../src/commands/storage.js'),
+    import('../src/commands/wait.js'),
+    import('../src/commands/inject.js'),
+    import('../src/commands/snapshot.js'),
+    import('../src/commands/type.js'),
+    import('../src/commands/click.js'),
+    import('../src/commands/hover.js'),
+    import('../src/commands/repl.js'),
+    import('../src/commands/devtools.js'),
+  ])
+
+  yargs(hideBin(process.argv))
+    .scriptName('chrome-bridge')
+    .usage('$0 <command> [options]')
+    .command(start)
+    .command(stop)
+    .command(status)
+    .command(tabs)
+    .command(query)
+    .command(exec)
+    .command(logs)
+    .command(trigger)
+    .command(screenshot)
+    .command(navigate)
+    .command(storage)
+    .command(wait)
+    .command(inject)
+    .command(snapshot)
+    .command(type)
+    .command(click)
+    .command(hover)
+    .command(repl)
+    .command(devtools)
+    .option('port', { type: 'number', default: 9876, global: true, describe: 'Relay port' })
+    .option('pipe', { type: 'boolean', describe: 'Force stdin pipe mode (NDJSON in, NDJSON out)' })
+    .demandCommand(1, 'Specify a command. Run --help for available commands.')
+    .strict()
+    .help()
+    .alias('h', 'help')
+    .wrap(null)
+    .parse()
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "chrome-cli-bridge",
+  "version": "0.1.0",
+  "description": "Connect CLI tools and AI agents to a live Chrome tab via WebSocket bridge",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "chrome-bridge": "./bin/chrome-bridge.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/chrome-bridge.js start",
+    "bridge": "node bin/chrome-bridge.js",
+    "test": "node --test tests/unit/**/*.test.js",
+    "test:integration": "node --test tests/integration/**/*.test.js"
+  },
+  "keywords": [
+    "chrome",
+    "browser",
+    "automation",
+    "cli",
+    "ai",
+    "websocket",
+    "devtools",
+    "scraping",
+    "bridge",
+    "agent"
+  ],
+  "author": "Nestor Mata <nestor.mata@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nestormata/chrome-bridge.git"
+  },
+  "homepage": "https://github.com/nestormata/chrome-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/nestormata/chrome-bridge/issues"
+  },
+  "dependencies": {
+    "ws": "^8.17.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "puppeteer": "^22.0.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,96 @@
+import { readToken } from './token.js'
+import { Relay } from './relay.js'
+
+let _client = null
+
+export async function getClient(port = 9876) {
+  if (_client) return _client
+  const token = await readToken()
+  if (!token) throw new Error('No session token found. Run: chrome-bridge start')
+
+  _client = new RelayClient(port, token)
+  await _client.connect()
+  return _client
+}
+
+export class RelayClient {
+  #ws = null
+  #token
+  #port
+  #pendingCalls = new Map()
+  #eventHandlers = new Map()
+  #nextId = (() => { let i = 0; return () => ++i })()
+
+  constructor(port, token) {
+    this.#port = port
+    this.#token = token
+  }
+
+  async connect() {
+    const { WebSocket } = await import('ws')
+    await new Promise((resolve, reject) => {
+      this.#ws = new WebSocket(`ws://127.0.0.1:${this.#port}`)
+      this.#ws.once('error', reject)
+      this.#ws.once('open', () => {
+        this.#ws.off('error', reject)
+        this.#ws.on('error', () => {})
+        this.#ws.on('message', (data) => this.#onMessage(data))
+        // send handshake with cli role
+        this.#ws.send(JSON.stringify({
+          jsonrpc: '2.0', method: 'handshake', params: { token: this.#token, role: 'cli' }, id: 0,
+        }))
+        resolve()
+      })
+    })
+  }
+
+  close() {
+    this.#ws?.terminate()
+    this.#ws = null
+  }
+
+  async call(method, params = {}, timeoutMs = 15000) {
+    return new Promise((resolve, reject) => {
+      const id = this.#nextId()
+      const timer = setTimeout(() => {
+        this.#pendingCalls.delete(id)
+        reject(new Error(`Timeout waiting for ${method}`))
+      }, timeoutMs)
+      this.#pendingCalls.set(id, { resolve, reject, timer })
+      this.#ws.send(JSON.stringify({ jsonrpc: '2.0', method, params, id }))
+    })
+  }
+
+  on(event, handler) {
+    if (!this.#eventHandlers.has(event)) this.#eventHandlers.set(event, new Set())
+    this.#eventHandlers.get(event).add(handler)
+    return () => this.#eventHandlers.get(event)?.delete(handler)
+  }
+
+  #onMessage(data) {
+    let msg
+    try { msg = JSON.parse(data.toString()) } catch { return }
+
+    if (msg.id !== undefined && (msg.result !== undefined || msg.error)) {
+      const pending = this.#pendingCalls.get(msg.id)
+      if (pending) {
+        clearTimeout(pending.timer)
+        this.#pendingCalls.delete(msg.id)
+        if (msg.error) {
+          const e = new Error(msg.error.message)
+          e.code = msg.error.code
+          e.data = msg.error.data
+          pending.reject(e)
+        } else {
+          pending.resolve(msg.result)
+        }
+      }
+      return
+    }
+
+    if (msg.method && msg.id === undefined) {
+      const handlers = this.#eventHandlers.get(msg.method)
+      if (handlers) handlers.forEach((fn) => fn(msg.params))
+    }
+  }
+}

package/src/commands/click.js

@@ -0,0 +1,22 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'click'
+export const describe = 'Simulate a mouse click on a DOM element'
+export const builder = {
+  selector: { type: 'string', demandOption: true, describe: 'CSS selector for target element' },
+  port:     { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.click', { selector: argv.selector })
+    out(result)
+    client.close()
+    if (result?.error) process.exit(1)
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/devtools.js

@@ -0,0 +1,57 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'devtools <subcommand>'
+export const describe = 'Access Chrome DevTools data (performance, memory, coverage)'
+export const builder = (yargs) => {
+  yargs
+    .command({
+      command: 'performance',
+      describe: 'Collect runtime performance metrics',
+      builder: { port: { type: 'number', default: 9876 } },
+      async handler(argv) {
+        try {
+          const client = await getClient(argv.port)
+          const result = await client.call('devtools.performance', {})
+          out(result)
+          client.close()
+        } catch (e) { err(e.message); process.exit(1) }
+      },
+    })
+    .command({
+      command: 'memory',
+      describe: 'Take a heap memory snapshot',
+      builder: {
+        output: { type: 'string', alias: 'o', describe: 'Output file path (default: ./heap-<ts>.heapsnapshot)' },
+        port:   { type: 'number', default: 9876 },
+      },
+      async handler(argv) {
+        try {
+          const client = await getClient(argv.port)
+          const output = argv.output || `./heap-${Date.now()}.heapsnapshot`
+          const result = await client.call('devtools.memory', { output })
+          out(result)
+          client.close()
+        } catch (e) { err(e.message); process.exit(1) }
+      },
+    })
+    .command({
+      command: 'coverage',
+      describe: 'Capture JavaScript code coverage',
+      builder: {
+        duration: { type: 'number', default: 5000, describe: 'Recording duration in ms' },
+        port:     { type: 'number', default: 9876 },
+      },
+      async handler(argv) {
+        try {
+          const client = await getClient(argv.port)
+          const result = await client.call('devtools.coverage', { duration: argv.duration })
+          out(result)
+          client.close()
+        } catch (e) { err(e.message); process.exit(1) }
+      },
+    })
+    .demandCommand(1, 'Specify a devtools subcommand: performance | memory | coverage')
+}
+
+export function handler() {}

package/src/commands/exec.js

@@ -0,0 +1,22 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'exec'
+export const describe = 'Execute JavaScript in the selected tab'
+export const builder = {
+  code: { type: 'string', demandOption: true, describe: 'JavaScript expression or statement' },
+  port: { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.exec', { code: argv.code })
+    out(result)
+    client.close()
+    if (result?.error) process.exit(1)
+  } catch (e) {
+    err(e.message, e.data)
+    process.exit(1)
+  }
+}

package/src/commands/hover.js

@@ -0,0 +1,22 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'hover'
+export const describe = 'Simulate a mouse hover over a DOM element'
+export const builder = {
+  selector: { type: 'string', demandOption: true, describe: 'CSS selector for target element' },
+  port:     { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.hover', { selector: argv.selector })
+    out(result)
+    client.close()
+    if (result?.error) process.exit(1)
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/inject.js

@@ -0,0 +1,31 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+import { readFile } from 'node:fs/promises'
+
+export const command = 'inject'
+export const describe = 'Inject a local JavaScript file into the selected tab'
+export const builder = {
+  file: { type: 'string', demandOption: true, describe: 'Path to JS file to inject' },
+  port: { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  let code
+  try {
+    code = await readFile(argv.file, 'utf8')
+  } catch {
+    err(`file_not_found: ${argv.file}`)
+    process.exit(1)
+  }
+
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.inject', { code })
+    out(result)
+    client.close()
+    if (result?.error) process.exit(1)
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/logs.js

@@ -0,0 +1,47 @@
+import { getClient } from '../client.js'
+import { out, outLine, err } from '../output.js'
+
+export const command = 'logs'
+export const describe = 'Read console or network logs from the selected tab'
+export const builder = {
+  follow:  { type: 'boolean', alias: 'f', describe: 'Stream logs in real time (legacy alias for --watch)' },
+  watch:   { type: 'boolean', alias: 'w', describe: 'Stream logs in real time via push events' },
+  level:   { type: 'string', describe: 'Filter by level: log|warn|error|info|debug' },
+  network: { type: 'boolean', describe: 'Show network requests instead of console logs' },
+  port:    { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+
+    if (argv.network) {
+      const result = await client.call('page.network', {})
+      out(result)
+      client.close()
+      return
+    }
+
+    if (argv.watch || argv.follow) {
+      // Print buffered logs first, then stream push events
+      const buffered = await client.call('page.logs', { level: argv.level })
+      buffered.forEach((entry) => outLine(entry))
+
+      // Subscribe to push events (stream.log is canonical; page:log is legacy)
+      client.on('stream.log', (entry) => {
+        if (!argv.level || entry.level === argv.level) outLine(entry)
+      })
+      client.on('page:log', () => {}) // drain legacy events silently
+
+      process.on('SIGINT', () => { client.close(); process.exit(0) })
+      return
+    }
+
+    const result = await client.call('page.logs', { level: argv.level })
+    out(result)
+    client.close()
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/navigate.js

@@ -0,0 +1,21 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'navigate'
+export const describe = 'Navigate the selected tab to a URL'
+export const builder = {
+  url:  { type: 'string', demandOption: true, describe: 'URL to navigate to' },
+  port: { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.navigate', { url: argv.url })
+    out(result)
+    client.close()
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/query.js

@@ -0,0 +1,29 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'query'
+export const describe = 'Query the DOM of the selected tab'
+export const builder = {
+  selector: { type: 'string', describe: 'CSS selector to query' },
+  html:     { type: 'boolean', describe: 'Return full page HTML' },
+  port:     { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  if (!argv.selector && !argv.html) {
+    err('Provide --selector <css> or --html')
+    process.exit(1)
+  }
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.query', {
+      selector: argv.selector,
+      full: argv.html ?? false,
+    })
+    out(result)
+    client.close()
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/repl.js

@@ -0,0 +1,63 @@
+import { createInterface } from 'node:readline'
+import { getClient } from '../client.js'
+import { err } from '../output.js'
+
+export const command = 'repl'
+export const describe = 'Start an interactive JavaScript REPL in the selected tab'
+export const builder = {
+  port: { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  let client
+  try {
+    client = await getClient(argv.port)
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+  await runRepl(process.stdin, process.stdout, client)
+  client.close()
+  process.exit(0)
+}
+
+/**
+ * Run the REPL loop.
+ * Accepts injectable input/output streams and a client for testability.
+ * @param {import('node:stream').Readable} input
+ * @param {import('node:stream').Writable} output
+ * @param {{ call: (method: string, params: object) => Promise<any> }} client
+ * @returns {Promise<void>} resolves when the REPL exits
+ */
+export async function runRepl(input, output, client) {
+  const isTTY = output.isTTY ?? false
+
+  if (isTTY) {
+    output.write('chrome-bridge REPL — JavaScript in the selected tab\n')
+    output.write('Type .exit or press Ctrl+C/Ctrl+D to quit.\n')
+  }
+
+  const rl = createInterface({ input, output: isTTY ? output : undefined, terminal: false, crlfDelay: Infinity })
+
+  if (isTTY) rl.setPrompt('> ')
+
+  return new Promise((resolve) => {
+    rl.on('line', async (line) => {
+      const code = line.trim()
+      if (!code || code === '.exit') { rl.close(); return }
+      rl.pause()
+      try {
+        const res = await client.call('page.exec', { code })
+        output.write(JSON.stringify(res.result) + '\n')
+      } catch (e) {
+        output.write(`Error: ${e.message}\n`)
+      }
+      rl.resume()
+      if (isTTY) rl.prompt()
+    })
+
+    rl.on('close', resolve)
+
+    if (isTTY) rl.prompt()
+  })
+}

package/src/commands/screenshot.js

@@ -0,0 +1,29 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+import { writeFile } from 'node:fs/promises'
+
+export const command = 'screenshot'
+export const describe = 'Capture a screenshot of the selected tab'
+export const builder = {
+  output: { type: 'string', alias: 'o', describe: 'Save PNG to file path instead of printing base64' },
+  port:   { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.screenshot', {})
+    client.close()
+
+    if (argv.output) {
+      const base64 = result.dataUrl.replace(/^data:image\/png;base64,/, '')
+      await writeFile(argv.output, Buffer.from(base64, 'base64'))
+      out({ saved: argv.output })
+    } else {
+      out(result)
+    }
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/snapshot.js

@@ -0,0 +1,21 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'snapshot'
+export const describe = 'Capture the full HTML of the current page'
+export const builder = {
+  styles: { type: 'boolean', default: false, describe: 'Include computed styles inline' },
+  port:   { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.snapshot', { styles: argv.styles })
+    out(result)
+    client.close()
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/start.js

@@ -0,0 +1,42 @@
+import { Relay } from '../relay.js'
+import { readToken, TOKEN_PATH } from '../token.js'
+import { writeFile, readFile, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const PID_FILE = join(homedir(), '.chrome-cli-bridge.pid')
+
+export const command = 'start'
+export const describe = 'Start the relay server'
+export const builder = {
+  port:     { type: 'number', default: 9876, describe: 'Port to listen on' },
+  detach:   { type: 'boolean', default: false, describe: 'Run in background (daemon mode)' },
+}
+
+export async function handler(argv) {
+  const relay = new Relay(argv.port)
+  try {
+    const token = await relay.start()
+    await writeFile(PID_FILE, String(process.pid), 'utf8')
+    console.log(`Relay started on ws://127.0.0.1:${argv.port}`)
+    console.log(`Session token: ${token}`)
+    console.log(`Token saved to: ${TOKEN_PATH}`)
+    console.log('')
+    console.log('Open the chrome-cli-bridge extension popup in Chrome, paste the token, and click Connect.')
+    console.log('Press Ctrl+C to stop.')
+
+    process.on('SIGINT', async () => {
+      await relay.stop()
+      await unlink(PID_FILE).catch(() => {})
+      process.exit(0)
+    })
+    process.on('SIGTERM', async () => {
+      await relay.stop()
+      await unlink(PID_FILE).catch(() => {})
+      process.exit(0)
+    })
+  } catch (e) {
+    console.error(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/status.js

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { out } from '../output.js'
+import { readToken } from '../token.js'
+import { RelayClient } from '../client.js'
+
+const PID_FILE = join(homedir(), '.chrome-cli-bridge.pid')
+
+export const command = 'status'
+export const describe = 'Check relay and extension connection status'
+export const builder = {
+  port: { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  const result = { relay: 'stopped', extension: 'disconnected', pid: null, token: null }
+
+  try {
+    const pid = parseInt(await readFile(PID_FILE, 'utf8'), 10)
+    process.kill(pid, 0) // check if alive
+    result.relay = 'running'
+    result.pid = pid
+  } catch { /* not running */ }
+
+  result.token = (await readToken()) ? '(set)' : '(not set)'
+
+  if (result.relay === 'running') {
+    try {
+      const token = await readToken()
+      const client = new RelayClient(argv.port, token)
+      await client.connect()
+      // If connect succeeded, relay responded; check if extension is attached
+      const tabs = await client.call('tabs.list', {}).catch(() => null)
+      result.extension = tabs !== null ? 'connected' : 'not connected'
+      client.close()
+    } catch {
+      result.extension = 'not connected'
+    }
+  }
+
+  out(result)
+}

package/src/commands/stop.js

@@ -0,0 +1,28 @@
+import { readFile, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const PID_FILE = join(homedir(), '.chrome-cli-bridge.pid')
+
+export const command = 'stop'
+export const describe = 'Stop the relay server'
+export const builder = {}
+
+export async function handler() {
+  try {
+    const pid = parseInt(await readFile(PID_FILE, 'utf8'), 10)
+    process.kill(pid, 'SIGTERM')
+    await unlink(PID_FILE).catch(() => {})
+    console.log(`Stopped relay (pid ${pid})`)
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      console.error('No relay is running (no PID file found)')
+    } else if (e.code === 'ESRCH') {
+      console.error('Relay process not found — cleaning up stale PID file')
+      await unlink(PID_FILE).catch(() => {})
+    } else {
+      console.error(e.message)
+    }
+    process.exit(1)
+  }
+}

package/src/commands/storage.js

@@ -0,0 +1,26 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'storage'
+export const describe = 'Read or write cookies, localStorage, or sessionStorage'
+export const builder = {
+  type: { type: 'string', choices: ['local', 'session', 'cookies'], demandOption: true, describe: 'Storage type' },
+  key:  { type: 'string', describe: 'Key to read or write' },
+  set:  { type: 'string', describe: 'Value to write (requires --key)' },
+  port: { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const params = { type: argv.type }
+    if (argv.key !== undefined) params.key = argv.key
+    if (argv.set !== undefined) params.set = argv.set
+    const result = await client.call('page.storage', params)
+    out(result)
+    client.close()
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/tabs.js

@@ -0,0 +1,29 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'tabs'
+export const describe = 'List open tabs or select a target tab'
+export const builder = {
+  select: { type: 'string', describe: 'Select a tab by ID or "active"' },
+  port:   { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+
+    if (argv.select !== undefined) {
+      const tabId = argv.select === 'active' ? 'active' : parseInt(argv.select, 10)
+      const result = await client.call('tabs.select', { tabId })
+      out(result)
+    } else {
+      const result = await client.call('tabs.list', {})
+      out(result)
+    }
+
+    client.close()
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/trigger.js

@@ -0,0 +1,22 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'trigger'
+export const describe = 'Dispatch a DOM event on an element in the selected tab'
+export const builder = {
+  selector: { type: 'string', demandOption: true, describe: 'CSS selector for the target element' },
+  event:    { type: 'string', demandOption: true, describe: 'Event type: click|input|change|submit|keydown|keyup' },
+  port:     { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.trigger', { selector: argv.selector, event: argv.event })
+    out(result)
+    client.close()
+  } catch (e) {
+    err(e.message)
+    process.exit(e.code === -32001 ? 1 : 1)
+  }
+}

package/src/commands/type.js

@@ -0,0 +1,23 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'type'
+export const describe = 'Simulate keyboard typing into a DOM element'
+export const builder = {
+  selector: { type: 'string', demandOption: true, describe: 'CSS selector for target element' },
+  text:     { type: 'string', demandOption: true, describe: 'Text to type' },
+  port:     { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.type', { selector: argv.selector, text: argv.text })
+    out(result)
+    client.close()
+    if (result?.error) process.exit(1)
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/commands/wait.js

@@ -0,0 +1,23 @@
+import { getClient } from '../client.js'
+import { out, err } from '../output.js'
+
+export const command = 'wait'
+export const describe = 'Wait until a CSS selector appears in the DOM'
+export const builder = {
+  selector: { type: 'string', demandOption: true, describe: 'CSS selector to wait for' },
+  timeout:  { type: 'number', default: 5000, describe: 'Timeout in ms (default 5000)' },
+  port:     { type: 'number', default: 9876, describe: 'Relay port' },
+}
+
+export async function handler(argv) {
+  try {
+    const client = await getClient(argv.port)
+    const result = await client.call('page.wait', { selector: argv.selector, timeout: argv.timeout })
+    out(result)
+    client.close()
+    if (!result.found) process.exit(1)
+  } catch (e) {
+    err(e.message)
+    process.exit(1)
+  }
+}

package/src/index.js

@@ -0,0 +1,83 @@
+import { Relay } from './relay.js'
+import { RelayClient } from './client.js'
+import { readToken } from './token.js'
+
+/**
+ * ChromeBridge SDK — programmatic interface for Node.js consumers.
+ *
+ * Usage:
+ *   const bridge = new ChromeBridge()
+ *   await bridge.connect()
+ *   const tabs = await bridge.tabs()
+ *   await bridge.selectTab(tabs[0].id)
+ *   const { result } = await bridge.exec({ code: 'document.title' })
+ *   await bridge.disconnect()
+ */
+export class ChromeBridge {
+  #client = null
+  #port
+
+  constructor({ port = 9876 } = {}) {
+    this.#port = port
+  }
+
+  async connect() {
+    const token = await readToken()
+    if (!token) throw new Error('No session token found. Run: chrome-bridge start')
+    this.#client = new RelayClient(this.#port, token)
+    await this.#client.connect()
+  }
+
+  async disconnect() {
+    this.#client?.close()
+    this.#client = null
+  }
+
+  #call(method, params) {
+    if (!this.#client) throw new Error('Not connected. Call bridge.connect() first.')
+    return this.#client.call(method, params)
+  }
+
+  // ── Existing commands ────────────────────────────────────────────────────
+  tabs()                    { return this.#call('tabs.list', {}) }
+  selectTab(tabId)          { return this.#call('tabs.select', { tabId }) }
+  query(params)             { return this.#call('page.query', params) }
+  exec(params)              { return this.#call('page.exec', params) }
+  logs(params = {})         { return this.#call('page.logs', params) }
+  network()                 { return this.#call('page.network', {}) }
+  trigger(params)           { return this.#call('page.trigger', params) }
+
+  // ── New commands ─────────────────────────────────────────────────────────
+  screenshot(params = {})              { return this.#call('page.screenshot', params) }
+  navigate(params)                     { return this.#call('page.navigate', params) }
+  storage(params)                      { return this.#call('page.storage', params) }
+  wait(params)                         { return this.#call('page.wait', params) }
+  inject(params)                       { return this.#call('page.inject', params) }
+  snapshot(params = {})                { return this.#call('page.snapshot', params) }
+  type(params)                         { return this.#call('page.type', params) }
+  click(params)                        { return this.#call('page.click', params) }
+  hover(params)                        { return this.#call('page.hover', params) }
+
+  /** Subscribe to real-time console log push events.
+   *  @returns {() => void} unsubscribe function */
+  streamLogs(handler) {
+    if (!this.#client) throw new Error('Not connected.')
+    return this.#client.on('stream.log', handler)
+  }
+
+  /** DevTools namespace */
+  get devtools() {
+    return {
+      performance: ()       => this.#call('devtools.performance', {}),
+      memory:      (params = {}) => this.#call('devtools.memory', params),
+      coverage:    (params = {}) => this.#call('devtools.coverage', params),
+    }
+  }
+
+  on(event, handler) {
+    if (!this.#client) throw new Error('Not connected.')
+    return this.#client.on(event, handler)
+  }
+}
+
+export { Relay, RelayClient, readToken }

package/src/output.js

@@ -0,0 +1,56 @@
+const isTTY = process.stdout.isTTY
+
+export function out(data) {
+  if (isTTY) {
+    prettyPrint(data)
+  } else {
+    process.stdout.write(JSON.stringify(data) + '\n')
+  }
+}
+
+export function outLine(data) {
+  process.stdout.write(JSON.stringify(data) + '\n')
+}
+
+export function err(msg, data) {
+  const obj = { error: msg, ...(data && { data }) }
+  if (isTTY) {
+    process.stderr.write(`\x1b[31mError:\x1b[0m ${msg}${data ? '\n' + JSON.stringify(data, null, 2) : ''}\n`)
+  } else {
+    process.stderr.write(JSON.stringify(obj) + '\n')
+  }
+}
+
+function prettyPrint(data) {
+  if (Array.isArray(data)) {
+    if (data.length === 0) { console.log('(empty)'); return }
+    // Detect tab list shape
+    if (data[0]?.id !== undefined && data[0]?.url !== undefined) {
+      const rows = data.map((t) =>
+        `  [${t.id}] ${t.active ? '●' : '○'} ${t.title?.slice(0, 50).padEnd(50)} ${t.url}`)
+      console.log(rows.join('\n'))
+      return
+    }
+    // Detect element list shape
+    if (data[0]?.tag !== undefined) {
+      data.forEach((el, i) => {
+        console.log(`  [${i}] <${el.tag}${el.id ? '#' + el.id : ''}> ${el.textContent?.slice(0, 80)}`)
+      })
+      return
+    }
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+  if (typeof data === 'object' && data !== null) {
+    // Log entry shape
+    if (data.level && data.message && data.timestamp) {
+      const d = new Date(data.timestamp).toISOString()
+      const lvl = data.level.toUpperCase().padEnd(5)
+      console.log(`  ${d} [${lvl}] ${data.message}`)
+      return
+    }
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+  console.log(data)
+}

package/src/relay.js

@@ -0,0 +1,200 @@
+import { WebSocketServer } from 'ws'
+import { generateToken, readToken } from './token.js'
+import { isRequest, isResponse, isEvent, error, ERR } from './rpc.js'
+
+const HANDSHAKE_TIMEOUT_MS = 5000
+const KEEPALIVE_INTERVAL_MS = 20000
+
+export class Relay {
+  #port
+  #wss = null
+  #extension = null          // the authenticated extension WS
+  #cliClients = new Set()    // all authenticated CLI client sockets
+  #token = null
+  #pendingCalls = new Map()  // id → { resolve, reject, timer }
+  #eventHandlers = new Map() // method → Set<fn>
+  #keepaliveTimer = null
+
+  constructor(port = 9876) {
+    this.#port = port
+  }
+
+  get port() { return this.#port }
+  get token() { return this.#token }
+  get connected() { return this.#extension !== null }
+
+  async start() {
+    this.#token = await generateToken()
+
+    await new Promise((resolve, reject) => {
+      this.#wss = new WebSocketServer({ host: '127.0.0.1', port: this.#port })
+
+      this.#wss.once('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          reject(new Error(`Port ${this.#port} is already in use. Is chrome-bridge already running?\nRun: chrome-bridge stop`))
+        } else {
+          reject(err)
+        }
+      })
+
+      this.#wss.once('listening', resolve)
+      this.#wss.on('connection', (ws) => this.#onConnection(ws))
+    })
+
+    return this.#token
+  }
+
+  async stop() {
+    clearInterval(this.#keepaliveTimer)
+    // Terminate ALL connected sockets (extension + any CLI clients) so wss.close()
+    // completes immediately instead of waiting for them to close on their own.
+    if (this.#wss) {
+      for (const ws of this.#wss.clients) ws.terminate()
+    }
+    this.#extension = null
+    await new Promise((resolve) => this.#wss ? this.#wss.close(resolve) : resolve())
+    this.#wss = null
+  }
+
+  // Send a JSON-RPC request to the extension and await the response
+  async call(method, params = {}, timeoutMs = 10000) {
+    if (!this.#extension) throw new Error('Extension not connected')
+
+    return new Promise((resolve, reject) => {
+      const msg = { jsonrpc: '2.0', method, params, id: this.#nextId() }
+      const timer = setTimeout(() => {
+        this.#pendingCalls.delete(msg.id)
+        reject(new Error(`Timeout waiting for response to ${method}`))
+      }, timeoutMs)
+
+      this.#pendingCalls.set(msg.id, { resolve, reject, timer })
+      this.#extension.send(JSON.stringify(msg))
+    })
+  }
+
+  on(event, handler) {
+    if (!this.#eventHandlers.has(event)) this.#eventHandlers.set(event, new Set())
+    this.#eventHandlers.get(event).add(handler)
+    return () => this.#eventHandlers.get(event)?.delete(handler)
+  }
+
+  #nextId = (() => { let i = 0; return () => ++i })()
+
+  #onConnection(ws) {
+    let role = null  // 'extension' | 'cli'
+
+    const handshakeTimer = setTimeout(() => {
+      if (!role) ws.close(4001, 'Unauthorized: handshake timeout')
+    }, HANDSHAKE_TIMEOUT_MS)
+
+    ws.on('message', (data) => {
+      let msg
+      try { msg = JSON.parse(data.toString()) } catch {
+        ws.send(JSON.stringify(error(null, ERR.PARSE_ERROR, 'Parse error')))
+        return
+      }
+
+      if (!role) {
+        if (msg.method === 'handshake' && msg.params?.token === this.#token) {
+          clearTimeout(handshakeTimer)
+          role = msg.params?.role === 'cli' ? 'cli' : 'extension'
+
+          if (role === 'extension') {
+            this.#extension = ws
+            this.#startKeepalive()
+          } else if (role === 'cli') {
+            this.#cliClients.add(ws)
+          }
+
+          ws.send(JSON.stringify({ jsonrpc: '2.0', result: { status: 'ok', role }, id: msg.id }))
+        } else {
+          ws.close(4001, 'Unauthorized')
+        }
+        return
+      }
+
+      if (role === 'cli') {
+        // Forward request to extension, send response back to this CLI client
+        if (!this.#extension) {
+          ws.send(JSON.stringify(error(msg.id, -32000, 'Extension not connected')))
+          return
+        }
+        const id = this.#nextId()
+        const forwarded = { ...msg, id }
+        const timer = setTimeout(() => {
+          this.#pendingCalls.delete(id)
+          ws.send(JSON.stringify(error(msg.id, -32000, 'Timeout')))
+        }, 10000)
+        this.#pendingCalls.set(id, {
+          resolve: (result) => ws.send(JSON.stringify({ jsonrpc: '2.0', result, id: msg.id })),
+          reject:  (err) => ws.send(JSON.stringify(error(msg.id, err.code ?? -32000, err.message))),
+          timer,
+        })
+        this.#extension.send(JSON.stringify(forwarded))
+        return
+      }
+
+      // role === 'extension': handle responses to our outgoing calls
+      if (isResponse(msg)) {
+        const pending = this.#pendingCalls.get(msg.id)
+        if (pending) {
+          clearTimeout(pending.timer)
+          this.#pendingCalls.delete(msg.id)
+          if (msg.error) {
+            const err = new Error(msg.error.message)
+            err.code = msg.error.code
+            err.data = msg.error.data
+            pending.reject(err)
+          } else {
+            pending.resolve(msg.result)
+          }
+        }
+        return
+      }
+
+      // Handle push events from the extension — forward to local handlers AND all CLI clients
+      if (isEvent(msg)) {
+        const handlers = this.#eventHandlers.get(msg.method)
+        if (handlers) handlers.forEach((fn) => fn(msg.params))
+        // Forward the raw event to all connected CLI WebSocket clients
+        const raw = data.toString()
+        for (const cliWs of this.#cliClients) {
+          if (cliWs.readyState === 1 /* OPEN */) cliWs.send(raw)
+        }
+        return
+      }
+    })
+
+    ws.on('close', () => {
+      this.#cliClients.delete(ws)
+      if (this.#extension === ws) {
+        this.#extension = null
+        clearInterval(this.#keepaliveTimer)
+        this.#keepaliveTimer = null
+        // reject all pending calls
+        for (const [, pending] of this.#pendingCalls) {
+          clearTimeout(pending.timer)
+          pending.reject(new Error('Extension disconnected'))
+        }
+        this.#pendingCalls.clear()
+      }
+    })
+  }
+
+  #startKeepalive() {
+    clearInterval(this.#keepaliveTimer)
+    this.#keepaliveTimer = setInterval(() => {
+      if (this.#extension?.readyState === 1 /* OPEN */) {
+        this.#extension.ping()
+      }
+    }, KEEPALIVE_INTERVAL_MS)
+  }
+}
+
+// Singleton for CLI commands
+let _relay = null
+
+export function getRelay(port) {
+  if (!_relay) _relay = new Relay(port)
+  return _relay
+}

package/src/rpc.js

@@ -0,0 +1,36 @@
+let _id = 0
+
+export function request(method, params = {}) {
+  return { jsonrpc: '2.0', method, params, id: ++_id }
+}
+
+export function response(id, result) {
+  return { jsonrpc: '2.0', result, id }
+}
+
+export function error(id, code, message, data) {
+  return { jsonrpc: '2.0', error: { code, message, ...(data && { data }) }, id }
+}
+
+export function isRequest(msg) {
+  return msg.jsonrpc === '2.0' && typeof msg.method === 'string' && msg.id !== undefined
+}
+
+export function isResponse(msg) {
+  return msg.jsonrpc === '2.0' && (msg.result !== undefined || msg.error !== undefined) && msg.id !== undefined
+}
+
+export function isEvent(msg) {
+  return msg.jsonrpc === '2.0' && typeof msg.method === 'string' && msg.id === undefined
+}
+
+export const ERR = {
+  PARSE_ERROR:         -32700,
+  INVALID_REQUEST:     -32600,
+  METHOD_NOT_FOUND:    -32601,
+  INVALID_PARAMS:      -32602,
+  TAB_NOT_FOUND:       -32000,
+  ELEMENT_NOT_FOUND:   -32001,
+  EXEC_ERROR:          -32002,
+  DEBUGGER_ATTACH_FAILED: -32003,
+}

package/src/token.js

@@ -0,0 +1,24 @@
+import { randomUUID } from 'node:crypto'
+import { writeFile, readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { chmod } from 'node:fs/promises'
+
+const TOKEN_PATH = join(homedir(), '.chrome-cli-bridge.token')
+
+export async function generateToken() {
+  const token = randomUUID()
+  await writeFile(TOKEN_PATH, token, { encoding: 'utf8', mode: 0o600 })
+  await chmod(TOKEN_PATH, 0o600)
+  return token
+}
+
+export async function readToken() {
+  try {
+    return (await readFile(TOKEN_PATH, 'utf8')).trim()
+  } catch {
+    return null
+  }
+}
+
+export { TOKEN_PATH }