@browserbridge/bbx 1.0.1 → 1.2.0

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

@@ -1,15 +1,32 @@
 // @ts-check
 
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
 /** @typedef {import('./mcp-config.js').McpClientName} McpClientName */
 /** @typedef {import('./install.js').SupportedTarget} SupportedTarget */
+/** @typedef {() => boolean | Promise<boolean>} Detector */
 
 const home = os.homedir();
 const platform = process.platform;
+const WINDOWS_EXECUTABLE_EXTENSIONS = new Set(
+  (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';')
+    .map((extension) => extension.trim().toLowerCase())
+    .filter(Boolean)
+);
+const DEFAULT_COMMAND_NAMES =
+  platform === 'darwin'
+    ? ['codex', 'claude', 'opencode', 'agy']
+    : platform === 'linux'
+      ? ['codex', 'claude', 'cursor', 'code', 'opencode', 'agy', 'windsurf']
+      : ['codex', 'claude', 'cursor', 'opencode', 'agy', 'windsurf'];
+
+const PATH_DELIMITER = platform === 'win32' ? ';' : ':';
+
+/** @type {Promise<Set<string>> | null} */
+let availableCommandsPromise = null;
 
 /**
  * @returns {string}
@@ -26,12 +43,12 @@ function getVsCodeUserDataDir() {
 }
 
 /**
- * @param {string} p
- * @returns {boolean}
+ * @param {string} targetPath
+ * @returns {Promise<boolean>}
  */
-function fsExists(p) {
+async function fsExists(targetPath) {
   try {
-    fs.accessSync(p);
+    await fs.promises.access(targetPath, fs.constants.F_OK);
     return true;
   } catch {
     return false;
@@ -39,24 +56,102 @@ function fsExists(p) {
 }
 
 /**
- * @param {string} cmd
- * @returns {boolean}
+ * @param {string} command
+ * @returns {string}
  */
-function commandExists(cmd) {
-  try {
-    execFileSync(platform === 'win32' ? 'where' : 'which', [cmd], {
-      stdio: 'ignore',
-    });
-    return true;
-  } catch {
-    return false;
+function normalizeCommandName(command) {
+  return platform === 'win32' ? command.toLowerCase() : command;
+}
+
+/**
+ * @param {string} entryName
+ * @returns {string | null}
+ */
+function getCommandNameFromPathEntry(entryName) {
+  if (platform !== 'win32') {
+    return entryName;
+  }
+
+  const extension = path.extname(entryName).toLowerCase();
+  if (!WINDOWS_EXECUTABLE_EXTENSIONS.has(extension)) {
+    return null;
   }
+  return entryName.slice(0, -extension.length).toLowerCase();
 }
 
-/** @returns {boolean} */
-function detectCopilot() {
-  if (fsExists(path.join(getVsCodeUserDataDir(), 'User'))) return true;
-  if (fsExists(path.join(home, '.vscode'))) return true;
+/**
+ * @param {readonly string[]} commands
+ * @returns {Promise<Set<string>>}
+ */
+async function resolveAvailableCommands(commands) {
+  const resolved = new Set();
+  const unresolved = new Set(commands.map((command) => normalizeCommandName(command)));
+  const pathEntries = (process.env.PATH || '').split(PATH_DELIMITER).filter(Boolean);
+  const executeAccessMode = platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK;
+
+  for (const directory of pathEntries) {
+    if (unresolved.size === 0) {
+      break;
+    }
+
+    let entries;
+    try {
+      entries = await fs.promises.readdir(directory);
+    } catch {
+      continue;
+    }
+
+    const matches = await Promise.all(
+      entries.map(async (entryName) => {
+        const commandName = getCommandNameFromPathEntry(entryName);
+        if (!commandName || !unresolved.has(commandName)) {
+          return null;
+        }
+
+        try {
+          await fs.promises.access(path.join(directory, entryName), executeAccessMode);
+          return commandName;
+        } catch {
+          return null;
+        }
+      })
+    );
+
+    for (const commandName of matches) {
+      if (!commandName) {
+        continue;
+      }
+      unresolved.delete(commandName);
+      resolved.add(commandName);
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * @returns {Promise<Set<string>>}
+ */
+function getAvailableCommands() {
+  if (!availableCommandsPromise) {
+    availableCommandsPromise = resolveAvailableCommands(DEFAULT_COMMAND_NAMES);
+  }
+  return availableCommandsPromise;
+}
+
+/**
+ * @param {string} command
+ * @returns {Promise<boolean>}
+ */
+async function commandExists(command) {
+  const availableCommands = await getAvailableCommands();
+  return availableCommands.has(normalizeCommandName(command));
+}
+
+/** @returns {Promise<boolean>} */
+async function detectCopilot() {
+  if (await fsExists(path.join(getVsCodeUserDataDir(), 'User'))) return true;
+  if (await fsExists(path.join(home, '.vscode'))) return true;
   if (platform === 'darwin') return fsExists('/Applications/Visual Studio Code.app');
   if (platform === 'win32') {
     const localAppData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
@@ -65,47 +160,47 @@ function detectCopilot() {
   return commandExists('code');
 }
 
-/** @returns {boolean} */
-function detectCursor() {
-  if (fsExists(path.join(home, '.cursor'))) return true;
+/** @returns {Promise<boolean>} */
+async function detectCursor() {
+  if (await fsExists(path.join(home, '.cursor'))) return true;
   if (platform === 'darwin') return fsExists('/Applications/Cursor.app');
   return commandExists('cursor');
 }
 
-/** @returns {boolean} */
-function detectWindsurf() {
-  if (fsExists(path.join(home, '.codeium', 'windsurf'))) return true;
+/** @returns {Promise<boolean>} */
+async function detectWindsurf() {
+  if (await fsExists(path.join(home, '.codeium', 'windsurf'))) return true;
   if (platform === 'darwin') return fsExists('/Applications/Windsurf.app');
   return commandExists('windsurf');
 }
 
-/** @returns {boolean} */
-function detectClaude() {
-  if (fsExists(path.join(home, '.claude'))) return true;
-  if (fsExists(path.join(home, '.claude.json'))) return true;
+/** @returns {Promise<boolean>} */
+async function detectClaude() {
+  if (await fsExists(path.join(home, '.claude'))) return true;
+  if (await fsExists(path.join(home, '.claude.json'))) return true;
   return commandExists('claude');
 }
 
-/** @returns {boolean} */
-function detectCodex() {
-  if (fsExists(path.join(home, '.codex'))) return true;
+/** @returns {Promise<boolean>} */
+async function detectCodex() {
+  if (await fsExists(path.join(home, '.codex'))) return true;
   return commandExists('codex');
 }
 
-/** @returns {boolean} */
-function detectOpencode() {
-  if (fsExists(path.join(home, '.config', 'opencode'))) return true;
-  if (fsExists(path.join(home, '.opencode'))) return true;
+/** @returns {Promise<boolean>} */
+async function detectOpencode() {
+  if (await fsExists(path.join(home, '.config', 'opencode'))) return true;
+  if (await fsExists(path.join(home, '.opencode'))) return true;
   return commandExists('opencode');
 }
 
-/** @returns {boolean} */
-function detectAntigravity() {
-  if (fsExists(path.join(home, '.gemini', 'antigravity'))) return true;
+/** @returns {Promise<boolean>} */
+async function detectAntigravity() {
+  if (await fsExists(path.join(home, '.gemini', 'antigravity'))) return true;
   return commandExists('agy');
 }
 
-/** @type {Record<string, () => boolean>} */
+/** @type {Record<string, Detector>} */
 const DETECTORS = {
   codex: detectCodex,
   claude: detectClaude,
@@ -138,26 +233,42 @@ const SKILL_TARGET_KEYS = [
   'windsurf',
 ];
 
+/**
+ * @template {string} T
+ * @param {readonly T[]} keys
+ * @param {Record<string, Detector>} detectors
+ * @returns {Promise<T[]>}
+ */
+async function detectTargets(keys, detectors) {
+  const detectionResults = await Promise.all(
+    keys.map(async (name) => ({
+      name,
+      detected: await (detectors[name]?.() ?? false),
+    }))
+  );
+  return detectionResults.filter((entry) => entry.detected).map((entry) => entry.name);
+}
+
 /**
  * Detect which MCP clients are installed on this machine.
  *
- * @param {Record<string, () => boolean>} [detectors=DETECTORS]
- * @returns {McpClientName[]}
+ * @param {Record<string, Detector>} [detectors=DETECTORS]
+ * @returns {Promise<McpClientName[]>}
  */
-export function detectMcpClients(detectors = DETECTORS) {
-  return MCP_CLIENT_KEYS.filter((name) => detectors[name]());
+export async function detectMcpClients(detectors = DETECTORS) {
+  return detectTargets(MCP_CLIENT_KEYS, detectors);
 }
 
 /**
  * Detect which skill targets are installed on this machine.
  * Always includes 'agents' as a generic fallback.
  *
- * @param {Record<string, () => boolean>} [detectors=DETECTORS]
- * @returns {SupportedTarget[]}
+ * @param {Record<string, Detector>} [detectors=DETECTORS]
+ * @returns {Promise<SupportedTarget[]>}
  */
-export function detectSkillTargets(detectors = DETECTORS) {
+export async function detectSkillTargets(detectors = DETECTORS) {
   /** @type {SupportedTarget[]} */
-  const detected = SKILL_TARGET_KEYS.filter((name) => detectors[name]());
+  const detected = await detectTargets(SKILL_TARGET_KEYS, detectors);
   detected.push('agents');
   return detected;
 }

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

@@ -157,6 +157,8 @@ export function parseInstallAgentArgs(args, cwd = process.cwd()) {
 export async function installAgentFiles(options) {
   /** @type {string[]} */
   const created = [];
+  /** @type {Array<{ path: string, existedBefore: boolean }>} */
+  const attempted = [];
   /** @type {Set<string>} */
   const seenTargets = new Set();
 
@@ -168,7 +170,14 @@ export async function installAgentFiles(options) {
         continue;
       }
       seenTargets.add(skillTargetDir);
-      await installManagedSkill(skillName, target, skillTargetDir);
+      const existedBefore = await pathExists(skillTargetDir);
+      attempted.push({ path: skillTargetDir, existedBefore });
+      try {
+        await installManagedSkill(skillName, target, skillTargetDir);
+      } catch (error) {
+        await rollbackInstalledSkillDirs(attempted);
+        throw error;
+      }
       created.push(skillTargetDir);
     }
   }
@@ -176,6 +185,20 @@ export async function installAgentFiles(options) {
   return created;
 }
 
+/**
+ * Remove any newly created managed skill directories after a failed install so a
+ * later retry starts cleanly. Pre-existing directories are left untouched.
+ *
+ * @param {Array<{ path: string, existedBefore: boolean }>} attempted
+ * @returns {Promise<void>}
+ */
+async function rollbackInstalledSkillDirs(attempted) {
+  const rollbackPaths = attempted
+    .filter((entry) => !entry.existedBefore)
+    .map((entry) => fs.promises.rm(entry.path, { recursive: true, force: true }));
+  await Promise.allSettled(rollbackPaths);
+}
+
 /**
  * Write MCP config for the given clients.
  *

package/packages/agent-client/src/mcp-config.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 /**
  * @typedef {'codex' | 'claude' | 'cursor' | 'copilot' | 'opencode' | 'antigravity' | 'windsurf' | 'agents'} McpClientName
@@ -41,6 +42,8 @@ export function isMcpClientName(value) {
 }
 
 const BROWSER_BRIDGE_SERVER_NAME = 'browser-bridge';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const mcpServerBinPath = path.join(packageRoot, 'packages', 'mcp-server', 'src', 'bin.js');
 
 /**
  * @returns {string}
@@ -93,17 +96,29 @@ export function getMcpConfigShape(clientName) {
  * }}
  */
 function createBaseServerConfig(clientName) {
+  const windowsCommand =
+    process.platform === 'win32'
+      ? {
+          command: process.execPath,
+          args: [mcpServerBinPath],
+          env: {},
+        }
+      : {
+          command: 'bbx',
+          args: ['mcp', 'serve'],
+          env: {},
+        };
+
   if (clientName === 'opencode') {
     return {
       type: 'local',
-      command: ['bbx', 'mcp', 'serve'],
+      command:
+        process.platform === 'win32'
+          ? [process.execPath, mcpServerBinPath]
+          : ['bbx', 'mcp', 'serve'],
     };
   }
-  return {
-    command: 'bbx',
-    args: ['mcp', 'serve'],
-    env: {},
-  };
+  return windowsCommand;
 }
 
 /** @type {Record<McpClientName, { key: string, includeType: boolean, legacyKeys?: string[], keepEmptyBlock?: boolean }>} */
@@ -129,11 +144,13 @@ const MCP_CONFIG_SHAPES = {
  */
 export function buildMcpConfig(clientName) {
   if (clientName === 'codex') {
+    const command = process.platform === 'win32' ? process.execPath : 'bbx';
+    const args = process.platform === 'win32' ? [mcpServerBinPath] : ['mcp', 'serve'];
     return {
       mcp_servers: {
         [BROWSER_BRIDGE_SERVER_NAME]: {
-          command: 'bbx',
-          args: ['mcp', 'serve'],
+          command,
+          args,
         },
       },
     };
@@ -262,10 +279,12 @@ export async function getMcpConfigPaths(clientName, options) {
  * @returns {string}
  */
 function formatCodexServerBlock() {
+  const command = process.platform === 'win32' ? process.execPath : 'bbx';
+  const args = process.platform === 'win32' ? [mcpServerBinPath] : ['mcp', 'serve'];
   return [
     `[mcp_servers."${BROWSER_BRIDGE_SERVER_NAME}"]`,
-    'command = "bbx"',
-    'args = ["mcp", "serve"]',
+    `command = ${JSON.stringify(command)}`,
+    `args = ${JSON.stringify(args)}`,
     '',
   ].join('\n');
 }

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,8 +76,16 @@ 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(detectSkillTargets(options.skillDetectors));
+  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))) {
       detectedSkillTargets.add(/** @type {SupportedTarget} */ (clientName));

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();
+}