@browserbridge/bbx 1.7.4 → 1.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -56,7 +56,7 @@
     "test": "c8 node --test",
     "coverage": "c8 report --reporter=text --reporter=text-summary",
     "coverage:review": "c8 report --reporter=json-summary && node scripts/review-coverage.mjs",
-    "coverage:check": "c8 check-coverage --lines 80 --branches 75",
+    "coverage:check": "c8 check-coverage --lines 92 --branches 83",
     "typecheck": "tsc --noEmit",
     "postinstall": "node packages/native-host/bin/postinstall.js",
     "package:extension": "node scripts/package-extension.mjs",
@@ -75,13 +75,13 @@
   "devDependencies": {
     "@types/chrome": "^0.2.2",
     "@types/node": "^26.1.1",
-    "c8": "^11.0.0",
+    "c8": "^12.0.0",
     "linkedom": "^0.18.13",
-    "oxfmt": "^0.58.0",
-    "oxlint": "^1.73.0",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
     "typescript": "^7.0.2"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   }
 }

package/packages/agent-client/src/atomic-write.js

@@ -0,0 +1,99 @@
+// @ts-check
+
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Replace a file through a sibling temporary file so readers never observe a
+ * partial write. Existing permissions are preserved unless an explicit mode is
+ * requested.
+ *
+ * @param {string} targetPath
+ * @param {string | NodeJS.ArrayBufferView} data
+ * @param {{ encoding?: BufferEncoding, mode?: number, preserveMode?: boolean }} [options={ }]
+ * @returns {Promise<void>}
+ */
+export async function atomicWriteFile(targetPath, data, options = {}) {
+  const directory = path.dirname(targetPath);
+  const temporaryPath = path.join(
+    directory,
+    `.${path.basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`
+  );
+  await fs.promises.mkdir(directory, { recursive: true });
+
+  let existingMode;
+  if (options.preserveMode !== false && options.mode === undefined) {
+    try {
+      existingMode = (await fs.promises.stat(targetPath)).mode & 0o777;
+    } catch (error) {
+      if (!isMissingFileError(error)) {
+        throw error;
+      }
+    }
+  }
+
+  const mode = options.mode ?? existingMode;
+  try {
+    await fs.promises.writeFile(temporaryPath, data, {
+      ...(options.encoding ? { encoding: options.encoding } : {}),
+      ...(mode === undefined ? {} : { mode }),
+      flag: 'wx',
+    });
+    if (process.platform !== 'win32' && mode !== undefined) {
+      await fs.promises.chmod(temporaryPath, mode);
+    }
+    try {
+      await fs.promises.rename(temporaryPath, targetPath);
+    } catch (error) {
+      if (process.platform !== 'win32' || !isReplaceError(error)) {
+        throw error;
+      }
+      try {
+        await fs.promises.stat(targetPath);
+      } catch {
+        throw error;
+      }
+
+      const backupPath = `${temporaryPath}.backup`;
+      await fs.promises.rename(targetPath, backupPath);
+      try {
+        await fs.promises.rename(temporaryPath, targetPath);
+      } catch (replaceError) {
+        await fs.promises.rename(backupPath, targetPath).catch(() => {});
+        throw replaceError;
+      }
+      await fs.promises.rm(backupPath, { force: true }).catch(() => {});
+    }
+    if (process.platform !== 'win32' && options.mode !== undefined) {
+      await fs.promises.chmod(targetPath, options.mode);
+    }
+  } catch (error) {
+    await fs.promises.rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * Windows does not replace an existing file with rename().
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isReplaceError(error) {
+  const code =
+    error && typeof error === 'object' ? /** @type {{ code?: unknown }} */ (error).code : null;
+  return code === 'EEXIST' || code === 'EPERM' || code === 'EACCES';
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isMissingFileError(error) {
+  return Boolean(
+    error &&
+    typeof error === 'object' &&
+    /** @type {{ code?: unknown }} */ (error).code === 'ENOENT'
+  );
+}

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

@@ -0,0 +1,152 @@
+// @ts-check
+
+import { METHODS } from '../../protocol/src/index.js';
+import { methodNeedsTab, parseIntArg, parseJsonObject } from './cli-helpers.js';
+
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+
+/**
+ * Read all of stdin as UTF-8 text. Resolves once stdin closes.
+ *
+ * @returns {Promise<string>}
+ */
+export function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = /** @type {Buffer[]} */ ([]);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8').trim()));
+    process.stdin.on('error', reject);
+    if (process.stdin.isTTY) {
+      resolve('');
+    }
+  });
+}
+
+/**
+ * Extract the global --remote flag from anywhere in the argument list.
+ * Exits with a usage error when the flag is present without a value.
+ *
+ * @param {string[]} args
+ * @returns {{ remoteId: string | null, explicit: boolean, rest: string[] }}
+ */
+export function extractRemoteFlag(args) {
+  const rest = [...args];
+  const index = rest.indexOf('--remote');
+  if (index === -1) {
+    return { remoteId: null, explicit: false, rest };
+  }
+  const remoteId = rest[index + 1];
+  if (!remoteId || remoteId.startsWith('--')) {
+    process.stderr.write('--remote requires a destination name (see `bbx remote list`).\n');
+    process.exit(1);
+  }
+  rest.splice(index, 2);
+  return { remoteId, explicit: true, rest };
+}
+
+/**
+ * @param {string[]} args
+ * @returns {{ tabId: number | null, rest: string[] }}
+ */
+export function extractTabFlag(args) {
+  const rest = [...args];
+  let tabId = null;
+  const tabIndex = rest.indexOf('--tab');
+  if (tabIndex !== -1) {
+    tabId = parseIntArg(rest[tabIndex + 1], 'tabId');
+    rest.splice(tabIndex, 2);
+  }
+  return { tabId, rest };
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<{ tabId: number | null, method: BridgeMethod, params: Record<string, unknown> }>}
+ */
+export async function parseCallCommand(args) {
+  const parsed = extractTabFlag(args);
+  const [first, second, ...extra] = parsed.rest;
+  if (!first) {
+    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+  }
+  if (extra.length > 0) {
+    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+  }
+
+  if (first.includes('.')) {
+    const method = /** @type {BridgeMethod} */ (first);
+    if (!METHODS.includes(method)) {
+      throw new Error(`Unknown method "${first}". Run bbx skill to see available methods.`);
+    }
+    let rawParams = second;
+    // Support piped stdin: `echo '{"key":"val"}' | bbx call method -`
+    if (rawParams === '-') {
+      rawParams = await readStdin();
+    }
+    return {
+      method,
+      tabId: methodNeedsTab(method) ? parsed.tabId : null,
+      params: parseJsonObject(rawParams),
+    };
+  }
+
+  throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+}
+
+/**
+ * @param {string[]} args
+ * @returns {{ pattern: string, isBlock: boolean, statusCode: number, body: string | undefined }}
+ */
+export function parseInterceptAddArgs(args) {
+  const [pattern, ...optionArgs] = args;
+  if (!pattern || pattern.startsWith('--')) {
+    throw new Error(
+      'Usage: intercept add <urlPattern> [--respond <body>] [--status <code>] [--block]'
+    );
+  }
+
+  let isBlock = false;
+  let statusCode = 200;
+  let hasStatus = false;
+  let body;
+  for (let index = 0; index < optionArgs.length; index += 1) {
+    const option = optionArgs[index];
+    if (option === '--block') {
+      if (isBlock) {
+        throw new Error('The --block option may only be specified once.');
+      }
+      isBlock = true;
+      continue;
+    }
+    if (option === '--respond') {
+      const value = optionArgs[++index];
+      if (body !== undefined) {
+        throw new Error('The --respond option may only be specified once.');
+      }
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error('--respond requires a body value.');
+      }
+      body = value;
+      continue;
+    }
+    if (option === '--status') {
+      if (hasStatus) {
+        throw new Error('The --status option may only be specified once.');
+      }
+      const value = optionArgs[++index];
+      statusCode = parseIntArg(value, 'status');
+      if (statusCode < 100 || statusCode > 599) {
+        throw new Error('status must be an integer between 100 and 599.');
+      }
+      hasStatus = true;
+      continue;
+    }
+    throw new Error(`Unknown or extra intercept add option "${option}".`);
+  }
+
+  if (isBlock && body !== undefined) {
+    throw new Error('Use either --block or --respond, not both.');
+  }
+  return { pattern, isBlock, statusCode, body };
+}

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

@@ -0,0 +1,140 @@
+// @ts-check
+
+import {
+  getProtocolVersion,
+  METHODS,
+  summarizeBatchErrorItem,
+  summarizeBatchResponseItem,
+} from '../../protocol/src/index.js';
+import { methodNeedsTab } from './cli-helpers.js';
+import { requestBridge } from './runtime.js';
+
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').BridgeRequestSource} BridgeRequestSource */
+
+/**
+ * @typedef {{
+ *   method: string,
+ *   tabId: null,
+ *   ok: false,
+ *   summary: string,
+ *   evidence: null,
+ *   durationMs: 0,
+ *   approxTokens: 0,
+ *   meta: { protocol_version: string },
+ *   error: { code: 'INVALID_REQUEST', message: string },
+ *   response: null,
+ * }} InvalidBatchItem
+ */
+
+/**
+ * @typedef {ReturnType<typeof summarizeBatchResponseItem>
+ *   | ReturnType<typeof summarizeBatchErrorItem>
+ *   | InvalidBatchItem} BatchResultItem
+ */
+
+/**
+ * Build the standard invalid-request batch item.
+ *
+ * @param {string} method
+ * @param {string} message
+ * @returns {InvalidBatchItem}
+ */
+function invalidBatchItem(method, message) {
+  return {
+    method,
+    tabId: null,
+    ok: false,
+    summary: `INVALID_REQUEST: ${message}`,
+    evidence: null,
+    durationMs: 0,
+    approxTokens: 0,
+    meta: { protocol_version: getProtocolVersion() },
+    error: {
+      code: 'INVALID_REQUEST',
+      message,
+    },
+    response: null,
+  };
+}
+
+/**
+ * Parse and execute `bbx batch '[...]'`: validate each call, run them in
+ * parallel against the bridge, and return per-call summary items.
+ *
+ * @param {import('./client.js').BridgeClient} client
+ * @param {string | undefined} input - Raw JSON array argument
+ * @param {BridgeRequestSource} source - Request source tag (e.g. 'cli')
+ * @returns {Promise<BatchResultItem[]>}
+ */
+export async function runBatchCalls(client, input, source) {
+  if (!input) {
+    throw new Error('Usage: batch \'[{"method":"...","params":{...}}, ...]\'');
+  }
+  let calls;
+  try {
+    calls = JSON.parse(input);
+  } catch {
+    throw new Error('Invalid JSON syntax. Expected a JSON array of bridge calls.');
+  }
+  if (!Array.isArray(calls)) {
+    throw new Error('Batch input must be a JSON array.');
+  }
+  if (!client.connected) {
+    await client.connect();
+  }
+  return Promise.all(
+    calls.map(async (call) => {
+      if (!call || typeof call !== 'object' || Array.isArray(call)) {
+        return invalidBatchItem('', 'Each batch call needs a method.');
+      }
+      const batchCall = /** @type {Record<string, unknown>} */ (call);
+      if (typeof batchCall.method !== 'string') {
+        return invalidBatchItem('', 'Each batch call needs a method.');
+      }
+      if (!METHODS.includes(/** @type {BridgeMethod} */ (batchCall.method))) {
+        return invalidBatchItem(batchCall.method, `Unknown bridge method "${batchCall.method}".`);
+      }
+      const method = /** @type {BridgeMethod} */ (batchCall.method);
+      if (
+        batchCall.params !== undefined &&
+        (!batchCall.params ||
+          typeof batchCall.params !== 'object' ||
+          Array.isArray(batchCall.params))
+      ) {
+        return invalidBatchItem(method, 'Batch call params must be a JSON object.');
+      }
+      const params =
+        batchCall.params === undefined
+          ? {}
+          : /** @type {Record<string, unknown>} */ (batchCall.params);
+      const tabId =
+        methodNeedsTab(method) &&
+        typeof batchCall.tabId === 'number' &&
+        Number.isInteger(batchCall.tabId) &&
+        batchCall.tabId > 0
+          ? batchCall.tabId
+          : null;
+      const startTime = Date.now();
+      try {
+        const response = await requestBridge(client, method, params, {
+          tabId,
+          source,
+        });
+        return summarizeBatchResponseItem({
+          method,
+          tabId,
+          response,
+          durationMs: Date.now() - startTime,
+        });
+      } catch (err) {
+        return summarizeBatchErrorItem({
+          method,
+          tabId,
+          error: err,
+          durationMs: Date.now() - startTime,
+        });
+      }
+    })
+  );
+}

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

@@ -96,7 +96,7 @@ export function parseJsonObject(value) {
 
 /**
  * Parse a CLI argument as a positive integer, throwing a user-friendly error
- * if the value is missing or not a finite number.
+ * if the value is missing or not a positive integer.
  *
  * @param {string | undefined} value
  * @param {string} argName - The argument name shown in the error message
@@ -104,12 +104,29 @@ export function parseJsonObject(value) {
  */
 export function parseIntArg(value, argName) {
   const n = Number(value);
-  if (!value || !Number.isFinite(n)) {
-    throw new Error(`${argName} must be a number (got ${JSON.stringify(value)}).`);
+  if (!value || !Number.isInteger(n) || n <= 0) {
+    throw new Error(`${argName} must be a positive integer (got ${JSON.stringify(value)}).`);
   }
   return n;
 }
 
+/**
+ * Parse a CLI argument as a finite number. This is intentionally separate from
+ * positive integer parsing because viewport coordinates may be fractional or
+ * negative.
+ *
+ * @param {string | undefined} value
+ * @param {string} argName
+ * @returns {number}
+ */
+export function parseNumberArg(value, argName) {
+  const number = Number(value);
+  if (value === undefined || value === '' || !Number.isFinite(number)) {
+    throw new Error(`${argName} must be a number (got ${JSON.stringify(value)}).`);
+  }
+  return number;
+}
+
 /**
  * @param {string} method
  * @returns {boolean}

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

@@ -0,0 +1,57 @@
+// @ts-check
+
+import { sanitizeOutput } from './cli-helpers.js';
+import { CLI_HELP_SECTIONS } from './command-registry.js';
+import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
+
+/**
+ * @param {unknown} value
+ * @returns {void}
+ */
+export function printJson(value) {
+  process.stdout.write(
+    `${JSON.stringify(sanitizeOutput(value), null, process.stdout.isTTY ? 2 : undefined)}\n`
+  );
+}
+
+/**
+ * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @param {string} [method] - Optional method name for disambiguation
+ * @returns {Promise<void>}
+ */
+export async function printSummary(response, method) {
+  if (!response.ok) {
+    process.exitCode = 1;
+  }
+  printJson(annotateBridgeSummary(summarizeBridgeResponse(response, method), response));
+}
+
+/**
+ * @param {import('../../protocol/src/types.js').BridgeResponse} response
+ * @returns {void}
+ */
+export function printCallResponse(response) {
+  if (response.ok) {
+    printJson(response.result);
+    return;
+  }
+
+  process.exitCode = 1;
+  const errorText = `${response.error.code}: ${response.error.message}`;
+  process.stderr.write(
+    `${process.stderr.isTTY ? `\u001b[31m${sanitizeOutput(errorText)}\u001b[0m` : sanitizeOutput(errorText)}\n`
+  );
+  printJson(response);
+}
+
+/**
+ * @returns {void}
+ */
+export function printUsage() {
+  const blocks = ['Usage: bbx [--remote <name>] <command> [args]'];
+  for (const section of CLI_HELP_SECTIONS) {
+    blocks.push('', `${section.title}:`);
+    blocks.push(...section.lines.map((line) => `  ${line}`));
+  }
+  process.stdout.write(`${blocks.join('\n')}\n`);
+}