browser-commander 0.26.3 → 0.28.0

package/src/browser/browser-cookie-session.js

@@ -0,0 +1,183 @@
+import path from 'node:path';
+import { rm } from 'node:fs/promises';
+import { browserFamily } from './browser-sources.js';
+import { matchesDomains } from './migration/domains.js';
+import {
+  resolveBrowserProfile,
+  resolveSourceBrowser,
+} from './browser-profiles.js';
+import { saveStorageState } from './storage-state.js';
+import { setCookies } from './session-cookies.js';
+
+/** Decrypt through the source browser in a disposable cookie-only snapshot. */
+export async function readBrowserCookieSession(options, dependencies = {}) {
+  const browser = await resolveSourceBrowser(options.browser, dependencies);
+  if (browserFamily(browser) !== 'chromium') {
+    throw new TypeError(
+      'Browser-backed cookie reading requires a Chromium snapshot; use via: database for Firefox or Safari'
+    );
+  }
+  const profile = options.profileDir
+    ? { path: options.profileDir }
+    : await resolveBrowserProfile({
+        ...dependencies,
+        browser,
+        profile: options.profile,
+      });
+  const launch =
+    dependencies.launch ??
+    (await import('./real-browser.js')).launchRealBrowser;
+  const result = await launch({
+    ...options.launchOptions,
+    channel: browser,
+    engine: options.engine ?? 'playwright',
+    attach: {
+      mode: 'snapshot',
+      browser,
+      profile: path.basename(profile.path),
+      userDataDir: path.dirname(profile.path),
+      include: ['cookies'],
+    },
+  });
+  try {
+    const state = await saveStorageState(result.page);
+    return state.cookies.filter((cookie) =>
+      matchesDomains(
+        cookie.domain,
+        options.domains ?? (options.domainFilter ? [options.domainFilter] : [])
+      )
+    );
+  } finally {
+    await result.close();
+  }
+}
+
+async function readDatabaseSession(source, options, dependencies) {
+  const read =
+    dependencies.readCookies ??
+    (await import('./browser-cookies.js')).readBrowserCookies;
+  const cookies = (
+    await read({
+      browser: source.browser,
+      profileDir: source.path,
+      via: 'database',
+      cache: false,
+    })
+  ).filter((cookie) => matchesDomains(cookie.domain, options.domains));
+  let loggedIn = null;
+  if (options.isLoggedIn) {
+    const launch =
+      dependencies.launch ?? (await import('./launcher.js')).launchBrowser;
+    const engine = source.engine ?? options.engine ?? 'playwright';
+    const result = await launch({
+      ...options.launchOptions,
+      ...source.launchOptions,
+      engine,
+      launch: 'engine',
+      userDataDir: undefined,
+      attach: undefined,
+      persistSessionCookies: false,
+    });
+    try {
+      await setCookies({ page: result.page, engine, cookies });
+      loggedIn = Boolean(
+        await options.isLoggedIn({ ...result, source, cookies })
+      );
+    } finally {
+      await result.close();
+    }
+  }
+  return { ...source, cookies, loggedIn };
+}
+
+/** Discover candidate profiles and optionally validate their live sign-in state. */
+export async function findSiteSessions(options = {}, dependencies = {}) {
+  if (!Array.isArray(options.domains) || !options.domains.length) {
+    throw new TypeError('findSiteSessions requires domains');
+  }
+  const list =
+    dependencies.listSources ??
+    (await import('./browser-cookies.js')).listCookieSources;
+  const sources = [
+    ...(options.sources ?? (await list({ domains: options.domains }))),
+    ...(options.profiles ?? []),
+  ];
+  const sessions = [];
+  for (const source of sources) {
+    let result;
+    let snapshot;
+    try {
+      if (browserFamily(source.browser) !== 'chromium') {
+        sessions.push(await readDatabaseSession(source, options, dependencies));
+        continue;
+      }
+      const attach = {
+        mode: 'snapshot',
+        browser: source.browser,
+        profile: path.basename(source.path),
+        userDataDir: path.dirname(source.path),
+        include: ['cookies'],
+      };
+      if (source.launch === 'engine') {
+        const copy =
+          dependencies.snapshot ??
+          (await import('./attach/snapshot.js')).snapshotUserDataDir;
+        snapshot = await copy(attach);
+        const launch =
+          dependencies.launch ?? (await import('./launcher.js')).launchBrowser;
+        result = await launch({
+          ...options.launchOptions,
+          ...source.launchOptions,
+          engine: source.engine ?? options.engine ?? 'playwright',
+          launch: 'engine',
+          userDataDir: snapshot.target,
+          args: [
+            ...(options.launchOptions?.args ?? []),
+            ...(source.launchOptions?.args ?? []),
+            `--profile-directory=${attach.profile}`,
+          ],
+        });
+      } else {
+        const launch =
+          dependencies.launch ??
+          (await import('./real-browser.js')).launchRealBrowser;
+        result = await launch({
+          ...options.launchOptions,
+          engine: source.engine ?? options.engine ?? 'playwright',
+          channel: source.browser,
+          attach,
+        });
+      }
+      const state = await saveStorageState(result.page);
+      const cookies = state.cookies.filter((cookie) =>
+        matchesDomains(cookie.domain, options.domains)
+      );
+      const loggedIn = options.isLoggedIn
+        ? Boolean(await options.isLoggedIn({ ...result, source, cookies }))
+        : null;
+      sessions.push({ ...source, cookies, loggedIn });
+    } catch (error) {
+      sessions.push({
+        ...source,
+        cookies: [],
+        loggedIn: null,
+        error: error.message,
+      });
+    } finally {
+      try {
+        await result?.close();
+      } catch (error) {
+        sessions.at(-1).error = error.message;
+      } finally {
+        if (snapshot) {
+          try {
+            await rm(snapshot.target, { recursive: true, force: true });
+          } catch (error) {
+            sessions.at(-1).error = error.message;
+          }
+        }
+      }
+    }
+  }
+  return sessions;
+}

package/src/browser/browser-cookies.js

@@ -1,3 +1,4 @@
+import { readBrowserCookieSession } from './browser-cookie-session.js';
 import { localStatePathForProfile } from './browser-profile-files.js';
 import os from 'node:os';
 
@@ -126,6 +127,17 @@ function encryptionPrefix(encryptedValue) {
 }
 
 function chromiumKeyForPrefix(context, prefix) {
+  if (context.keystore === 'mock') {
+    if (context.platform === 'win32') {
+      throw new Error(
+        'Use via: browser for Windows engine mock-keystore profiles'
+      );
+    }
+    return deriveChromiumCookieKey(
+      context.platform === 'darwin' ? 'mock_password' : 'peanuts',
+      context.platform
+    );
+  }
   if (context.platform === 'linux' && prefix === 'v10') {
     return deriveChromiumCookieKey('peanuts', 'linux');
   }
@@ -279,6 +291,21 @@ export async function readBrowserCookiesWithDependencies(
     throw new TypeError('readBrowserCookies requires an options object');
   }
   const platform = dependencies.platform ?? process.platform;
+  const via =
+    options.via ??
+    (platform === 'darwin' &&
+    options.keystore !== 'mock' &&
+    browserFamily(
+      await resolveSourceBrowser(options.browser, { ...dependencies, platform })
+    ) === 'chromium'
+      ? 'browser'
+      : 'database');
+  if (!['browser', 'database', 'keychain'].includes(via)) {
+    throw new TypeError('via must be browser, database, or keychain');
+  }
+  if (via === 'browser') {
+    return readBrowserCookieSession(options, { ...dependencies, platform });
+  }
   const homeDir = dependencies.homeDir ?? os.homedir();
   const environment = dependencies.environment ?? process.env;
   const runCommand = dependencies.runCommand;
@@ -316,6 +343,7 @@ export async function readBrowserCookiesWithDependencies(
     profile: profilePath,
     domainFilter: options.domainFilter ?? null,
     ignoreDecryptionErrors: options.ignoreDecryptionErrors === true,
+    keystore: options.keystore ?? 'os',
   });
   const now = dependencies.now ?? Date.now;
   const cachedCookies = await readCookieResultCache({
@@ -348,6 +376,7 @@ export async function readBrowserCookiesWithDependencies(
       const rows = readChromiumRows(database, options.domainFilter);
       cookies = await mapChromiumRows(rows, databaseVersion, {
         browser,
+        keystore: options.keystore,
         cache,
         credentialKeys: new Map(),
         decryptWindowsDpapi:

package/src/browser/connector.js

@@ -45,6 +45,7 @@ async function connectSelenium(options, dependencies) {
         ...options,
         debuggerAddress: new URL(options.cdpEndpoint).host,
       });
+  await selectWebDriverTab(connected.driver, options);
   return {
     ...connected,
     browser: connected.driver,
@@ -52,6 +53,52 @@ async function connectSelenium(options, dependencies) {
   };
 }
 
+async function selectWebDriverTab(driver, options) {
+  if (!driver?.getAllWindowHandles) {
+    return;
+  }
+  const original = await driver.getWindowHandle();
+  const handles = await driver.getAllWindowHandles();
+  let selected = original;
+  if (options.targetId || options.url) {
+    selected = null;
+    for (const handle of handles) {
+      if (
+        options.targetId &&
+        handle !== options.targetId &&
+        handle !== `CDwindow-${options.targetId}`
+      ) {
+        continue;
+      }
+      await driver.switchTo().window(handle);
+      const url = await driver.getCurrentUrl();
+      if (
+        options.url &&
+        !(typeof options.url === 'function'
+          ? options.url(url)
+          : options.url instanceof RegExp
+            ? options.url.test(url)
+            : url === options.url)
+      ) {
+        continue;
+      }
+      selected = handle;
+      break;
+    }
+    if (!selected) {
+      await driver.switchTo().window(original);
+      throw new Error('No tab matches the requested targetId or URL');
+    }
+  }
+  if (options.singleTab) {
+    for (const handle of handles.filter((handle) => handle !== selected)) {
+      await driver.switchTo().window(handle);
+      await driver.close();
+    }
+  }
+  await driver.switchTo().window(selected);
+}
+
 function addDefinedOptions(options, values) {
   for (const [key, value] of Object.entries(values)) {
     if (value !== undefined) {
@@ -111,19 +158,75 @@ async function prepareStorageState({ storageState, seedCookies }) {
  * @param {Object[]} pages - Engine page handles
  * @returns {Promise<Object|undefined>}
  */
-export async function pickForegroundPage(pages) {
+export async function pickForegroundPage(pages, options = {}) {
+  const targets = new Map();
+  // Playwright emulates focus on every attached tab. Remove the emulation
+  // before observing visibility; DevTools target order has no active-tab flag.
   for (const page of pages) {
-    if (typeof page?.evaluate !== 'function') {
-      continue;
+    let session;
+    try {
+      session =
+        (await page.context?.().newCDPSession?.(page)) ??
+        (await page.target?.().createCDPSession?.());
+      if (!session) {
+        continue;
+      }
+      const { targetInfo } = await session.send('Target.getTargetInfo');
+      targets.set(page, targetInfo.targetId);
+      await session.send('Emulation.setFocusEmulationEnabled', {
+        enabled: false,
+      });
+    } catch {
+      // Non-Chromium engines do not expose CDP. Explicit URL matching still
+      // works there, and normal visibility is not affected by this emulation.
+    } finally {
+      await session?.detach?.().catch(() => {});
+    }
+  }
+  let selected;
+  if (options.targetId || options.url) {
+    selected = pages.find((page) => {
+      if (options.targetId && targets.get(page) !== options.targetId) {
+        return false;
+      }
+      const url = page.url();
+      const matcher = options.url;
+      if (matcher instanceof RegExp) {
+        matcher.lastIndex = 0;
+        return matcher.test(url);
+      }
+      if (typeof matcher === 'function') {
+        return matcher(url);
+      }
+      return !matcher || matcher === url;
+    });
+    if (!selected) {
+      throw new RangeError('No tab matches the requested targetId/URL');
     }
-    const state = await page
-      .evaluate(() => document.visibilityState)
-      .catch(() => null);
-    if (state === 'visible') {
-      return page;
+  }
+  if (!selected) {
+    for (const page of pages) {
+      if (typeof page?.evaluate !== 'function') {
+        continue;
+      }
+      const state = await page
+        .evaluate(() => document.visibilityState)
+        .catch(() => null);
+      if (state === 'visible') {
+        selected = page;
+        break;
+      }
+    }
+  }
+  selected ??= pages[0];
+  if (options.singleTab && selected) {
+    for (const page of pages) {
+      if (page !== selected) {
+        await page.close();
+      }
     }
   }
-  return pages[0];
+  return selected;
 }
 
 async function connectPlaywright({ options, loadPlaywright, storageState }) {
@@ -138,10 +241,11 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
     throw new Error('Connected Playwright browser has no default context');
   }
   const page =
-    (await pickForegroundPage(context.pages())) ?? (await context.newPage());
+    (await pickForegroundPage(context.pages(), options)) ??
+    (await context.newPage());
 
   await restorePlaywrightStorageState({ context, storageState });
-  return { browser, page };
+  return { browser, page, detach: browser.close?.bind(browser) };
 }
 
 async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
@@ -151,11 +255,11 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
     buildPuppeteerConnectOptions(options)
   );
   const page =
-    (await pickForegroundPage(await browser.pages())) ??
+    (await pickForegroundPage(await browser.pages(), options)) ??
     (await browser.newPage());
 
   await restorePuppeteerStorageState({ page, storageState });
-  return { browser, page };
+  return { browser, page, detach: browser.disconnect?.bind(browser) };
 }
 
 /**

package/src/browser/debugging-port.js

@@ -117,7 +117,7 @@ export function watchDevToolsOutput(stream, { forward = false } = {}) {
   }
   let text = '';
   let settled = null;
-  stream.on('data', (chunk) => {
+  const onData = (chunk) => {
     if (forward) {
       process.stderr.write(chunk);
     }
@@ -130,9 +130,11 @@ export function watchDevToolsOutput(stream, { forward = false } = {}) {
     if (parsed.listening) {
       settled = parsed;
     }
-  });
+  };
+  stream.on('data', onData);
   return {
     available: true,
+    dispose: () => stream.off?.('data', onData),
     state: () => settled ?? parseDevToolsOutput(text),
   };
 }

package/src/browser/default-browser.js

@@ -68,16 +68,40 @@ function parseMacLaunchServicesHandler(output) {
 }
 
 async function resolveDarwinDefault(runCommand, environment) {
-  const output = await runCommand(
-    'defaults',
-    [
-      'read',
-      'com.apple.LaunchServices/com.apple.launchservices.secure',
-      'LSHandlers',
-    ],
-    environment
+  const output = await Promise.resolve()
+    .then(() =>
+      runCommand(
+        'defaults',
+        [
+          'read',
+          'com.apple.LaunchServices/com.apple.launchservices.secure',
+          'LSHandlers',
+        ],
+        environment
+      )
+    )
+    .catch(() => '');
+  const legacy = browserForIdentifier(
+    parseMacLaunchServicesHandler(output),
+    'darwin'
   );
-  return browserForIdentifier(parseMacLaunchServicesHandler(output), 'darwin');
+  if (legacy) {
+    return legacy;
+  }
+  try {
+    const script =
+      "ObjC.import('AppKit'); var app = $.NSWorkspace.sharedWorkspace.URLForApplicationToOpenURL($.NSURL.URLWithString('https://example.invalid')); app ? ObjC.unwrap($.NSBundle.bundleWithURL(app).bundleIdentifier) : ''";
+    return browserForIdentifier(
+      await runCommand(
+        'osascript',
+        ['-l', 'JavaScript', '-e', script],
+        environment
+      ),
+      'darwin'
+    );
+  } catch {
+    return null;
+  }
 }
 
 async function resolveLinuxDefault(runCommand, environment) {

package/src/browser/launch-diagnostics.js

@@ -0,0 +1,102 @@
+/** Bounded launch evidence with a stable contract independent of engine text. */
+export class BrowserLaunchError extends Error {
+  constructor({
+    phase,
+    engine,
+    category,
+    exitCode = null,
+    signal = null,
+    stderrTail = '',
+    cause,
+  }) {
+    super(
+      `Browser launch failed (${phase}: ${category}): ${stderrTail || cause?.message || ''}`,
+      { cause }
+    );
+    this.name = 'BrowserLaunchError';
+    Object.assign(this, {
+      phase,
+      engine,
+      category,
+      exitCode,
+      signal,
+      stderrTail,
+    });
+  }
+}
+
+/** Remove paths, URL credentials/query strings and common secret assignments. */
+export function redactLaunchEvidence(value, redactor) {
+  let text = String(value ?? '')
+    .replace(/\b(?:https?|wss?):\/\/[^\s"'<>]+/giu, '[url]')
+    .replace(/(?:[A-Za-z]:\\|\/)(?:[^\s:;"'<>]+)/gu, '[path]')
+    .replace(
+      /\b(token|password|secret|authorization|cookie)\s*[=:]\s*[^\s,;]+/giu,
+      '$1=[redacted]'
+    );
+  if (redactor) {
+    try {
+      text = String(redactor(text));
+    } catch {
+      text = '[diagnostic redaction failed]';
+    }
+  }
+  const bytes = Buffer.from(text, 'utf8');
+  let start = Math.max(0, bytes.length - 4096);
+  while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) {
+    start++;
+  }
+  return bytes.subarray(start).toString('utf8');
+}
+
+export function launchFailure(
+  cause,
+  {
+    phase,
+    engine = 'playwright',
+    browserProcess,
+    diagnosticRedactor,
+    executablePath,
+    userDataDir,
+  } = {}
+) {
+  if (cause instanceof BrowserLaunchError) {
+    return cause;
+  }
+  const raw = String(cause?.message ?? cause);
+  const category =
+    cause?.code === 'ENOENT' ||
+    /not found|does not exist|not an executable|not accessible|could not find an installed|no .*executable/i.test(
+      raw
+    )
+      ? 'missing_executable'
+      : cause?.name === 'PortRaceError'
+        ? 'port_race'
+        : /timed out|timeout/i.test(raw)
+          ? 'startup_timeout'
+          : browserProcess?.exitCode !== null &&
+              browserProcess?.exitCode !== undefined
+            ? 'early_exit'
+            : 'configuration';
+  const scrub = (value) => {
+    let text = String(value ?? '');
+    for (const sensitive of [executablePath, userDataDir]) {
+      if (sensitive) {
+        text = text.replaceAll(sensitive, '[path]');
+      }
+    }
+    return redactLaunchEvidence(text, diagnosticRedactor);
+  };
+  const safeCause = new Error(scrub(raw));
+  safeCause.name = cause?.name ?? 'Error';
+  safeCause.code = cause?.code;
+  return new BrowserLaunchError({
+    phase,
+    engine,
+    category,
+    exitCode: browserProcess?.exitCode ?? null,
+    signal: browserProcess?.signalCode ?? null,
+    stderrTail: scrub(browserProcess?.stderrTail ?? cause?.stderrTail ?? ''),
+    cause: safeCause,
+  });
+}

package/src/browser/launch-options.js

@@ -26,6 +26,7 @@ export function resolveChromeArgs({
   extraArgs = [],
   ignoreDefaultArgs = [],
   restrictions = [],
+  disableFeatures = [],
 } = {}) {
   assertStringArray(args, 'args');
   assertStringArray(extraArgs, 'extraArgs');
@@ -41,7 +42,7 @@ export function resolveChromeArgs({
 
   return {
     args: mergeFeatureSwitches([
-      ...resolveRestrictions(restrictions).args,
+      ...resolveRestrictions(restrictions, { disableFeatures }).args,
       ...args,
       ...extraArgs,
     ]),

package/src/browser/launch-restrictions.json

@@ -17,7 +17,8 @@
         "--disable-session-crashed-bubble",
         "--hide-crash-restore-bubble",
         "--disable-crash-restore"
-      ]
+      ],
+      "disableFeatures": ["SessionRestoreInfobar"]
     },
     {
       "id": "no-infobars",
@@ -60,7 +61,12 @@
     {
       "id": "no-translate",
       "description": "Disable the Translate feature and its bubble.",
-      "disableFeatures": ["Translate"]
+      "disableFeatures": ["Translate"],
+      "preferences": {
+        "translate": {
+          "enabled": false
+        }
+      }
     },
     {
       "id": "no-component-update",
@@ -124,6 +130,24 @@
       "id": "start-maximized",
       "description": "Start with a maximized window.",
       "args": ["--start-maximized"]
+    },
+    {
+      "id": "no-save-bubbles",
+      "description": "Suppress password and payment-card saving bubbles and browser promos.",
+      "disableFeatures": [
+        "AutofillSaveCardUi",
+        "ChromeWhatsNewUI",
+        "PromotionalTabs"
+      ],
+      "preferences": {
+        "credentials_enable_service": false,
+        "profile": {
+          "password_manager_enabled": false
+        },
+        "autofill": {
+          "credit_card_enabled": false
+        }
+      }
     }
   ],
   "presets": {
@@ -142,6 +166,13 @@
       "no-default-browser-check",
       "no-google-services",
       "no-translate"
+    ],
+    "quiet-ui": [
+      "no-first-run",
+      "no-default-browser-check",
+      "no-crash-restore",
+      "no-translate",
+      "no-save-bubbles"
     ]
   }
 }