browser-commander 0.14.0 → 0.16.0

package/src/browser/browser-profiles.js

@@ -0,0 +1,280 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const SUPPORTED_COOKIE_BROWSERS = [
+  'chrome',
+  'edge',
+  'brave',
+  'chromium',
+  'firefox',
+];
+
+function platformPath(platform) {
+  return platform === 'win32' ? path.win32 : path;
+}
+
+export function normalizeCookieBrowser(browser) {
+  const normalized = browser === 'msedge' ? 'edge' : browser;
+  if (!SUPPORTED_COOKIE_BROWSERS.includes(normalized)) {
+    throw new Error(
+      `Unsupported browser: ${browser}. Expected one of ${SUPPORTED_COOKIE_BROWSERS.join(', ')}`
+    );
+  }
+  return normalized;
+}
+
+export function browserProfileRoot(
+  browser,
+  {
+    platform = process.platform,
+    homeDir = os.homedir(),
+    environment = process.env,
+  } = {}
+) {
+  const normalizedBrowser = normalizeCookieBrowser(browser);
+  const pathApi = platformPath(platform);
+  if (platform === 'darwin') {
+    const support = pathApi.join(homeDir, 'Library', 'Application Support');
+    const roots = {
+      brave: pathApi.join(support, 'BraveSoftware', 'Brave-Browser'),
+      chrome: pathApi.join(support, 'Google', 'Chrome'),
+      chromium: pathApi.join(support, 'Chromium'),
+      edge: pathApi.join(support, 'Microsoft Edge'),
+      firefox: pathApi.join(support, 'Firefox'),
+    };
+    return roots[normalizedBrowser];
+  }
+  if (platform === 'win32') {
+    const localAppData =
+      environment.LOCALAPPDATA ?? pathApi.join(homeDir, 'AppData', 'Local');
+    const roamingAppData =
+      environment.APPDATA ?? pathApi.join(homeDir, 'AppData', 'Roaming');
+    const roots = {
+      brave: pathApi.join(
+        localAppData,
+        'BraveSoftware',
+        'Brave-Browser',
+        'User Data'
+      ),
+      chrome: pathApi.join(localAppData, 'Google', 'Chrome', 'User Data'),
+      chromium: pathApi.join(localAppData, 'Chromium', 'User Data'),
+      edge: pathApi.join(localAppData, 'Microsoft', 'Edge', 'User Data'),
+      firefox: pathApi.join(roamingAppData, 'Mozilla', 'Firefox'),
+    };
+    return roots[normalizedBrowser];
+  }
+  const roots = {
+    brave: pathApi.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser'),
+    chrome: pathApi.join(homeDir, '.config', 'google-chrome'),
+    chromium: pathApi.join(homeDir, '.config', 'chromium'),
+    edge: pathApi.join(homeDir, '.config', 'microsoft-edge'),
+    firefox: pathApi.join(homeDir, '.mozilla', 'firefox'),
+  };
+  return roots[normalizedBrowser];
+}
+
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function chromiumCookiePaths(profilePath, pathApi = path) {
+  return [
+    pathApi.join(profilePath, 'Network', 'Cookies'),
+    pathApi.join(profilePath, 'Cookies'),
+  ];
+}
+
+export async function findCookieDatabase(browser, profilePath, platform) {
+  const pathApi = platformPath(platform ?? process.platform);
+  if (normalizeCookieBrowser(browser) === 'firefox') {
+    const candidate = pathApi.join(profilePath, 'cookies.sqlite');
+    return (await pathExists(candidate)) ? candidate : null;
+  }
+  for (const candidate of chromiumCookiePaths(profilePath, pathApi)) {
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function listChromiumProfiles(browser, root, platform) {
+  if (!(await pathExists(root))) {
+    return [];
+  }
+  const pathApi = platformPath(platform);
+  const localState = await readJson(pathApi.join(root, 'Local State'));
+  const infoCache = localState.profile?.info_cache ?? {};
+  const names = new Set(Object.keys(infoCache));
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const entry of entries) {
+      if (
+        entry.isDirectory() &&
+        (entry.name === 'Default' || entry.name.startsWith('Profile '))
+      ) {
+        names.add(entry.name);
+      }
+    }
+  } catch {
+    return [];
+  }
+
+  const profiles = [];
+  for (const name of names) {
+    const profilePath = pathApi.join(root, name);
+    if (!(await findCookieDatabase(browser, profilePath, platform))) {
+      continue;
+    }
+    profiles.push({
+      browser,
+      name,
+      displayName: infoCache[name]?.name ?? name,
+      path: profilePath,
+      isDefault:
+        name === (localState.profile?.last_used ?? 'Default') ||
+        (names.size === 1 && name === 'Default'),
+    });
+  }
+  return profiles.sort(
+    (left, right) =>
+      Number(right.isDefault) - Number(left.isDefault) ||
+      left.name.localeCompare(right.name)
+  );
+}
+
+function parseIni(text) {
+  const sections = [];
+  let current;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const sectionMatch = /^\[([^\]]+)]$/.exec(line);
+    if (sectionMatch) {
+      current = { section: sectionMatch[1] };
+      sections.push(current);
+      continue;
+    }
+    const separator = line.indexOf('=');
+    if (current && separator > 0 && !line.startsWith(';')) {
+      current[line.slice(0, separator)] = line.slice(separator + 1);
+    }
+  }
+  return sections;
+}
+
+async function listFirefoxProfiles(root, platform) {
+  if (!(await pathExists(root))) {
+    return [];
+  }
+  const pathApi = platformPath(platform);
+  let sections = [];
+  try {
+    sections = parseIni(
+      await readFile(pathApi.join(root, 'profiles.ini'), 'utf8')
+    );
+  } catch {
+    const profilesRoot = pathApi.join(root, 'Profiles');
+    try {
+      const entries = await readdir(profilesRoot, { withFileTypes: true });
+      sections = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({
+          section: 'Profile',
+          Name: entry.name,
+          Path: entry.name,
+          ProfilesRoot: profilesRoot,
+        }));
+    } catch {
+      return [];
+    }
+  }
+
+  const profiles = [];
+  for (const section of sections.filter(({ section }) =>
+    section.startsWith('Profile')
+  )) {
+    if (!section.Path) {
+      continue;
+    }
+    const relativeRoot = section.ProfilesRoot ?? root;
+    const profilePath =
+      section.IsRelative === '0'
+        ? section.Path
+        : pathApi.resolve(relativeRoot, section.Path);
+    if (!(await findCookieDatabase('firefox', profilePath, platform))) {
+      continue;
+    }
+    const displayName = section.Name ?? pathApi.basename(profilePath);
+    profiles.push({
+      browser: 'firefox',
+      name: displayName,
+      displayName,
+      path: profilePath,
+      isDefault: section.Default === '1',
+    });
+  }
+  return profiles.sort(
+    (left, right) =>
+      Number(right.isDefault) - Number(left.isDefault) ||
+      left.name.localeCompare(right.name)
+  );
+}
+
+/** Discover cookie-bearing profiles from installed browsers. */
+export async function listBrowserProfiles({
+  browser,
+  platform = process.platform,
+  homeDir = os.homedir(),
+  environment = process.env,
+} = {}) {
+  const browsers = browser
+    ? [normalizeCookieBrowser(browser)]
+    : SUPPORTED_COOKIE_BROWSERS;
+  const profiles = [];
+  for (const candidate of browsers) {
+    const root = browserProfileRoot(candidate, {
+      platform,
+      homeDir,
+      environment,
+    });
+    profiles.push(
+      ...(candidate === 'firefox'
+        ? await listFirefoxProfiles(root, platform)
+        : await listChromiumProfiles(candidate, root, platform))
+    );
+  }
+  return profiles;
+}
+
+export async function resolveBrowserProfile(options) {
+  const browser = normalizeCookieBrowser(options.browser);
+  const profiles = await listBrowserProfiles({ ...options, browser });
+  const requested = options.profile;
+  const selected = requested
+    ? profiles.find(
+        ({ name, displayName, path: profilePath }) =>
+          requested === name ||
+          requested === displayName ||
+          requested === platformPath(options.platform).basename(profilePath)
+      )
+    : (profiles.find(({ isDefault }) => isDefault) ?? profiles[0]);
+  if (!selected) {
+    const detail = requested ? ` profile "${requested}"` : ' profile';
+    throw new Error(`Could not find a cookie database for ${browser}${detail}`);
+  }
+  return selected;
+}

package/src/browser/launch-options.js

@@ -1,3 +1,47 @@
+import { CHROME_ARGS } from '../core/constants.js';
+
+function stringArray(value, name) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    throw new TypeError(`${name} must be an array of strings`);
+  }
+  return value;
+}
+
+/** Resolve Browser Commander defaults, compatibility args, and extra args. */
+export function resolveChromeArgs({
+  args = [],
+  extraArgs = [],
+  ignoreDefaultArgs = [],
+} = {}) {
+  stringArray(args, 'args');
+  stringArray(extraArgs, 'extraArgs');
+  if (
+    typeof ignoreDefaultArgs !== 'boolean' &&
+    !Array.isArray(ignoreDefaultArgs)
+  ) {
+    throw new TypeError('ignoreDefaultArgs must be a boolean or string array');
+  }
+  if (Array.isArray(ignoreDefaultArgs)) {
+    stringArray(ignoreDefaultArgs, 'ignoreDefaultArgs');
+  }
+
+  const normalizedIgnoreDefaultArgs =
+    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
+  const ignored = new Set(
+    normalizedIgnoreDefaultArgs === true
+      ? CHROME_ARGS
+      : normalizedIgnoreDefaultArgs
+  );
+  return {
+    args: [
+      ...CHROME_ARGS.filter((argument) => !ignored.has(argument)),
+      ...args,
+      ...extraArgs,
+    ],
+    ignoreDefaultArgs: normalizedIgnoreDefaultArgs,
+  };
+}
+
 function setBrowserSelectionOptions(options, { channel, executablePath }) {
   if (channel !== undefined) {
     options.channel = channel;
@@ -15,14 +59,21 @@ export function buildPlaywrightLaunchOptions({
   colorScheme,
   channel,
   executablePath,
+  ignoreDefaultArgs = [],
 }) {
+  const normalizedIgnoreDefaultArgs =
+    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
+  const engineIgnoreDefaultArgs =
+    normalizedIgnoreDefaultArgs === true
+      ? true
+      : [...new Set(['--enable-automation', ...normalizedIgnoreDefaultArgs])];
   const options = {
     headless,
     slowMo,
     chromiumSandbox: true,
     viewport: null,
     args: chromeArgs,
-    ignoreDefaultArgs: ['--enable-automation'],
+    ignoreDefaultArgs: engineIgnoreDefaultArgs,
   };
 
   if (colorScheme !== undefined) {
@@ -38,14 +89,21 @@ export function buildPuppeteerLaunchOptions({
   userDataDir,
   channel,
   executablePath,
+  ignoreDefaultArgs = [],
 }) {
-  return setBrowserSelectionOptions(
-    {
-      headless,
-      defaultViewport: null,
-      args: ['--start-maximized', ...chromeArgs],
-      userDataDir,
-    },
-    { channel, executablePath }
-  );
+  const normalizedIgnoreDefaultArgs =
+    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
+  const options = {
+    headless,
+    defaultViewport: null,
+    args: ['--start-maximized', ...chromeArgs],
+    userDataDir,
+  };
+  if (
+    normalizedIgnoreDefaultArgs === true ||
+    normalizedIgnoreDefaultArgs.length > 0
+  ) {
+    options.ignoreDefaultArgs = normalizedIgnoreDefaultArgs;
+  }
+  return setBrowserSelectionOptions(options, { channel, executablePath });
 }

package/src/browser/launcher.js

@@ -1,11 +1,11 @@
 import path from 'path';
 import os from 'os';
-import { CHROME_ARGS } from '../core/constants.js';
 import { disableTranslateInPreferences } from '../core/preferences.js';
 import { emulateMedia } from './media.js';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
+  resolveChromeArgs,
 } from './launch-options.js';
 import {
   loadStorageState,
@@ -22,6 +22,8 @@ import {
  * @param {number} options.slowMo - Slow down operations by ms (default: 150 for Playwright, 0 for Puppeteer)
  * @param {boolean} options.verbose - Enable verbose logging (default: false)
  * @param {string[]} options.args - Custom Chrome arguments to append to the default CHROME_ARGS
+ * @param {string[]} [options.extraArgs] - Additional Chrome arguments appended after legacy args
+ * @param {boolean|string[]} [options.ignoreDefaultArgs] - Browser Commander defaults to omit, or true for all
  * @param {string|null} [options.colorScheme] - Emulate color scheme: 'light', 'dark', 'no-preference', or null to reset
  * @param {string} [options.channel] - Installed browser channel, such as 'chrome', 'chrome-beta', or 'msedge'
  * @param {string} [options.executablePath] - Explicit path to a Chrome or Chromium executable
@@ -36,14 +38,20 @@ export async function launchBrowser(options = {}) {
     slowMo = engine === 'playwright' ? 150 : 0,
     verbose = false,
     args = [],
+    extraArgs = [],
+    ignoreDefaultArgs = [],
     colorScheme,
     channel,
     executablePath,
     storageState,
   } = options;
 
-  // Combine default CHROME_ARGS with custom args
-  const chromeArgs = [...CHROME_ARGS, ...args];
+  const resolvedChromeArgs = resolveChromeArgs({
+    args,
+    extraArgs,
+    ignoreDefaultArgs,
+  });
+  const chromeArgs = resolvedChromeArgs.args;
 
   if (!['playwright', 'puppeteer'].includes(engine)) {
     throw new Error(
@@ -77,6 +85,7 @@ export async function launchBrowser(options = {}) {
       colorScheme,
       channel,
       executablePath,
+      ignoreDefaultArgs: resolvedChromeArgs.ignoreDefaultArgs,
     });
     browser = await chromium.launchPersistentContext(
       userDataDir,
@@ -96,6 +105,7 @@ export async function launchBrowser(options = {}) {
         userDataDir,
         channel,
         executablePath,
+        ignoreDefaultArgs: resolvedChromeArgs.ignoreDefaultArgs,
       })
     );
     const pages = await browser.pages();

package/src/browser/real-browser.js

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { connectBrowser } from './connector.js';
+import { resolveChromeArgs } from './launch-options.js';
 
 const MANAGED_ARGUMENTS = [
   '--remote-debugging-address',
@@ -240,6 +241,8 @@ export function buildRealBrowserArgs({
   remoteDebuggingPort = 0,
   headless = false,
   args = [],
+  extraArgs = [],
+  ignoreDefaultArgs = [],
 }) {
   if (
     !Number.isInteger(remoteDebuggingPort) ||
@@ -250,7 +253,8 @@ export function buildRealBrowserArgs({
       'remoteDebuggingPort must be an integer from 0 to 65535'
     );
   }
-  const conflictingArgument = args.find((argument) =>
+  const customArgs = [...args, ...extraArgs];
+  const conflictingArgument = customArgs.find((argument) =>
     MANAGED_ARGUMENTS.some(
       (managed) => argument === managed || argument.startsWith(`${managed}=`)
     )
@@ -261,14 +265,15 @@ export function buildRealBrowserArgs({
     );
   }
 
+  const defaultArgs = resolveChromeArgs({ ignoreDefaultArgs }).args;
+
   return [
     '--remote-debugging-address=127.0.0.1',
     `--remote-debugging-port=${remoteDebuggingPort}`,
     `--user-data-dir=${userDataDir}`,
-    '--no-first-run',
-    '--no-default-browser-check',
+    ...defaultArgs,
     ...(headless ? ['--headless=new'] : []),
-    ...args,
+    ...customArgs,
   ];
 }
 
@@ -353,6 +358,8 @@ export async function waitForCdpEndpoint({
  * @param {number} [options.remoteDebuggingPort=0] - Loopback CDP port; zero lets Chrome choose
  * @param {boolean} [options.headless=false] - Run the installed browser headlessly
  * @param {string[]} [options.args] - Additional browser arguments
+ * @param {string[]} [options.extraArgs] - Additional browser arguments appended after legacy args
+ * @param {boolean|string[]} [options.ignoreDefaultArgs] - Browser Commander defaults to omit, or true for all
  * @param {number} [options.startupTimeout=30000] - CDP readiness timeout in milliseconds
  * @param {Object[]} [options.seedCookies] - Cookies to seed after connecting
  * @param {boolean} [options.verbose=false] - Show browser and connection logs
@@ -384,6 +391,8 @@ export async function launchAndConnectRealBrowserWithDependencies(
     remoteDebuggingPort = 0,
     headless = false,
     args = [],
+    extraArgs = [],
+    ignoreDefaultArgs = [],
     startupTimeout = 30_000,
     verbose = false,
     cdpEndpoint,
@@ -409,6 +418,8 @@ export async function launchAndConnectRealBrowserWithDependencies(
     remoteDebuggingPort,
     headless,
     args,
+    extraArgs,
+    ignoreDefaultArgs,
   });
   const spawnBrowser = dependencies.spawnBrowser ?? spawn;
   const browserProcess = spawnBrowser(resolvedExecutablePath, browserArgs, {

package/src/core/constants.js

@@ -5,6 +5,7 @@ export const CHROME_ARGS = [
   '--disable-session-crashed-bubble',
   '--hide-crash-restore-bubble',
   '--disable-infobars',
+  '--password-store=basic',
   '--no-first-run',
   '--no-default-browser-check',
   '--disable-crash-restore',

package/src/exports.js

@@ -43,6 +43,10 @@ export {
 
 // Re-export browser management
 export { connectBrowser } from './browser/connector.js';
+export {
+  listBrowserProfiles,
+  readBrowserCookies,
+} from './browser/browser-cookies.js';
 export {
   launchAndConnectRealBrowser,
   launchRealBrowser,

package/tests/fixtures/browser-cookie-cache-worker.mjs

@@ -0,0 +1,21 @@
+import { appendFile } from 'node:fs/promises';
+
+import { getCachedCredential } from '../../src/browser/browser-cookie-cache.js';
+
+const [, , cacheDir, credentialReads] = process.argv;
+
+await getCachedCredential({
+  cache: { enabled: true, dir: cacheDir, ttlSeconds: 60 },
+  identity: 'chrome:linux:safe-storage',
+  refresh: false,
+  metadata: {
+    browser: 'chrome',
+    platform: 'linux',
+    source: 'safe-storage',
+  },
+  create: async () => {
+    await appendFile(credentialReads, `${process.pid}\n`, 'utf8');
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    return Buffer.alloc(16, 7);
+  },
+});