browser-commander 0.19.0 → 0.21.0

package/src/cli/main.js

@@ -0,0 +1,67 @@
+/**
+ * Entry point of the `browser-commander` CLI (issue #104).
+ *
+ * Every command writes exactly one JSON document to stdout. Exit codes: 0
+ * success, 1 error, 2 `doctor` found an unlisted difference, 64 usage error.
+ */
+import { parseCommandLine, UsageError } from './args.js';
+import { COMMAND_HANDLERS } from './commands.js';
+import { describeError, RPC_ERROR, RpcError } from './rpc-error.js';
+
+/** Process exit codes. */
+export const EXIT_CODES = Object.freeze({
+  OK: 0,
+  ERROR: 1,
+  UNLISTED_DIFFERENCE: 2,
+  USAGE: 64,
+});
+
+function isUsageError(error) {
+  return (
+    error instanceof UsageError ||
+    (error instanceof RpcError && error.code === RPC_ERROR.INVALID_PARAMS)
+  );
+}
+
+/**
+ * Run the CLI.
+ *
+ * @param {string[]} argv - Arguments after the program name
+ * @param {Object} [io]
+ * @param {{write: function(string): unknown}} [io.stdout=process.stdout]
+ * @param {Object} [io.stdin=process.stdin]
+ * @param {Object} [io.signals=process] - Emits SIGINT/SIGTERM
+ * @param {Object} [io.dependencies] - Dispatcher dependencies (tests)
+ * @returns {Promise<number>} The exit code
+ */
+export async function runCli(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const write = (text) => stdout.write(text);
+  const print = (document) => write(`${JSON.stringify(document)}\n`);
+  const context = {
+    write,
+    print,
+    stdin: io.stdin ?? process.stdin,
+    signals: io.signals ?? process,
+    dependencies: io.dependencies,
+  };
+  try {
+    const parsed = parseCommandLine(argv);
+    const { document, exitCode } = await COMMAND_HANDLERS[parsed.command](
+      parsed,
+      context
+    );
+    if (document !== null) {
+      print(document);
+    }
+    return exitCode;
+  } catch (error) {
+    const usage = isUsageError(error);
+    print({
+      error: usage
+        ? { name: 'UsageError', message: error.message }
+        : describeError(error),
+    });
+    return usage ? EXIT_CODES.USAGE : EXIT_CODES.ERROR;
+  }
+}

package/src/cli/modules.js

@@ -0,0 +1,100 @@
+/**
+ * The library functions the CLI dispatcher calls, loaded on first use.
+ *
+ * Loading lazily keeps `browser-commander version` fast and lets commands
+ * whose module is not installed (an optional engine, or a feature shipped by
+ * a later release) fail with a JSON error instead of breaking every command.
+ * Tests replace any entry through the dispatcher's `dependencies` object.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+
+const PACKAGE_JSON = new URL('../../package.json', import.meta.url);
+
+/** Import a module, turning "not installed" into a readable error. */
+export async function importOptional(specifier, feature) {
+  try {
+    return await import(specifier);
+  } catch (error) {
+    if (
+      error?.code === 'ERR_MODULE_NOT_FOUND' ||
+      error?.code === 'MODULE_NOT_FOUND'
+    ) {
+      throw new Error(`${feature} is not available: ${error.message}`, {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+}
+
+/** Read the package name and version for `version`. */
+export async function readPackageInfo() {
+  const { name, version } = JSON.parse(await readFile(PACKAGE_JSON, 'utf8'));
+  return { name, version, language: 'js' };
+}
+
+/**
+ * Render a trace bundle's static viewer, into the bundle by default or to
+ * `output`.
+ *
+ * @param {string} bundlePath
+ * @param {string} [output]
+ * @returns {Promise<string>} The written file
+ */
+export async function writeTraceViewer(bundlePath, output) {
+  const viewer = await import('../traces/viewer.js');
+  if (!output) {
+    return await viewer.writeTraceViewer(bundlePath);
+  }
+  const { readTrace } = await import('../traces/reader.js');
+  const document = await viewer.renderTraceViewer(await readTrace(bundlePath));
+  await writeFile(output, document);
+  return output;
+}
+
+/** Default implementations; every entry is a zero-coupling async function. */
+export const DEFAULT_DEPENDENCIES = Object.freeze({
+  packageInfo: readPackageInfo,
+  launchBrowser: async (options) =>
+    (await import('../browser/launcher.js')).launchBrowser(options),
+  connectBrowser: async (options) =>
+    (await import('../browser/connector.js')).connectBrowser(options),
+  startTrace: async (options) =>
+    (await import('../traces/recorder.js')).startTrace(options),
+  writeTraceViewer,
+  readBrowserCookies: async (options) =>
+    (await import('../browser/browser-cookies.js')).readBrowserCookies(options),
+  loadEngine: (name) => importOptional(name, `The ${name} engine`),
+  openInUserBrowser: async (url) =>
+    (
+      await importOptional(
+        '../browser/open-in-user-browser.js',
+        'open (openInUserBrowser)'
+      )
+    ).openInUserBrowser(url),
+  migrateProfile: async (options) =>
+    (
+      await importOptional(
+        '../browser/migration/index.js',
+        'profile migrate (migrateProfile)'
+      )
+    ).migrateProfile(options),
+  snapshotUserDataDir: async (options) =>
+    (
+      await importOptional(
+        '../browser/attach/snapshot.js',
+        'profile snapshot (snapshotUserDataDir)'
+      )
+    ).snapshotUserDataDir(options),
+  attachUserBrowser: async (options) =>
+    (
+      await importOptional(
+        '../browser/attach/index.js',
+        'attach (attachUserBrowser)'
+      )
+    ).attachUserBrowser(options),
+  measureParity: async (options) =>
+    (
+      await importOptional('../browser/parity.js', 'doctor (measureParity)')
+    ).measureParity(options),
+});

package/src/cli/rpc-error.js

@@ -0,0 +1,77 @@
+/**
+ * JSON-RPC 2.0 error codes used by `serve --stdio` and `run` (issue #104).
+ * See docs/cli-and-bridge.md, "Errors".
+ */
+export const RPC_ERROR = Object.freeze({
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  ENGINE_ERROR: -32000,
+});
+
+/** An error that carries its JSON-RPC code. */
+export class RpcError extends Error {
+  /**
+   * @param {number} code - One of {@link RPC_ERROR}
+   * @param {string} message - Human-readable message
+   * @param {Object} [data] - Optional structured detail
+   */
+  constructor(code, message, data) {
+    super(message);
+    this.name = 'RpcError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/** Shorthand for an invalid-params error. */
+export function invalidParams(message) {
+  return new RpcError(RPC_ERROR.INVALID_PARAMS, message);
+}
+
+/** A required non-empty string param, or an invalid-params error. */
+export function requireString(params, name) {
+  const value = params[name];
+  if (typeof value !== 'string' || value === '') {
+    throw invalidParams(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+/** `{name, message}` of any thrown value. */
+export function describeError(error) {
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message };
+  }
+  return { name: 'Error', message: String(error) };
+}
+
+/**
+ * The JSON-RPC `error` member for a thrown value: an {@link RpcError} keeps its
+ * code, anything else is an engine error with name, message and stack.
+ *
+ * @param {unknown} error
+ * @param {Object} [options]
+ * @param {boolean} [options.stack=true] - Include the stack in `data`
+ * @returns {{code: number, message: string, data: (Object|undefined)}}
+ */
+export function toRpcError(error, { stack = true } = {}) {
+  if (error instanceof RpcError) {
+    return {
+      code: error.code,
+      message: error.message,
+      ...(error.data === undefined ? {} : { data: error.data }),
+    };
+  }
+  const { name, message } = describeError(error);
+  return {
+    code: RPC_ERROR.ENGINE_ERROR,
+    message,
+    data: {
+      name,
+      message,
+      ...(stack && error instanceof Error ? { stack: error.stack } : {}),
+    },
+  };
+}

package/src/cli/script.js

@@ -0,0 +1,77 @@
+/**
+ * `browser-commander run <script.json>`: execute a command script through the
+ * same dispatcher as `serve --stdio` (docs/cli-and-bridge.md,
+ * "Command scripts").
+ */
+import { createDispatcher, substituteSession } from './dispatcher.js';
+import { toRpcError } from './rpc-error.js';
+
+/**
+ * Check the script shape: `{"steps": [{"method": "…", "params": {…}}]}`.
+ *
+ * @param {unknown} script
+ * @returns {Object[]} The steps
+ */
+export function validateScript(script) {
+  const steps = script?.steps;
+  if (!Array.isArray(steps)) {
+    throw new TypeError('A command script must be {"steps": [...]}');
+  }
+  steps.forEach((step, index) => {
+    if (typeof step?.method !== 'string') {
+      throw new TypeError(`Step ${index + 1} has no "method"`);
+    }
+  });
+  return steps;
+}
+
+async function runStep(dispatcher, step, params) {
+  try {
+    return {
+      method: step.method,
+      result: (await dispatcher.dispatch(step.method, params)) ?? null,
+    };
+  } catch (error) {
+    // Stacks differ between machines and languages; the name and message
+    // are what the cross-language comparison needs.
+    return { method: step.method, error: toRpcError(error, { stack: false }) };
+  }
+}
+
+/**
+ * Run every step in order. A failed step is recorded and the script goes on,
+ * so later steps (such as `session.close`) still run. Sessions left open are
+ * closed at the end.
+ *
+ * @param {Object} script - The parsed command script
+ * @param {Object} [options]
+ * @param {Object} [options.dependencies] - Dispatcher dependencies (tests)
+ * @param {Object} [options.launchDefaults] - `session.launch` params used when a step leaves them out
+ * @returns {Promise<{results: Object[], failed: boolean}>}
+ */
+export async function runScript(script, options = {}) {
+  const { dependencies, launchDefaults = {} } = options;
+  const steps = validateScript(script);
+  const dispatcher = createDispatcher({ dependencies });
+  const results = [];
+  let latestSession = null;
+  try {
+    for (const step of steps) {
+      const params = substituteSession(step.params ?? {}, latestSession);
+      const entry = await runStep(
+        dispatcher,
+        step,
+        step.method === 'session.launch'
+          ? { ...launchDefaults, ...params }
+          : params
+      );
+      if (typeof entry.result?.session === 'string') {
+        latestSession = entry.result.session;
+      }
+      results.push(entry);
+    }
+  } finally {
+    await dispatcher.close();
+  }
+  return { results, failed: results.some((entry) => 'error' in entry) };
+}

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,195 @@
+/**
+ * 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',
+]);
+
+/** 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',