browser-commander 0.19.0 → 0.21.0

package/src/cli/handle-methods.js

@@ -0,0 +1,136 @@
+/**
+ * Generic handle methods (docs/cli-and-bridge.md, "Generic handle methods").
+ *
+ * They reach every public method of Playwright and Puppeteer through remote
+ * object handles, so a Rust or Python program - or a shell script - can call
+ * `page.route()`, `locator.boundingBox()` or `cdpSession.send()` without a
+ * native binding for each of them.
+ */
+import { decodeValue, describeObject, encodeValue } from './handles.js';
+import { invalidParams, requireString } from './rpc-error.js';
+
+const ENGINE_ROOTS = Object.freeze(['playwright', 'puppeteer']);
+
+function targetOf(state, params) {
+  const handle = params.handle;
+  const id = typeof handle === 'object' && handle ? handle.$handle : handle;
+  return state.handles.get(requireString({ id }, 'id'));
+}
+
+/** Roots are always handles, even when the engine object is a plain object. */
+function handleOrNull(state, value) {
+  return value === null || value === undefined
+    ? null
+    : state.handles.register(value);
+}
+
+/**
+ * `playwright` and `puppeteer` resolve to the engine's entry object;
+ * `session:<id>` to the session's browser, context and page.
+ */
+async function root(state, params) {
+  const name = requireString(params, 'name');
+  if (name.startsWith('session:')) {
+    const session = state.sessions.get(name.slice('session:'.length));
+    return {
+      browser: handleOrNull(state, session.browser),
+      context: handleOrNull(state, session.context),
+      page: handleOrNull(state, session.page),
+    };
+  }
+  if (!ENGINE_ROOTS.includes(name)) {
+    throw invalidParams(
+      `Unknown root "${name}"; expected playwright, puppeteer or session:<id>`
+    );
+  }
+  const module = await state.dependencies.loadEngine(name);
+  return state.handles.register(module.default ?? module);
+}
+
+async function call(state, params) {
+  const target = targetOf(state, params);
+  const method = requireString(params, 'method');
+  const args = params.args ?? [];
+  if (!Array.isArray(args)) {
+    throw invalidParams('args must be an array');
+  }
+  if (typeof target?.[method] !== 'function') {
+    throw invalidParams(`${method} is not a method of this handle`);
+  }
+  const result = await target[method](...decodeValue(args, state.handles));
+  return encodeValue(result, state.handles);
+}
+
+async function get(state, params) {
+  const target = targetOf(state, params);
+  const property = requireString(params, 'property');
+  const value = target?.[property];
+  return encodeValue(
+    value instanceof Promise ? await value : value,
+    state.handles
+  );
+}
+
+function dispose(state, params) {
+  const id =
+    typeof params.handle === 'object' && params.handle
+      ? params.handle.$handle
+      : params.handle;
+  if (!state.handles.dispose(requireString({ id }, 'id'))) {
+    throw invalidParams(`Unknown handle: ${id}`);
+  }
+  return { disposed: true };
+}
+
+function describe(state, params) {
+  return describeObject(targetOf(state, params));
+}
+
+function subscribe(state, params) {
+  const target = targetOf(state, params);
+  const event = requireString(params, 'event');
+  if (typeof target?.on !== 'function') {
+    throw invalidParams('This handle does not emit events');
+  }
+  const subscription = `e${state.nextSubscription++}`;
+  const listener = (...args) =>
+    state.notify('events.emit', {
+      subscription,
+      args: args.map((arg) => encodeValue(arg, state.handles)),
+    });
+  target.on(event, listener);
+  state.subscriptions.set(subscription, { target, event, listener });
+  return { subscription };
+}
+
+/** Remove one subscription's listener. */
+export function removeSubscription(state, subscription) {
+  const entry = state.subscriptions.get(subscription);
+  if (!entry) {
+    return false;
+  }
+  state.subscriptions.delete(subscription);
+  const { target, event, listener } = entry;
+  const off = target.off ?? target.removeListener;
+  off?.call(target, event, listener);
+  return true;
+}
+
+function unsubscribe(state, params) {
+  const subscription = requireString(params, 'subscription');
+  if (!removeSubscription(state, subscription)) {
+    throw invalidParams(`Unknown subscription: ${subscription}`);
+  }
+  return { unsubscribed: true };
+}
+
+/** Method name to implementation. */
+export const HANDLE_METHODS = Object.freeze({
+  'handle.root': root,
+  'handle.call': call,
+  'handle.get': get,
+  'handle.dispose': dispose,
+  'handle.describe': describe,
+  'events.subscribe': subscribe,
+  'events.unsubscribe': unsubscribe,
+});

package/src/cli/handles.js

@@ -0,0 +1,273 @@
+/**
+ * Remote object handles and the value encoding of the `serve --stdio` bridge
+ * (issue #104, docs/cli-and-bridge.md "Value encoding").
+ *
+ * JSON values cross the bridge unchanged. Anything else - an engine object, a
+ * function, a buffer, a date - is tagged, so a client in any language can hold
+ * a Playwright `Page` or a Puppeteer `ElementHandle` as `{"$handle": "h3"}`
+ * and pass it back as an argument.
+ */
+import { invalidParams } from './rpc-error.js';
+
+const TAGS = Object.freeze([
+  '$handle',
+  '$binary',
+  '$function',
+  '$undefined',
+  '$date',
+  '$regexp',
+  '$bigint',
+  '$error',
+]);
+
+function isModuleNamespace(value) {
+  return Object.prototype.toString.call(value) === '[object Module]';
+}
+
+/** True for `{}` literals and null-prototype records, not class instances. */
+export function isPlainObject(value) {
+  if (value === null || typeof value !== 'object' || isModuleNamespace(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isBinary(value) {
+  return value instanceof Uint8Array || value instanceof ArrayBuffer;
+}
+
+/**
+ * The class name a client sees for a handle.
+ *
+ * Bundlers rename colliding classes (`Page2`), so a trailing number after a
+ * lowercase letter is dropped to keep the public name.
+ */
+export function typeName(value) {
+  if (typeof value === 'function') {
+    return 'Function';
+  }
+  const name = value?.constructor?.name;
+  if (!name || isModuleNamespace(value)) {
+    return 'Object';
+  }
+  return name.replace(/(?<=[a-z])\d+$/u, '');
+}
+
+/**
+ * A table of remote objects with deterministic ids (`h1`, `h2`, …).
+ *
+ * The same object always gets the same id while it is registered, so a page
+ * returned by two calls is one handle.
+ */
+export class HandleTable {
+  constructor() {
+    this.nextId = 1;
+    this.byId = new Map();
+    this.idOf = new Map();
+  }
+
+  /** Register an object (or reuse its id) and return the encoded handle. */
+  register(value) {
+    let id = this.idOf.get(value);
+    if (!id) {
+      id = `h${this.nextId++}`;
+      this.byId.set(id, value);
+      this.idOf.set(value, id);
+    }
+    return { $handle: id, type: typeName(value) };
+  }
+
+  /** The object behind an id, or an invalid-params error. */
+  get(id) {
+    if (!this.byId.has(id)) {
+      throw invalidParams(`Unknown handle: ${id}`);
+    }
+    return this.byId.get(id);
+  }
+
+  /** Forget a handle. Returns whether it existed. */
+  dispose(id) {
+    if (!this.byId.has(id)) {
+      return false;
+    }
+    this.idOf.delete(this.byId.get(id));
+    this.byId.delete(id);
+    return true;
+  }
+}
+
+function encodeError(error) {
+  return { $error: { name: error.name, message: error.message } };
+}
+
+/**
+ * Encode a value for the wire.
+ *
+ * @param {unknown} value
+ * @param {HandleTable} handles - Where non-JSON objects are registered
+ * @param {Set<Object>} [seen] - Cycle guard for plain objects and arrays
+ * @returns {unknown} JSON-compatible value
+ */
+export function encodeValue(value, handles, seen = new Set()) {
+  if (value === undefined) {
+    return { $undefined: true };
+  }
+  if (value === null || ['boolean', 'string'].includes(typeof value)) {
+    return value;
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === 'bigint') {
+    return { $bigint: value.toString() };
+  }
+  if (typeof value === 'symbol') {
+    return value.toString();
+  }
+  if (isBinary(value)) {
+    return { $binary: Buffer.from(value).toString('base64') };
+  }
+  if (value instanceof Date) {
+    return { $date: value.toISOString() };
+  }
+  if (value instanceof RegExp) {
+    return { $regexp: { source: value.source, flags: value.flags } };
+  }
+  if (value instanceof Error) {
+    return encodeError(value);
+  }
+  const container = Array.isArray(value) || isPlainObject(value);
+  if (!container || seen.has(value)) {
+    return handles.register(value);
+  }
+  seen.add(value);
+  const encoded = Array.isArray(value)
+    ? value.map((item) => encodeValue(item, handles, seen))
+    : Object.fromEntries(
+        Object.entries(value).map(([key, item]) => [
+          key,
+          encodeValue(item, handles, seen),
+        ])
+      );
+  seen.delete(value);
+  return encoded;
+}
+
+/**
+ * Compile a `$function` source on the server.
+ *
+ * The result's `toString()` is the original source, which is what both
+ * engines serialize when the function is evaluated in the page.
+ */
+export function compileFunction(source) {
+  if (typeof source !== 'string' || source.trim() === '') {
+    throw invalidParams('$function must be a function source string');
+  }
+  let compiled;
+  try {
+    compiled = (0, eval)(`(${source})`);
+  } catch (error) {
+    throw invalidParams(`Invalid $function source: ${error.message}`);
+  }
+  if (typeof compiled !== 'function') {
+    throw invalidParams('$function source did not evaluate to a function');
+  }
+  return compiled;
+}
+
+function decodeError({ name = 'Error', message = '' } = {}) {
+  const error = new Error(message);
+  error.name = name;
+  return error;
+}
+
+const DECODERS = {
+  $handle: (tag, handles) => handles.get(tag),
+  $binary: (tag) => Buffer.from(String(tag), 'base64'),
+  $function: (tag) => compileFunction(tag),
+  $undefined: () => undefined,
+  $date: (tag) => new Date(tag),
+  $regexp: (tag) => new RegExp(tag?.source ?? '', tag?.flags ?? ''),
+  $bigint: (tag) => BigInt(tag),
+  $error: (tag) => decodeError(tag),
+};
+
+function tagOf(value) {
+  return TAGS.find((tag) => Object.hasOwn(value, tag));
+}
+
+/**
+ * Decode a value received from a client.
+ *
+ * @param {unknown} value
+ * @param {HandleTable} handles - Resolves `$handle` references
+ * @returns {unknown}
+ */
+export function decodeValue(value, handles) {
+  if (Array.isArray(value)) {
+    return value.map((item) => decodeValue(item, handles));
+  }
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  const tag = tagOf(value);
+  if (tag) {
+    return DECODERS[tag](value[tag], handles);
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      decodeValue(item, handles),
+    ])
+  );
+}
+
+function isPublicName(name) {
+  return (
+    typeof name === 'string' && name !== 'constructor' && !name.startsWith('_')
+  );
+}
+
+function collectMembers(target) {
+  const methods = new Set();
+  const properties = new Set();
+  let current = target;
+  while (current && current !== Object.prototype) {
+    for (const name of Object.getOwnPropertyNames(current)) {
+      if (!isPublicName(name) || (current === target && name === 'prototype')) {
+        continue;
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(current, name);
+      if (typeof descriptor.value === 'function') {
+        methods.add(name);
+      } else {
+        properties.add(name);
+      }
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  for (const name of methods) {
+    properties.delete(name);
+  }
+  return { methods, properties };
+}
+
+/**
+ * Describe a remote object: every callable member on the object and its
+ * prototype chain, and its other public properties.
+ *
+ * @param {unknown} target
+ * @returns {{type: string, methods: string[], properties: string[]}}
+ */
+export function describeObject(target) {
+  const { methods, properties } =
+    target !== null && ['object', 'function'].includes(typeof target)
+      ? collectMembers(target)
+      : { methods: new Set(), properties: new Set() };
+  return {
+    type: typeName(target),
+    methods: [...methods].sort(),
+    properties: [...properties].sort(),
+  };
+}

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