browser-commander 0.20.0 → 0.21.1

package/src/cli/high-level-methods.js

@@ -0,0 +1,310 @@
+/**
+ * High-level JSON-RPC methods (docs/cli-and-bridge.md, "High-level methods").
+ * They mirror the CLI commands and return plain JSON, so the same command
+ * script gives the same results in JS, Rust and Python.
+ *
+ * Every method is `(state, params) => result`, where `state` is the
+ * dispatcher state built by `createDispatcher()`.
+ */
+import path from 'node:path';
+
+import { invalidParams, requireString } from './rpc-error.js';
+import {
+  buildLaunchOptions,
+  resolveEngine,
+  sessionFromConnect,
+  sessionFromLaunch,
+} from './sessions.js';
+
+function sessionOf(state, params) {
+  return state.sessions.get(params.session);
+}
+
+async function launchSession(state, params) {
+  const options = buildLaunchOptions(params);
+  const launched = await state.dependencies.launchBrowser(options);
+  const session = state.sessions.add(
+    sessionFromLaunch(options.engine, launched)
+  );
+  return {
+    session,
+    cdpEndpoint: launched.cdpEndpoint ?? null,
+    remoteDebuggingPort: launched.remoteDebuggingPort ?? null,
+    userDataDir: launched.userDataDir ?? null,
+    temporaryProfile: launched.temporaryProfile ?? false,
+    ...(launched.attach ? { attach: launched.attach } : {}),
+  };
+}
+
+async function connectSession(state, params) {
+  const cdpEndpoint = requireString(params, 'cdpEndpoint');
+  const engine = resolveEngine(params.engine);
+  const connected = await state.dependencies.connectBrowser({
+    engine,
+    cdpEndpoint,
+  });
+  const session = state.sessions.add(sessionFromConnect(engine, connected));
+  return { session, cdpEndpoint };
+}
+
+async function closeSession(state, params) {
+  await state.sessions.close(params.session);
+  return { closed: true };
+}
+
+async function goto(state, params) {
+  const { page } = sessionOf(state, params);
+  await page.goto(requireString(params, 'url'));
+  return { url: page.url(), title: await page.title() };
+}
+
+async function click(state, params) {
+  const selector = requireString(params, 'selector');
+  await sessionOf(state, params).page.click(selector);
+  return { clicked: selector };
+}
+
+async function fill(state, params) {
+  const selector = requireString(params, 'selector');
+  const value = params.value === undefined ? '' : String(params.value);
+  const { engine, page } = sessionOf(state, params);
+  if (engine === 'playwright') {
+    await page.fill(selector, value);
+  } else {
+    await page.locator(selector).fill(value);
+  }
+  return { filled: selector, value };
+}
+
+async function evaluate(state, params) {
+  const expression = requireString(params, 'expression');
+  const value = await sessionOf(state, params).page.evaluate(expression);
+  return { value: value === undefined ? null : value };
+}
+
+/** Write to `path` when given, otherwise return the bytes inline. */
+async function capture(params, write) {
+  if (params.path !== undefined) {
+    const target = path.resolve(requireString(params, 'path'));
+    const bytes = await write({ path: target });
+    return { path: target, bytes: bytes.length };
+  }
+  const bytes = await write({});
+  return { data: { $binary: Buffer.from(bytes).toString('base64') } };
+}
+
+function screenshot(state, params) {
+  const { page } = sessionOf(state, params);
+  return capture(params, (options) =>
+    page.screenshot({ ...options, fullPage: params.fullPage === true })
+  );
+}
+
+function pdf(state, params) {
+  const { page } = sessionOf(state, params);
+  return capture(params, (options) => page.pdf(options));
+}
+
+async function traceStart(state, params) {
+  const session = sessionOf(state, params);
+  if (session.trace) {
+    throw invalidParams('A trace is already recording in this session');
+  }
+  const output = path.resolve(requireString(params, 'out'));
+  session.trace = await state.dependencies.startTrace({
+    page: session.page,
+    output,
+  });
+  return { trace: session.trace.path ?? output };
+}
+
+async function traceStop(state, params) {
+  const session = sessionOf(state, params);
+  if (!session.trace) {
+    throw invalidParams('No trace is recording in this session');
+  }
+  const { trace } = session;
+  session.trace = null;
+  await trace.stop();
+  return { trace: trace.path };
+}
+
+function cookieKey(cookie) {
+  return `${cookie.domain}\t${cookie.path}\t${cookie.name}`;
+}
+
+async function readCookies(state, params) {
+  const from = requireString(params, 'from');
+  const domains = params.domains ?? [];
+  if (!Array.isArray(domains)) {
+    throw invalidParams('domains must be an array of strings');
+  }
+  const filters = domains.length > 0 ? domains : [undefined];
+  const unique = new Map();
+  for (const domainFilter of filters) {
+    const cookies = await state.dependencies.readBrowserCookies({
+      browser: from,
+      profile: params.profile,
+      domainFilter,
+      ignoreDecryptionErrors: true,
+    });
+    for (const cookie of cookies) {
+      unique.set(cookieKey(cookie), cookie);
+    }
+  }
+  return [...unique.values()];
+}
+
+function cookieAdder({ engine, context, page }) {
+  return engine === 'playwright'
+    ? (cookies) => context.addCookies(cookies)
+    : (cookies) => page.setCookie(...cookies);
+}
+
+/**
+ * Import cookies from an installed browser profile into the session. A batch
+ * that the engine rejects is retried one cookie at a time, so one malformed
+ * cookie is reported in `skipped` instead of failing the whole import.
+ */
+async function importCookies(state, params) {
+  const session = sessionOf(state, params);
+  const cookies = await readCookies(state, params);
+  const add = cookieAdder(session);
+  if (cookies.length === 0) {
+    return { imported: 0, skipped: [] };
+  }
+  try {
+    await add(cookies);
+    return { imported: cookies.length, skipped: [] };
+  } catch {
+    const skipped = [];
+    for (const cookie of cookies) {
+      await add([cookie]).catch((error) =>
+        skipped.push({
+          item: `${cookie.domain} ${cookie.name}`,
+          reason: error.message,
+        })
+      );
+    }
+    return { imported: cookies.length - skipped.length, skipped };
+  }
+}
+
+function migrateProfile(state, params) {
+  return state.dependencies.migrateProfile({
+    from: params.from,
+    profile: params.profile,
+    to: params.to,
+    include: params.include,
+    domains: params.domains,
+  });
+}
+
+function snapshotProfile(state, params) {
+  return state.dependencies.snapshotUserDataDir({
+    browser: requireString(params, 'from'),
+    profile: params.profile,
+    userDataDir: params.userDataDir,
+    to: params.to,
+  });
+}
+
+function relayOf(state) {
+  if (!state.relay) {
+    throw invalidParams('No extension is attached; call attach first');
+  }
+  return state.relay;
+}
+
+/**
+ * Start the extension relay and wait for the companion extension. The relay
+ * stays open until `attach.close` or the end of the connection.
+ */
+async function attach(state, params) {
+  if (params.mode !== 'extension') {
+    throw invalidParams(
+      `attach supports mode "extension", got ${JSON.stringify(params.mode)}; use session.launch with attach for a snapshot and open for the user's browser`
+    );
+  }
+  if (state.relay) {
+    throw invalidParams('An extension is already attached; call attach.close');
+  }
+  const relay = await state.dependencies.attachUserBrowser({
+    mode: 'extension',
+    port: params.port,
+    host: params.host,
+    timeoutMs: params.timeoutMs,
+    allowedExtensionIds: params.allowedExtensionIds,
+  });
+  state.relay = relay;
+  return {
+    mode: relay.mode,
+    extension: relay.extension,
+    tabs: await relay.tabs(),
+    differences: relay.differences,
+  };
+}
+
+async function attachTabs(state) {
+  return await relayOf(state).tabs();
+}
+
+/** Send one CDP command to a tab of the attached browser. */
+async function attachSend(state, params) {
+  const relay = relayOf(state);
+  if (!Number.isInteger(params.tabId)) {
+    throw invalidParams('tabId must be an integer');
+  }
+  const session = await relay.session(params.tabId);
+  return await session.send(
+    requireString(params, 'method'),
+    params.params ?? {}
+  );
+}
+
+async function attachClose(state) {
+  const { relay } = state;
+  state.relay = null;
+  await relay?.close();
+  return { closed: Boolean(relay) };
+}
+
+async function open(state, params) {
+  const url = requireString(params, 'url');
+  const result = await state.dependencies.openInUserBrowser(url);
+  return result && typeof result === 'object' ? result : { opened: url };
+}
+
+/** `measureParity()` takes launch options: engine, channel, executablePath… */
+function doctor(state, params) {
+  return state.dependencies.measureParity(buildLaunchOptions(params));
+}
+
+function version(state) {
+  return state.dependencies.packageInfo();
+}
+
+/** Method name to implementation. */
+export const HIGH_LEVEL_METHODS = Object.freeze({
+  'session.launch': launchSession,
+  'session.connect': connectSession,
+  'session.close': closeSession,
+  'page.goto': goto,
+  'page.click': click,
+  'page.fill': fill,
+  'page.eval': evaluate,
+  'page.screenshot': screenshot,
+  'page.pdf': pdf,
+  'trace.start': traceStart,
+  'trace.stop': traceStop,
+  'cookies.import': importCookies,
+  'profile.migrate': migrateProfile,
+  'profile.snapshot': snapshotProfile,
+  attach,
+  'attach.tabs': attachTabs,
+  'attach.send': attachSend,
+  'attach.close': attachClose,
+  open,
+  doctor,
+  version,
+});

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