@browserbridge/bbx 1.0.0 → 1.1.0

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

@@ -3,7 +3,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { APP_NAME, getManifestInstallDir, SUPPORTED_BROWSERS } from '../../native-host/src/config.js';
+import {
+  APP_NAME,
+  getManifestInstallDir,
+  SUPPORTED_BROWSERS,
+} from '../../native-host/src/config.js';
 import { resolveDefaultExtensionId } from '../../native-host/src/install-manifest.js';
 import { methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
@@ -65,7 +69,7 @@ export async function requestBridge(client, method, params = {}, options = {}) {
     method,
     params,
     tabId: methodNeedsTab(method) ? (options.tabId ?? null) : null,
-    meta: withRequestMeta(options.source, options.tokenBudget)
+    meta: withRequestMeta(options.source, options.tokenBudget),
   });
 }
 
@@ -81,9 +85,14 @@ export async function resolveRef(client, refOrSelector, tabId = null, source) {
     return refOrSelector;
   }
 
-  const response = await requestBridge(client, 'dom.query', {
-    selector: refOrSelector
-  }, { tabId, source });
+  const response = await requestBridge(
+    client,
+    'dom.query',
+    {
+      selector: refOrSelector,
+    },
+    { tabId, source }
+  );
 
   if (!response.ok) {
     throw new Error(response.error.message);
@@ -184,9 +193,7 @@ export async function checkBrowserManifests() {
  */
 export async function getDoctorReport(options = {}) {
   const manifest = await (options.loadManifest || loadInstalledManifest)();
-  const allowedOrigins = Array.isArray(manifest?.allowed_origins)
-    ? manifest.allowed_origins
-    : [];
+  const allowedOrigins = Array.isArray(manifest?.allowed_origins) ? manifest.allowed_origins : [];
   const manifestInstalled = Boolean(manifest);
   const defaultExtensionId = options.defaultExtensionIdInfo || resolveDefaultExtensionId();
 
@@ -208,7 +215,7 @@ export async function getDoctorReport(options = {}) {
     routeReason: 'access_disabled',
     issues: [],
     nextSteps: [],
-    browserManifests
+    browserManifests,
   };
 
   try {
@@ -217,7 +224,8 @@ export async function getDoctorReport(options = {}) {
       if (!response.ok) {
         throw new Error(response.error.message);
       }
-      const result = /** @type {{ daemon?: string, extensionConnected?: boolean, access?: {
+      const result =
+        /** @type {{ daemon?: string, extensionConnected?: boolean, access?: {
         enabled?: boolean,
         windowId?: number | null,
         routeTabId?: number | null,
@@ -227,10 +235,13 @@ export async function getDoctorReport(options = {}) {
       report.daemonReachable = result.daemon === 'ok';
       report.extensionConnected = result.extensionConnected === true;
       report.accessEnabled = result.access?.enabled === true;
-      report.enabledWindowId = typeof result.access?.windowId === 'number' ? result.access.windowId : null;
-      report.routeTabId = typeof result.access?.routeTabId === 'number' ? result.access.routeTabId : null;
+      report.enabledWindowId =
+        typeof result.access?.windowId === 'number' ? result.access.windowId : null;
+      report.routeTabId =
+        typeof result.access?.routeTabId === 'number' ? result.access.routeTabId : null;
       report.routeReady = result.access?.routeReady === true;
-      report.routeReason = typeof result.access?.reason === 'string' ? result.access.reason : 'access_disabled';
+      report.routeReason =
+        typeof result.access?.reason === 'string' ? result.access.reason : 'access_disabled';
     });
   } catch {
     report.daemonReachable = false;
@@ -241,13 +252,17 @@ export async function getDoctorReport(options = {}) {
 
   if (!report.manifestInstalled) {
     report.issues.push('native_host_manifest_missing');
-    report.nextSteps.push(defaultExtensionId.extensionId
-      ? 'Run `bbx install` (or `bbx install --all` for all browsers) to install the native host manifest.'
-      : 'Run `bbx install <extension-id>` (or `bbx install --all`) to install the native host manifest.');
+    report.nextSteps.push(
+      defaultExtensionId.extensionId
+        ? 'Run `bbx install` (or `bbx install --all` for all browsers) to install the native host manifest.'
+        : 'Run `bbx install <extension-id>` (or `bbx install --all`) to install the native host manifest.'
+    );
   } else if (browsersWithoutManifest.length > 0) {
     report.issues.push('native_host_manifest_partial');
     const missing = browsersWithoutManifest.map((b) => b.browser).join(', ');
-    report.nextSteps.push(`Manifests missing for: ${missing}. Run \`bbx install --all\` to install for all supported browsers.`);
+    report.nextSteps.push(
+      `Manifests missing for: ${missing}. Run \`bbx install --all\` to install for all supported browsers.`
+    );
   }
   if (!report.daemonReachable) {
     report.issues.push('daemon_offline');
@@ -255,14 +270,20 @@ export async function getDoctorReport(options = {}) {
   }
   if (report.daemonReachable && !report.extensionConnected) {
     report.issues.push('extension_disconnected');
-    report.nextSteps.push('Open Chrome and make sure the Browser Bridge extension is installed and active.');
+    report.nextSteps.push(
+      'Open Chrome and make sure the Browser Bridge extension is installed and active.'
+    );
   }
   if (report.daemonReachable && report.extensionConnected && !report.accessEnabled) {
     report.issues.push('access_disabled');
-    report.nextSteps.push('If a Browser Bridge call returns ACCESS_DENIED, stop requesting access. Ask the user to click Enable for the needed window, then tell you when that window is ready.');
+    report.nextSteps.push(
+      'If a Browser Bridge call returns ACCESS_DENIED, stop requesting access. Ask the user to click Enable for the needed window, then tell you when that window is ready.'
+    );
   } else if (report.daemonReachable && report.extensionConnected && !report.routeReady) {
     report.issues.push(report.routeReason || 'no_routable_active_tab');
-    report.nextSteps.push('Switch to a supported page in the enabled window, or use an explicit tabId override.');
+    report.nextSteps.push(
+      'Switch to a supported page in the enabled window, or use an explicit tabId override.'
+    );
   }
 
   return report;

package/packages/agent-client/src/setup-status.js

@@ -57,8 +57,8 @@ const SKILL_TARGET_LABELS = {
  *   global?: boolean,
  *   cwd?: string,
  *   projectPath?: string,
- *   mcpDetectors?: Record<string, () => boolean>,
- *   skillDetectors?: Record<string, () => boolean>,
+ *   mcpDetectors?: Record<string, () => boolean | Promise<boolean>>,
+ *   skillDetectors?: Record<string, () => boolean | Promise<boolean>>,
  *   access?: (targetPath: string) => Promise<void>,
  *   readFile?: (targetPath: string, encoding: BufferEncoding) => Promise<string>
  * }} SetupStatusOptions
@@ -76,14 +76,18 @@ export async function collectSetupStatus(options = {}) {
   const projectPath = options.projectPath || cwd;
   const access = options.access || fs.promises.access.bind(fs.promises);
   const readFile = options.readFile || fs.promises.readFile.bind(fs.promises);
-  const detectedMcpClients = new Set(detectMcpClients(options.mcpDetectors));
-  const detectedSkillTargets = new Set(
+  const [detectedMcpClientResult, detectedSkillTargetResult] = await Promise.allSettled([
+    detectMcpClients(options.mcpDetectors),
     detectSkillTargets(options.skillDetectors),
-  );
+  ]);
+  const detectedMcpClientNames =
+    detectedMcpClientResult.status === 'fulfilled' ? detectedMcpClientResult.value : [];
+  const detectedSkillTargetNames =
+    detectedSkillTargetResult.status === 'fulfilled' ? detectedSkillTargetResult.value : [];
+  const detectedMcpClients = new Set(detectedMcpClientNames);
+  const detectedSkillTargets = new Set(detectedSkillTargetNames);
   for (const clientName of detectedMcpClients) {
-    if (
-      SUPPORTED_TARGETS.includes(/** @type {SupportedTarget} */ (clientName))
-    ) {
+    if (SUPPORTED_TARGETS.includes(/** @type {SupportedTarget} */ (clientName))) {
       detectedSkillTargets.add(/** @type {SupportedTarget} */ (clientName));
     }
   }
@@ -96,7 +100,7 @@ export async function collectSetupStatus(options = {}) {
         detected: detectedMcpClients.has(clientName),
         readFile,
       });
-    }),
+    })
   );
   const skillTargets = await Promise.all(
     SUPPORTED_TARGETS.map(async (target) => {
@@ -107,7 +111,7 @@ export async function collectSetupStatus(options = {}) {
         access,
         readFile,
       });
-    }),
+    })
   );
 
   return {
@@ -138,12 +142,8 @@ async function collectMcpClientStatus(clientName, options) {
   });
   const entries = await Promise.all(
     configPaths.map(async (configPath) => {
-      return readBrowserBridgeMcpEntry(
-        clientName,
-        configPath,
-        options.readFile,
-      );
-    }),
+      return readBrowserBridgeMcpEntry(clientName, configPath, options.readFile);
+    })
   );
   const preferredEntry =
     entries.find((entry) => entry.configured) ||
@@ -188,20 +188,17 @@ async function collectSkillTargetStatus(target, options) {
         skillName,
         sentinelFilename,
         options.access,
-        options.readFile,
+        options.readFile
       );
-    }),
+    })
   );
   const skillByName = new Map(skills.map((skill) => [skill.name, skill]));
   const coreSkill = skillByName.get(coreSkillName) || null;
   const coreInstalled = Boolean(coreSkill?.exists);
   const coreManaged = Boolean(coreSkill?.exists && coreSkill.managed);
-  const installedVersion = getInstalledSkillBundleVersion(
-    coreSkill ? [coreSkill] : [],
-  );
+  const installedVersion = getInstalledSkillBundleVersion(coreSkill ? [coreSkill] : []);
   const updateAvailable =
-    coreManaged &&
-    isManagedVersionOutdated(coreSkill?.version || null, currentVersion);
+    coreManaged && isManagedVersionOutdated(coreSkill?.version || null, currentVersion);
 
   return {
     key: target,
@@ -230,15 +227,13 @@ async function collectInstalledSkillStatus(
   skillName,
   sentinelFilename,
   access,
-  readFile,
+  readFile
 ) {
   const skillPath = path.join(basePath, skillName);
   const exists = await pathExists(skillPath, access);
   const sentinelPath = path.join(skillPath, sentinelFilename);
   const managed = exists && (await pathExists(sentinelPath, access));
-  const version = managed
-    ? await readManagedSkillVersion(sentinelPath, readFile)
-    : null;
+  const version = managed ? await readManagedSkillVersion(sentinelPath, readFile) : null;
 
   return {
     name: skillName,
@@ -261,9 +256,7 @@ function getInstalledSkillBundleVersion(skills) {
   if (!first || typeof first.version !== 'string') {
     return null;
   }
-  return skills.every((skill) => skill.version === first.version)
-    ? first.version
-    : null;
+  return skills.every((skill) => skill.version === first.version) ? first.version : null;
 }
 
 /**

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

@@ -1,10 +1,62 @@
 #!/usr/bin/env node
 // @ts-check
 
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
 import { startBridgeMcpServer } from './server.js';
 
-startBridgeMcpServer().catch((error) => {
-  const message = error instanceof Error ? error.stack || error.message : String(error);
-  process.stderr.write(`${message}\n`);
-  process.exit(1);
-});
+/**
+ * @typedef {{
+ *   start?: () => Promise<void>,
+ *   argv?: string[],
+ *   stdout?: { write: (chunk: string) => unknown },
+ *   stderr?: { write: (chunk: string) => unknown },
+ *   exit?: (code: number) => unknown,
+ * }} BridgeMcpCliOptions
+ */
+
+const HELP_FLAGS = new Set(['help', '--help', '-h']);
+
+const MCP_USAGE = [
+  'Usage: bbx-mcp [--help]',
+  '',
+  'Start the Browser Bridge MCP stdio server.',
+].join('\n');
+
+/**
+ * Start the MCP server CLI and report startup failures to stderr.
+ *
+ * @param {BridgeMcpCliOptions} [options]
+ * @returns {Promise<number>}
+ */
+export async function runBridgeMcpCli(options = {}) {
+  const {
+    start = startBridgeMcpServer,
+    argv = process.argv.slice(2),
+    stdout = process.stdout,
+    stderr = process.stderr,
+    exit = process.exit,
+  } = options;
+
+  if (argv.some((arg) => HELP_FLAGS.has(arg))) {
+    stdout.write(`${MCP_USAGE}\n`);
+    return 0;
+  }
+
+  try {
+    await start();
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.stack || error.message : String(error);
+    stderr.write(`${message}\n`);
+    exit(1);
+    return 1;
+  }
+}
+
+const entryPointUrl = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null;
+
+if (entryPointUrl === import.meta.url) {
+  void runBridgeMcpCli();
+}