@browserbridge/bbx 1.0.1 → 1.1.0

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

@@ -1,12 +1,40 @@
 #!/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 { 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 });
 
-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 +49,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,31 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { installNativeManifest, parseExtensionId } from '../src/install-manifest.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 +43,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,7 +62,15 @@ 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,

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-process.js

@@ -0,0 +1,396 @@
+// @ts-check
+
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+import { pingExistingDaemon } from './daemon.js';
+import {
+  createSocketBridgeTransport,
+  formatBridgeTransport,
+  getBridgeDir,
+  getBridgeTransport,
+  getDaemonPidPath,
+} from './config.js';
+
+/** @typedef {import('./config.js').BridgeTransport} BridgeTransport */
+
+const execFileAsync = promisify(execFile);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const daemonEntryPath = path.resolve(__dirname, '../bin/bridge-daemon.js');
+const DEFAULT_DAEMON_RESTART_TIMEOUT_MS = 5_000;
+const DEFAULT_DAEMON_POLL_INTERVAL_MS = 100;
+
+/**
+ * @typedef {{
+ *   transport?: BridgeTransport,
+ *   socketPath?: string,
+ *   pidPath?: string,
+ *   timeoutMs?: number,
+ *   pollIntervalMs?: number,
+ *   pingDaemonFn?: (transport: BridgeTransport) => Promise<boolean>,
+ *   readPidFn?: (pidPath?: string) => Promise<number | null>,
+ *   findPidByTransportFn?: (transport: BridgeTransport) => Promise<number | null>,
+ *   killFn?: typeof process.kill,
+ *   rmFn?: typeof fs.promises.rm,
+ *   sleepFn?: (ms: number) => Promise<void>,
+ * }} StopBridgeDaemonOptions
+ */
+
+/**
+ * @typedef {{
+ *   transport?: BridgeTransport,
+ *   socketPath?: string,
+ *   pidPath?: string,
+ *   timeoutMs?: number,
+ *   pollIntervalMs?: number,
+ *   pingDaemonFn?: (transport: BridgeTransport) => Promise<boolean>,
+ *   readPidFn?: (pidPath?: string) => Promise<number | null>,
+ *   findPidByTransportFn?: (transport: BridgeTransport) => Promise<number | null>,
+ *   killFn?: typeof process.kill,
+ *   rmFn?: typeof fs.promises.rm,
+ *   sleepFn?: (ms: number) => Promise<void>,
+ *   spawnDaemonFn?: typeof spawnBridgeDaemonProcess,
+ * }} RestartBridgeDaemonOptions
+ */
+
+/**
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnBridgeDaemonProcess() {
+  const child = spawn(process.execPath, [daemonEntryPath], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  return child;
+}
+
+/**
+ * @param {number} [pid=process.pid]
+ * @param {string} [pidPath=getDaemonPidPath()]
+ * @returns {Promise<void>}
+ */
+export async function writeDaemonPidFile(pid = process.pid, pidPath = getDaemonPidPath()) {
+  await fs.promises.mkdir(getBridgeDir(), { recursive: true });
+  await fs.promises.writeFile(pidPath, `${pid}\n`, 'utf8');
+}
+
+/**
+ * @param {string} [pidPath=getDaemonPidPath()]
+ * @returns {Promise<number | null>}
+ */
+export async function readDaemonPidFile(pidPath = getDaemonPidPath()) {
+  try {
+    const raw = await fs.promises.readFile(pidPath, 'utf8');
+    const pid = Number.parseInt(raw.trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {{ pid?: number | null, pidPath?: string, rmFn?: typeof fs.promises.rm }} [options={}]
+ * @returns {Promise<void>}
+ */
+export async function clearDaemonPidFile(options = {}) {
+  const { pid = null, pidPath = getDaemonPidPath(), rmFn = fs.promises.rm } = options;
+
+  if (pid !== null) {
+    const currentPid = await readDaemonPidFile(pidPath);
+    if (currentPid !== pid) {
+      return;
+    }
+  }
+
+  try {
+    await rmFn(pidPath, { force: true });
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {StopBridgeDaemonOptions} [options={}]
+ * @returns {Promise<{ transport: string, socketPath: string, previouslyRunning: boolean, previousPid: number | null, removedStaleSocket: boolean }>}
+ */
+export async function stopBridgeDaemon(options = {}) {
+  const {
+    transport = getBridgeTransport(),
+    socketPath = undefined,
+    pidPath = getDaemonPidPath(),
+    timeoutMs = DEFAULT_DAEMON_RESTART_TIMEOUT_MS,
+    pollIntervalMs = DEFAULT_DAEMON_POLL_INTERVAL_MS,
+    pingDaemonFn = pingExistingDaemon,
+    readPidFn = readDaemonPidFile,
+    findPidByTransportFn = findDaemonPidByTransport,
+    killFn = process.kill.bind(process),
+    rmFn = fs.promises.rm,
+    sleepFn = sleep,
+  } = options;
+  const resolvedTransport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
+  const resolvedSocketPath =
+    resolvedTransport.type === 'socket' ? resolvedTransport.socketPath : '';
+
+  let previousPid = await readPidFn(pidPath);
+  let previouslyRunning = previousPid !== null;
+
+  if (previousPid === null && (await safePingDaemon(resolvedTransport, pingDaemonFn))) {
+    previousPid = await findPidByTransportFn(resolvedTransport);
+    previouslyRunning = true;
+  }
+
+  if (previousPid !== null) {
+    try {
+      killFn(previousPid, 'SIGTERM');
+    } catch (error) {
+      if (!isMissingProcessError(error)) {
+        throw error;
+      }
+    }
+
+    const stopped = await waitForDaemonReachability({
+      transport: resolvedTransport,
+      reachable: false,
+      timeoutMs,
+      pollIntervalMs,
+      pingDaemonFn,
+      sleepFn,
+    });
+    if (!stopped) {
+      throw new Error(`Timed out waiting for Browser Bridge daemon (pid ${previousPid}) to stop.`);
+    }
+  }
+
+  await clearDaemonPidFile({ pid: previousPid, pidPath, rmFn });
+
+  const removedStaleSocket = await removeStaleSocket(resolvedTransport, rmFn, pingDaemonFn);
+  return {
+    transport: formatBridgeTransport(resolvedTransport),
+    socketPath: resolvedSocketPath,
+    previouslyRunning,
+    previousPid,
+    removedStaleSocket,
+  };
+}
+
+/**
+ * @param {RestartBridgeDaemonOptions} [options={}]
+ * @returns {Promise<{
+ *   transport: string,
+ *   socketPath: string,
+ *   pidPath: string,
+ *   pid: number | null,
+ *   previouslyRunning: boolean,
+ *   previousPid: number | null,
+ *   removedStaleSocket: boolean,
+ * }>}
+ */
+export async function restartBridgeDaemon(options = {}) {
+  const {
+    transport = getBridgeTransport(),
+    socketPath = undefined,
+    pidPath = getDaemonPidPath(),
+    timeoutMs = DEFAULT_DAEMON_RESTART_TIMEOUT_MS,
+    pollIntervalMs = DEFAULT_DAEMON_POLL_INTERVAL_MS,
+    pingDaemonFn = pingExistingDaemon,
+    readPidFn = readDaemonPidFile,
+    findPidByTransportFn = findDaemonPidByTransport,
+    killFn = process.kill.bind(process),
+    rmFn = fs.promises.rm,
+    sleepFn = sleep,
+    spawnDaemonFn = spawnBridgeDaemonProcess,
+  } = options;
+  const resolvedTransport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
+
+  const stopResult = await stopBridgeDaemon({
+    transport: resolvedTransport,
+    pidPath,
+    timeoutMs,
+    pollIntervalMs,
+    pingDaemonFn,
+    readPidFn,
+    findPidByTransportFn,
+    killFn,
+    rmFn,
+    sleepFn,
+  });
+
+  spawnDaemonFn();
+
+  const started = await waitForDaemonReachability({
+    transport: resolvedTransport,
+    reachable: true,
+    timeoutMs,
+    pollIntervalMs,
+    pingDaemonFn,
+    sleepFn,
+  });
+  if (!started) {
+    throw new Error('Timed out waiting for Browser Bridge daemon to start.');
+  }
+
+  return {
+    ...stopResult,
+    pidPath,
+    pid: await readPidFn(pidPath),
+  };
+}
+
+/**
+ * @param {BridgeTransport} transport
+ * @returns {Promise<number | null>}
+ */
+export async function findDaemonPidByTransport(transport) {
+  if (transport.type !== 'socket') {
+    return null;
+  }
+  return findDaemonPidBySocket(transport.socketPath);
+}
+
+/**
+ * @param {string} socketPath
+ * @returns {Promise<number | null>}
+ */
+export async function findDaemonPidBySocket(socketPath) {
+  if (process.platform === 'win32') {
+    return null;
+  }
+
+  try {
+    const { stdout } = await execFileAsync('lsof', ['-t', '--', socketPath]);
+    const pid = Number.parseInt(
+      stdout
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .find(Boolean) ?? '',
+      10
+    );
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch (error) {
+    if (isCommandNotFoundError(error) || isLsofNoResultsError(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {{
+ *   transport: BridgeTransport,
+ *   reachable: boolean,
+ *   timeoutMs: number,
+ *   pollIntervalMs: number,
+ *   pingDaemonFn: (transport: BridgeTransport) => Promise<boolean>,
+ *   sleepFn: (ms: number) => Promise<void>,
+ * }} options
+ * @returns {Promise<boolean>}
+ */
+async function waitForDaemonReachability(options) {
+  const { transport, reachable, timeoutMs, pollIntervalMs, pingDaemonFn, sleepFn } = options;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    if ((await safePingDaemon(transport, pingDaemonFn)) === reachable) {
+      return true;
+    }
+    await sleepFn(pollIntervalMs);
+  }
+  return false;
+}
+
+/**
+ * @param {BridgeTransport} transport
+ * @param {typeof fs.promises.rm} rmFn
+ * @param {(transport: BridgeTransport) => Promise<boolean>} pingDaemonFn
+ * @returns {Promise<boolean>}
+ */
+async function removeStaleSocket(transport, rmFn, pingDaemonFn) {
+  if (transport.type !== 'socket') {
+    return false;
+  }
+
+  if (await safePingDaemon(transport, pingDaemonFn)) {
+    return false;
+  }
+
+  try {
+    await fs.promises.access(transport.socketPath);
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return false;
+    }
+    throw error;
+  }
+
+  try {
+    await rmFn(transport.socketPath, { force: true });
+    return true;
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {BridgeTransport} transport
+ * @param {(transport: BridgeTransport) => Promise<boolean>} pingDaemonFn
+ * @returns {Promise<boolean>}
+ */
+async function safePingDaemon(transport, pingDaemonFn) {
+  try {
+    return await pingDaemonFn(transport);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isMissingFileError(error) {
+  return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isMissingProcessError(error) {
+  return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ESRCH');
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isCommandNotFoundError(error) {
+  return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isLsofNoResultsError(error) {
+  return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 1);
+}