package-registry-manager 0.22.2 → 0.22.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "package-registry-manager",
-  "version": "0.22.2",
+  "version": "0.22.4",
   "description": "Inspect repositories and guide secure package-registry setup",
   "type": "module",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "exports": "./src/index.mjs",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12.0"
   },
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "provenance": true
   },
   "scripts": {
-    "syntax": "node --check src/cli.mjs && node --check src/direct-execution.mjs && node --check src/index.mjs && node --check src/browser.mjs && node --check src/browser-options.mjs && node --check src/automation.mjs && node --check src/profile.mjs && node --check src/setup.mjs && node --check src/auth-urls.mjs && node --check src/containers.mjs && node --check src/flows.mjs && node --check src/prerequisites.mjs && node --check src/registry-state.mjs && node --check src/workflows.mjs && node --check src/publishers.mjs && node --check src/skips.mjs && node --check src/tokens.mjs && node --check src/approvals.mjs && node --check src/default-browser.mjs && node --check src/pages.mjs && node --check src/crates-api.mjs && node --check src/sign-in-import.mjs && node --check scripts/publish-to-npm.mjs && node --check scripts/setup-npm.mjs && node --check scripts/sanitize-npm-userconfig.mjs",
+    "syntax": "node --check src/cli.mjs && node --check src/direct-execution.mjs && node --check src/index.mjs && node --check src/browser.mjs && node --check src/browser-options.mjs && node --check src/browser-catalogue.mjs && node --check src/automation.mjs && node --check src/webdriver-automation.mjs && node --check src/profile.mjs && node --check src/setup.mjs && node --check src/auth-urls.mjs && node --check src/containers.mjs && node --check src/flows.mjs && node --check src/prerequisites.mjs && node --check src/registry-state.mjs && node --check src/workflows.mjs && node --check src/publishers.mjs && node --check src/skips.mjs && node --check src/tokens.mjs && node --check src/approvals.mjs && node --check src/default-browser.mjs && node --check src/pages.mjs && node --check src/crates-api.mjs && node --check src/sign-in-import.mjs && node --check scripts/publish-to-npm.mjs && node --check scripts/setup-npm.mjs && node --check scripts/sanitize-npm-userconfig.mjs",
     "lint": "eslint src test scripts --max-warnings 0",
     "lint:fix": "eslint src test scripts --fix --max-warnings 0",
     "format": "prettier --write .",
@@ -36,16 +36,18 @@
     "check:duplication": "jscpd src",
     "check": "npm run syntax && npm run lint && npm run format:check && npm run check:duplication",
     "test": "node --test --test-timeout=30000",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "audit": "node scripts/npm-audit.mjs"
   },
   "dependencies": {
-    "browser-commander": "^0.22.0",
-    "command-stream": "^1.3.0",
-    "playwright": "^1.63.0"
+    "browser-commander": "^0.25.0",
+    "command-stream": "^1.6.2",
+    "playwright": "^1.63.0",
+    "selenium-webdriver": "^4.50.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.11.0",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "jscpd": "^5.4.0",
     "prettier": "^3.9.9"

package/src/automation.mjs

@@ -5,8 +5,11 @@ import {
   attachViaExtension,
   EXTENSION_DIRECTORY,
   launchRealBrowser,
+  findBrowserSource,
 } from "browser-commander";
 
+import { connectWebDriverAutomation } from "./webdriver-automation.mjs";
+
 import { snapshotBrowser } from "./browser-options.mjs";
 import { defaultBrowserProfile, ensureProfileIgnored } from "./profile.mjs";
 import { IMPORT_CHOICES, migrationFor } from "./sign-in-import.mjs";
@@ -28,7 +31,10 @@ export function relayExtensionDirectory() {
  */
 export function launchOptions(browser, profile, verbose = false, domains = []) {
   const options = {
-    engine: "playwright",
+    engine:
+      findBrowserSource(browser.channel)?.controlProtocol === "cdp"
+        ? "playwright"
+        : "selenium",
     channel: browser.channel,
     headless: false,
     verbose,
@@ -75,25 +81,29 @@ export function extensionInstructions(directory) {
  * Connects the browser that fills forms and returns a page with `goto`,
  * `evaluate`, `close`, and, for a launched profile, `clearCookies(domains)`.
  */
-export async function connectAutomation({
-  browser,
-  profile,
-  verbose = false,
-  domains = [],
-}) {
+export async function connectAutomation(
+  { browser, profile, verbose = false, domains = [] },
+  dependencies = {},
+) {
   if (browser.attach?.mode === "extension") {
     return connectExtension();
   }
+  if (findBrowserSource(browser.channel)?.controlProtocol === "bidi") {
+    return connectWebDriverAutomation(
+      { browser, profile, verbose, domains },
+      dependencies,
+    );
+  }
   if (!browser.attach) {
     await ensureProfileIgnored(profile, { verbose });
   }
-  const connection = await launchRealBrowser(
-    launchOptions(browser, profile, verbose, domains),
-  );
+  const connection = await (
+    dependencies.launchRealBrowser ?? launchRealBrowser
+  )(launchOptions(browser, profile, verbose, domains));
   return {
     goto: (url) => connection.page.goto(url),
     evaluate: (script) => connection.page.evaluate(script),
-    close: () => connection.browser.close(),
+    close: () => connection.close(),
     async clearCookies(names) {
       for (const name of names) {
         const escaped = name.replaceAll(".", "\\.");

package/src/browser-catalogue.mjs

@@ -0,0 +1,209 @@
+import { constants, existsSync, realpathSync } from "node:fs";
+import { access } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { BROWSER_IDS, findBrowserSource } from "browser-commander";
+
+/** Catalogue entries reached through Browser Commander's public exports. */
+export const browserSources = () => BROWSER_IDS.map(findBrowserSource);
+
+/** Catalogue channels with a launch control protocol. */
+export function launchChannels() {
+  return browserSources()
+    .filter((source) => source.controlProtocol)
+    .flatMap((source) => [source.id, ...(source.aliases ?? [])]);
+}
+
+/** A readable name from the catalogue's application path or canonical alias. */
+export function catalogueName(id) {
+  const source = findBrowserSource(id);
+  if (!source) {
+    return id;
+  }
+  const app = source.executables?.darwin?.[0]?.match(/\/([^/]+)\.app\//)?.[1];
+  // Preserve the established short name of Brave.
+  if (app) {
+    return app === "Brave Browser" ? "Brave" : app;
+  }
+  const label = [source.id, ...(source.aliases ?? [])]
+    .map((name) => name.replace(/^apple-/, ""))
+    .reduce((longest, name) => (name.length > longest.length ? name : longest));
+  return label
+    .replace(/^apple-/, "")
+    .split("-")
+    .map((word) =>
+      word.length <= 2
+        ? word.toUpperCase()
+        : word[0].toUpperCase() + word.slice(1),
+    )
+    .join(" ")
+    .replace("Duckduckgo", "DuckDuckGo");
+}
+
+/** Installed executables or existing profile roots; never reads cookie data. */
+export function installedBrowsers(options = {}) {
+  const exists = options.exists ?? existsSync;
+  const platform = options.platform ?? process.platform;
+  const environment = options.environment ?? process.env;
+  const discovery = {
+    ...options,
+    platform,
+    environment:
+      platform === "win32"
+        ? Object.fromEntries(
+            Object.entries(environment).map(([key, value]) => [
+              key.toUpperCase(),
+              value,
+            ]),
+          )
+        : environment,
+  };
+  return browserSources()
+    .filter((source) =>
+      installedCandidates(source, discovery).some((candidate) =>
+        exists(candidate),
+      ),
+    )
+    .map((source) => source.id);
+}
+
+function installedCandidates(
+  source,
+  {
+    platform = process.platform,
+    homeDir = os.homedir(),
+    environment = process.env,
+  },
+) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const variables = {
+    home: homeDir,
+    config: environment.XDG_CONFIG_HOME ?? pathApi.join(homeDir, ".config"),
+    appSupport: pathApi.join(homeDir, "Library", "Application Support"),
+    appData: environment.APPDATA ?? pathApi.join(homeDir, "AppData", "Roaming"),
+    localAppData:
+      environment.LOCALAPPDATA ?? pathApi.join(homeDir, "AppData", "Local"),
+    programFiles: environment.PROGRAMFILES,
+    programFilesX86: environment["PROGRAMFILES(X86)"],
+  };
+  const templates = [
+    ...(source.executables?.[platform] ?? []),
+    ...(source.roots?.[platform] ?? []),
+  ];
+  const candidates = templates.flatMap((template) => {
+    const match = /^\{(\w+)\}\/?(.*)$/.exec(template);
+    if (!match) {
+      return [template];
+    }
+    const base = variables[match[1]];
+    return base === undefined
+      ? []
+      : [pathApi.join(base, ...match[2].split("/"))];
+  });
+  for (const directory of (environment.PATH ?? "")
+    .split(platform === "win32" ? ";" : ":")
+    .filter(Boolean)) {
+    for (const name of source.executableNames ?? []) {
+      candidates.push(
+        pathApi.join(directory, platform === "win32" ? `${name}.exe` : name),
+      );
+    }
+  }
+  return candidates;
+}
+
+/** Discovery information included when an import or channel is invalid. */
+export function installedDescription(options = {}) {
+  const found = installedBrowsers(options);
+  return `Installed browsers found: ${found.join(", ") || "none"}.`;
+}
+
+/** Reject unavailable engines before creating an automated profile. */
+export function validateChannel(channel) {
+  const known = findBrowserSource(channel);
+  if (known?.controlProtocol) {
+    return channel;
+  }
+  const reason = known
+    ? `${channel} has no launch control protocol in browser-commander's catalogue${known.family === "safari" ? " (Safari setup: https://github.com/link-foundation/browser-commander/issues/126)" : ""}`
+    : `unknown --browser-channel '${channel}'`;
+  throw new Error(
+    `${reason}; choose from ${launchChannels().join(", ")}. ${installedDescription()}`,
+  );
+}
+
+/** Resolves the selected installed binary using catalogue paths and PATH. */
+export async function resolveExecutable(
+  { channel, executablePath },
+  discovery = {},
+) {
+  const platform = discovery.platform ?? process.platform;
+  const environment = discovery.environment ?? process.env;
+  const options = {
+    ...discovery,
+    platform,
+    environment:
+      platform === "win32"
+        ? Object.fromEntries(
+            Object.entries(environment).map(([key, value]) => [
+              key.toUpperCase(),
+              value,
+            ]),
+          )
+        : environment,
+  };
+  const source = findBrowserSource(channel);
+  const candidates = executablePath
+    ? [executablePath]
+    : installedCandidates({ ...source, roots: {} }, options);
+  for (const candidate of candidates) {
+    try {
+      await (discovery.access ?? access)(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      // Continue through the catalogue's executable paths and PATH names.
+    }
+  }
+  throw new Error(
+    `could not find an installed ${channel} browser; use --browser-executable`,
+  );
+}
+
+/** Refuses a source profile even when reached through a symlink. */
+export function assertDedicatedProfile(profile, discovery = {}) {
+  const physical = (file) => {
+    try {
+      return realpathSync(file);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+      return path.join(physical(path.dirname(file)), path.basename(file));
+    }
+  };
+  const requested = physical(path.resolve(profile));
+  const roots = browserSources().flatMap((source) =>
+    installedCandidates(
+      {
+        ...source,
+        executables: {},
+        executableNames: [],
+      },
+      discovery,
+    ),
+  );
+  for (const root of roots) {
+    const relative = path.relative(physical(path.resolve(root)), requested);
+    if (
+      relative === "" ||
+      (!relative.startsWith(`..${path.sep}`) &&
+        relative !== ".." &&
+        !path.isAbsolute(relative))
+    ) {
+      throw new Error(
+        "automation requires a dedicated profile, not a browser default profile; use --browser-import to reuse sign-in",
+      );
+    }
+  }
+}

package/src/browser-options.mjs

@@ -1,10 +1,12 @@
 import path from "node:path";
 
 import {
+  findBrowserSource,
   LAUNCH_RESTRICTION_PRESETS,
   LAUNCH_RESTRICTIONS,
 } from "browser-commander";
 
+import { installedDescription, validateChannel } from "./browser-catalogue.mjs";
 import {
   IMPORT_CHOICES,
   IMPORT_SCOPES,
@@ -50,10 +52,14 @@ export function parseBrowserOptions({
   profileGiven = false,
 } = {}) {
   const options = {
-    channel,
+    channel: attach === "extension" ? channel : validateChannel(channel),
     executable: executable ? path.resolve(executable) : null,
     import: importFrom ? parseImport(importFrom) : null,
-    importScope: parseImportScope(importScope, importFrom),
+    importScope:
+      (importScope === undefined || importScope === null) &&
+      findBrowserSource(channel)?.controlProtocol === "bidi"
+        ? "domains"
+        : parseImportScope(importScope, importFrom),
     attach: attach ? parseAttach(attach) : null,
     preferences: parsePreferences(preferences),
     restrictions: validateRestrictions(restrictions),
@@ -78,25 +84,47 @@ export function parseBrowserOptions({
       "--browser-attach extension cannot be combined with --browser-executable, --browser-pref, or --browser-restriction",
     );
   }
+  validateEngineOptions(options);
   return options;
 }
 
+/** Rejects capabilities the installed upstream non-CDP launchers lack. */
+function validateEngineOptions(options) {
+  if (
+    options.attach?.mode === "extension" ||
+    findBrowserSource(options.channel)?.controlProtocol === "cdp"
+  ) {
+    return;
+  }
+  const unsupported = options.attach
+    ? "--browser-attach snapshot"
+    : options.restrictions.length
+      ? "--browser-restriction"
+      : Object.keys(options.preferences).length
+        ? "--browser-pref"
+        : options.import && options.importScope === "full"
+          ? "--browser-import-scope full"
+          : null;
+  if (unsupported) {
+    throw new Error(
+      `${unsupported} is unavailable for ${options.channel} in the installed browser-commander; use --browser-import-scope domains for sign-in cookies`,
+    );
+  }
+}
+
 /** Parses `<browser>[:profile]`, `default`, or `auto`. */
-export function parseImport(spec) {
+export function parseImport(spec, discovery = {}) {
   const separator = spec.indexOf(":");
   const browser = separator === -1 ? spec : spec.slice(0, separator);
   const profile = separator === -1 ? null : spec.slice(separator + 1);
   const choice = IMPORT_CHOICES.includes(browser);
-  if (
-    !importBrowsers().includes(browser) ||
-    profile === "" ||
-    (choice && profile !== null)
-  ) {
+  const source = findBrowserSource(browser);
+  if ((!source && !choice) || profile === "" || (choice && profile !== null)) {
     throw new Error(
-      `--browser-import must be <${importSources().join("|")}>[:profile], default, or auto`,
+      `--browser-import must be <${importSources().join("|")}>[:profile], default, or auto. ${installedDescription(discovery)}`,
     );
   }
-  return { browser, profile };
+  return { browser: source?.id ?? browser, profile };
 }
 
 /**
@@ -184,10 +212,7 @@ export function validateRestrictions(names) {
 
 /** The installed browser a snapshot copies for a launch channel. */
 export function snapshotBrowser(channel) {
-  if (channel.startsWith("msedge")) {
-    return "edge";
-  }
-  return ["brave", "chromium"].includes(channel) ? channel : "chrome";
+  return findBrowserSource(channel)?.id ?? channel;
 }
 
 /** Describes where forms are filled, for the browser prerequisite. */

package/src/cli.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import process from "node:process";
 import { parseArgs } from "node:util";
 
+import { launchChannels } from "./browser-catalogue.mjs";
 import { parseBrowserOptions } from "./browser-options.mjs";
 import { isDirectExecution } from "./direct-execution.mjs";
 import { inspectRepository } from "./discovery.mjs";
@@ -14,6 +15,7 @@ import { buildPlans } from "./plan.mjs";
 import { probeEnvironment, renderPrerequisites } from "./prerequisites.mjs";
 import { probeRegistryState } from "./registry-state.mjs";
 import { BROWSER_MODES, defaultBrowserProfile, executePlan } from "./setup.mjs";
+import { importSources } from "./sign-in-import.mjs";
 
 export { isDirectExecution };
 
@@ -62,17 +64,16 @@ Setup options:
   --browser <default|automated>   Open sign-in and approval pages in your
                                   default browser, or in the automated
                                   profile too (default: default)
-  --browser-channel <channel>     Installed browser channel: chrome, chromium,
-                                  brave, msedge, msedge-beta, msedge-dev, or
-                                  msedge-canary (default: chrome)
+  --browser-channel <channel>     Installed browser channel (default: chrome):
+                                  ${launchChannels().join(", ")}
   --browser-executable <path>     Installed browser executable to launch
                                   instead of the channel's
   --browser-profile <path>        Dedicated automation profile, used to fill
                                   forms (default: per-user state directory)
   --browser-import <browser>[:<profile>]|default|auto
-                                  Copy data from your chrome, edge, brave,
-                                  chromium, or firefox profile into the
-                                  automated profile first; default takes the
+                                  Copy data from your installed browser profile:
+                                  ${importSources().join(", ")}
+                                  into the automated profile; default takes the
                                   system default browser, auto the first
                                   browser signed in to the registry
   --browser-import-scope <full|domains>
@@ -226,7 +227,8 @@ export async function main(args = process.argv.slice(2)) {
     browser: values.browser,
     browserOptions,
     browserProfile: path.resolve(
-      values["browser-profile"] ?? defaultBrowserProfile(),
+      values["browser-profile"] ??
+        defaultBrowserProfile({ channel: browserOptions.channel }),
     ),
     verbose: values.verbose,
     verifyRelease: values["verify-release"],
@@ -272,7 +274,10 @@ function browserSummary(command, values, browserOptions) {
     channel: browserOptions.channel,
     profile:
       values.browser === "automated" && !browserOptions.attach
-        ? path.resolve(values["browser-profile"] ?? defaultBrowserProfile())
+        ? path.resolve(
+            values["browser-profile"] ??
+              defaultBrowserProfile({ channel: browserOptions.channel }),
+          )
         : undefined,
     import: browserOptions.import ?? undefined,
     attach: browserOptions.attach ?? undefined,

package/src/default-browser.mjs

@@ -1,22 +1,6 @@
 import { exec } from "command-stream";
 
-/**
- * Names of common browsers by macOS bundle id, Linux desktop entry, and
- * Windows URL ProgId, so the tool can say which browser it opened.
- */
-const KNOWN_BROWSERS = [
-  [/^com\.apple\.safari$|^SafariURL/i, "Safari"],
-  [/^com\.google\.chrome\.canary$/i, "Google Chrome Canary"],
-  [/^com\.google\.chrome$|google-chrome|^ChromeHTML$/i, "Google Chrome"],
-  [/^org\.chromium\.chromium$|chromium|^ChromiumHTM/i, "Chromium"],
-  [/^org\.mozilla\.firefox$|firefox|^FirefoxURL/i, "Firefox"],
-  [/^com\.microsoft\.edgemac$|microsoft-edge|^MSEdgeHTM$/i, "Microsoft Edge"],
-  [/^com\.brave\.browser$|brave-browser|^BraveHTML$/i, "Brave"],
-  [/^company\.thebrowser\.browser$/i, "Arc"],
-  [/^com\.operasoftware\.opera$|opera|^OperaStable$/i, "Opera"],
-  [/^com\.vivaldi\.vivaldi$|vivaldi|^VivaldiHTM/i, "Vivaldi"],
-  [/^IE\.HTTP/i, "Internet Explorer"],
-];
+import { browserSources, catalogueName } from "./browser-catalogue.mjs";
 
 /** The command that reports the default browser, as an exact argument vector. */
 export function defaultBrowserQuery(platform = process.platform) {
@@ -100,8 +84,40 @@ export function browserName(id) {
   if (!id) {
     return undefined;
   }
-  const known = KNOWN_BROWSERS.find(([pattern]) => pattern.test(id));
-  return known?.[1];
+  const needle = id.trim().toLowerCase();
+  const sources = browserSources();
+  const known =
+    sources.find((source) =>
+      Object.values(source.default ?? {})
+        .flat()
+        .some((candidate) => needle === candidate.toLowerCase()),
+    ) ??
+    sources.find(
+      (source) =>
+        (source.default?.win32 ?? []).some((candidate) =>
+          needle.startsWith(candidate.toLowerCase()),
+        ) ||
+        (needle.endsWith(".desktop") &&
+          (source.executableNames ?? []).some((name) =>
+            ["-", "_", "."].some((separator) =>
+              needle.startsWith(`${name.toLowerCase()}${separator}`),
+            ),
+          )),
+    );
+  if (known) {
+    return catalogueName(known.id);
+  }
+  // Legacy ProgIds absent from the upstream catalogue remain recognizable.
+  if (/^safariurl/i.test(id)) {
+    return catalogueName("safari");
+  }
+  if (/^chromiumhtm/i.test(id)) {
+    return catalogueName("chromium");
+  }
+  if (/^ie\.http/i.test(id)) {
+    return "Internet Explorer";
+  }
+  return undefined;
 }
 
 /**

package/src/profile.mjs

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { exec } from "command-stream";
+import { findBrowserSource } from "browser-commander";
 
 const APPLICATION = "package-registry-manager";
 const PROFILE = "browser-profile";
@@ -17,20 +18,26 @@ export function defaultBrowserProfile({
   platform = process.platform,
   env = process.env,
   home = os.homedir(),
+  channel = "chrome",
 } = {}) {
+  const source = findBrowserSource(channel);
+  const profile =
+    source?.controlProtocol && source.controlProtocol !== "cdp"
+      ? `${PROFILE}-${source.id}`
+      : PROFILE;
   const join = platform === "win32" ? path.win32.join : path.posix.join;
   if (platform === "win32") {
     const base = env.LOCALAPPDATA || join(home, "AppData", "Local");
-    return join(base, APPLICATION, PROFILE);
+    return join(base, APPLICATION, profile);
   }
   if (platform === "darwin") {
-    return join(home, "Library", "Application Support", APPLICATION, PROFILE);
+    return join(home, "Library", "Application Support", APPLICATION, profile);
   }
   // The XDG specification ignores relative values.
   const state = path.posix.isAbsolute(env.XDG_STATE_HOME ?? "")
     ? env.XDG_STATE_HOME
     : join(home, ".local", "state");
-  return join(state, APPLICATION, PROFILE);
+  return join(state, APPLICATION, profile);
 }
 
 /** The profile location used before it moved out of the repository. */

package/src/sign-in-import.mjs

@@ -5,10 +5,9 @@
 // printed, logged, or cached: they are only counted.
 import * as commander from "browser-commander";
 
+import { catalogueName } from "./browser-catalogue.mjs";
 import { detectDefaultBrowser } from "./default-browser.mjs";
 
-/** Browser Commander's cookie sources, should a release stop exporting them. */
-const FALLBACK_SOURCES = ["chrome", "edge", "brave", "chromium", "firefox"];
 /** `--browser-import` values that pick the source browser for the user. */
 export const IMPORT_CHOICES = ["default", "auto"];
 /** `--browser-import-scope` values. */
@@ -21,22 +20,9 @@ export const SIGN_IN_DOMAINS = {
   pypi: ["pypi.org", "github.com"],
 };
 
-/** Display names of the source browsers, as the default-browser query names them. */
-const SOURCE_NAMES = {
-  chrome: "Google Chrome",
-  edge: "Microsoft Edge",
-  brave: "Brave",
-  chromium: "Chromium",
-  firefox: "Firefox",
-};
-
-/**
- * Every browser `--browser-import` can read, from Browser Commander. Safari,
- * Opera, Vivaldi, and Arc follow once Browser Commander reads them
- * (link-foundation/browser-commander#114).
- */
+/** Every import id from Browser Commander's public catalogue. */
 export function importSources() {
-  return [...(commander.SUPPORTED_COOKIE_BROWSERS ?? FALLBACK_SOURCES)];
+  return [...commander.BROWSER_IDS];
 }
 
 /** The sign-in domains of a registry, or none. */
@@ -46,15 +32,12 @@ export function signInDomains(registry) {
 
 /** The display name of a source browser. */
 export function sourceName(browser) {
-  return SOURCE_NAMES[browser] ?? browser;
+  return catalogueName(browser);
 }
 
 /** The source id of a default-browser display name, when it can be imported. */
 export function sourceId(displayName) {
-  const entry = Object.entries(SOURCE_NAMES).find(
-    ([, name]) => name === displayName,
-  );
-  return entry && importSources().includes(entry[0]) ? entry[0] : undefined;
+  return importSources().find((id) => sourceName(id) === displayName);
 }
 
 /**
@@ -87,7 +70,12 @@ export async function findSignInSources(domains, options = {}) {
   );
   const found = [];
   for (const browser of browsers) {
-    const profiles = await list({ browser }).catch(() => []);
+    const profiles = await list({ browser }).catch((error) => {
+      if (options.verbose) {
+        console.error(`could not list ${browser} profiles: ${error.message}`);
+      }
+      return [];
+    });
     for (const profile of profiles) {
       const matched = [];
       for (const domain of domains) {
@@ -171,15 +159,15 @@ export async function chooseSignInSource(sources, domains, ask, auto) {
  * Resolves `--browser-import default|auto` to an installed source browser:
  * the system default browser, or for `auto` the first browser with a
  * sign-in for `domains`. Throws when `default` names a browser Browser
- * Commander cannot read yet, such as Safari.
+ * Commander cannot identify.
  */
 export async function resolveImportChoice(choice, domains, options = {}) {
   const preferred = await defaultSource(options);
   if (choice === "default") {
     if (!preferred) {
       throw new Error(
-        "--browser-import default: the default browser cannot be imported yet (Browser Commander reads " +
-          `${importSources().join(", ")}; see link-foundation/browser-commander#114)`,
+        "--browser-import default: the default browser is unknown or cannot be imported (Browser Commander sources: " +
+          `${importSources().join(", ")})`,
       );
     }
     return { browser: preferred, profile: null };

package/src/webdriver-automation.mjs

@@ -0,0 +1,125 @@
+// Firefox-family browsers use Browser Commander's native WebDriver/BiDi API.
+// Its real/CDP launcher and migration target writers do not support them yet.
+import { launchWebDriver, readBrowserCookies } from "browser-commander";
+
+import {
+  assertDedicatedProfile,
+  resolveExecutable,
+} from "./browser-catalogue.mjs";
+import { ensureProfileIgnored } from "./profile.mjs";
+import { IMPORT_CHOICES } from "./sign-in-import.mjs";
+
+/** True only for a requested host or its subdomains, never a substring. */
+export function matchesDomains(host, domains) {
+  const normalized = host.replace(/^\./, "").toLowerCase();
+  return domains.some(
+    (domain) => normalized === domain || normalized.endsWith(`.${domain}`),
+  );
+}
+
+/** The BiDi cookie shape; session cookies omit expiry. */
+export function bidiCookie(cookie) {
+  const result = {
+    name: cookie.name,
+    value: { type: "string", value: cookie.value },
+    domain: cookie.domain,
+    path: cookie.path ?? "/",
+    httpOnly: cookie.httpOnly ?? false,
+    secure: cookie.secure ?? false,
+    sameSite: (cookie.sameSite ?? "Lax").toLowerCase(),
+  };
+  if (cookie.expires > 0) {
+    result.expiry = cookie.expires;
+  }
+  return result;
+}
+
+/** Launches the selected installed Firefox variant and exposes the common page API. */
+export async function connectWebDriverAutomation(
+  { browser, profile, verbose, domains },
+  dependencies = {},
+) {
+  // Validation happens before profile creation, including programmatic callers.
+  if (
+    browser.attach ||
+    browser.restrictions.length ||
+    Object.keys(browser.preferences).length ||
+    (browser.import && browser.importScope === "full")
+  ) {
+    throw new Error(
+      `unsupported Firefox launch options for ${browser.channel}; use --browser-import-scope domains without snapshot, preferences or restrictions`,
+    );
+  }
+  if (browser.import && domains.length === 0) {
+    throw new Error("a domains import needs the registry's sign-in domains");
+  }
+  const executablePath = await (
+    dependencies.resolveExecutable ?? resolveExecutable
+  )({
+    channel: browser.channel.toLowerCase(),
+    executablePath: browser.executable,
+  });
+  assertDedicatedProfile(profile);
+  await ensureProfileIgnored(profile, { verbose });
+  const connection = await (dependencies.launchWebDriver ?? launchWebDriver)({
+    browser: "firefox",
+    executablePath,
+    userDataDir: profile,
+    headless: false,
+    bidi: true,
+    verbose,
+  });
+  try {
+    await connection.page.bidiCommand("storage.getCookies", {});
+    if (browser.import && !IMPORT_CHOICES.includes(browser.import.browser)) {
+      const read = dependencies.readCookies ?? readBrowserCookies;
+      const seen = new Set();
+      for (const domain of domains) {
+        const cookies = await read({
+          browser: browser.import.browser,
+          profile: browser.import.profile ?? undefined,
+          domainFilter: domain,
+          cache: false,
+        });
+        for (const cookie of cookies) {
+          const key = JSON.stringify([cookie.domain, cookie.path, cookie.name]);
+          if (!matchesDomains(cookie.domain, domains) || seen.has(key)) {
+            continue;
+          }
+          seen.add(key);
+          await connection.page.bidiCommand("storage.setCookie", {
+            cookie: bidiCookie(cookie),
+          });
+        }
+      }
+    }
+  } catch (error) {
+    await connection.close().catch(() => {});
+    throw new Error(
+      `could not prepare ${browser.channel} sign-in cookies (WebDriver BiDi storage is required)`,
+      { cause: error },
+    );
+  }
+  return {
+    goto: (url) => connection.page.goto(url),
+    evaluate: (script) => connection.page.evaluate(script),
+    close: () => connection.close(),
+    async clearCookies(names) {
+      const { cookies } = await connection.page.bidiCommand(
+        "storage.getCookies",
+        {},
+      );
+      for (const cookie of cookies) {
+        if (matchesDomains(cookie.domain, names)) {
+          await connection.page.bidiCommand("storage.deleteCookies", {
+            filter: {
+              name: cookie.name,
+              domain: cookie.domain,
+              path: cookie.path,
+            },
+          });
+        }
+      }
+    },
+  };
+}