@bubstack/moe-glass 0.1.0

package/skills/browsing/chrome-ws

@@ -0,0 +1,1021 @@
+#!/usr/bin/env node
+
+const process = require('process');
+
+// Parse --port=N flag from anywhere in argv (filter it out of positional args)
+const allArgs = process.argv.slice(2);
+const portArg = allArgs.find(a => a.startsWith('--port='));
+const positionalArgs = allArgs.filter(a => !a.startsWith('--port='));
+const [command, wsUrlOrIndex, ...args] = positionalArgs;
+
+// Handle --help and --version before any other processing
+if (command === '--help' || command === '-h' || !command) {
+  console.log(`Usage: chrome-ws <command> [args]
+
+Commands:
+  start [port]                                  Start Chrome with remote debugging
+  stop                                           Kill Chrome
+  pid                                            Print Chrome PID
+  info                                           Print Chrome info (JSON)
+  tabs                                           List open tabs
+  new <url>                                      Open a new tab
+  close <tab>                                    Close a tab
+  navigate <tab> <url>                           Navigate tab to URL
+  extract <tab> <selector>                       Extract element text content
+  attr <tab> <selector> <attribute>             Get element attribute
+  html <tab> [selector]                         Get HTML content
+  click <tab> <selector>                         Click an element
+  fill <tab> <selector> <text>                   Fill an input field
+  select <tab> <selector> <value>               Select a dropdown option
+  eval <tab> <js>                                Evaluate JavaScript
+  wait-for <tab> <selector> [timeout-ms]        Wait for element to appear
+  wait-text <tab> <text> [timeout-ms]           Wait for text to appear
+  screenshot <tab> <filename.png> [--fullpage]  Take a screenshot
+  markdown <tab> <filename.md>                  Save page as markdown
+  har <tab> <filename.har>                      Export HAR (after har-start)
+  raw <ws-url> <json-rpc-payload>               Send raw CDP command
+
+  --help, -h                                     Show this help
+  --version, -v                                  Show version
+  --port=N                                       Override CHROME_WS_PORT env var
+
+Tab arg: numeric index (0, 1, 2...) or full ws:// URL.
+`);
+  process.exit(0);
+}
+if (command === '--version' || command === '-v') {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const hostOverride = require('./host-override').createOverride();
+const { createSession } = require('./chrome-ws-lib');
+const { buildChromeArgs } = require('./lib/chrome-launcher-helpers');
+const CHROME_DEBUG_HOST = hostOverride.getHost();
+const CHROME_DEBUG_PORT = hostOverride.getPort();
+const WS_OVERRIDE_ENABLED = hostOverride.isOverrideEnabled();
+const rewriteWsUrl = hostOverride.rewriteWsUrl;
+
+// Effective port: --port=N flag overrides CHROME_WS_PORT env / default 9222
+const effectivePort = portArg ? parseInt(portArg.split('=')[1], 10) : CHROME_DEBUG_PORT;
+
+// Session pointed at the effective port. Built after effectivePort is known
+// so the lib's pooled connections target the right Chrome instance.
+const session = createSession({ host: CHROME_DEBUG_HOST, port: effectivePort });
+
+// Minimal WebSocket client implementation (dependency-free)
+class WebSocketClient {
+  constructor(url) {
+    this.url = new URL(url);
+    this.callbacks = {};
+    this.socket = null;
+    this.buffer = Buffer.alloc(0);
+  }
+
+  on(event, callback) {
+    this.callbacks[event] = callback;
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      const http = require('http');
+      const crypto = require('crypto');
+
+      const key = crypto.randomBytes(16).toString('base64');
+
+      const options = {
+        hostname: this.url.hostname,
+        port: this.url.port || 80,
+        path: this.url.pathname + this.url.search,
+        headers: {
+          'Upgrade': 'websocket',
+          'Connection': 'Upgrade',
+          'Sec-WebSocket-Key': key,
+          'Sec-WebSocket-Version': '13'
+        }
+      };
+
+      const req = http.request(options);
+
+      req.on('upgrade', (res, socket) => {
+        this.socket = socket;
+
+        socket.on('data', (data) => {
+          this.buffer = Buffer.concat([this.buffer, data]);
+          this.processFrames();
+        });
+
+        socket.on('error', (err) => {
+          if (this.callbacks.error) this.callbacks.error(err);
+        });
+
+        if (this.callbacks.open) this.callbacks.open();
+        resolve();
+      });
+
+      req.on('error', reject);
+      req.end();
+    });
+  }
+
+  processFrames() {
+    while (this.buffer.length >= 2) {
+      const firstByte = this.buffer[0];
+      const secondByte = this.buffer[1];
+
+      const fin = (firstByte & 0x80) !== 0;
+      const opcode = firstByte & 0x0F;
+      const masked = (secondByte & 0x80) !== 0;
+      let payloadLen = secondByte & 0x7F;
+
+      let offset = 2;
+
+      if (payloadLen === 126) {
+        if (this.buffer.length < 4) return;
+        payloadLen = this.buffer.readUInt16BE(2);
+        offset = 4;
+      } else if (payloadLen === 127) {
+        if (this.buffer.length < 10) return;
+        payloadLen = Number(this.buffer.readBigUInt64BE(2));
+        offset = 10;
+      }
+
+      if (this.buffer.length < offset + payloadLen) return;
+
+      let payload = this.buffer.slice(offset, offset + payloadLen);
+      this.buffer = this.buffer.slice(offset + payloadLen);
+
+      if (opcode === 0x1 && this.callbacks.message) {
+        this.callbacks.message(payload.toString('utf8'));
+      }
+    }
+  }
+
+  send(data) {
+    const payload = Buffer.from(data, 'utf8');
+    const payloadLen = payload.length;
+
+    let frame;
+    let offset = 2;
+
+    if (payloadLen < 126) {
+      frame = Buffer.alloc(payloadLen + 6);
+      frame[1] = payloadLen | 0x80;
+    } else if (payloadLen < 65536) {
+      frame = Buffer.alloc(payloadLen + 8);
+      frame[1] = 126 | 0x80;
+      frame.writeUInt16BE(payloadLen, 2);
+      offset = 4;
+    } else {
+      frame = Buffer.alloc(payloadLen + 14);
+      frame[1] = 127 | 0x80;
+      frame.writeBigUInt64BE(BigInt(payloadLen), 2);
+      offset = 10;
+    }
+
+    frame[0] = 0x81; // FIN + text frame
+
+    const mask = Buffer.alloc(4);
+    require('crypto').randomFillSync(mask);
+    mask.copy(frame, offset);
+    offset += 4;
+
+    for (let i = 0; i < payloadLen; i++) {
+      frame[offset + i] = payload[i] ^ mask[i % 4];
+    }
+
+    this.socket.write(frame);
+  }
+
+  close() {
+    if (this.socket) {
+      this.socket.end();
+      this.socket = null;
+    }
+  }
+}
+
+// Helper to convert string tab specifier to the type expected by session methods.
+// session.fill/evaluate/etc. use getPageSession which accepts a number (index) or
+// a ws:// string — but NOT a numeric string like "0".
+function resolveTabArg(wsUrlOrIndex) {
+  if (wsUrlOrIndex && wsUrlOrIndex.startsWith('ws://')) {
+    return wsUrlOrIndex; // Already a ws URL string
+  }
+  const index = parseInt(wsUrlOrIndex, 10);
+  if (!isNaN(index)) {
+    return index; // Numeric tab index as a number
+  }
+  throw new Error(`Invalid tab specifier: ${wsUrlOrIndex}`);
+}
+
+// Helper to resolve tab index or ws URL to actual ws URL
+async function resolveWsUrl(wsUrlOrIndex) {
+  // If it's already a WebSocket URL, return it
+  if (wsUrlOrIndex && wsUrlOrIndex.startsWith('ws://')) {
+    return wsUrlOrIndex;
+  }
+
+  // If it's a number (tab index), resolve it
+  const index = parseInt(wsUrlOrIndex);
+  if (!isNaN(index)) {
+    const tabs = await chromeHttp('/json');
+    const pageTabs = Array.isArray(tabs)
+      ? tabs
+          .filter(t => t.type === 'page')
+          .map(tab => WS_OVERRIDE_ENABLED
+            ? { ...tab, webSocketDebuggerUrl: rewriteWsUrl(tab.webSocketDebuggerUrl) }
+            : tab
+          )
+      : [];
+
+    // Auto-create tab if none exist (similar to auto-start Chrome behavior)
+    if (pageTabs.length === 0) {
+      const newTabInfo = await chromeHttp('/json/new?about:blank', 'PUT');
+      return WS_OVERRIDE_ENABLED ? rewriteWsUrl(newTabInfo.webSocketDebuggerUrl) : newTabInfo.webSocketDebuggerUrl;
+    }
+
+    if (index < 0 || index >= pageTabs.length) {
+      throw new Error(`Tab index ${index} out of range (0-${pageTabs.length - 1})`);
+    }
+    return WS_OVERRIDE_ENABLED ? rewriteWsUrl(pageTabs[index].webSocketDebuggerUrl) : pageTabs[index].webSocketDebuggerUrl;
+  }
+
+  throw new Error(`Invalid tab specifier: ${wsUrlOrIndex}`);
+}
+
+// Helper to make HTTP requests to Chrome on the effective port
+async function chromeHttp(path, method = 'GET') {
+  const http = require('http');
+
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: CHROME_DEBUG_HOST,
+      port: effectivePort,
+      path,
+      method: method
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        if (!data) {
+          resolve({});
+          return;
+        }
+        try {
+          resolve(JSON.parse(data));
+        } catch (e) {
+          // Some endpoints return plain text (e.g., "Target is closing")
+          resolve({ message: data });
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// Command: start - launch Chrome with remote debugging
+if (command === 'start') {
+  const { spawn } = require('child_process');
+  const { existsSync } = require('fs');
+  const os = require('os');
+
+  // Platform-specific Chrome paths
+  const chromePaths = {
+    darwin: [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium'
+    ],
+    linux: [
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser'
+    ],
+    win32: [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+      'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe'
+    ]
+  };
+
+  const platform = os.platform();
+  const paths = chromePaths[platform];
+
+  if (!paths) {
+    console.error(`Unsupported platform: ${platform}`);
+    process.exit(1);
+  }
+
+  // Find Chrome executable (CHROME_WS_BROWSER env var overrides auto-detection)
+  const chromePath = process.env.CHROME_WS_BROWSER || paths.find(p => existsSync(p));
+
+  if (!chromePath) {
+    console.error('Chrome not found. Searched:');
+    paths.forEach(p => console.error(`  ${p}`));
+    process.exit(1);
+  }
+
+  // Launch Chrome
+  const userDataDir = platform === 'win32'
+    ? 'C:\\temp\\chrome-debug'
+    : '/tmp/chrome-debug';
+
+  const chromeArgs = buildChromeArgs({
+    chosenPort: effectivePort,
+    chromeUserDataDir: userDataDir,
+    chromeHeadless: false,
+  });
+
+  console.log(`Starting Chrome: ${chromePath}`);
+
+  // Capture Chrome's stderr to a tempfile (issue #35): with stdio 'ignore',
+  // Chrome's own complaint (sandbox, missing libs, profile lock) vanished and
+  // every launch failure looked like an ambiguous port timeout.
+  const { openSync, closeSync, readFileSync: readFile, unlinkSync } = require('fs');
+  const pathMod = require('path');
+  const stderrLogPath = pathMod.join(os.tmpdir(), `chrome-ws-start-${process.pid}.log`);
+  const stderrFd = openSync(stderrLogPath, 'w');
+
+  const chrome = spawn(chromePath, chromeArgs, {
+    detached: true,
+    stdio: ['ignore', 'ignore', stderrFd]
+  });
+
+  // Race Chrome's exit against the port poll so "Chrome died at launch" is
+  // reported as that, not as "debug port not accessible".
+  let exited = null;
+  chrome.on('exit', (code, signal) => { exited = { code, signal }; });
+  chrome.on('error', (err) => {
+    console.error(`Failed to launch Chrome (${chromePath}): ${err.message}`);
+    process.exit(1);
+  });
+  chrome.unref();
+  closeSync(stderrFd); // the child keeps its own descriptor
+
+  const stderrTail = () => {
+    try {
+      const lines = readFile(stderrLogPath, 'utf8').trim().split('\n');
+      return lines.slice(-20).join('\n').trim();
+    } catch (_e) {
+      return '';
+    }
+  };
+
+  const debugBase = `http://${CHROME_DEBUG_HOST}:${effectivePort}`;
+
+  // Wait and verify
+  setTimeout(async () => {
+    try {
+      const version = await chromeHttp('/json/version');
+      console.log(`Chrome started: ${version.Browser}`);
+      console.log(`Remote debugging: ${debugBase}`);
+      try { unlinkSync(stderrLogPath); } catch (_e) { /* best-effort */ }
+    } catch (e) {
+      if (exited) {
+        const how = exited.signal ? `signal ${exited.signal}` : `code ${exited.code}`;
+        console.error(`Chrome exited with ${how} before opening the debug port`);
+      } else {
+        console.error(`Chrome is running but the debug port at ${debugBase} is not responding`);
+        console.error(`Try: curl ${debugBase}/json/version`);
+      }
+      const tail = stderrTail();
+      if (tail) {
+        console.error(`Chrome stderr (full log: ${stderrLogPath}):`);
+        console.error(tail);
+      }
+      process.exit(1);
+    }
+  }, 2000);
+
+  return;
+}
+
+// Command: stop - kill the Chrome process this session manages
+if (command === 'stop') {
+  (async () => {
+    try {
+      await session.killChrome();
+      console.log('Chrome stopped');
+    } catch (e) {
+      console.error('Failed to stop Chrome:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: pid - print Chrome PID (for X11 window management, etc.)
+if (command === 'pid') {
+  const pid = session.getChromePid();
+  if (pid === null) {
+    console.error('Chrome is not running (started via MCP). PID is only available when Chrome was started in this process.');
+    process.exit(1);
+  }
+  console.log(pid);
+  return;
+}
+
+// Command: info - print Chrome info as JSON (pid, mode, profile, port)
+if (command === 'info') {
+  (async () => {
+    try {
+      const mode = await session.getBrowserMode();
+      // Also try to get PID from meta.json if available
+      const meta = session.readProfileMeta ? session.readProfileMeta(mode.profile) : null;
+      const info = {
+        pid: meta ? meta.pid : mode.pid,
+        port: meta ? meta.port : mode.port,
+        mode: meta ? (meta.headless ? 'headless' : 'headed') : mode.mode,
+        profile: mode.profile,
+        profileDir: mode.profileDir,
+        running: meta !== null
+      };
+      console.log(JSON.stringify(info, null, 2));
+    } catch (e) {
+      console.error('Failed to get Chrome info:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: tabs - list all tabs
+if (command === 'tabs') {
+  (async () => {
+    try {
+      const tabs = await chromeHttp('/json');
+      tabs.forEach(tab => {
+        if (tab.type === 'page') {
+          console.log(`${tab.id}\t${tab.url}\t${tab.title}`);
+        }
+      });
+    } catch (e) {
+      console.error('Failed to list tabs:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: new - create new tab
+if (command === 'new') {
+  // For this command, wsUrlOrIndex variable contains the URL parameter
+  if (!wsUrlOrIndex) {
+    console.error('Usage: chrome-ws new <url>');
+    process.exit(1);
+  }
+  const url = wsUrlOrIndex;
+  (async () => {
+    try {
+      const encoded = encodeURIComponent(url);
+      const tab = await chromeHttp(`/json/new?${encoded}`, 'PUT');
+      const wsUrl = WS_OVERRIDE_ENABLED ? rewriteWsUrl(tab.webSocketDebuggerUrl) : tab.webSocketDebuggerUrl;
+      console.log(wsUrl);
+    } catch (e) {
+      console.error('Failed to create tab:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: close - close tab by ws URL or numeric index
+if (command === 'close') {
+  if (!wsUrlOrIndex) {
+    console.error('Usage: chrome-ws close <tab>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const tabWsUrl = await resolveWsUrl(wsUrlOrIndex);
+      // Extract tab ID from ws URL
+      const match = tabWsUrl.match(/\/devtools\/page\/([A-F0-9-]+)/i);
+      if (!match) {
+        console.error('Invalid WebSocket URL');
+        process.exit(1);
+      }
+      await chromeHttp(`/json/close/${match[1]}`);
+      console.log('Tab closed');
+    } catch (e) {
+      console.error('Failed to close tab:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Helper to send CDP command via WebSocket
+async function sendCdpCommand(wsUrl, method, params = {}) {
+  return new Promise(async (resolve, reject) => {
+    const ws = new WebSocketClient(wsUrl);
+    const id = Math.floor(Math.random() * 1000000);
+
+    const timeout = setTimeout(() => {
+      ws.close();
+      reject(new Error('Timeout after 30s'));
+    }, 30000);
+
+    ws.on('message', (data) => {
+      const response = JSON.parse(data);
+      if (response.id === id) {
+        clearTimeout(timeout);
+        if (response.error) {
+          ws.close();
+          reject(new Error(response.error.message));
+        } else {
+          ws.close();
+          resolve(response.result);
+        }
+      }
+    });
+
+    ws.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    try {
+      await ws.connect();
+      ws.send(JSON.stringify({ id, method, params }));
+    } catch (err) {
+      clearTimeout(timeout);
+      reject(err);
+    }
+  });
+}
+
+// Command: navigate
+if (command === 'navigate') {
+  const [url] = args;
+  if (!wsUrlOrIndex || !url) {
+    console.error('Usage: chrome-ws navigate <tab-index-or-ws-url> <url>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const wsUrl = await resolveWsUrl(wsUrlOrIndex);
+      await sendCdpCommand(wsUrl, 'Page.navigate', { url });
+      console.log(`Navigated to ${url}`);
+    } catch (e) {
+      console.error('Navigation failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: wait-for - wait for selector to appear
+if (command === 'wait-for') {
+  const [selector, timeoutArg] = args;
+  if (!wsUrlOrIndex || !selector) {
+    console.error('Usage: chrome-ws wait-for <tab-index-or-ws-url> <selector> [timeout-ms]');
+    process.exit(1);
+  }
+  const timeout = timeoutArg ? parseInt(timeoutArg, 10) : 5000;
+  if (Number.isNaN(timeout) || timeout < 0) {
+    console.error(`Invalid timeout: ${timeoutArg}`);
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      await session.waitForElement(resolveTabArg(wsUrlOrIndex), selector, timeout);
+      console.log(`Element found: ${selector}`);
+      process.exit(0);
+    } catch (e) {
+      console.error('Wait failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: click
+if (command === 'click') {
+  const [selector] = args;
+  if (!wsUrlOrIndex || !selector) {
+    console.error('Usage: chrome-ws click <tab-index-or-ws-url> <selector>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const wsUrl = await resolveWsUrl(wsUrlOrIndex);
+      const js = `document.querySelector(${JSON.stringify(selector)}).click()`;
+      await sendCdpCommand(wsUrl, 'Runtime.evaluate', { expression: js });
+      console.log(`Clicked: ${selector}`);
+    } catch (e) {
+      console.error('Click failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: fill
+if (command === 'fill') {
+  const [selector, value] = args;
+  if (!wsUrlOrIndex || !selector || value === undefined) {
+    console.error('Usage: chrome-ws fill <tab-index-or-ws-url> <selector> <value>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      await session.fill(resolveTabArg(wsUrlOrIndex), selector, value);
+      console.log(`Filled: ${selector}`);
+      process.exit(0);
+    } catch (e) {
+      console.error('Fill failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: select - select dropdown option
+if (command === 'select') {
+  const [selector, value] = args;
+  if (!wsUrlOrIndex || !selector || value === undefined) {
+    console.error('Usage: chrome-ws select <tab-index-or-ws-url> <selector> <value-or-label-or-json-array>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      // Accept JSON array (multi-select) or plain string (value or label).
+      let selectValue = value;
+      if (typeof value === 'string' && value.trim().startsWith('[')) {
+        try {
+          const parsed = JSON.parse(value);
+          if (Array.isArray(parsed) && parsed.every(v => typeof v === 'string')) {
+            selectValue = parsed;
+          }
+        } catch (_e) { /* not JSON, treat as plain string */ }
+      }
+      const result = await session.selectOption(resolveTabArg(wsUrlOrIndex), selector, selectValue);
+      console.log(JSON.stringify(result.matched.map(o => o.value)));
+      process.exit(0);
+    } catch (e) {
+      console.error('Select failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: eval - evaluate JavaScript
+if (command === 'eval') {
+  const expression = args.join(' ');
+  if (!wsUrlOrIndex || !expression) {
+    console.error('Usage: chrome-ws eval <tab-index-or-ws-url> <js-expression>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const value = await session.evaluate(resolveTabArg(wsUrlOrIndex), expression);
+      console.log(JSON.stringify(value, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error('Eval failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: extract - get element text content
+if (command === 'extract') {
+  const [selector] = args;
+  if (!wsUrlOrIndex || !selector) {
+    console.error('Usage: chrome-ws extract <tab-index-or-ws-url> <selector>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const wsUrl = await resolveWsUrl(wsUrlOrIndex);
+      const js = `document.querySelector(${JSON.stringify(selector)})?.textContent`;
+      const result = await sendCdpCommand(wsUrl, 'Runtime.evaluate', {
+        expression: js,
+        returnByValue: true
+      });
+      console.log(result.result.value);
+    } catch (e) {
+      console.error('Extract failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: attr - get element attribute
+if (command === 'attr') {
+  const [selector, attrName] = args;
+  if (!wsUrlOrIndex || !selector || !attrName) {
+    console.error('Usage: chrome-ws attr <tab-index-or-ws-url> <selector> <attribute>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const wsUrl = await resolveWsUrl(wsUrlOrIndex);
+      const js = `document.querySelector(${JSON.stringify(selector)})?.getAttribute(${JSON.stringify(attrName)})`;
+      const result = await sendCdpCommand(wsUrl, 'Runtime.evaluate', {
+        expression: js,
+        returnByValue: true
+      });
+      console.log(result.result.value);
+    } catch (e) {
+      console.error('Attr failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: html - get HTML content
+if (command === 'html') {
+  const [selector] = args;
+  if (!wsUrlOrIndex) {
+    console.error('Usage: chrome-ws html <tab-index-or-ws-url> [selector]');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const wsUrl = await resolveWsUrl(wsUrlOrIndex);
+      const js = selector
+        ? `document.querySelector(${JSON.stringify(selector)})?.innerHTML`
+        : 'document.documentElement.outerHTML';
+      const result = await sendCdpCommand(wsUrl, 'Runtime.evaluate', {
+        expression: js,
+        returnByValue: true
+      });
+      console.log(result.result.value);
+    } catch (e) {
+      console.error('HTML failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: wait-text - wait for text to appear
+if (command === 'wait-text') {
+  // Last positional arg is treated as timeout if it parses as a non-negative
+  // integer; otherwise everything is text. This handles both:
+  //   wait-text 0 "the text" 3000
+  //   wait-text 0 "text without timeout"
+  if (!wsUrlOrIndex || args.length === 0) {
+    console.error('Usage: chrome-ws wait-text <tab-index-or-ws-url> <text> [timeout-ms]');
+    process.exit(1);
+  }
+  let textArgs = args;
+  let timeout = 5000;
+  const last = args[args.length - 1];
+  const parsedLast = parseInt(last, 10);
+  if (args.length >= 2 && Number.isFinite(parsedLast) && parsedLast >= 0 && String(parsedLast) === last.trim()) {
+    timeout = parsedLast;
+    textArgs = args.slice(0, -1);
+  }
+  const text = textArgs.join(' ');
+  if (!text) {
+    console.error('Usage: chrome-ws wait-text <tab-index-or-ws-url> <text> [timeout-ms]');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      await session.waitForText(resolveTabArg(wsUrlOrIndex), text, timeout);
+      console.log(`Text found: ${text}`);
+      process.exit(0);
+    } catch (e) {
+      console.error('Wait failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: screenshot - capture screenshot
+if (command === 'screenshot') {
+  const fullPage = args.includes('--fullpage');
+  const cleanArgs = args.filter(a => a !== '--fullpage');
+  const [filename] = cleanArgs;
+  if (!wsUrlOrIndex || !filename) {
+    console.error('Usage: chrome-ws screenshot <tab-index-or-ws-url> <filename.png> [--fullpage]');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const savedPath = await session.screenshot(resolveTabArg(wsUrlOrIndex), filename, null, fullPage);
+      console.log(`Screenshot saved to ${savedPath}`);
+      process.exit(0);
+    } catch (e) {
+      console.error('Screenshot failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: markdown - save page as markdown
+if (command === 'markdown') {
+  const [filename] = args;
+  if (!wsUrlOrIndex || !filename) {
+    console.error('Usage: chrome-ws markdown <tab-index-or-ws-url> <filename.md>');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const wsUrl = await resolveWsUrl(wsUrlOrIndex);
+
+      // Extract page content intelligently
+      const js = `
+        (() => {
+          const title = document.title;
+          const url = window.location.href;
+
+          // Get main content (try article, main, or body)
+          let content = document.querySelector('article') ||
+                       document.querySelector('main') ||
+                       document.body;
+
+          // Convert to markdown-ish text
+          function nodeToMarkdown(node, level = 0) {
+            let md = '';
+
+            if (node.nodeType === Node.TEXT_NODE) {
+              const text = node.textContent.trim();
+              return text ? text + ' ' : '';
+            }
+
+            if (node.nodeType !== Node.ELEMENT_NODE) return '';
+
+            const tag = node.tagName.toLowerCase();
+
+            // Headers
+            if (/^h[1-6]$/.test(tag)) {
+              const hLevel = parseInt(tag[1]);
+              md += '\\n' + '#'.repeat(hLevel) + ' ' + node.textContent.trim() + '\\n\\n';
+              return md;
+            }
+
+            // Paragraphs
+            if (tag === 'p') {
+              md += node.textContent.trim() + '\\n\\n';
+              return md;
+            }
+
+            // Links
+            if (tag === 'a') {
+              const href = node.getAttribute('href') || '';
+              const text = node.textContent.trim();
+              return \`[\${text}](\${href}) \`;
+            }
+
+            // Lists
+            if (tag === 'li') {
+              return '- ' + node.textContent.trim() + '\\n';
+            }
+
+            // Code
+            if (tag === 'code' || tag === 'pre') {
+              return '\`' + node.textContent.trim() + '\` ';
+            }
+
+            // Recurse for other elements
+            for (const child of node.childNodes) {
+              md += nodeToMarkdown(child, level + 1);
+            }
+
+            if (tag === 'div' || tag === 'section') md += '\\n';
+
+            return md;
+          }
+
+          const markdown = nodeToMarkdown(content);
+
+          return \`# \${title}\\n\\nSource: \${url}\\n\\n\${markdown}\`;
+        })()
+      `;
+
+      const result = await sendCdpCommand(wsUrl, 'Runtime.evaluate', {
+        expression: js,
+        returnByValue: true
+      });
+
+      const fs = require('fs');
+      fs.writeFileSync(filename, result.result.value);
+      console.log(`Markdown saved to ${filename}`);
+    } catch (e) {
+      console.error('Markdown conversion failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Command: har - save network traffic as HAR
+if (command === 'har') {
+  const [filename] = args;
+  if (!wsUrlOrIndex || !filename) {
+    console.error('Usage: chrome-ws har <tab-index-or-ws-url> <filename.har>');
+    console.error('Note: Start recording with "chrome-ws har-start <tab>" first');
+    process.exit(1);
+  }
+  (async () => {
+    try {
+      const wsUrl = await resolveWsUrl(wsUrlOrIndex);
+
+      // Get HAR data
+      const js = `window.__chrome_ws_har__ || []`;
+      const result = await sendCdpCommand(wsUrl, 'Runtime.evaluate', {
+        expression: js,
+        returnByValue: true
+      });
+
+      const har = {
+        log: {
+          version: '1.2',
+          creator: { name: 'chrome-ws', version: '1.0.0' },
+          entries: result.result.value || []
+        }
+      };
+
+      const fs = require('fs');
+      fs.writeFileSync(filename, JSON.stringify(har, null, 2));
+      console.log(`HAR saved to ${filename} (${har.log.entries.length} entries)`);
+    } catch (e) {
+      console.error('HAR export failed:', e.message);
+      process.exit(1);
+    }
+  })();
+  return;
+}
+
+// Past all the named-command dispatches without a return → either it's the
+// raw escape hatch or it's a typo. Separate those cases so users get an
+// actionable error instead of a confusing "Usage: chrome-ws raw ..." banner.
+if (command !== 'raw') {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Run 'chrome-ws --help' for the list of commands.`);
+  process.exit(1);
+}
+
+if (!wsUrlOrIndex || args.length === 0) {
+  console.error('Usage: chrome-ws raw <tab-index-or-ws-url> <json-rpc-payload>');
+  process.exit(1);
+}
+
+const payload = args.join(' ');
+let message;
+try {
+  message = JSON.parse(payload);
+} catch (e) {
+  console.error('Invalid JSON payload:', e.message);
+  process.exit(1);
+}
+
+// For raw command, wsUrlOrIndex must be a full WebSocket URL (not an index)
+// since this is the low-level escape hatch
+if (!wsUrlOrIndex.startsWith('ws://')) {
+  console.error('raw command requires full WebSocket URL, not tab index');
+  console.error('Use: chrome-ws tabs  # to get WebSocket URLs');
+  process.exit(1);
+}
+
+(async () => {
+  const ws = new WebSocketClient(wsUrlOrIndex);
+
+  const timeout = setTimeout(() => {
+    console.error('Timeout after 30s');
+    ws.close();
+    process.exit(1);
+  }, 30000);
+
+  ws.on('message', (data) => {
+    const response = JSON.parse(data);
+    if (response.id === message.id) {
+      clearTimeout(timeout);
+      console.log(JSON.stringify(response, null, 2));
+      ws.close();
+      process.exit(0);
+    }
+  });
+
+  ws.on('error', (error) => {
+    clearTimeout(timeout);
+    console.error('WebSocket error:', error.message);
+    process.exit(1);
+  });
+
+  try {
+    await ws.connect();
+    ws.send(JSON.stringify(message));
+  } catch (err) {
+    clearTimeout(timeout);
+    console.error('Connection failed:', err.message);
+    process.exit(1);
+  }
+})();