@browserbridge/bbx 1.7.8 → 1.9.0

package/packages/agent-client/src/cli.js

@@ -4,6 +4,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
@@ -16,6 +18,8 @@ import {
 import { startBridgeMcpServer } from '../../mcp-server/src/server.js';
 import {
   extractRemoteFlag,
+  extractHarFlags,
+  extractScreenshotFlags,
   extractTabFlag,
   parseCallCommand,
   parseInterceptAddArgs,
@@ -31,12 +35,16 @@ import {
   uninstallBrowserBridge,
 } from './cli-setup-commands.js';
 import { SHORTCUT_COMMANDS } from './command-registry.js';
+import { getAutoUpdatePolicy, parseAutoUpdatePolicy, setAutoUpdatePolicy } from './config.js';
 import { formatMcpConfig, isMcpClientName, MCP_CLIENT_NAMES } from './mcp-config.js';
 import { getDoctorReport, requestBridge, resolveRef } from './runtime.js';
 import { createBridgeClientForDestination } from './remotes.js';
+import { atomicWriteFile } from './atomic-write.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
 /** @typedef {import('./types.js').ScreenshotResult} ScreenshotResult */
+/** @typedef {import('../../protocol/src/types.js').ArtifactDescriptor} ArtifactDescriptor */
+/** @typedef {import('../../protocol/src/types.js').HarExportResult} HarExportResult */
 
 const REQUEST_SOURCE = 'cli';
 const TEST_TIMEOUT_ENV = 'BBX_CLIENT_REQUEST_TIMEOUT_MS';
@@ -63,6 +71,7 @@ const LOCAL_ONLY_COMMANDS = new Set([
   'mcp',
   'proxy',
   'remote',
+  'config',
   'doctor',
   'restart',
 ]);
@@ -166,6 +175,11 @@ if (command === 'remote') {
   process.exit();
 }
 
+if (command === 'config') {
+  await runLocalCommand(() => handleConfigCommand(rest));
+  process.exit();
+}
+
 const clientTimeoutMs = getClientTimeoutOverride();
 applyWindowsTcpTransportDefaults();
 const client = await createCliClient();
@@ -188,6 +202,26 @@ async function runLocalCommand(run) {
   }
 }
 
+/**
+ * @param {string[]} args
+ * @returns {Promise<void>}
+ */
+async function handleConfigCommand(args) {
+  const [action, key, value] = args;
+  if (action === 'get' && key === 'auto-update' && value === undefined) {
+    process.stdout.write(`${await getAutoUpdatePolicy()}\n`);
+    return;
+  }
+  if (action === 'set' && key === 'auto-update' && value !== undefined && args.length === 3) {
+    const policy = parseAutoUpdatePolicy(value);
+    const configPath = await setAutoUpdatePolicy(policy);
+    process.stdout.write(`Browser Bridge auto-update policy set to "${policy}".\n`);
+    process.stdout.write(`Config: ${configPath}\n`);
+    return;
+  }
+  throw new Error('Usage: bbx config <get auto-update|set auto-update off|compatible>');
+}
+
 /**
  * Create the bridge client for this invocation, honoring the --remote flag
  * and BBX_REMOTE env var. Exits with a friendly error when the destination
@@ -197,10 +231,10 @@ async function runLocalCommand(run) {
  */
 async function createCliClient() {
   try {
-    return await createBridgeClientForDestination(
-      remoteDestinationId,
-      clientTimeoutMs ? { defaultTimeoutMs: clientTimeoutMs } : {}
-    );
+    return await createBridgeClientForDestination(remoteDestinationId, {
+      checkProtocolOnConnect: false,
+      ...(clientTimeoutMs ? { defaultTimeoutMs: clientTimeoutMs } : {}),
+    });
   } catch (error) {
     printJson({
       ok: false,
@@ -212,6 +246,7 @@ async function createCliClient() {
 }
 
 async function main() {
+  let relaunchAfterUpdate = false;
   try {
     if (command === 'status') {
       const healthResponse = await requestBridge(
@@ -337,7 +372,7 @@ async function main() {
         tabId,
         source: REQUEST_SOURCE,
       });
-      printCallResponse(response);
+      printCallResponse(response, method);
       return;
     }
 
@@ -356,68 +391,37 @@ async function main() {
         tabId,
         source: REQUEST_SOURCE,
       });
-      printCallResponse(response);
+      printCallResponse(response, method);
       return;
     }
 
     const shortcutCmd = SHORTCUT_COMMANDS[command];
     if (shortcutCmd) {
-      // Allow `bbx <shortcut> --tab <id> ...` to target a specific tab.
-      // Without this, --tab gets eaten as a positional argument and the
-      // request hits whatever tab the bridge route happens to be pointing
-      // at (typically the active tab). For element-resolving shortcuts
-      // the ref must be resolved against the SAME tab the action targets,
-      // so we pass tabId to both resolveRef and the subsequent request.
       const { tabId, rest: shortcutArgs } = extractTabFlag(rest);
-      const selectorInput = shortcutCmd.resolve ? shortcutArgs[0] : null;
-      if (shortcutCmd.resolve && !selectorInput) {
-        throw new Error(`Usage: ${command} <ref|selector>`);
-      }
-
-      // Retry-on-stale: if the action fails with ELEMENT_STALE and the
-      // original input was a selector (not an el_xxx ref), re-resolve the
-      // selector and retry once. This handles the common case where the
-      // agent resolved an element, then the page re-rendered (React
-      // reconciliation, SPA navigation) before the action was dispatched.
-      const canRetry = typeof selectorInput === 'string' && !selectorInput.startsWith('el_');
-      const maxAttempts = canRetry ? 2 : 1;
-      /** @type {import('./runtime.js').BridgeResponse | undefined} */
-      let response;
-      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        let elementRef;
-        if (shortcutCmd.resolve && selectorInput) {
-          elementRef = await resolveRef(client, selectorInput, tabId, REQUEST_SOURCE);
-        }
-        response = await requestBridge(
-          client,
-          shortcutCmd.method,
-          shortcutCmd.build(shortcutArgs, elementRef),
-          { source: REQUEST_SOURCE, tabId }
-        );
-        const isStale = !response.ok && response.error?.code === 'ELEMENT_STALE';
-        if (isStale && attempt < maxAttempts) {
-          process.stderr.write(
-            `bbx: ELEMENT_STALE on "${selectorInput}", re-resolving and retrying...\n`
-          );
-        }
-        if (!isStale || attempt >= maxAttempts) break;
-      }
-      if (response) await printSummary(response, shortcutCmd.printMethod);
+      const response = await requestBridge(
+        client,
+        shortcutCmd.method,
+        shortcutCmd.build(shortcutArgs),
+        { source: REQUEST_SOURCE, tabId }
+      );
+      await printSummary(response, shortcutCmd.printMethod);
       return;
     }
 
     if (command === 'press-key') {
       const [key, refOrSelector] = rest;
       if (!key) throw new Error('Usage: press-key <key> [ref|selector]');
-      const elementRef = refOrSelector
-        ? await resolveRef(client, refOrSelector, null, REQUEST_SOURCE)
+      const target = refOrSelector
+        ? refOrSelector.startsWith('el_')
+          ? { elementRef: refOrSelector }
+          : { selector: refOrSelector }
         : undefined;
       const response = await requestBridge(
         client,
         'input.press_key',
         {
           key,
-          target: elementRef ? { elementRef } : undefined,
+          target,
         },
         { source: REQUEST_SOURCE }
       );
@@ -447,15 +451,21 @@ async function main() {
 
     if (command === 'screenshot') {
       const parsed = extractTabFlag(rest);
-      const [refOrSelector, outputPath] = parsed.rest;
+      const screenshotOptions = extractScreenshotFlags(parsed.rest);
+      const [refOrSelector, outputPath] = screenshotOptions.rest;
       if (!refOrSelector)
-        throw new Error('Usage: screenshot [--tab <tabId>] <ref|selector> [path]');
+        throw new Error(
+          'Usage: screenshot [--tab <tabId>] [--format png|jpeg|webp] [--quality 0-100] <ref|selector> [path]'
+        );
       const elementRef = await resolveRef(client, refOrSelector, parsed.tabId, REQUEST_SOURCE);
       const response = await requestBridge(
         client,
         'screenshot.capture_element',
         {
           elementRef,
+          format: screenshotOptions.format,
+          quality: screenshotOptions.quality,
+          delivery: 'artifact',
         },
         { tabId: parsed.tabId, source: REQUEST_SOURCE }
       );
@@ -464,13 +474,79 @@ async function main() {
         return;
       }
       const screenshotResult = /** @type {ScreenshotResult} */ (response.result);
-      const filePath = outputPath || path.join(os.tmpdir(), `bbx-${Date.now()}.png`);
-      const data = screenshotResult.image.replace(/^data:image\/png;base64,/, '');
-      await fs.promises.writeFile(filePath, Buffer.from(data, 'base64'));
+      const extension = screenshotOptions.format === 'jpeg' ? 'jpg' : screenshotOptions.format;
+      const acceptedExtensions =
+        screenshotOptions.format === 'jpeg'
+          ? new Set(['.jpg', '.jpeg'])
+          : new Set([`.${extension}`]);
+      let filePath = outputPath || path.join(os.tmpdir(), `bbx-${Date.now()}.${extension}`);
+      if (outputPath && !path.extname(outputPath)) filePath = `${outputPath}.${extension}`;
+      if (
+        outputPath &&
+        path.extname(outputPath) &&
+        !acceptedExtensions.has(path.extname(outputPath))
+      ) {
+        throw new Error(`Screenshot path extension must match ${screenshotOptions.format} format.`);
+      }
+      const imageBytes =
+        screenshotResult.delivery === 'artifact'
+          ? await downloadArtifact(client, screenshotResult.artifact, 'screenshot')
+          : decodeScreenshotDataUrl(screenshotResult.image);
+      await atomicWriteFile(filePath, imageBytes);
       printJson({
         ok: true,
         summary: `Screenshot saved to ${filePath}.`,
-        evidence: { savedTo: filePath, rect: screenshotResult.rect },
+        evidence: {
+          savedTo: filePath,
+          rect: screenshotResult.rect,
+          format: screenshotResult.format,
+          complete: screenshotResult.complete,
+          clipped: screenshotResult.clipped,
+        },
+      });
+      return;
+    }
+
+    if (command === 'har') {
+      const parsed = extractTabFlag(rest);
+      const harOptions = extractHarFlags(parsed.rest);
+      const [outputPath = 'browser-bridge.har', ...extra] = harOptions.rest;
+      if (extra.length > 0) {
+        throw new Error(
+          'Usage: har [--tab <tabId>] [--limit 1-200] [--url-pattern <pattern>] [--delivery inline|artifact|auto] [outPath]'
+        );
+      }
+      if (path.extname(outputPath) !== '.har') {
+        throw new Error('HAR output path must use the .har extension.');
+      }
+      const response = await requestBridge(
+        client,
+        'network.export_har',
+        {
+          limit: harOptions.limit,
+          urlPattern: harOptions.urlPattern,
+          delivery: harOptions.delivery,
+        },
+        { tabId: parsed.tabId, source: REQUEST_SOURCE }
+      );
+      if (!response.ok) {
+        await printSummary(response);
+        return;
+      }
+      const result = /** @type {HarExportResult} */ (response.result);
+      let harBytes;
+      if (result.delivery === 'artifact') {
+        harBytes = await downloadArtifact(client, result.artifact, 'har');
+        assertValidHarBytes(harBytes);
+      } else {
+        assertValidHarDocument(result.har);
+        harBytes = Buffer.from(`${JSON.stringify(result.har, null, 2)}\n`, 'utf8');
+      }
+      await atomicWriteFile(outputPath, harBytes);
+      printJson({
+        ok: true,
+        summary: `HAR saved to ${outputPath}.`,
+        evidence: { savedTo: outputPath, delivery: result.delivery },
       });
       return;
     }
@@ -565,25 +641,151 @@ async function main() {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     const raw = getErrorCode(error);
-    let code = 'ERROR';
-    if (raw === 'ENOENT' || raw === 'ECONNREFUSED' || raw === 'EINVAL') {
-      code = 'DAEMON_OFFLINE';
-    } else if (raw === 'BRIDGE_TIMEOUT') {
-      code = 'BRIDGE_TIMEOUT';
-    } else if (/socket closed/i.test(message)) {
-      code = 'CONNECTION_LOST';
-    } else if (raw) {
-      code = String(raw);
+    if (raw === 'BBX_NPM_UPDATED') {
+      relaunchAfterUpdate = true;
+    } else {
+      let code = 'ERROR';
+      if (raw === 'ENOENT' || raw === 'ECONNREFUSED' || raw === 'EINVAL') {
+        code = 'DAEMON_OFFLINE';
+      } else if (raw === 'BRIDGE_TIMEOUT') {
+        code = 'BRIDGE_TIMEOUT';
+      } else if (/socket closed/i.test(message)) {
+        code = 'CONNECTION_LOST';
+      } else if (raw) {
+        code = String(raw);
+      }
+      printJson({
+        ok: false,
+        summary: `${code}: ${message}`,
+        evidence: null,
+      });
+      process.exitCode = 1;
     }
-    printJson({
-      ok: false,
-      summary: `${code}: ${message}`,
-      evidence: null,
-    });
-    process.exitCode = 1;
   } finally {
     await client.close();
   }
+  if (relaunchAfterUpdate) {
+    relaunchCli();
+  }
+}
+
+/** @param {string} value */
+function decodeScreenshotDataUrl(value) {
+  const match = /^data:image\/(?:png|jpeg|webp);base64,([A-Za-z0-9+/]*={0,2})$/u.exec(value);
+  if (!match) throw new Error('Screenshot response contains invalid base64 image data.');
+  const bytes = Buffer.from(match[1], 'base64');
+  if (bytes.toString('base64') !== match[1]) {
+    throw new Error('Screenshot response contains non-canonical base64 image data.');
+  }
+  return bytes;
+}
+
+/**
+ * @param {import('./client.js').BridgeClient} client
+ * @param {ArtifactDescriptor} artifact
+ * @param {'screenshot' | 'har'} [expectedKind]
+ */
+async function downloadArtifact(client, artifact, expectedKind) {
+  const chunks = [];
+  let offset = 0;
+  try {
+    if (expectedKind && artifact.kind !== expectedKind) {
+      throw new Error(`Artifact kind does not match the expected ${expectedKind} result.`);
+    }
+    if (expectedKind === 'har' && artifact.mimeType !== 'application/json') {
+      throw new Error('HAR artifact MIME type is invalid.');
+    }
+    while (offset < artifact.byteLength) {
+      const response = await requestBridge(
+        client,
+        'artifact.read',
+        { artifactId: artifact.artifactId, offset },
+        { source: REQUEST_SOURCE }
+      );
+      if (!response.ok) throw new Error(response.error.message);
+      const result = /** @type {Record<string, unknown>} */ (response.result);
+      if (result.artifactId !== artifact.artifactId || result.offset !== offset) {
+        throw new Error('Artifact chunk metadata is inconsistent.');
+      }
+      const data = String(result.data ?? '');
+      const bytes = Buffer.from(data, 'base64');
+      if (bytes.toString('base64') !== data || bytes.length !== result.byteLength) {
+        throw new Error('Artifact chunk contains invalid base64 data.');
+      }
+      chunks.push(bytes);
+      if (result.nextOffset === null) break;
+      if (typeof result.nextOffset !== 'number' || result.nextOffset <= offset) {
+        throw new Error('Artifact chunk did not advance the read offset.');
+      }
+      offset = result.nextOffset;
+    }
+    const output = Buffer.concat(chunks);
+    const sha256 = createHash('sha256').update(output).digest('hex');
+    if (output.length !== artifact.byteLength || sha256 !== artifact.sha256) {
+      throw new Error('Artifact length or checksum does not match the capture metadata.');
+    }
+    return output;
+  } finally {
+    await requestBridge(
+      client,
+      'artifact.delete',
+      { artifactId: artifact.artifactId },
+      { source: REQUEST_SOURCE }
+    ).catch(() => {});
+  }
+}
+
+/** @param {Buffer} bytes */
+function assertValidHarBytes(bytes) {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text, 'utf8').equals(bytes)) {
+    throw new Error('HAR artifact is not valid UTF-8 JSON.');
+  }
+  let document;
+  try {
+    document = JSON.parse(text);
+  } catch {
+    throw new Error('HAR artifact is not valid JSON.');
+  }
+  assertValidHarDocument(document);
+}
+
+/** @param {unknown} document */
+function assertValidHarDocument(document) {
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+    throw new Error('HAR response does not contain an inline HAR object.');
+  }
+  const log = Reflect.get(document, 'log');
+  if (
+    !log ||
+    typeof log !== 'object' ||
+    Array.isArray(log) ||
+    Reflect.get(log, 'version') !== '1.2' ||
+    !Array.isArray(Reflect.get(log, 'entries'))
+  ) {
+    throw new Error('HAR response does not contain a valid HAR 1.2 document.');
+  }
+}
+
+/**
+ * Replace this invocation with a fresh Node process after npm has replaced the
+ * package on disk. Child stdio is inherited so command output remains stable.
+ *
+ * @returns {void}
+ */
+function relaunchCli() {
+  const result = spawnSync(
+    process.execPath,
+    [fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+    {
+      stdio: 'inherit',
+      env: process.env,
+    }
+  );
+  if (result.error) {
+    throw result.error;
+  }
+  process.exitCode = result.status ?? 1;
 }
 
 /**