@browserbridge/bbx 1.0.0 → 1.1.0

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

@@ -1,23 +1,39 @@
 // @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}
  */
 function getVsCodeUserDataDir() {
   if (platform === 'win32') {
-    const appData =
-      process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
     return path.join(appData, 'Code');
   }
   if (platform === 'linux') {
@@ -27,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;
@@ -40,75 +56,151 @@ 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;
-  if (platform === 'darwin')
-    return fsExists('/Applications/Visual Studio Code.app');
+/**
+ * @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');
+    const localAppData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
     return fsExists(path.join(localAppData, 'Programs', 'Microsoft VS Code'));
   }
   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,
@@ -141,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

@@ -29,9 +29,7 @@ const targetAliases = /** @type {const} */ ({
 
 const packageManifest = loadPackageManifest();
 const managedPackageName =
-  typeof packageManifest.name === 'string'
-    ? packageManifest.name
-    : '@browserbridge/bbx';
+  typeof packageManifest.name === 'string' ? packageManifest.name : '@browserbridge/bbx';
 const managedPackageVersion =
   typeof packageManifest.version === 'string' ? packageManifest.version : null;
 const copilotBrowserBridgeNote = [
@@ -91,9 +89,7 @@ export function parseInstallAgentArgs(args, cwd = process.cwd()) {
     if (arg === '--agents' || arg === '--agent') {
       const value = args[index + 1];
       if (!value) {
-        throw new Error(
-          'Usage: install-skill [targets|all] [--project <path>]',
-        );
+        throw new Error('Usage: install-skill [targets|all] [--project <path>]');
       }
       targets = parseTargetList(value);
       index += 1;
@@ -113,9 +109,7 @@ export function parseInstallAgentArgs(args, cwd = process.cwd()) {
     if (arg === '--project') {
       const value = args[index + 1];
       if (!value) {
-        throw new Error(
-          'Usage: install-skill [targets|all] [--project <path>] [--global]',
-        );
+        throw new Error('Usage: install-skill [targets|all] [--project <path>] [--global]');
       }
       projectPath = path.resolve(cwd, value);
       isGlobal = false;
@@ -163,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();
 
@@ -174,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);
     }
   }
@@ -182,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.
  *
@@ -204,7 +221,7 @@ export async function installMcpClientSetup(clients, options) {
         global: options.global,
         cwd: options.projectPath,
         stdout: options.stdout,
-      }),
+      })
     );
   }
 
@@ -289,7 +306,7 @@ function parseTargetList(raw) {
     );
     if (!canonical) {
       throw new Error(
-        `Unknown install-skill target "${value}". Supported targets: ${supportedTargets.join(', ')}, all. Aliases: openai -> codex, google -> antigravity.`,
+        `Unknown install-skill target "${value}". Supported targets: ${supportedTargets.join(', ')}, all. Aliases: openai -> codex, google -> antigravity.`
       );
     }
     parsed.add(canonical);
@@ -380,7 +397,7 @@ export function formatManagedSkillSentinel(skillName) {
       version: managedPackageVersion,
     },
     null,
-    2,
+    2
   )}\n`;
 }
 
@@ -414,10 +431,7 @@ export function parseManagedSkillSentinel(raw) {
  * @param {string | null} [currentVersion=managedPackageVersion]
  * @returns {boolean}
  */
-export function isManagedVersionOutdated(
-  installedVersion,
-  currentVersion = managedPackageVersion,
-) {
+export function isManagedVersionOutdated(installedVersion, currentVersion = managedPackageVersion) {
   if (!currentVersion) {
     return false;
   }
@@ -439,19 +453,13 @@ async function installManagedSkill(skillName, target, targetDir) {
   const targetExists = await pathExists(targetDir);
 
   if (targetExists && !(await pathExists(sentinelPath))) {
-    throw new Error(
-      `Refusing to overwrite unmanaged skill directory: ${targetDir}`,
-    );
+    throw new Error(`Refusing to overwrite unmanaged skill directory: ${targetDir}`);
   }
 
   await fs.promises.rm(targetDir, { recursive: true, force: true });
   await copyDir(sourceDir, targetDir);
   await applyManagedSkillPatches(skillName, target, targetDir);
-  await fs.promises.writeFile(
-    sentinelPath,
-    formatManagedSkillSentinel(skillName),
-    'utf8',
-  );
+  await fs.promises.writeFile(sentinelPath, formatManagedSkillSentinel(skillName), 'utf8');
 }
 
 /**
@@ -532,9 +540,7 @@ async function applyManagedSkillPatches(skillName, target, targetDir) {
  */
 function loadPackageManifest() {
   try {
-    return JSON.parse(
-      fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'),
-    );
+    return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
   } catch {
     return {};
   }

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}
@@ -48,8 +51,7 @@ const BROWSER_BRIDGE_SERVER_NAME = 'browser-bridge';
 function getVsCodeUserDataDir() {
   const home = os.homedir();
   if (process.platform === 'win32') {
-    const appData =
-      process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
     return path.join(appData, 'Code');
   }
   if (process.platform === 'linux') {
@@ -79,9 +81,7 @@ function getLegacyCopilotVsCodeConfigPath() {
  * @returns {{ key: string, includeType: boolean, legacyKeys?: string[], keepEmptyBlock?: boolean }}
  */
 export function getMcpConfigShape(clientName) {
-  return (
-    MCP_CONFIG_SHAPES[clientName] ?? { key: 'mcpServers', includeType: false }
-  );
+  return MCP_CONFIG_SHAPES[clientName] ?? { key: 'mcpServers', includeType: false };
 }
 
 /**
@@ -96,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 }>} */
@@ -132,20 +144,20 @@ 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,
         },
       },
     };
   }
   const serverConfig = createBaseServerConfig(clientName);
   const shape = getMcpConfigShape(clientName);
-  const entry = shape.includeType
-    ? { type: 'stdio', ...serverConfig }
-    : serverConfig;
+  const entry = shape.includeType ? { type: 'stdio', ...serverConfig } : serverConfig;
   return { [shape.key]: { [BROWSER_BRIDGE_SERVER_NAME]: entry } };
 }
 
@@ -169,10 +181,7 @@ export function formatMcpConfig(clientName) {
  * @param {{ global: boolean, cwd?: string }} options
  * @returns {string}
  */
-export function getMcpConfigPath(
-  clientName,
-  { global: isGlobal, cwd = process.cwd() },
-) {
+export function getMcpConfigPath(clientName, { global: isGlobal, cwd = process.cwd() }) {
   const home = os.homedir();
 
   if (!isGlobal) {
@@ -252,7 +261,9 @@ export async function getMcpConfigPaths(clientName, options) {
     const entries = await readdir(profilesDir, { withFileTypes: true });
     const profilePaths = entries
       .filter((/** @type {import('node:fs').Dirent} */ entry) => entry.isDirectory())
-      .map((/** @type {import('node:fs').Dirent} */ entry) => path.join(profilesDir, entry.name, 'mcp.json'));
+      .map((/** @type {import('node:fs').Dirent} */ entry) =>
+        path.join(profilesDir, entry.name, 'mcp.json')
+      );
     for (const profilePath of profilePaths) {
       if (!paths.includes(profilePath)) {
         paths.push(profilePath);
@@ -268,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');
 }
@@ -533,11 +546,7 @@ async function installJsonMcpConfig(clientName, configPath, stdout) {
   }
 
   await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.promises.writeFile(
-    configPath,
-    `${JSON.stringify(merged, null, 2)}\n`,
-    'utf8',
-  );
+  await fs.promises.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
   stdout.write(`Wrote ${configPath}\n`);
 }
 
@@ -600,11 +609,7 @@ async function removeJsonMcpConfig(clientName, configPath, stdout) {
   }
 
   await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.promises.writeFile(
-    configPath,
-    `${JSON.stringify(merged, null, 2)}\n`,
-    'utf8',
-  );
+  await fs.promises.writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
   stdout.write(`Removed ${configPath}\n`);
   return true;
 }
@@ -647,16 +652,11 @@ export function parseInstalledMcpConfig(clientName, raw) {
     const parsed = JSON.parse(raw);
     const block =
       parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-        ? getMergedJsonMcpBlock(
-          /** @type {Record<string, unknown>} */ (parsed),
-          clientName,
-        )
+        ? getMergedJsonMcpBlock(/** @type {Record<string, unknown>} */ (parsed), clientName)
         : {};
     return {
       configured: Boolean(
-        block &&
-        typeof block === 'object' &&
-        Object.hasOwn(block, BROWSER_BRIDGE_SERVER_NAME),
+        block && typeof block === 'object' && Object.hasOwn(block, BROWSER_BRIDGE_SERVER_NAME)
       ),
     };
   } catch {