@browserbridge/bbx 1.0.1 → 1.2.0

package/packages/mcp-server/src/server.js

@@ -37,6 +37,7 @@ import {
   DEFAULT_WAIT_TIMEOUT_MS,
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
+import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
@@ -369,7 +370,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Input',
       description:
-        'Simulate user input: click, focus, type, press keys, set checked, select options, hover, drag, or scroll into view. Reuse elementRef from prior queries.',
+        'Simulate user input: click, focus, type, press keys, CDP key events, set checked, select options, hover, drag, or scroll into view. Reuse elementRef from prior queries.',
       inputSchema: {
         action: z
           .enum([
@@ -377,6 +378,7 @@ export function createBridgeMcpServer() {
             'focus',
             'type',
             'press_key',
+            'cdp_press_key',
             'set_checked',
             'select_option',
             'hover',
@@ -399,10 +401,17 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Mouse button for click (default: left)'),
         clickCount: z.number().optional().describe('Click count (1=single, 2=double)'),
-        text: z.string().optional().describe('Text to type (for type action)'),
+        text: z.string().max(100000).optional().describe('Text to type (for type action)'),
         clear: z.boolean().optional().describe('Clear field before typing (default: false)'),
         submit: z.boolean().optional().describe('Press Enter after typing (default: false)'),
-        key: z.string().optional().describe('Key to press (e.g., "Enter", "Tab", "ArrowDown")'),
+        key: z
+          .string()
+          .optional()
+          .describe('Key to press (e.g., "Escape", "Enter", "Tab", "ArrowDown")'),
+        code: z
+          .string()
+          .optional()
+          .describe('Optional physical key code for cdp_press_key (e.g., "Escape", "KeyA")'),
         modifiers: z
           .array(z.enum(['Alt', 'Control', 'Meta', 'Shift']))
           .optional()
@@ -652,6 +661,7 @@ export function createBridgeMcpServer() {
  * @returns {Promise<void>}
  */
 export async function startBridgeMcpServer() {
+  applyWindowsTcpTransportDefaults();
   const server = createBridgeMcpServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/packages/native-host/bin/bridge-daemon.js

@@ -1,12 +1,41 @@
 #!/usr/bin/env node
 // @ts-check
 import { BridgeDaemon } from '../src/daemon.js';
-import { getSocketPath } from '../src/config.js';
+import {
+  applyWindowsTcpTransportDefaults,
+  formatBridgeTransport,
+  getBridgeTransport,
+} from '../src/config.js';
+import { DaemonLogger } from '../src/daemon-logger.js';
+import { clearDaemonPidFile, writeDaemonPidFile } from '../src/daemon-process.js';
 
-const daemon = new BridgeDaemon({ socketPath: getSocketPath() });
-await daemon.start();
+applyWindowsTcpTransportDefaults();
+const transport = getBridgeTransport();
+const daemon = new BridgeDaemon({ transport, logger: new DaemonLogger() });
 
-process.stdout.write(`Browser Bridge daemon listening on ${getSocketPath()}\n`);
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isExistingDaemonError(error) {
+  return (
+    error instanceof Error && error.message.startsWith('Another daemon is already running on ')
+  );
+}
+
+try {
+  await daemon.start();
+  await writeDaemonPidFile(process.pid);
+} catch (error) {
+  if (isExistingDaemonError(error)) {
+    process.stdout.write(`${error.message}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+}
+
+process.stdout.write(`Browser Bridge daemon listening on ${formatBridgeTransport(transport)}\n`);
 
 let shuttingDown = false;
 
@@ -21,6 +50,7 @@ async function shutdown() {
   shuttingDown = true;
   try {
     await daemon.stop();
+    await clearDaemonPidFile({ pid: process.pid });
     process.exit(0);
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);

package/packages/native-host/bin/install-manifest.js

@@ -3,22 +3,32 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { installNativeManifest, parseExtensionId } from '../src/install-manifest.js';
+import { restartBridgeDaemonIfRunning } from '../src/daemon-process.js';
+import {
+  installNativeManifest,
+  parseExtensionId,
+  uninstallNativeManifest,
+} from '../src/install-manifest.js';
 import { SUPPORTED_BROWSERS } from '../src/config.js';
 
 /** @typedef {import('../src/config.js').SupportedBrowser} SupportedBrowser */
 
+const USAGE = 'Usage: bbx-install [<extension-id>] [--browser <browser>] [--all] [--uninstall]\n';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, '../../..');
 
 const args = process.argv.slice(2);
 let extensionIdArg = /** @type {string | undefined} */ (undefined);
 let installAll = false;
+let uninstall = false;
 const browsers = /** @type {SupportedBrowser[]} */ ([]);
 
 for (let i = 0; i < args.length; i++) {
   if (args[i] === '--all') {
     installAll = true;
+  } else if (args[i] === '--uninstall') {
+    uninstall = true;
   } else if (args[i] === '--browser' && args[i + 1]) {
     const candidate = args[i + 1];
     if (!SUPPORTED_BROWSERS.includes(/** @type {SupportedBrowser} */ (candidate))) {
@@ -34,6 +44,11 @@ for (let i = 0; i < args.length; i++) {
   }
 }
 
+if (uninstall && extensionIdArg) {
+  process.stderr.write(USAGE);
+  process.exit(1);
+}
+
 if (extensionIdArg && !parseExtensionId(extensionIdArg)) {
   process.stderr.write(
     `Invalid extension ID: ${extensionIdArg}\n` +
@@ -48,10 +63,25 @@ const targets = installAll
     ? browsers
     : [/** @type {SupportedBrowser} */ ('chrome')];
 
-for (const target of targets) {
+for (const [index, target] of targets.entries()) {
+  if (uninstall) {
+    await uninstallNativeManifest({
+      browser: target,
+      removeBridgeDir: index === targets.length - 1,
+    });
+    continue;
+  }
+
   await installNativeManifest({
     repoRoot,
     extensionIdArg,
     browser: target,
   });
 }
+
+if (!uninstall) {
+  const restartResult = await restartBridgeDaemonIfRunning();
+  if (restartResult) {
+    process.stdout.write('Restarted Browser Bridge daemon to use the updated install.\n');
+  }
+}

package/packages/native-host/bin/postinstall.js

@@ -10,6 +10,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { restartBridgeDaemonIfRunning } from '../src/daemon-process.js';
 import { installNativeManifest } from '../src/install-manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -24,4 +25,19 @@ try {
   process.stderr.write(
     `Browser Bridge: native host auto-install skipped (${message}).\nRun \`bbx install\` manually if needed.\n`
   );
+  process.exit(0);
+}
+
+try {
+  const restartResult = await restartBridgeDaemonIfRunning();
+  if (restartResult) {
+    process.stdout.write(
+      'Browser Bridge: restarted the local daemon to use the updated install.\n'
+    );
+  }
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(
+    `Browser Bridge: native host installed, but daemon restart failed (${message}).\nRun \`bbx restart\` if needed.\n`
+  );
 }

package/packages/native-host/src/config.js

@@ -5,6 +5,10 @@ import path from 'node:path';
 
 export const APP_NAME = 'com.browserbridge.browser_bridge';
 export const BRIDGE_HOME_ENV = 'BROWSER_BRIDGE_HOME';
+export const BRIDGE_TCP_PORT_ENV = 'BBX_TCP_PORT';
+export const DEFAULT_WINDOWS_TCP_PORT = 9223;
+
+/** @typedef {{ type: 'socket', socketPath: string, label: string } | { type: 'tcp', host: string, port: number, label: string }} BridgeTransport */
 
 /**
  * The official Chrome Web Store extension ID used when callers do not provide
@@ -15,10 +19,11 @@ export const BRIDGE_HOME_ENV = 'BROWSER_BRIDGE_HOME';
 export const PUBLISHED_EXTENSION_ID = 'jjjkmmcdkpcgamlopogicbnnhdgebhie';
 
 /**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
  * @returns {string}
  */
-export function getBridgeDir() {
-  const override = process.env[BRIDGE_HOME_ENV];
+export function getBridgeDir(env = process.env) {
+  const override = env[BRIDGE_HOME_ENV];
   if (override) {
     return override;
   }
@@ -31,19 +36,139 @@ export function getBridgeDir() {
   }
 
   if (platform === 'win32') {
-    const localAppData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    const localAppData = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
     return path.join(localAppData, 'Browser Bridge');
   }
 
-  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+  const xdgDataHome = env.XDG_DATA_HOME || path.join(home, '.local', 'share');
   return path.join(xdgDataHome, 'browser-bridge');
 }
 
 /**
+ * Resolve the IPC endpoint the daemon listens on and the CLI / native host
+ * connect to. On Windows we use a Named Pipe by default because Node's AF_UNIX
+ * support fails with EACCES on listen() under recent Node + Windows 11
+ * combinations, while Named Pipes are the historical and reliable Windows IPC
+ * mechanism. An explicit bridge-home override keeps the legacy socket path so
+ * callers can opt into custom test or compatibility setups.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getSocketPath(env = process.env) {
+  if (os.platform() === 'win32' && !env[BRIDGE_HOME_ENV]) {
+    return `\\\\.\\pipe\\${APP_NAME}`;
+  }
+  return path.join(getBridgeDir(env), 'bridge.sock');
+}
+
+/**
+ * @param {string} socketPath
+ * @returns {BridgeTransport}
+ */
+export function createSocketBridgeTransport(socketPath) {
+  return {
+    type: 'socket',
+    socketPath,
+    label: socketPath,
+  };
+}
+
+/**
+ * @param {number} port
+ * @param {string} [host='127.0.0.1']
+ * @returns {BridgeTransport}
+ */
+export function createTcpBridgeTransport(port, host = '127.0.0.1') {
+  return {
+    type: 'tcp',
+    host,
+    port,
+    label: `${host}:${port}`,
+  };
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {number | null}
+ */
+export function getBridgeTcpPort(env = process.env) {
+  const raw = env[BRIDGE_TCP_PORT_ENV];
+  if (raw == null || raw === '') {
+    return null;
+  }
+
+  const port = Number.parseInt(raw, 10);
+  if (!Number.isInteger(port) || String(port) !== String(raw).trim() || port < 1 || port > 65535) {
+    throw new Error(
+      `${BRIDGE_TCP_PORT_ENV} must be an integer between 1 and 65535 (got ${JSON.stringify(raw)}).`
+    );
+  }
+
+  return port;
+}
+
+/**
+ * Align Windows CLI/daemon entrypoints with the installed native-host launcher,
+ * which uses TCP by default. Preserve explicit overrides and custom bridge-home
+ * test setups that rely on the socket transport.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {boolean}
+ */
+export function applyWindowsTcpTransportDefaults(env = process.env) {
+  if (os.platform() !== 'win32') {
+    return false;
+  }
+  if (env[BRIDGE_TCP_PORT_ENV] != null && env[BRIDGE_TCP_PORT_ENV] !== '') {
+    return false;
+  }
+  if (env[BRIDGE_HOME_ENV]) {
+    return false;
+  }
+
+  env[BRIDGE_TCP_PORT_ENV] = String(DEFAULT_WINDOWS_TCP_PORT);
+  return true;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {BridgeTransport}
+ */
+export function getBridgeTransport(env = process.env) {
+  const tcpPort = getBridgeTcpPort(env);
+  if (tcpPort !== null) {
+    return createTcpBridgeTransport(tcpPort);
+  }
+
+  return createSocketBridgeTransport(getSocketPath(env));
+}
+
+/**
+ * @param {BridgeTransport} [transport=getBridgeTransport()]
+ * @returns {import('node:net').ListenOptions | string}
+ */
+export function getBridgeListenTarget(transport = getBridgeTransport()) {
+  if (transport.type === 'tcp') {
+    return { host: transport.host, port: transport.port };
+  }
+  return transport.socketPath;
+}
+
+/**
+ * @param {BridgeTransport} [transport=getBridgeTransport()]
+ * @returns {string}
+ */
+export function formatBridgeTransport(transport = getBridgeTransport()) {
+  return transport.label;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
  * @returns {string}
  */
-export function getSocketPath() {
-  return path.join(getBridgeDir(), 'bridge.sock');
+export function getDaemonPidPath(env = process.env) {
+  return path.join(getBridgeDir(env), 'daemon.pid');
 }
 
 /**

package/packages/native-host/src/daemon-logger.js

@@ -0,0 +1,157 @@
+// @ts-check
+
+/** @typedef {{ write: (chunk: string) => void }} LogStream */
+
+/**
+ * @enum {number}
+ * @private
+ */
+const LOG_LEVELS = /** @type {const} */ ({
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+});
+
+/** @typedef {keyof typeof LOG_LEVELS} LogLevel */
+
+/**
+ * @typedef {{
+ *   debug(message: string, extra?: Record<string, unknown>): void;
+ *   info(message: string, extra?: Record<string, unknown>): void;
+ *   warn(message: string, extra?: Record<string, unknown>): void;
+ *   error(message: string, extra?: Record<string, unknown>): void;
+ * }} DaemonLoggerLike
+ */
+
+/**
+ * Structured JSON logger for the daemon. Each call emits a single NDJSON line
+ * with a timestamp, level, message, and optional structured fields.
+ */
+export class DaemonLogger {
+  /** @type {LogStream} */
+  #stream;
+  /** @type {LogLevel} */
+  #minLevel;
+  /** @type {Record<string, unknown>} */
+  #defaults;
+
+  /**
+   * @param {{ stream?: LogStream, minLevel?: LogLevel, defaults?: Record<string, unknown> }} [options]
+   */
+  constructor({ stream, minLevel = 'info', defaults = {} } = {}) {
+    this.#stream = stream ?? /** @type {LogStream} */ (process.stderr);
+    this.#minLevel = minLevel;
+    this.#defaults = defaults;
+  }
+
+  /**
+   * @param {LogLevel} level
+   * @param {string} message
+   * @param {Record<string, unknown>} [extra]
+   * @returns {void}
+   */
+  #write(level, message, extra) {
+    if (LOG_LEVELS[level] < LOG_LEVELS[this.#minLevel]) {
+      return;
+    }
+    const entry = {
+      ...this.#defaults,
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      ...extra,
+    };
+    this.#stream.write(`${JSON.stringify(entry)}\n`);
+  }
+
+  /**
+   * @param {string} message
+   * @param {Record<string, unknown>} [extra]
+   * @returns {void}
+   */
+  debug(message, extra) {
+    this.#write('debug', message, extra);
+  }
+
+  /**
+   * @param {string} message
+   * @param {Record<string, unknown>} [extra]
+   * @returns {void}
+   */
+  info(message, extra) {
+    this.#write('info', message, extra);
+  }
+
+  /**
+   * @param {string} message
+   * @param {Record<string, unknown>} [extra]
+   * @returns {void}
+   */
+  warn(message, extra) {
+    this.#write('warn', message, extra);
+  }
+
+  /**
+   * @param {string} message
+   * @param {Record<string, unknown>} [extra]
+   * @returns {void}
+   */
+  error(message, extra) {
+    this.#write('error', message, extra);
+  }
+}
+
+/**
+ * A silent logger that discards all output. Useful in tests.
+ * @type {DaemonLoggerLike}
+ */
+export const silentLogger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};
+
+/**
+ * Wrap a legacy `Pick<Console, 'log' | 'error'>` logger into the new
+ * `DaemonLoggerLike` interface. Used for backward compatibility with
+ * callers that still pass `{ log() {}, error() {} }`.
+ *
+ * @param {Pick<Console, 'log' | 'error'>} legacy
+ * @returns {DaemonLoggerLike}
+ */
+export function wrapLegacyLogger(legacy) {
+  return {
+    debug(message, extra) {
+      legacy.log?.(`[debug] ${message}`, extra ?? '');
+    },
+    info(message, extra) {
+      legacy.log?.(`[info] ${message}`, extra ?? '');
+    },
+    warn(message, extra) {
+      legacy.log?.(`[warn] ${message}`, extra ?? '');
+    },
+    error(message, extra) {
+      legacy.error?.(`[error] ${message}`, extra ?? '');
+    },
+  };
+}
+
+/**
+ * Accept either a `DaemonLoggerLike` or a legacy `Pick<Console, 'log' | 'error'>`
+ * and return a normalized `DaemonLoggerLike`. If the input already has an `info`
+ * method it is returned as-is; otherwise it is wrapped via `wrapLegacyLogger`.
+ *
+ * @param {DaemonLoggerLike | Pick<Console, 'log' | 'error'> | undefined} logger
+ * @returns {DaemonLoggerLike}
+ */
+export function normalizeDaemonLogger(logger) {
+  if (logger === undefined) {
+    return new DaemonLogger();
+  }
+  if (typeof (/** @type {any} */ (logger).info) === 'function') {
+    return /** @type {DaemonLoggerLike} */ (logger);
+  }
+  return wrapLegacyLogger(/** @type {Pick<Console, 'log' | 'error'>} */ (logger));
+}