browser-commander 0.19.0 → 0.21.0

package/src/cli/args.js

@@ -0,0 +1,253 @@
+/**
+ * Command-line parsing for `browser-commander` (docs/cli-and-bridge.md,
+ * "Commands"). Built on `node:util` `parseArgs`; option names are kebab-case
+ * on the command line and camelCase in the parsed result.
+ */
+import { parseArgs } from 'node:util';
+
+/** A malformed command line. The CLI prints it as JSON and exits 64. */
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+const STRING = { type: 'string' };
+const STRINGS = { type: 'string', multiple: true };
+const FLAG = { type: 'boolean' };
+
+/** Options that choose and start a browser. */
+const BROWSER_OPTIONS = Object.freeze({
+  engine: STRING,
+  browser: STRING,
+  'executable-path': STRING,
+  'user-data-dir': STRING,
+  headless: FLAG,
+  launch: STRING,
+  restriction: STRINGS,
+  arg: STRINGS,
+});
+
+/** Options accepted by every page command. */
+const PAGE_OPTIONS = Object.freeze({
+  ...BROWSER_OPTIONS,
+  'cdp-endpoint': STRING,
+  url: STRING,
+});
+
+/**
+ * Every command: its positional argument names and its options.
+ * Two-word commands (`trace start`) are keyed by both words.
+ */
+export const COMMANDS = Object.freeze({
+  version: { positionals: [], options: {} },
+  launch: {
+    positionals: [],
+    options: {
+      ...BROWSER_OPTIONS,
+      'keep-open': FLAG,
+      attach: STRING,
+      from: STRING,
+      profile: STRING,
+    },
+  },
+  open: { positionals: ['url'], options: {} },
+  goto: { positionals: ['url'], options: PAGE_OPTIONS },
+  click: { positionals: ['selector'], options: PAGE_OPTIONS },
+  fill: { positionals: ['selector', 'value'], options: PAGE_OPTIONS },
+  eval: { positionals: ['expression'], options: PAGE_OPTIONS },
+  screenshot: {
+    positionals: ['path'],
+    options: { ...PAGE_OPTIONS, 'full-page': FLAG },
+  },
+  pdf: { positionals: ['path'], options: PAGE_OPTIONS },
+  'trace start': { positionals: [], options: { ...PAGE_OPTIONS, out: STRING } },
+  'trace stop': { positionals: [], options: { out: STRING } },
+  'trace view': { positionals: ['dir'], options: { out: STRING } },
+  'cookies import': {
+    positionals: [],
+    options: {
+      ...PAGE_OPTIONS,
+      from: STRING,
+      profile: STRING,
+      domain: STRINGS,
+    },
+  },
+  'profile migrate': {
+    positionals: [],
+    options: {
+      from: STRING,
+      profile: STRING,
+      to: STRING,
+      include: STRING,
+      domain: STRINGS,
+    },
+  },
+  'profile snapshot': {
+    positionals: [],
+    options: { from: STRING, profile: STRING, to: STRING },
+  },
+  attach: {
+    positionals: [],
+    options: { mode: STRING, port: STRING, timeout: STRING },
+  },
+  doctor: { positionals: [], options: BROWSER_OPTIONS },
+  run: { positionals: ['script'], options: BROWSER_OPTIONS },
+  serve: { positionals: [], options: { stdio: FLAG } },
+});
+
+const GROUPS = new Set(
+  Object.keys(COMMANDS)
+    .filter((name) => name.includes(' '))
+    .map((name) => name.split(' ')[0])
+);
+
+/** `executable-path` → `executablePath`. */
+export function camelCase(name) {
+  return name.replace(/-([a-z])/gu, (_, letter) => letter.toUpperCase());
+}
+
+function resolveCommand(argv) {
+  const [first, second] = argv;
+  if (first === undefined || first.startsWith('-')) {
+    throw new UsageError(
+      `Missing command; expected one of: ${Object.keys(COMMANDS).join(', ')}`
+    );
+  }
+  if (GROUPS.has(first)) {
+    const name = `${first} ${second}`;
+    if (!Object.hasOwn(COMMANDS, name)) {
+      const choices = Object.keys(COMMANDS)
+        .filter((command) => command.startsWith(`${first} `))
+        .join(', ');
+      throw new UsageError(`Unknown command "${name}"; expected ${choices}`);
+    }
+    return { name, rest: argv.slice(2) };
+  }
+  if (!Object.hasOwn(COMMANDS, first)) {
+    throw new UsageError(`Unknown command "${first}"`);
+  }
+  return { name: first, rest: argv.slice(1) };
+}
+
+/**
+ * Parse a command line.
+ *
+ * @param {string[]} argv - Arguments after the program name
+ * @returns {{command: string, args: Object<string,string>, options: Object}}
+ * @throws {UsageError}
+ */
+export function parseCommandLine(argv) {
+  const { name, rest } = resolveCommand(argv);
+  const spec = COMMANDS[name];
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: rest,
+      options: spec.options,
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (error) {
+    throw new UsageError(`${name}: ${error.message}`);
+  }
+  if (parsed.positionals.length !== spec.positionals.length) {
+    const expected = spec.positionals.map((item) => `<${item}>`).join(' ');
+    throw new UsageError(
+      `Usage: browser-commander ${name}${expected ? ` ${expected}` : ''}`
+    );
+  }
+  const args = Object.fromEntries(
+    spec.positionals.map((item, index) => [item, parsed.positionals[index]])
+  );
+  const options = Object.fromEntries(
+    Object.entries(parsed.values).map(([key, value]) => [camelCase(key), value])
+  );
+  return { command: name, args, options };
+}
+
+/** Throw a usage error unless an option was given. */
+export function requireOption(options, name, command) {
+  if (options[name] === undefined || options[name] === '') {
+    throw new UsageError(
+      `${command} requires --${name.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`)}`
+    );
+  }
+  return options[name];
+}
+
+/**
+ * `session.launch` params from browser options (`--arg` → `args`,
+ * `--restriction` → `restrictions`), with unset options left out.
+ */
+export function launchParams(options) {
+  const params = {
+    engine: options.engine,
+    browser: options.browser,
+    executablePath: options.executablePath,
+    userDataDir: options.userDataDir,
+    headless: options.headless,
+    launch: options.launch,
+    restrictions: options.restriction,
+    args: options.arg,
+  };
+  return Object.fromEntries(
+    Object.entries(params).filter(([, value]) => value !== undefined)
+  );
+}
+
+/**
+ * The `attach` launch param of `launch --attach snapshot --from BROWSER
+ * --profile NAME`, or undefined without `--attach`.
+ *
+ * @throws {UsageError}
+ */
+export function launchAttachParams(options) {
+  if (options.attach === undefined) {
+    if (options.from !== undefined || options.profile !== undefined) {
+      throw new UsageError(
+        'launch: --from and --profile need --attach snapshot'
+      );
+    }
+    return undefined;
+  }
+  if (options.attach !== 'snapshot') {
+    throw new UsageError(
+      `launch: --attach supports "snapshot", got "${options.attach}"; use attach --mode extension or open <url> for the other modes`
+    );
+  }
+  if (options.userDataDir !== undefined) {
+    throw new UsageError(
+      'launch: --attach snapshot and --user-data-dir are mutually exclusive'
+    );
+  }
+  if (options.launch === 'engine') {
+    throw new UsageError(
+      'launch: --attach snapshot needs --launch real; an engine launch starts its own profile'
+    );
+  }
+  return Object.fromEntries(
+    Object.entries({
+      mode: 'snapshot',
+      browser: options.from,
+      profile: options.profile,
+    }).filter(([, value]) => value !== undefined)
+  );
+}
+
+/**
+ * A non-negative integer option such as `--port 9333`, or undefined.
+ *
+ * @throws {UsageError}
+ */
+export function integerOption(options, name, command) {
+  const value = options[name];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!/^\d+$/u.test(value)) {
+    throw new UsageError(`${command}: --${name} must be an integer`);
+  }
+  return Number.parseInt(value, 10);
+}

package/src/cli/commands.js

@@ -0,0 +1,332 @@
+/**
+ * The `browser-commander` commands (docs/cli-and-bridge.md, "Commands").
+ *
+ * Page commands run through the same dispatcher as `serve --stdio`: open a
+ * session (attach with `--cdp-endpoint`, or launch a temporary browser), run
+ * one high-level method, and close the session again.
+ *
+ * Every command is `(parsed, io) => {document, exitCode}`. A command that
+ * prints its document early (`launch --keep-open`) returns `document: null`.
+ */
+import { readFile, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  integerOption,
+  launchAttachParams,
+  launchParams,
+  requireOption,
+  UsageError,
+} from './args.js';
+import { createDispatcher } from './dispatcher.js';
+import { DEFAULT_DEPENDENCIES } from './modules.js';
+import { runScript } from './script.js';
+import { serveStdio } from './serve.js';
+
+/** Where `trace stop` asks a running `trace start` to finish. */
+export const TRACE_STOP_MARKER = '.stop';
+
+const TRACE_POLL_MS = 250;
+
+function done(document, exitCode = 0) {
+  return { document, exitCode };
+}
+
+/**
+ * Resolve once any stop source fires: SIGINT/SIGTERM, the end of stdin when
+ * `stdin` is given, or any of the `extra` promises.
+ */
+export function waitForStop({ signals, stdin, extra = [] }) {
+  return new Promise((resolve) => {
+    const cleanups = [];
+    const finish = () => {
+      cleanups.forEach((cleanup) => cleanup());
+      resolve();
+    };
+    const listen = (emitter, event) => {
+      emitter.once(event, finish);
+      cleanups.push(() => emitter.off(event, finish));
+    };
+    listen(signals, 'SIGINT');
+    listen(signals, 'SIGTERM');
+    if (stdin) {
+      listen(stdin, 'end');
+      listen(stdin, 'close');
+      stdin.resume?.();
+    }
+    extra.forEach((promise) => promise.then(finish, finish));
+  });
+}
+
+/** Resolve when the browser goes away (the user closed the window). */
+function browserGone(session) {
+  const { browser } = session;
+  if (typeof browser?.once !== 'function') {
+    return new Promise(() => {});
+  }
+  return new Promise((resolve) => browser.once('disconnected', resolve));
+}
+
+/**
+ * Open a session for a page command, run `work(sessionId, dispatcher)`, and
+ * close the session (a connected browser keeps running).
+ */
+async function withPageSession(parsed, io, work, { skipUrl = false } = {}) {
+  const { options } = parsed;
+  const dispatcher = createDispatcher({ dependencies: io.dependencies });
+  try {
+    const opened = options.cdpEndpoint
+      ? await dispatcher.dispatch('session.connect', {
+          cdpEndpoint: options.cdpEndpoint,
+          engine: options.engine,
+        })
+      : await dispatcher.dispatch('session.launch', launchParams(options));
+    if (options.url && !skipUrl) {
+      await dispatcher.dispatch('page.goto', {
+        session: opened.session,
+        url: options.url,
+      });
+    }
+    return await work(opened.session, dispatcher);
+  } finally {
+    await dispatcher.close();
+  }
+}
+
+function pageCommand(method, paramsOf, { skipUrl = false } = {}) {
+  return (parsed, io) => {
+    // Params are read first, so a usage error never starts a browser.
+    const params = paramsOf(parsed);
+    return withPageSession(
+      parsed,
+      io,
+      async (session, dispatcher) =>
+        done(await dispatcher.dispatch(method, { session, ...params })),
+      { skipUrl }
+    );
+  };
+}
+
+async function dispatchOnce(io, method, params = {}) {
+  const dispatcher = createDispatcher({ dependencies: io.dependencies });
+  try {
+    return await dispatcher.dispatch(method, params);
+  } finally {
+    await dispatcher.close();
+  }
+}
+
+async function version(parsed, io) {
+  return done(await dispatchOnce(io, 'version'));
+}
+
+/**
+ * Launch a browser and print its endpoint. Without `--keep-open` the browser
+ * is closed right after printing, which is only useful to check a launch.
+ */
+async function launch(parsed, io) {
+  const attach = launchAttachParams(parsed.options);
+  const dispatcher = createDispatcher({ dependencies: io.dependencies });
+  try {
+    const opened = await dispatcher.dispatch('session.launch', {
+      ...launchParams(parsed.options),
+      ...(attach ? { attach } : {}),
+    });
+    const session = dispatcher.state.sessions.get(opened.session);
+    const document = {
+      cdpEndpoint: opened.cdpEndpoint,
+      remoteDebuggingPort: opened.remoteDebuggingPort,
+      userDataDir: opened.userDataDir,
+      temporaryProfile: opened.temporaryProfile,
+      args: session.args,
+      ...(opened.attach ? { attach: opened.attach } : {}),
+    };
+    if (!parsed.options.keepOpen) {
+      return done(document);
+    }
+    io.print(document);
+    await waitForStop({
+      signals: io.signals,
+      stdin: io.stdin,
+      extra: [browserGone(session)],
+    });
+    return done(null);
+  } finally {
+    await dispatcher.close();
+  }
+}
+
+async function open(parsed, io) {
+  return done(await dispatchOnce(io, 'open', { url: parsed.args.url }));
+}
+
+async function markerAppears(marker, stopped) {
+  while (!stopped()) {
+    if (await stat(marker).catch(() => null)) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, TRACE_POLL_MS));
+  }
+}
+
+/** Record until `trace stop --out DIR` writes the marker, or SIGINT. */
+function traceStart(parsed, io) {
+  const out = path.resolve(requireOption(parsed.options, 'out', 'trace start'));
+  const marker = path.join(out, TRACE_STOP_MARKER);
+  return withPageSession(parsed, io, async (session, dispatcher) => {
+    await rm(marker, { force: true });
+    const { trace } = await dispatcher.dispatch('trace.start', {
+      session,
+      out,
+    });
+    let stopped = false;
+    await waitForStop({
+      signals: io.signals,
+      extra: [markerAppears(marker, () => stopped)],
+    });
+    stopped = true;
+    await rm(marker, { force: true });
+    await dispatcher.dispatch('trace.stop', { session });
+    return done({ trace, stopped: true });
+  });
+}
+
+async function traceStop(parsed) {
+  const out = path.resolve(requireOption(parsed.options, 'out', 'trace stop'));
+  await writeFile(path.join(out, TRACE_STOP_MARKER), '');
+  return done({ trace: out, stopRequested: true });
+}
+
+async function traceView(parsed, io) {
+  const bundle = path.resolve(parsed.args.dir);
+  const output = parsed.options.out && path.resolve(parsed.options.out);
+  const { writeTraceViewer } = { ...DEFAULT_DEPENDENCIES, ...io.dependencies };
+  return done({ viewer: await writeTraceViewer(bundle, output) });
+}
+
+async function profileMigrate(parsed, io) {
+  const { options } = parsed;
+  return done(
+    await dispatchOnce(io, 'profile.migrate', {
+      from: requireOption(options, 'from', 'profile migrate'),
+      profile: options.profile,
+      to: options.to,
+      include: options.include
+        ?.split(',')
+        .map((item) => item.trim())
+        .filter(Boolean),
+      domains: options.domain,
+    })
+  );
+}
+
+/** Copy a real profile into `--to` (or a new temporary directory). */
+async function profileSnapshot(parsed, io) {
+  const { options } = parsed;
+  return done(
+    await dispatchOnce(io, 'profile.snapshot', {
+      from: requireOption(options, 'from', 'profile snapshot'),
+      profile: options.profile,
+      to: options.to && path.resolve(options.to),
+    })
+  );
+}
+
+/**
+ * Wait for the companion extension, print its tabs, and close the relay.
+ * `serve --stdio` keeps the relay open instead (`attach` ... `attach.close`).
+ */
+async function attach(parsed, io) {
+  const { options } = parsed;
+  const mode = requireOption(options, 'mode', 'attach');
+  if (mode !== 'extension') {
+    throw new UsageError(
+      `attach: --mode supports "extension", got "${mode}"; use launch --attach snapshot or open <url> for the other modes`
+    );
+  }
+  const params = { mode };
+  const port = integerOption(options, 'port', 'attach');
+  const timeoutMs = integerOption(options, 'timeout', 'attach');
+  if (port !== undefined) {
+    params.port = port;
+  }
+  if (timeoutMs !== undefined) {
+    params.timeoutMs = timeoutMs;
+  }
+  return done(await dispatchOnce(io, 'attach', params));
+}
+
+/** Exit 2 when the report has a difference not listed in limitations.json. */
+async function doctor(parsed, io) {
+  const report = await dispatchOnce(io, 'doctor', launchParams(parsed.options));
+  const unlisted = report?.ok === false || report?.unlisted?.length > 0;
+  return done(report, unlisted ? 2 : 0);
+}
+
+async function run(parsed, io) {
+  const scriptPath = path.resolve(parsed.args.script);
+  let script;
+  try {
+    script = JSON.parse(await readFile(scriptPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Cannot read ${scriptPath}: ${error.message}`, {
+      cause: error,
+    });
+  }
+  const { results, failed } = await runScript(script, {
+    dependencies: io.dependencies,
+    launchDefaults: launchParams(parsed.options),
+  });
+  return done({ results }, failed ? 1 : 0);
+}
+
+async function serve(parsed, io) {
+  if (!parsed.options.stdio) {
+    throw new UsageError('serve requires --stdio');
+  }
+  await serveStdio({
+    input: io.stdin,
+    write: io.write,
+    dependencies: io.dependencies,
+  });
+  return done(null);
+}
+
+/** Command name to implementation. */
+export const COMMAND_HANDLERS = Object.freeze({
+  version,
+  launch,
+  open,
+  goto: pageCommand('page.goto', ({ args }) => ({ url: args.url }), {
+    skipUrl: true,
+  }),
+  click: pageCommand('page.click', ({ args }) => ({
+    selector: args.selector,
+  })),
+  fill: pageCommand('page.fill', ({ args }) => ({
+    selector: args.selector,
+    value: args.value,
+  })),
+  eval: pageCommand('page.eval', ({ args }) => ({
+    expression: args.expression,
+  })),
+  screenshot: pageCommand('page.screenshot', ({ args, options }) => ({
+    path: args.path,
+    fullPage: options.fullPage === true,
+  })),
+  pdf: pageCommand('page.pdf', ({ args }) => ({ path: args.path })),
+  'trace start': traceStart,
+  'trace stop': traceStop,
+  'trace view': traceView,
+  'cookies import': pageCommand('cookies.import', ({ options }) => ({
+    from: requireOption(options, 'from', 'cookies import'),
+    profile: options.profile,
+    domains: options.domain,
+  })),
+  'profile migrate': profileMigrate,
+  'profile snapshot': profileSnapshot,
+  attach,
+  doctor,
+  run,
+  serve,
+});

package/src/cli/dispatcher.js

@@ -0,0 +1,99 @@
+/**
+ * The one dispatcher behind `serve --stdio` and `run` (issue #104).
+ *
+ * It owns the handle table, the sessions and the event subscriptions of one
+ * connection, and maps a JSON-RPC method name and params to a result or a
+ * thrown error. Transports (the stdio server and the script runner) only
+ * frame messages around it.
+ */
+import { HANDLE_METHODS, removeSubscription } from './handle-methods.js';
+import { HandleTable } from './handles.js';
+import { HIGH_LEVEL_METHODS } from './high-level-methods.js';
+import { DEFAULT_DEPENDENCIES } from './modules.js';
+import { RPC_ERROR, RpcError, invalidParams } from './rpc-error.js';
+import { SessionTable } from './sessions.js';
+
+const METHODS = Object.freeze({ ...HIGH_LEVEL_METHODS, ...HANDLE_METHODS });
+
+/** Every method name the dispatcher answers. */
+export const METHOD_NAMES = Object.freeze(Object.keys(METHODS).sort());
+
+/**
+ * Create a dispatcher.
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.dependencies] - Replacements for {@link DEFAULT_DEPENDENCIES}
+ * @param {function(string, Object): void} [options.notify] - Sends a server notification (`events.emit`)
+ * @returns {{dispatch: function(string, Object=): Promise<unknown>, close: function(): Promise<void>, state: Object}}
+ */
+export function createDispatcher({
+  dependencies = {},
+  notify = () => {},
+} = {}) {
+  const state = {
+    dependencies: { ...DEFAULT_DEPENDENCIES, ...dependencies },
+    handles: new HandleTable(),
+    sessions: new SessionTable(),
+    subscriptions: new Map(),
+    nextSubscription: 1,
+    relay: null,
+    notify,
+  };
+
+  async function dispatch(method, params = {}) {
+    if (typeof method !== 'string' || !Object.hasOwn(METHODS, method)) {
+      throw new RpcError(
+        RPC_ERROR.METHOD_NOT_FOUND,
+        `Unknown method: ${method}`
+      );
+    }
+    if (
+      params === null ||
+      typeof params !== 'object' ||
+      Array.isArray(params)
+    ) {
+      throw invalidParams('params must be an object');
+    }
+    return await METHODS[method](state, params);
+  }
+
+  /** Remove every subscription, close every session and the relay. */
+  async function close() {
+    for (const subscription of [...state.subscriptions.keys()]) {
+      removeSubscription(state, subscription);
+    }
+    const { relay } = state;
+    state.relay = null;
+    await Promise.all([
+      state.sessions.closeAll(),
+      relay?.close().catch(() => {}),
+    ]);
+  }
+
+  return { dispatch, close, state };
+}
+
+/**
+ * Replace `"$session"` anywhere in params with the latest session id.
+ *
+ * @param {unknown} value - Step params
+ * @param {string|null} session - Latest session id
+ * @returns {unknown}
+ */
+export function substituteSession(value, session) {
+  if (value === '$session') {
+    return session ?? value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => substituteSession(item, session));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        substituteSession(item, session),
+      ])
+    );
+  }
+  return value;
+}