browser-commander 0.24.0 → 0.26.0

package/src/browser/safari-access.js

@@ -0,0 +1,45 @@
+import { stat } from 'node:fs/promises';
+
+/** A protected path remains a source, so reads can explain Full Disk Access. */
+export async function findSafariFile(candidates, statFile = stat) {
+  for (const candidate of candidates) {
+    try {
+      if ((await statFile(candidate)).isFile()) {
+        return candidate;
+      }
+    } catch (error) {
+      if (['EPERM', 'EACCES'].includes(error.code)) {
+        return candidate;
+      }
+      if (!['ENOENT', 'ENOTDIR'].includes(error.code)) {
+        throw error;
+      }
+    }
+  }
+  return null;
+}
+
+/** Enrich protection failures for every Safari store, preserving the cause. */
+export async function withSafariAccess(
+  filename,
+  read,
+  environment = process.env
+) {
+  try {
+    return await read();
+  } catch (error) {
+    if (!['EPERM', 'EACCES'].includes(error.code)) {
+      throw error;
+    }
+    const app =
+      environment.__CFBundleIdentifier ||
+      environment.TERM_PROGRAM ||
+      process.execPath;
+    const diagnostic = new Error(
+      `Safari access denied (${error.code}) at ${filename}. Grant Full Disk Access to ${app}, the app running Browser Commander, then retry: x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles`,
+      { cause: error }
+    );
+    diagnostic.code = error.code;
+    throw diagnostic;
+  }
+}

package/src/browser/safari-cookies.js

@@ -4,7 +4,9 @@
  */
 import { readFile as readFileBytes, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { findSafariFile, withSafariAccess } from './safari-access.js';
 import { TextDecoder } from 'node:util';
+import { matchesDomains } from './migration/domains.js';
 
 const APPLE_EPOCH = 978_307_200;
 const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
@@ -121,7 +123,7 @@ export function countSafariCookies(data, domains) {
     const host = string(record, 16).toLowerCase();
     total += 1;
     for (const domain of Object.keys(byDomain ?? {})) {
-      if (host.includes(domain.toLowerCase())) {
+      if (matchesDomains(host, [domain])) {
         byDomain[domain] += 1;
       }
     }
@@ -130,44 +132,45 @@ export function countSafariCookies(data, domains) {
 }
 
 /** A protected path is still a source: preserve it for an actionable read error. */
-export async function findSafariCookieFile(profileDir, statFile = stat) {
-  for (const candidate of [
-    path.join(profileDir, 'Cookies', 'Cookies.binarycookies'),
-    path.join(profileDir, 'Cookies.binarycookies'),
-  ]) {
-    try {
-      if ((await statFile(candidate)).isFile()) {
-        return candidate;
-      }
-    } catch (error) {
-      if (['EPERM', 'EACCES'].includes(error.code)) {
-        return candidate;
-      }
-      if (!['ENOENT', 'ENOTDIR'].includes(error.code)) {
-        throw error;
-      }
-    }
-  }
-  return null;
+export function findSafariCookieFile(profileDir, statFile = stat) {
+  const named =
+    path.basename(path.dirname(profileDir)) === 'Profiles' &&
+    path.basename(path.dirname(path.dirname(profileDir))) === 'Safari';
+  const root = named
+    ? path.dirname(path.dirname(path.dirname(profileDir)))
+    : profileDir;
+  const modern = named
+    ? [
+        path.join(
+          root,
+          'WebKit/WebsiteDataStore',
+          path.basename(profileDir).toLowerCase(),
+          'Cookies/Cookies.binarycookies'
+        ),
+      ]
+    : [
+        path.join(
+          root,
+          'WebKit/WebsiteData/Default/Cookies/Cookies.binarycookies'
+        ),
+        path.join(
+          root,
+          'WebKit/WebsiteDataStore/Default/Cookies/Cookies.binarycookies'
+        ),
+      ];
+  return findSafariFile(
+    [
+      ...modern,
+      path.join(profileDir, 'Cookies', 'Cookies.binarycookies'),
+      path.join(profileDir, 'Cookies.binarycookies'),
+    ],
+    statFile
+  );
 }
 
-export async function readSafariCookieFile(
+export function readSafariCookieFile(
   filePath,
   { environment = process.env, readFile = readFileBytes } = {}
 ) {
-  try {
-    return await readFile(filePath);
-  } catch (error) {
-    if (!['EPERM', 'EACCES'].includes(error.code)) {
-      throw error;
-    }
-    const app =
-      environment.__CFBundleIdentifier ||
-      environment.TERM_PROGRAM ||
-      process.execPath;
-    throw new Error(
-      `Safari cookie access denied (${error.code}) at ${filePath}. Grant Full Disk Access to ${app}, the app running Browser Commander, then retry: x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles`,
-      { cause: error }
-    );
-  }
+  return withSafariAccess(filePath, () => readFile(filePath), environment);
 }

package/src/browser/safari-launch.js

@@ -0,0 +1,42 @@
+import { launchWebDriver } from './webdriver.js';
+import { findBrowserSource } from './browser-sources.js';
+import { validateSafariOptions } from './safari-support.js';
+import { restoreWebDriverStorageState } from './storage-state.js';
+
+/** Launch installed Safari through its native W3C WebDriver server. */
+export async function launchSafari(options = {}, dependencies = {}) {
+  validateSafariOptions(options);
+  const channel = findBrowserSource(
+    options.channel ?? options.browser ?? 'safari'
+  ).id;
+  const launched = await (dependencies.launchWebDriver ?? launchWebDriver)(
+    {
+      ...options,
+      browser: channel,
+      driverPath: options.driverPath ?? options.executablePath,
+      executablePath: undefined,
+    },
+    dependencies
+  );
+  try {
+    const state = options.storageState;
+    await restoreWebDriverStorageState({
+      page: launched.page,
+      storageState: state,
+      seedCookies: options.seedCookies,
+    });
+  } catch (error) {
+    await launched.close();
+    throw error;
+  }
+  return {
+    ...launched,
+    browser: launched.driver,
+    engine: 'selenium',
+    controlProtocol: 'webdriver',
+    executablePath: launched.driverPath,
+    browserProcess: launched.driverProcess,
+    downloads: null,
+    launch: options.launch ?? 'real',
+  };
+}

package/src/browser/safari-profiles.js

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import { open } from 'node:fs/promises';
+import { findSafariCookieFile } from './safari-cookies.js';
+import { findSafariFile, withSafariAccess } from './safari-access.js';
+import { openSqliteDatabase } from './browser-cookie-database.js';
+
+/** SafariTabs supplies names; each UUID has separate Safari and WebKit stores. */
+export async function listSafariProfiles(browser, root) {
+  const profiles = [];
+  const defaultFile =
+    (await findSafariCookieFile(root)) ??
+    (await findSafariFile([
+      path.join(root, 'Safari/History.db'),
+      path.join(root, 'History.db'),
+      path.join(root, 'Safari/Bookmarks.plist'),
+      path.join(root, 'Bookmarks.plist'),
+    ]));
+  if (defaultFile) {
+    profiles.push({
+      browser,
+      name: 'Default',
+      displayName: 'Default',
+      path: root,
+      isDefault: true,
+    });
+  }
+  const tabs = await findSafariFile([
+    path.join(root, 'Safari/SafariTabs.db'),
+    path.join(root, 'SafariTabs.db'),
+  ]);
+  if (!tabs) {
+    return profiles;
+  }
+  let rows;
+  try {
+    rows = await withSafariAccess(tabs, async () => {
+      const file = await open(tabs, 'r');
+      await file.close();
+      const db = await openSqliteDatabase(tabs, {
+        readOnly: true,
+        fileMustExist: true,
+      });
+      try {
+        return db
+          .prepare(
+            "SELECT DISTINCT external_uuid,title FROM bookmarks WHERE subtype=2 AND external_uuid != 'DefaultProfile' ORDER BY external_uuid"
+          )
+          .all();
+      } finally {
+        db.close();
+      }
+    });
+  } catch (error) {
+    profiles.push({
+      browser,
+      name: 'Profiles',
+      displayName: 'Safari profile discovery',
+      path: root,
+      isDefault: false,
+      error: error.message,
+    });
+    return profiles;
+  }
+  for (const row of rows) {
+    if (
+      !/^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/iu.test(
+        row.external_uuid ?? ''
+      )
+    ) {
+      continue;
+    }
+    const name = row.external_uuid.toUpperCase();
+    const profilePath = path.join(root, 'Safari/Profiles', name);
+    profiles.push({
+      browser,
+      name,
+      displayName: row.title ?? name,
+      path: profilePath,
+      isDefault: false,
+    });
+  }
+  return profiles;
+}

package/src/browser/safari-support.js

@@ -0,0 +1,98 @@
+import { findBrowserSource } from './browser-sources.js';
+import { runCommand } from '../utilities/subprocess.js';
+
+/** Whether a channel (including aliases) selects an installed Safari. */
+export function isSafariChannel(channel) {
+  return findBrowserSource(channel)?.family === 'safari';
+}
+
+/** A requested operation unavailable in Safari's classic WebDriver. */
+export class SafariUnsupportedError extends Error {
+  constructor(feature) {
+    super(`${feature} is unsupported on safari`);
+    this.name = 'SafariUnsupportedError';
+    this.code = 'SAFARI_UNSUPPORTED';
+    this.feature = feature;
+  }
+}
+
+/** One-time setup failure with actionable instructions and a settings opener. */
+export class SafariSetupError extends Error {
+  constructor(cause, channel = 'safari') {
+    const driver = findBrowserSource(channel).executables.darwin[0];
+    super(
+      `Safari automation setup required: ${cause.message}. In Safari → Settings → Advanced enable "Show features for web developers", then Develop → "Allow Remote Automation". Run "${driver}" --enable once (an admin password may be required). Call error.openSettings() to open Safari's Advanced settings.`,
+      { cause }
+    );
+    this.name = 'SafariSetupError';
+    this.code = 'SAFARI_SETUP_REQUIRED';
+    this.channel = channel;
+  }
+  openSettings() {
+    return openSafariSettings({ channel: this.channel });
+  }
+}
+
+/** Translate only recognizable authorization failures; preserve other errors. */
+export function safariLaunchError(error, channel) {
+  return /allow\s+remote\s+automation|remote automation.*(?:disabled|enable)|(?:safaridriver|webdriver).*(?:--enable|authoriz|not enabled)|not authorized.*(?:safari|automation)/i.test(
+    error.message
+  )
+    ? new SafariSetupError(error, channel)
+    : error;
+}
+
+/** Open Advanced settings on explicit request; never change authorization. */
+export async function openSafariSettings({
+  channel = 'safari',
+  platform = process.platform,
+  run = runCommand,
+} = {}) {
+  if (platform !== 'darwin') {
+    throw new SafariUnsupportedError('Safari settings outside macOS');
+  }
+  const app =
+    findBrowserSource(channel)?.id === 'safari-technology-preview'
+      ? 'Safari Technology Preview'
+      : 'Safari';
+  return await run('osascript', [
+    '-e',
+    `tell application "${app}" to activate`,
+    '-e',
+    `tell application "${app}" to open location "x-safari-preferences:com.apple.Safari.preferences.Advanced"`,
+  ]);
+}
+
+/** Reject settings Safari cannot apply before touching disk or starting it. */
+export function validateSafariOptions(options) {
+  for (const name of [
+    'headless',
+    'userDataDir',
+    'attach',
+    'migrateFrom',
+    'remoteDebuggingPort',
+    'cdpEndpoint',
+    'wsEndpoint',
+    'fingerprint',
+    'colorScheme',
+    'downloads',
+    'bidi',
+    'preferences',
+    'localState',
+    'defaultBrowserCheck',
+    'firstRun',
+  ]) {
+    if (
+      options[name] !== undefined &&
+      options[name] !== null &&
+      options[name] !== false
+    ) {
+      throw new SafariUnsupportedError(name);
+    }
+  }
+  for (const name of ['args', 'extraArgs', 'restrictions']) {
+    if (options[name]?.length) {
+      throw new SafariUnsupportedError(name);
+    }
+  }
+}

package/src/browser/storage-state.js

@@ -31,27 +31,47 @@ function restoreOriginLocalStorage(origins) {
 }
 
 /** Restore classic WebDriver cookies; origin preload scripts require BiDi. */
-export async function restoreWebDriverStorageState({ page, storageState }) {
-  if (!storageState) {
+export async function restoreWebDriverStorageState({
+  page,
+  storageState,
+  seedCookies = [],
+}) {
+  storageState = await loadStorageState(storageState);
+  if (!storageState && !seedCookies.length) {
     return;
   }
-  const origins = storageState.origins ?? [];
+  const origins = storageState?.origins ?? [];
   if (origins.length) {
-    await page.evaluateOnNewDocument(restoreOriginLocalStorage, origins);
-    await page.evaluate(restoreOriginLocalStorage, origins);
+    if (!page.browserName?.toLowerCase().startsWith('safari')) {
+      await page.evaluateOnNewDocument(restoreOriginLocalStorage, origins);
+      await page.evaluate(restoreOriginLocalStorage, origins);
+    }
   }
   const originalUrl = page.url();
-  const cookies = storageState.cookies ?? [];
+  const cookies = [...(storageState?.cookies ?? []), ...seedCookies];
   try {
     for (const cookie of cookies) {
       const origin = cookie.url
         ? new URL(cookie.url).origin
-        : `${cookie.secure ? 'https' : 'http'}://${cookie.domain.replace(/^\./u, '')}`;
+        : (origins.find(
+            ({ origin }) =>
+              new URL(origin).hostname === cookie.domain?.replace(/^\./u, '')
+          )?.origin ??
+          `${cookie.secure ? 'https' : 'http'}://${cookie.domain.replace(/^\./u, '')}`);
       await page.goto(origin);
       await page.setCookie(cookie);
     }
+    if (page.browserName?.toLowerCase().startsWith('safari')) {
+      for (const { origin } of origins) {
+        await page.goto(origin);
+        await page.evaluate(restoreOriginLocalStorage, origins);
+      }
+    }
   } finally {
-    if (cookies.length) {
+    if (
+      cookies.length ||
+      (origins.length && page.browserName?.toLowerCase().startsWith('safari'))
+    ) {
       await page.goto(originalUrl);
     }
   }

package/src/browser/system-browser.js

@@ -1,4 +1,10 @@
 import { constants } from 'node:fs';
+import { physicalPath } from './browser-profile-files.js';
+import {
+  BROWSER_SOURCES,
+  resolveBrowserRoots,
+  resolveBrowserExecutables,
+} from './browser-sources.js';
 import { access } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -9,18 +15,16 @@ import path from 'node:path';
  * to refuse a default profile; profile migration uses it to find the source.
  */
 
-export const CHANNEL_EXECUTABLE_NAMES = {
-  brave: ['brave-browser', 'brave-browser-stable', 'brave'],
-  chrome: ['google-chrome', 'google-chrome-stable', 'chrome'],
-  'chrome-beta': ['google-chrome-beta'],
-  'chrome-canary': ['google-chrome-canary'],
-  'chrome-dev': ['google-chrome-unstable'],
-  chromium: ['chromium', 'chromium-browser'],
-  msedge: ['microsoft-edge', 'microsoft-edge-stable', 'msedge'],
-  'msedge-beta': ['microsoft-edge-beta'],
-  'msedge-canary': ['microsoft-edge-canary'],
-  'msedge-dev': ['microsoft-edge-dev'],
-};
+export const CHANNEL_EXECUTABLE_NAMES = Object.freeze(
+  Object.fromEntries(
+    BROWSER_SOURCES.flatMap((browser) =>
+      [browser.id, ...(browser.aliases ?? [])].map((name) => [
+        name,
+        browser.executableNames ?? [],
+      ])
+    )
+  )
+);
 
 function platformPath(platform) {
   return platform === 'win32' ? path.win32 : path;
@@ -41,72 +45,13 @@ export function knownDefaultUserDataDirs({
   homeDir = os.homedir(),
   environment = process.env,
 } = {}) {
-  const pathApi = platformPath(platform);
-  if (platform === 'darwin') {
-    const applicationSupport = pathApi.join(
+  return BROWSER_SOURCES.flatMap((browser) =>
+    resolveBrowserRoots(browser.id, {
+      platform,
       homeDir,
-      'Library',
-      'Application Support'
-    );
-    return [
-      pathApi.join(applicationSupport, 'Google', 'Chrome'),
-      pathApi.join(applicationSupport, 'Google', 'Chrome Beta'),
-      pathApi.join(applicationSupport, 'Google', 'Chrome Canary'),
-      pathApi.join(applicationSupport, 'Google', 'Chrome Dev'),
-      pathApi.join(applicationSupport, 'Chromium'),
-      pathApi.join(applicationSupport, 'BraveSoftware', 'Brave-Browser'),
-      pathApi.join(applicationSupport, 'BraveSoftware', 'Brave-Browser-Beta'),
-      pathApi.join(
-        applicationSupport,
-        'BraveSoftware',
-        'Brave-Browser-Nightly'
-      ),
-      pathApi.join(applicationSupport, 'Microsoft Edge'),
-      pathApi.join(applicationSupport, 'Microsoft Edge Beta'),
-      pathApi.join(applicationSupport, 'Microsoft Edge Canary'),
-      pathApi.join(applicationSupport, 'Microsoft Edge Dev'),
-    ];
-  }
-  if (platform === 'win32') {
-    const localAppData =
-      environment.LOCALAPPDATA ?? pathApi.join(homeDir, 'AppData', 'Local');
-    return [
-      pathApi.join(localAppData, 'Google', 'Chrome', 'User Data'),
-      pathApi.join(localAppData, 'Google', 'Chrome Beta', 'User Data'),
-      pathApi.join(localAppData, 'Google', 'Chrome Dev', 'User Data'),
-      pathApi.join(localAppData, 'Google', 'Chrome SxS', 'User Data'),
-      pathApi.join(localAppData, 'Chromium', 'User Data'),
-      pathApi.join(localAppData, 'BraveSoftware', 'Brave-Browser', 'User Data'),
-      pathApi.join(
-        localAppData,
-        'BraveSoftware',
-        'Brave-Browser-Beta',
-        'User Data'
-      ),
-      pathApi.join(
-        localAppData,
-        'BraveSoftware',
-        'Brave-Browser-Nightly',
-        'User Data'
-      ),
-      pathApi.join(localAppData, 'Microsoft', 'Edge', 'User Data'),
-      pathApi.join(localAppData, 'Microsoft', 'Edge Beta', 'User Data'),
-      pathApi.join(localAppData, 'Microsoft', 'Edge Dev', 'User Data'),
-      pathApi.join(localAppData, 'Microsoft', 'Edge SxS', 'User Data'),
-    ];
-  }
-  return [
-    pathApi.join(homeDir, '.config', 'google-chrome'),
-    pathApi.join(homeDir, '.config', 'google-chrome-beta'),
-    pathApi.join(homeDir, '.config', 'google-chrome-unstable'),
-    pathApi.join(homeDir, '.config', 'chromium'),
-    pathApi.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser'),
-    pathApi.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser-Beta'),
-    pathApi.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser-Nightly'),
-    pathApi.join(homeDir, '.config', 'microsoft-edge'),
-    pathApi.join(homeDir, '.config', 'microsoft-edge-beta'),
-    pathApi.join(homeDir, '.config', 'microsoft-edge-dev'),
-  ];
+      environment,
+    })
+  );
 }
 
 /** Ensure Chrome is not asked to expose the user's default profile over CDP. */
@@ -117,12 +62,17 @@ export function assertDedicatedUserDataDir(userDataDir, platformOptions = {}) {
   const platform = platformOptions.platform ?? process.platform;
   const pathApi = platformPath(platform);
   const normalize = (value) => {
-    const resolved = pathApi.resolve(value).replace(/[\\/]+$/, '');
+    let resolved = pathApi.resolve(value).replace(/[\\/]+$/, '');
+    if (platform === process.platform) {
+      resolved = physicalPath(resolved);
+    }
     return platform === 'win32' ? resolved.toLowerCase() : resolved;
   };
   const requested = normalize(userDataDir);
   const isDefault = knownDefaultUserDataDirs(platformOptions).some(
-    (directory) => normalize(directory) === requested
+    (directory) =>
+      requested === normalize(directory) ||
+      requested.startsWith(`${normalize(directory)}${pathApi.sep}`)
   );
   if (isDefault) {
     throw new Error(
@@ -136,74 +86,12 @@ function browserInstallCandidates({
   platform = process.platform,
   environment = process.env,
 }) {
-  const candidates = [];
-  const names = CHANNEL_EXECUTABLE_NAMES[channel];
-  if (!names) {
+  if (!CHANNEL_EXECUTABLE_NAMES[channel]?.length) {
     throw new Error(
       `Unknown browser channel: ${channel}. Expected one of ${Object.keys(CHANNEL_EXECUTABLE_NAMES).join(', ')}`
     );
   }
-
-  if (platform === 'darwin') {
-    const applications = {
-      brave: 'Brave Browser.app/Contents/MacOS/Brave Browser',
-      chrome: 'Google Chrome.app/Contents/MacOS/Google Chrome',
-      'chrome-beta': 'Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
-      'chrome-canary':
-        'Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
-      'chrome-dev': 'Google Chrome Dev.app/Contents/MacOS/Google Chrome Dev',
-      chromium: 'Chromium.app/Contents/MacOS/Chromium',
-      msedge: 'Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
-      'msedge-beta':
-        'Microsoft Edge Beta.app/Contents/MacOS/Microsoft Edge Beta',
-      'msedge-canary':
-        'Microsoft Edge Canary.app/Contents/MacOS/Microsoft Edge Canary',
-      'msedge-dev': 'Microsoft Edge Dev.app/Contents/MacOS/Microsoft Edge Dev',
-    };
-    candidates.push(path.join('/Applications', applications[channel]));
-  } else if (platform === 'win32') {
-    const roots = [
-      environment.PROGRAMFILES,
-      environment['PROGRAMFILES(X86)'],
-      environment.LOCALAPPDATA,
-    ].filter(Boolean);
-    const relativePaths = {
-      brave: ['BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'],
-      chrome: ['Google', 'Chrome', 'Application', 'chrome.exe'],
-      'chrome-beta': ['Google', 'Chrome Beta', 'Application', 'chrome.exe'],
-      'chrome-canary': ['Google', 'Chrome SxS', 'Application', 'chrome.exe'],
-      'chrome-dev': ['Google', 'Chrome Dev', 'Application', 'chrome.exe'],
-      chromium: ['Chromium', 'Application', 'chrome.exe'],
-      msedge: ['Microsoft', 'Edge', 'Application', 'msedge.exe'],
-      'msedge-beta': ['Microsoft', 'Edge Beta', 'Application', 'msedge.exe'],
-      'msedge-canary': ['Microsoft', 'Edge SxS', 'Application', 'msedge.exe'],
-      'msedge-dev': ['Microsoft', 'Edge Dev', 'Application', 'msedge.exe'],
-    };
-    for (const root of roots) {
-      candidates.push(path.win32.join(root, ...relativePaths[channel]));
-    }
-  } else {
-    for (const name of names) {
-      candidates.push(`/usr/bin/${name}`, `/usr/local/bin/${name}`);
-    }
-    if (channel === 'chrome') {
-      candidates.push('/opt/google/chrome/google-chrome');
-    }
-  }
-
-  const pathApi = platformPath(platform);
-  const delimiter = platform === 'win32' ? ';' : path.delimiter;
-  for (const directory of (environment.PATH ?? '').split(delimiter)) {
-    if (!directory) {
-      continue;
-    }
-    for (const name of names) {
-      candidates.push(
-        pathApi.join(directory, platform === 'win32' ? `${name}.exe` : name)
-      );
-    }
-  }
-  return [...new Set(candidates)];
+  return resolveBrowserExecutables(channel, { platform, environment });
 }
 
 /** Resolve a genuine installed Chrome-family browser executable. */