browser-commander 0.23.0 → 0.25.0

package/src/browser/connector.js

@@ -1,8 +1,10 @@
 import { attachDownloads } from '../downloads/attach.js';
+import { connectWebDriver, launchWebDriver } from './webdriver.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
   restorePuppeteerStorageState,
+  restoreWebDriverStorageState,
 } from './storage-state.js';
 
 /**
@@ -11,9 +13,9 @@ import {
  * @param {string} engine
  */
 export function assertSupportedEngine(engine) {
-  if (!['playwright', 'puppeteer'].includes(engine)) {
+  if (!['playwright', 'puppeteer', 'selenium'].includes(engine)) {
     throw new Error(
-      `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
+      `Invalid engine: ${engine}. Expected 'playwright', 'puppeteer' or 'selenium'`
     );
   }
 }
@@ -28,6 +30,28 @@ function validateConnectionOptions({ engine, cdpEndpoint, wsEndpoint }) {
   }
 }
 
+async function connectSelenium(options, dependencies) {
+  if (Boolean(options.serverUrl) === Boolean(options.cdpEndpoint)) {
+    throw new Error(
+      'selenium requires exactly one of serverUrl or cdpEndpoint'
+    );
+  }
+  if (options.wsEndpoint) {
+    throw new Error('selenium requires an HTTP cdpEndpoint or serverUrl');
+  }
+  const connected = options.serverUrl
+    ? await (dependencies.connectWebDriver ?? connectWebDriver)(options)
+    : await (dependencies.launchWebDriver ?? launchWebDriver)({
+        ...options,
+        debuggerAddress: new URL(options.cdpEndpoint).host,
+      });
+  return {
+    ...connected,
+    browser: connected.driver,
+    disconnect: connected.close,
+  };
+}
+
 function addDefinedOptions(options, values) {
   for (const [key, value] of Object.entries(values)) {
     if (value !== undefined) {
@@ -135,10 +159,12 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
 }
 
 /**
- * Attach to an already-running Chromium-family browser over CDP.
+ * Attach over CDP or create a native session on a WebDriver server.
  *
  * @param {Object} options - Connection options
- * @param {'playwright'|'puppeteer'} [options.engine='playwright'] - Automation engine
+ * @param {'playwright'|'puppeteer'|'selenium'} [options.engine='playwright'] - Automation engine
+ * @param {string} [options.serverUrl] - Selenium Grid or WebDriver server URL
+ * @param {Object} [options.capabilities] - Native WebDriver capabilities
  * @param {string} [options.cdpEndpoint] - HTTP DevTools endpoint, such as http://127.0.0.1:9222
  * @param {string} [options.wsEndpoint] - DevTools browser WebSocket endpoint
  * @param {number} [options.slowMo] - Delay engine operations by this many milliseconds
@@ -171,6 +197,22 @@ export async function connectBrowserWithDependencies(
     verbose: false,
     ...options,
   };
+  if (normalizedOptions.engine === 'selenium') {
+    assertSupportedEngine(normalizedOptions.engine);
+    const storageState = await prepareStorageState(normalizedOptions);
+    const result = await connectSelenium(normalizedOptions, dependencies);
+    try {
+      await restoreWebDriverStorageState({ page: result.page, storageState });
+      const downloads = await attachDownloads({
+        ...normalizedOptions,
+        ...result,
+      });
+      return { ...result, downloads };
+    } catch (error) {
+      await result.close();
+      throw error;
+    }
+  }
   validateConnectionOptions(normalizedOptions);
 
   const storageState = await prepareStorageState(normalizedOptions);

package/src/browser/launcher.js

@@ -16,10 +16,12 @@ import { resolveRestrictions } from './restrictions.js';
 import { resolveSystemBrowserExecutable } from './system-browser.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
 import { attachDownloads } from '../downloads/attach.js';
+import { launchWebDriver } from './webdriver.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
   restorePuppeteerStorageState,
+  restoreWebDriverStorageState,
 } from './storage-state.js';
 
 /** How `launchBrowser` starts the browser (issue #103). */
@@ -131,6 +133,13 @@ async function launchReal(options, dependencies) {
 }
 
 async function launchWithEngine(options, dependencies) {
+  if (options.engine === 'selenium') {
+    const launched = await (dependencies.launchWebDriver ?? launchWebDriver)({
+      ...options,
+      args: [...options.args, ...options.extraArgs],
+    });
+    return { ...launched, browser: launched.driver };
+  }
   const {
     engine,
     userDataDir: requestedUserDataDir,
@@ -261,7 +270,7 @@ async function unfocusAddressBar(page, verbose, settleMs = 500) {
  * limitations.json (`engine-launch-switches`).
  *
  * @param {Object} options - Configuration options
- * @param {string} [options.engine='playwright'] - Browser automation engine: 'playwright' or 'puppeteer'
+ * @param {string} [options.engine='playwright'] - Browser automation engine: 'playwright', 'puppeteer' or 'selenium'
  * @param {'real'|'engine'} [options.launch='real'] - Who starts the browser: Browser Commander (a hand-started command line) or the automation engine
  * @param {string} [options.userDataDir] - Persistent profile directory. When omitted a fresh temporary profile is created and deleted on close.
  * @param {boolean} [options.headless=false] - Run in headless mode
@@ -309,6 +318,16 @@ export async function launchBrowserWithDependencies(
     ...rest
   } = options;
   validateLaunchMode({ engine, launch, attach: rest.attach });
+  if (engine === 'selenium') {
+    if (colorScheme !== undefined || fingerprint !== undefined || downloads) {
+      throw new Error(
+        'selenium does not support CDP emulation, fingerprint overrides or managed downloads (webdriver-no-cdp-emulation)'
+      );
+    }
+    if (launch === 'real' && rest.browser === 'firefox') {
+      throw new Error("selenium Firefox requires launch: 'engine'");
+    }
+  }
   // Validate arguments before anything is started or written to disk.
   resolveChromeArgs({ args, extraArgs, ignoreDefaultArgs, restrictions });
   const resolvedStorageState = await loadStorageState(storageState);
@@ -341,6 +360,12 @@ export async function launchBrowserWithDependencies(
   }
 
   try {
+    if (engine === 'selenium' && launch === 'engine') {
+      await restoreWebDriverStorageState({
+        page,
+        storageState: resolvedStorageState,
+      });
+    }
     // A Playwright-launched context applies colorScheme itself; an attached
     // browser and Puppeteer need page-level emulation.
     const emulateColorScheme =

package/src/browser/migration/capabilities.json

@@ -0,0 +1,117 @@
+{
+  "schemaVersion": 1,
+  "classes": [
+    "cookies",
+    "bookmarks",
+    "history",
+    "passwords",
+    "preferences",
+    "extensions",
+    "localStorage",
+    "indexedDB",
+    "sessionStorage",
+    "autofill",
+    "paymentCards",
+    "searchEngines",
+    "siteSettings",
+    "openTabs",
+    "downloads",
+    "readingList",
+    "clientCertificates",
+    "passkeys"
+  ],
+  "sourceFamilies": ["chromium", "firefox", "safari"],
+  "targetFamilies": ["chromium", "firefox", "webkit"],
+  "imports": {
+    "chromium": {
+      "chromium": [
+        "seed",
+        "copy",
+        "snapshot",
+        "rekey",
+        "copy",
+        "copy",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "consent/unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "non-exportable"
+      ]
+    },
+    "firefox": {
+      "chromium": [
+        "seed",
+        "translate",
+        "translate",
+        "NSS/rekey",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "consent/unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "non-exportable"
+      ]
+    },
+    "safari": {
+      "chromium": [
+        "seed",
+        "translate",
+        "translate",
+        "CSV/rekey",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "consent/unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "non-exportable"
+      ]
+    }
+  },
+  "wholeProfileMigration": {
+    "chromium": "not implemented",
+    "firefox": "not implemented",
+    "webkit": "not implemented"
+  },
+  "pendingClasses": [
+    "localStorage",
+    "indexedDB",
+    "sessionStorage",
+    "autofill",
+    "paymentCards",
+    "searchEngines",
+    "siteSettings",
+    "openTabs",
+    "downloads",
+    "readingList",
+    "clientCertificates"
+  ],
+  "installedBrowserLaunch": {
+    "chromium": "CDP",
+    "firefox": "explicit WebDriver setup",
+    "safari": "explicit safaridriver setup",
+    "detection": "unsupported"
+  }
+}

package/src/browser/migration/chromium-history.sql

@@ -0,0 +1,22 @@
+-- Core tables match Chromium History schema 70 (compatible version 16).
+-- Chromium initializes remaining ancillary tables when it opens the profile.
+CREATE TABLE meta (key LONGVARCHAR NOT NULL UNIQUE PRIMARY KEY, value LONGVARCHAR);
+INSERT INTO meta VALUES ('version', '70'), ('last_compatible_version', '16');
+CREATE TABLE urls (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, url LONGVARCHAR, title LONGVARCHAR,
+  visit_count INTEGER DEFAULT 0 NOT NULL, typed_count INTEGER DEFAULT 0 NOT NULL,
+  last_visit_time INTEGER DEFAULT 0 NOT NULL, hidden INTEGER DEFAULT 0 NOT NULL
+);
+CREATE TABLE visits (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, url INTEGER NOT NULL,
+  visit_time INTEGER NOT NULL, from_visit INTEGER DEFAULT 0,
+  external_referrer_url TEXT, transition INTEGER DEFAULT 0 NOT NULL,
+  segment_id INTEGER DEFAULT 0, visit_duration INTEGER DEFAULT 0 NOT NULL,
+  incremented_omnibox_typed_score BOOLEAN DEFAULT FALSE NOT NULL,
+  opener_visit INTEGER DEFAULT 0, originator_cache_guid TEXT DEFAULT '',
+  originator_visit_id INTEGER DEFAULT 0, originator_from_visit INTEGER DEFAULT 0,
+  originator_opener_visit INTEGER DEFAULT 0, is_known_to_sync BOOLEAN DEFAULT FALSE NOT NULL,
+  consider_for_ntp_most_visited BOOLEAN DEFAULT FALSE NOT NULL,
+  visited_link_id INTEGER DEFAULT 0 NOT NULL, app_id TEXT
+);
+CREATE TABLE visit_source (id INTEGER PRIMARY KEY, source INTEGER NOT NULL);

package/src/browser/migration/chromium-writers.js

@@ -0,0 +1,85 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { openSqliteDatabase } from '../browser-cookie-database.js';
+
+export async function writeChromiumBookmarks(targetProfileDir, entries) {
+  let id = 3;
+  let count = 0;
+  function convert(node) {
+    const result = {
+      id: String(++id),
+      date_added: '13300000000000000',
+      name: node.name,
+      type: node.type,
+    };
+    if (node.type === 'url') {
+      count += 1;
+      result.url = node.url;
+    } else {
+      result.date_modified = result.date_added;
+      result.children = (node.children ?? []).map(convert);
+    }
+    return result;
+  }
+  const roots = Object.fromEntries(
+    ['bookmark_bar', 'other', 'synced'].map((name, index) => [
+      name,
+      {
+        id: String(index + 1),
+        name,
+        type: 'folder',
+        date_added: '13300000000000000',
+        date_modified: '13300000000000000',
+        children: name === 'other' ? entries.map(convert) : [],
+      },
+    ])
+  );
+  await mkdir(targetProfileDir, { recursive: true });
+  await writeFile(
+    path.join(targetProfileDir, 'Bookmarks'),
+    JSON.stringify({ version: 1, roots })
+  );
+  return count;
+}
+
+export async function writeChromiumHistory(targetProfileDir, entries) {
+  await mkdir(targetProfileDir, { recursive: true });
+  const db = await openSqliteDatabase(path.join(targetProfileDir, 'History'));
+  try {
+    db.exec(
+      await readFile(new URL('./chromium-history.sql', import.meta.url), 'utf8')
+    );
+    const urls = new Map();
+    const insertUrl = db.prepare(
+      'INSERT INTO urls (url,title,visit_count,last_visit_time) VALUES (?,?,0,0)'
+    );
+    const updateUrl = db.prepare(
+      'UPDATE urls SET title=?, visit_count=visit_count+1,last_visit_time=max(last_visit_time,?) WHERE id=?'
+    );
+    const insertVisit = db.prepare(
+      'INSERT INTO visits (url,visit_time) VALUES (?,?)'
+    );
+    db.exec('BEGIN');
+    try {
+      for (const entry of entries) {
+        if (!urls.has(entry.url)) {
+          urls.set(
+            entry.url,
+            insertUrl.run(entry.url, entry.title).lastInsertRowid
+          );
+        }
+        const id = urls.get(entry.url);
+        const time = BigInt(entry.time) + 11644473600000000n;
+        updateUrl.run(entry.title, time, id);
+        insertVisit.run(id, time);
+      }
+      db.exec('COMMIT');
+    } catch (error) {
+      db.exec('ROLLBACK');
+      throw error;
+    }
+  } finally {
+    db.close();
+  }
+  return entries.length;
+}

package/src/browser/migration/cookies.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 
 import { pathExists } from './fs-utils.js';
+import { matchesDomains } from './domains.js';
 
 import { readBrowserCookies } from '../browser-cookies.js';
 
@@ -130,7 +131,9 @@ export async function migrateCookies({
       );
     }
   }
-  const cookies = [...seen.values()];
+  const cookies = [...seen.values()].filter((cookie) =>
+    matchesDomains(cookie.domain, domains)
+  );
 
   const skipped = [];
   for (const cookie of cookies) {

package/src/browser/migration/data-classes.js

@@ -0,0 +1,68 @@
+/** Explicit reports for selected classes without a native target writer. */
+export const ADDITIONAL_DATA_CLASSES = Object.freeze([
+  'localStorage',
+  'indexedDB',
+  'sessionStorage',
+  'autofill',
+  'paymentCards',
+  'searchEngines',
+  'siteSettings',
+  'openTabs',
+  'downloads',
+  'readingList',
+  'clientCertificates',
+  'passkeys',
+]);
+
+export function reportAdditionalClasses({
+  selected,
+  profileDir,
+  includePaymentCards,
+}) {
+  return ADDITIONAL_DATA_CLASSES.filter((type) => selected.has(type)).flatMap(
+    (type) => reportAdditionalClass({ type, profileDir, includePaymentCards })
+  );
+}
+
+export function reportAdditionalClass({
+  type,
+  profileDir,
+  includePaymentCards,
+}) {
+  const entry = (item, reason, detail) => ({ type, item, reason, detail });
+  if (type === 'passkeys') {
+    return ['iCloud Keychain', 'Google Password Manager', 'Windows Hello'].map(
+      (provider) =>
+        entry(
+          provider,
+          'passkey-not-exportable',
+          `${provider} private keys cannot be exported by copying browser profile files. Provider-authorized transfer may be available separately. Sign in once with the platform passkey in a dedicated persistent profile and retain its session.`
+        )
+    );
+  }
+  if (type === 'paymentCards' && !includePaymentCards) {
+    return [
+      entry(
+        profileDir,
+        'payment-card-consent-required',
+        'Payment cards require includePaymentCards=true (Python/Rust: include_payment_cards; CLI: --include-payment-cards). Selecting the class alone does not grant consent.'
+      ),
+    ];
+  }
+  if (type === 'clientCertificates') {
+    return [
+      entry(
+        profileDir,
+        'client-certificates-os-export-required',
+        'Client certificate private keys require an authorized export from the OS or NSS store. Hardware-backed or non-exportable keys cannot be copied from browser profile files.'
+      ),
+    ];
+  }
+  return [
+    entry(
+      profileDir,
+      'data-class-not-supported',
+      `A native source reader and compatible target writer for ${type} are not implemented; no data was copied.`
+    ),
+  ];
+}

package/src/browser/migration/domains.js

@@ -0,0 +1,32 @@
+/** Site filters match a host or its subdomains, never an unrelated suffix. */
+export function matchesDomains(value, domains) {
+  if (!domains?.length) {
+    return true;
+  }
+  let host;
+  try {
+    host = value.includes('://') ? new URL(value).hostname : value;
+  } catch {
+    return false;
+  }
+  host = host.replace(/^\./, '').toLowerCase().replace(/\.$/, '');
+  return domains.some((domain) => {
+    const filter = domain.replace(/^\./, '').toLowerCase().replace(/\.$/, '');
+    return host === filter || host.endsWith(`.${filter}`);
+  });
+}
+
+export function validateDomains(domains) {
+  if (domains === undefined) {
+    return;
+  }
+  if (
+    !Array.isArray(domains) ||
+    domains.some(
+      (domain) =>
+        typeof domain !== 'string' || !domain || /[\s/:]/u.test(domain)
+    )
+  ) {
+    throw new TypeError('domains must be an array of host names');
+  }
+}

package/src/browser/migration/firefox-history.js

@@ -0,0 +1,106 @@
+import { matchesDomains } from './domains.js';
+import { profileFileIfPresent } from './fs-utils.js';
+import { readDatabaseSnapshot } from './sqlite-snapshot.js';
+import { writeChromiumHistory } from './chromium-writers.js';
+import { preserveIntegerPrecision } from '../browser-cookie-database.js';
+
+/** Translate individual Firefox visits using a consistent read-only snapshot. */
+export async function migrateFirefoxHistory({
+  profileDir,
+  targetProfileDir,
+  domains,
+}) {
+  const sourcePath = await profileFileIfPresent(profileDir, 'places.sqlite');
+  const entry = (reason, detail, item = 'places.sqlite') => ({
+    type: 'history',
+    item,
+    reason,
+    detail,
+  });
+  if (!sourcePath) {
+    return { migrated: 0, skipped: [entry('source-missing')], warnings: [] };
+  }
+  const rows = await readDatabaseSnapshot({
+    sourcePath,
+    read: (db) => {
+      for (const [table, required] of [
+        ['moz_places', ['id', 'url', 'title']],
+        ['moz_historyvisits', ['id', 'place_id', 'visit_date']],
+      ]) {
+        const columns = new Set(
+          db
+            .prepare(`PRAGMA table_info(${table})`)
+            .all()
+            .map(({ name }) => name)
+        );
+        if (!required.every((name) => columns.has(name))) {
+          return null;
+        }
+      }
+      return preserveIntegerPrecision(
+        db.prepare(
+          'SELECT p.url,p.title,v.id,v.visit_date AS time FROM moz_historyvisits v JOIN moz_places p ON v.place_id=p.id ORDER BY v.visit_date,v.id'
+        )
+      ).all();
+    },
+  });
+  if (rows === null) {
+    return {
+      migrated: 0,
+      skipped: [
+        entry(
+          'source-format-unsupported',
+          'Firefox history requires moz_places and moz_historyvisits with URL, title and integer visit dates; no target was written.'
+        ),
+      ],
+      warnings: [],
+    };
+  }
+  const skipped = [];
+  const visits = [];
+  for (const row of rows) {
+    if (typeof row.url !== 'string' || !row.url) {
+      skipped.push(
+        entry(
+          'invalid-history-url',
+          'The visit URL is not a nonempty string.',
+          `places.sqlite visit ${row.id}`
+        )
+      );
+      continue;
+    }
+    if (!matchesDomains(row.url, domains)) {
+      continue;
+    }
+    if (
+      typeof row.time !== 'bigint' ||
+      row.time < -11644473600000000n ||
+      row.time > 9211727563254775807n
+    ) {
+      skipped.push(
+        entry(
+          'invalid-history-timestamp',
+          'The visit date is not an integer representable in the target history format.',
+          `places.sqlite visit ${row.id}`
+        )
+      );
+      continue;
+    }
+    visits.push({ url: row.url, title: row.title ?? '', time: row.time });
+  }
+  const migrated = visits.length
+    ? await writeChromiumHistory(targetProfileDir, visits)
+    : 0;
+  return {
+    migrated,
+    skipped,
+    warnings: migrated
+      ? [
+          entry(
+            'firefox-history-metadata-not-translated',
+            'URL/title and visit dates were translated; Firefox transition types, referring visits and sync metadata were not copied.'
+          ),
+        ]
+      : [],
+  };
+}