browser-commander 0.26.2 → 0.27.0

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/browser-sources.js

@@ -141,6 +141,19 @@ export function resolveBrowserRoots(name, options = {}) {
   return resolveTemplates(templates, options);
 }
 
+/**
+ * Browser-owned paths forbidden as automation profiles. Import discovery may
+ * search broader locations; use explicit protection roots when declared.
+ */
+export function resolveBrowserProtectionRoots(name, options = {}) {
+  const source = normalizeBrowserSource(name);
+  const roots = source.protectionRoots ?? source.roots;
+  return resolveTemplates(
+    roots?.[options.platform ?? process.platform] ?? [],
+    options
+  );
+}
+
 function resolveTemplates(
   templates,
   {

package/src/browser/browser-sources.json

@@ -764,6 +764,13 @@
           "{home}/Library"
         ]
       },
+      "protectionRoots": {
+        "darwin": [
+          "{home}/Library/Safari",
+          "{home}/Library/Containers/com.apple.Safari",
+          "{home}/Library/Cookies"
+        ]
+      },
       "default": {
         "darwin": ["com.apple.safari"]
       },
@@ -781,6 +788,12 @@
           "{home}/Library/Safari Technology Preview"
         ]
       },
+      "protectionRoots": {
+        "darwin": [
+          "{home}/Library/Safari Technology Preview",
+          "{home}/Library/Containers/com.apple.SafariTechnologyPreview"
+        ]
+      },
       "default": {
         "darwin": ["com.apple.safaritechnologypreview"]
       },

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/launcher.js

@@ -1,4 +1,9 @@
 import { access } from 'node:fs/promises';
+import { launchFailure } from './launch-diagnostics.js';
+import {
+  installSessionPersistence,
+  sessionPersistencePath,
+} from './session-persistence.js';
 
 import { assertSupportedEngine } from './connector.js';
 import { emulateMedia } from './media.js';
@@ -302,6 +307,7 @@ export async function launchBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  sessionPersistencePath(options);
   if (isSafariChannel(options.channel ?? options.browser)) {
     validateLaunchMode({
       engine: options.engine ?? 'playwright',
@@ -310,7 +316,13 @@ export async function launchBrowserWithDependencies(
     });
     return await launchSafari(options, dependencies);
   }
-  return await launchNonSafariBrowser(options, dependencies);
+  const result = await launchNonSafariBrowser(options, dependencies);
+  try {
+    return await installSessionPersistence(result, options);
+  } catch (error) {
+    await result.close();
+    throw error;
+  }
 }
 
 async function launchNonSafariBrowser(options, dependencies) {
@@ -361,13 +373,21 @@ async function launchNonSafariBrowser(options, dependencies) {
     automationParity,
     storageState: resolvedStorageState,
   };
-  const launched =
-    launch === 'engine'
-      ? await launchWithEngine(
-          { ...common, ignoreDefaultArgs, colorScheme },
-          dependencies
-        )
-      : await launchReal(common, dependencies);
+  let launched;
+  try {
+    launched =
+      launch === 'engine'
+        ? await launchWithEngine(
+            { ...common, ignoreDefaultArgs, colorScheme },
+            dependencies
+          )
+        : await launchReal(common, dependencies);
+  } catch (error) {
+    throw launchFailure(error, {
+      ...common,
+      phase: launch === 'engine' ? 'engine_launch' : 'launch',
+    });
+  }
   const { browser, page } = launched;
   if (verbose) {
     console.log(`✅ Browser launched with ${engine} engine`);

package/src/browser/migration/sqlite-snapshot.js

@@ -3,9 +3,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { pathExists } from './fs-utils.js';
 
-import BetterSqlite3 from 'better-sqlite3';
-
-import { openSqliteDatabase } from '../browser-cookie-database.js';
+import {
+  openSqliteDatabase,
+  backupSqliteDatabase,
+} from '../browser-cookie-database.js';
 
 /**
  * Read a Chromium SQLite database (History, Top Sites, Login Data, Web Data)
@@ -40,36 +41,13 @@ export async function withDatabaseSnapshot({ sourcePath, read }) {
   try {
     // The backup API needs to open the source. It opens read-only, so nothing
     // is written to the user's real database.
-    let source;
     try {
-      source = new BetterSqlite3(sourcePath, {
-        readonly: true,
-        fileMustExist: true,
-        timeout: 1000,
-      });
-      // Detect an exclusive lock before better-sqlite3's initial zero-page
-      // transfer can mistake SQLITE_BUSY for an empty completed backup.
-      source.pragma('schema_version');
-      let remaining = Infinity;
-      let lastProgress = Date.now();
-      await source.backup(snapshotPath, {
-        progress: ({ remainingPages }) => {
-          if (remainingPages < remaining) {
-            lastProgress = Date.now();
-          } else if (Date.now() - lastProgress >= 1000) {
-            throw new Error('SQLite backup made no progress');
-          }
-          remaining = remainingPages;
-          return 256;
-        },
-      });
+      await backupSqliteDatabase(sourcePath, snapshotPath);
     } catch (cause) {
       throw new Error(
         `Consistent SQLite snapshot unavailable for ${sourcePath}; close the source browser and retry, or supply a consistent read-only snapshot. ${cause.message}`,
         { cause }
       );
-    } finally {
-      source?.close();
     }
     return await read(snapshotPath);
   } finally {