browser-commander 0.20.0 → 0.21.1

package/src/cli/serve.js

@@ -0,0 +1,144 @@
+/**
+ * `browser-commander serve --stdio`: JSON-RPC 2.0 over stdin/stdout, one
+ * message per line (issue #104). Requests may be pipelined; each response
+ * carries its request id, and server notifications (`events.emit`) have none.
+ */
+import { once } from 'node:events';
+import readline from 'node:readline';
+
+import { createDispatcher } from './dispatcher.js';
+import { RPC_ERROR, toRpcError } from './rpc-error.js';
+
+/** How long pending requests may run after stdin closes. */
+export const DEFAULT_DRAIN_TIMEOUT_MS = 5_000;
+
+function errorResponse(id, code, message) {
+  return { jsonrpc: '2.0', id, error: { code, message } };
+}
+
+function isValidId(id) {
+  return id === null || typeof id === 'string' || typeof id === 'number';
+}
+
+function isRequest(message) {
+  return (
+    message !== null &&
+    typeof message === 'object' &&
+    !Array.isArray(message) &&
+    message.jsonrpc === '2.0' &&
+    typeof message.method === 'string' &&
+    (!('id' in message) || isValidId(message.id))
+  );
+}
+
+/**
+ * Build the handler for one JSON-RPC message or batch.
+ *
+ * @param {{dispatch: Function}} dispatcher
+ * @returns {function(unknown): Promise<Object|Array<Object>|null>} The response, or null for notifications
+ */
+export function createMessageHandler(dispatcher) {
+  async function handleOne(message) {
+    if (!isRequest(message)) {
+      const id = isValidId(message?.id) ? message.id : null;
+      return errorResponse(id, RPC_ERROR.INVALID_REQUEST, 'Invalid request');
+    }
+    const notification = !('id' in message);
+    try {
+      const result = await dispatcher.dispatch(
+        message.method,
+        message.params ?? {}
+      );
+      return notification
+        ? null
+        : { jsonrpc: '2.0', id: message.id, result: result ?? null };
+    } catch (error) {
+      return notification
+        ? null
+        : { jsonrpc: '2.0', id: message.id, error: toRpcError(error) };
+    }
+  }
+
+  return async function handleMessage(message) {
+    if (!Array.isArray(message)) {
+      return await handleOne(message);
+    }
+    if (message.length === 0) {
+      return errorResponse(null, RPC_ERROR.INVALID_REQUEST, 'Empty batch');
+    }
+    const responses = (await Promise.all(message.map(handleOne))).filter(
+      Boolean
+    );
+    return responses.length > 0 ? responses : null;
+  };
+}
+
+/**
+ * Parse one line and answer it.
+ *
+ * @param {string} line
+ * @param {Function} handleMessage - From {@link createMessageHandler}
+ * @returns {Promise<Object|Object[]|null>}
+ */
+export async function handleLine(line, handleMessage) {
+  if (line.trim() === '') {
+    return null;
+  }
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch (error) {
+    return errorResponse(
+      null,
+      RPC_ERROR.PARSE_ERROR,
+      `Parse error: ${error.message}`
+    );
+  }
+  return await handleMessage(message);
+}
+
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref?.();
+  });
+}
+
+/**
+ * Serve JSON-RPC until `input` ends, then close every session.
+ *
+ * @param {Object} options
+ * @param {Object} options.input - Usually process.stdin
+ * @param {function(string): void} options.write - Writes one line to stdout
+ * @param {Object} [options.dependencies] - Dispatcher dependencies (tests)
+ * @param {number} [options.drainTimeoutMs] - Grace for in-flight requests
+ * @returns {Promise<void>}
+ */
+export async function serveStdio({
+  input,
+  write,
+  dependencies,
+  drainTimeoutMs = DEFAULT_DRAIN_TIMEOUT_MS,
+}) {
+  const send = (message) => write(`${JSON.stringify(message)}\n`);
+  const dispatcher = createDispatcher({
+    dependencies,
+    notify: (method, params) => send({ jsonrpc: '2.0', method, params }),
+  });
+  const handleMessage = createMessageHandler(dispatcher);
+  const pending = new Set();
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  lines.on('line', (line) => {
+    const task = handleLine(line, handleMessage)
+      .then((response) => {
+        if (response) {
+          send(response);
+        }
+      })
+      .catch(() => {});
+    pending.add(task);
+    task.finally(() => pending.delete(task));
+  });
+  await once(lines, 'close');
+  await Promise.race([Promise.allSettled([...pending]), delay(drainTimeoutMs)]);
+  await dispatcher.close();
+}

package/src/cli/sessions.js

@@ -0,0 +1,199 @@
+/**
+ * Browser sessions owned by one `serve --stdio` or `run` dispatcher
+ * (issue #104). A session is a launched or attached browser with the engine
+ * objects behind it: `browser`, `context` and the `page` commands act on.
+ */
+import { invalidParams } from './rpc-error.js';
+
+/** `--browser` names mapped to installed-browser channels. */
+export const BROWSER_CHANNELS = Object.freeze({
+  chrome: 'chrome',
+  edge: 'msedge',
+  msedge: 'msedge',
+  brave: 'brave',
+  chromium: 'chromium',
+});
+
+const ENGINES = Object.freeze(['playwright', 'puppeteer']);
+
+/**
+ * Launch options that are forwarded to `launchBrowser()` as they are, so the
+ * bridge can express everything the old Rust bridge's `launch` operation did.
+ */
+const LAUNCH_PASSTHROUGH = Object.freeze([
+  'args',
+  'extraArgs',
+  'ignoreDefaultArgs',
+  'slowMo',
+  'colorScheme',
+  'channel',
+  'storageState',
+  'fingerprint',
+  'remoteDebuggingPort',
+  'automationParity',
+  'env',
+  'startupTimeout',
+  'attach',
+  'preferences',
+  'localState',
+  'defaultBrowserCheck',
+  'firstRun',
+]);
+
+/** Validate an engine name, defaulting to Playwright. */
+export function resolveEngine(engine = 'playwright') {
+  if (!ENGINES.includes(engine)) {
+    throw invalidParams(
+      `Unsupported engine "${engine}"; expected ${ENGINES.join(' or ')}`
+    );
+  }
+  return engine;
+}
+
+function resolveChannel(browser) {
+  if (browser === undefined) {
+    return undefined;
+  }
+  const channel = BROWSER_CHANNELS[browser];
+  if (!channel) {
+    throw invalidParams(
+      `Unsupported browser "${browser}"; expected chrome, edge, brave or chromium`
+    );
+  }
+  return channel;
+}
+
+function assertStringList(value, name) {
+  if (
+    value !== undefined &&
+    (!Array.isArray(value) || value.some((item) => typeof item !== 'string'))
+  ) {
+    throw invalidParams(`${name} must be an array of strings`);
+  }
+}
+
+/**
+ * Translate `session.launch` params into `launchBrowser()` options.
+ *
+ * @param {Object} params - JSON-RPC params
+ * @returns {Object} launchBrowser options
+ */
+export function buildLaunchOptions(params = {}) {
+  assertStringList(params.restrictions, 'restrictions');
+  assertStringList(params.args, 'args');
+  const options = {
+    engine: resolveEngine(params.engine),
+    headless: params.headless === true,
+  };
+  const channel = resolveChannel(params.browser);
+  const defined = {
+    launch: params.launch,
+    executablePath: params.executablePath,
+    userDataDir: params.userDataDir,
+    restrictions: params.restrictions,
+    channel,
+  };
+  for (const name of LAUNCH_PASSTHROUGH) {
+    defined[name] ??= params[name];
+  }
+  for (const [key, value] of Object.entries(defined)) {
+    if (value !== undefined) {
+      options[key] = value;
+    }
+  }
+  return options;
+}
+
+/**
+ * Build a session from a `launchBrowser()` result.
+ *
+ * Playwright's real launch returns the default context as `browser` and the
+ * CDP-connected `Browser` as `connectedBrowser`; the engine launch returns a
+ * persistent context whose `browser()` is null. Puppeteer returns a Browser.
+ */
+export function sessionFromLaunch(engine, launched) {
+  const playwright = engine === 'playwright';
+  const handle = launched.browser;
+  return {
+    engine,
+    browser: playwright
+      ? (launched.connectedBrowser ?? handle?.browser?.() ?? null)
+      : handle,
+    context: playwright ? handle : (handle?.defaultBrowserContext?.() ?? null),
+    page: launched.page,
+    args: launched.args ?? [],
+    close: () => launched.close(),
+    connected: false,
+  };
+}
+
+/**
+ * Build a session from a `connectBrowser()` result. Closing it only
+ * disconnects: the browser keeps running for the next command.
+ */
+export function sessionFromConnect(engine, connected) {
+  const { browser, page } = connected;
+  const playwright = engine === 'playwright';
+  return {
+    engine,
+    browser,
+    context: playwright
+      ? (page?.context?.() ?? null)
+      : (browser?.defaultBrowserContext?.() ?? null),
+    page,
+    // Playwright's close() on a connectOverCDP browser disconnects;
+    // Puppeteer's close() would quit the browser, disconnect() does not.
+    close: async () => {
+      await connected.downloads?.dispose?.();
+      await (playwright ? browser.close() : browser.disconnect());
+    },
+    connected: true,
+  };
+}
+
+/** Sessions with deterministic ids `s1`, `s2`, … */
+export class SessionTable {
+  constructor() {
+    this.nextId = 1;
+    this.sessions = new Map();
+    this.latest = null;
+  }
+
+  /** Add a session and return its id. */
+  add(session) {
+    const id = `s${this.nextId++}`;
+    this.sessions.set(id, session);
+    this.latest = id;
+    return id;
+  }
+
+  /** The session behind an id (or the latest one when omitted). */
+  get(id) {
+    const resolved = id ?? this.latest;
+    const session = resolved ? this.sessions.get(resolved) : undefined;
+    if (!session) {
+      throw invalidParams(
+        id ? `Unknown session: ${id}` : 'No session; call session.launch first'
+      );
+    }
+    return session;
+  }
+
+  /** Close one session and forget it. */
+  async close(id) {
+    const resolved = id ?? this.latest;
+    const session = this.get(resolved);
+    this.sessions.delete(resolved);
+    if (this.latest === resolved) {
+      this.latest = [...this.sessions.keys()].at(-1) ?? null;
+    }
+    await session.trace?.stop?.().catch(() => {});
+    await session.close();
+  }
+
+  /** Close every session, ignoring individual failures. */
+  async closeAll() {
+    const ids = [...this.sessions.keys()];
+    await Promise.all(ids.map((id) => this.close(id).catch(() => {})));
+  }
+}

package/src/core/constants.js

@@ -1,5 +1,11 @@
 /**
- * Common Chrome arguments used across both Playwright and Puppeteer
+ * The switches Browser Commander added to every launch before issue #103.
+ *
+ * They are no longer added by default: a launch starts Chrome with only
+ * `--user-data-dir` and `--remote-debugging-port`. The list is kept for
+ * callers that relied on it and equals the `legacy-defaults` restriction
+ * preset, so `launchBrowser({ restrictions: ['legacy-defaults'] })` restores
+ * the old command line.
  */
 export const CHROME_ARGS = [
   '--disable-session-crashed-bubble',

package/src/core/engine-adapter.js

@@ -606,9 +606,115 @@ export function createEngineAdapter(page, engine) {
     return new PlaywrightAdapter(page);
   } else if (engine === 'puppeteer') {
     return new PuppeteerAdapter(page);
+  } else if (engine === 'selenium') {
+    return new SeleniumAdapter(page);
   } else {
     throw new Error(
-      `Unsupported engine: ${engine}. Expected 'playwright' or 'puppeteer'`
+      `Unsupported engine: ${engine}. Expected 'playwright', 'puppeteer' or 'selenium'`
     );
   }
 }
+
+/**
+ * Selenium (WebDriver) adapter implementation (issue #104).
+ *
+ * The page is a `WebDriverPage` facade, which already speaks the Puppeteer
+ * page API, so everything not listed here is the Puppeteer implementation.
+ * The overrides use WebDriver's native element commands where they exist:
+ * Element Click, Element Send Keys and Element Clear run the browser's own
+ * interactability checks and produce trusted input events.
+ */
+export class SeleniumAdapter extends PuppeteerAdapter {
+  getEngineName() {
+    return 'selenium';
+  }
+
+  async click(locatorOrElement, options = {}) {
+    if (options.force) {
+      // Element Click refuses an obscured element; force means "click where
+      // it is anyway", which is a pointer action at the element's centre.
+      await this.page.evaluate(
+        (el) => el.scrollIntoView({ block: 'center', inline: 'center' }),
+        locatorOrElement
+      );
+      await this.page.driver
+        .actions({ async: true })
+        .move({ origin: locatorOrElement })
+        .click()
+        .perform();
+    } else {
+      await locatorOrElement.click();
+    }
+    // A click may navigate; page.url() should say where it went.
+    await this.page.syncUrl();
+  }
+
+  async type(locatorOrElement, text) {
+    await locatorOrElement.sendKeys(text);
+  }
+
+  async fill(locatorOrElement, text) {
+    await locatorOrElement.clear();
+    await locatorOrElement.sendKeys(text);
+  }
+
+  async focus(locatorOrElement) {
+    await this.page.evaluate((el) => el.focus(), locatorOrElement);
+  }
+
+  // ============================================================================
+  // WebDriver and BiDi access
+  // ============================================================================
+
+  /** @returns {Object} The selenium-webdriver WebDriver */
+  getDriver() {
+    return this.page.driver;
+  }
+
+  /** @returns {Promise<Object|null>} The BiDi connection, null for classic */
+  getBidi() {
+    return this.page.bidi();
+  }
+
+  /**
+   * Subscribe to a raw BiDi event, e.g. 'log.entryAdded'.
+   * @returns {Promise<{unsubscribe: Function}>}
+   */
+  onBidiEvent(method, handler) {
+    return this.page.subscribeBidi(method, handler);
+  }
+
+  /**
+   * Receive console messages (BiDi `log.entryAdded`).
+   * @param {Function} handler - Receives a Puppeteer-shaped ConsoleMessage
+   * @returns {Promise<Function>} Resolves once subscribed, to an unsubscribe
+   */
+  onConsoleMessage(handler) {
+    return this._listen('console', handler);
+  }
+
+  /**
+   * Receive top-level navigations (BiDi browsingContext events).
+   * @param {Function} handler - Receives the new URL
+   * @returns {Promise<Function>} Resolves once subscribed, to an unsubscribe
+   */
+  onNavigation(handler) {
+    return this._listen('framenavigated', (frame) => handler(frame.url()));
+  }
+
+  async _listen(eventName, handler) {
+    await this.page.requireBidi(`page "${eventName}" events`);
+    this.page.on(eventName, handler);
+    await this.page.eventsReady();
+    return () => this.page.off(eventName, handler);
+  }
+
+  /**
+   * Navigate with BiDi `browsingContext.navigate`.
+   * @param {string} url
+   * @param {Object} [options] - {wait: 'none'|'interactive'|'complete'}
+   */
+  navigate(url, options = {}) {
+    return this.page.navigateBidi(url, options);
+  }
+}

package/src/core/engine-detection.js

@@ -2,10 +2,25 @@ import { isVerboseEnabled } from './logger.js';
 
 /**
  * Detect which browser automation engine is being used
- * @param {Object} pageOrContext - Page or context object from Playwright or Puppeteer
- * @returns {string} - 'playwright' or 'puppeteer'
+ * @param {Object} pageOrContext - Page or context object from Playwright or
+ *   Puppeteer, a selenium-webdriver WebDriver, or a WebDriverPage over one
+ * @returns {string} - 'playwright', 'puppeteer' or 'selenium'
  */
 export function detectEngine(pageOrContext) {
+  // Selenium first: the WebDriverPage facade has $eval/$$eval like Puppeteer,
+  // and a bare WebDriver has none of the page methods the checks below use.
+  if (
+    pageOrContext.isWebDriverPage === true ||
+    (typeof pageOrContext.findElements === 'function' &&
+      typeof pageOrContext.executeScript === 'function' &&
+      typeof pageOrContext.getCurrentUrl === 'function')
+  ) {
+    if (isVerboseEnabled()) {
+      console.log('🔍 [ENGINE DETECTION] Detected: selenium');
+    }
+    return 'selenium';
+  }
+
   const hasEval = !!pageOrContext.$eval;
   const hasEvalAll = !!pageOrContext.$$eval;
   const locatorType = typeof pageOrContext.locator;
@@ -44,6 +59,6 @@ export function detectEngine(pageOrContext) {
     console.log('🔍 [ENGINE DETECTION] Could not detect engine!');
   }
   throw new Error(
-    'Unknown browser automation engine. Expected Playwright or Puppeteer page object.'
+    'Unknown browser automation engine. Expected a Playwright or Puppeteer page, or a selenium-webdriver WebDriver.'
   );
 }

package/src/core/navigation-safety.js

@@ -27,6 +27,10 @@ export function isNavigationError(error) {
     'Frame was detached',
     'context was destroyed',
     'Page crashed',
+    // WebDriver (selenium engine): an element or window from the previous
+    // document after a navigation.
+    'stale element reference',
+    'no such window',
   ];
 
   return navigationErrorPatterns.some((pattern) =>