browser-commander 0.23.0 → 0.25.0

package/src/browser/migration/safari-import.js

@@ -0,0 +1,100 @@
+import path from 'node:path';
+import { findSafariFile } from '../safari-access.js';
+import {
+  readSafariBookmarks,
+  readSafariHistory,
+  readSafariPasswords,
+} from './safari.js';
+import {
+  writeChromiumBookmarks,
+  writeChromiumHistory,
+} from './chromium-writers.js';
+import { writeChromiumPasswords } from './firefox.js';
+
+function findStore(profileDir, name, legacyDir) {
+  return findSafariFile([
+    path.join(profileDir, 'Safari', name),
+    path.join(profileDir, name),
+    ...(legacyDir ? [path.join(legacyDir, name)] : []),
+  ]);
+}
+
+export async function migrateSafariClass({
+  type,
+  profileDir,
+  targetProfileDir,
+  domains,
+  passwordCsv,
+  passwordKeys,
+  platform,
+  legacyDir,
+}) {
+  const skipped = (reason, detail) => ({
+    migrated: 0,
+    skipped: [
+      { type, item: profileDir, reason, ...(detail ? { detail } : {}) },
+    ],
+    warnings: [],
+  });
+  if (type === 'preferences' || type === 'extensions') {
+    return skipped(
+      'safari-class-not-supported',
+      'Safari preferences and extensions do not use Chromium formats.'
+    );
+  }
+  if (type === 'passwords') {
+    if (!passwordCsv) {
+      return skipped(
+        'safari-password-export-required',
+        'Export Passwords from Safari or the Passwords app to CSV, then supply passwordCsv (CLI: --password-csv).'
+      );
+    }
+    const entries = await readSafariPasswords(passwordCsv, domains);
+    if (!passwordKeys?.targetKey) {
+      return skipped(
+        'target-key-unavailable',
+        'Supply the dedicated target profile encryption key; no plaintext passwords are written.'
+      );
+    }
+    const migrated = await writeChromiumPasswords({
+      entries,
+      targetProfileDir,
+      platform,
+      ...passwordKeys,
+    });
+    return { migrated, skipped: [], warnings: [] };
+  }
+  const filename = await findStore(
+    profileDir,
+    type === 'bookmarks' ? 'Bookmarks.plist' : 'History.db',
+    legacyDir
+  );
+  if (!filename) {
+    return skipped('source-missing');
+  }
+  if (type === 'bookmarks') {
+    const entries = await readSafariBookmarks(filename);
+    const hasReadingList = (nodes) =>
+      nodes.some(
+        (node) => node.readingList || hasReadingList(node.children ?? [])
+      );
+    const migrated = await writeChromiumBookmarks(targetProfileDir, entries);
+    const warnings = hasReadingList(entries)
+      ? [
+          {
+            type,
+            item: filename,
+            reason: 'safari-reading-list-translated',
+            detail:
+              'Reading-list URLs become bookmarks; read status and preview metadata are not translated.',
+          },
+        ]
+      : [];
+    return { migrated, skipped: [], warnings };
+  }
+  const migrated = await writeChromiumHistory(
+    targetProfileDir,
+    await readSafariHistory(filename, domains)
+  );
+  return { migrated, skipped: [], warnings: [] };
+}

package/src/browser/migration/safari.js

@@ -0,0 +1,110 @@
+import { open, readFile } from 'node:fs/promises';
+import * as bplist from 'bplist-parser';
+import * as plist from 'plist';
+import { parse } from 'csv-parse/sync';
+import { matchesDomains } from './domains.js';
+import { readDatabaseSnapshot } from './sqlite-snapshot.js';
+
+import { withSafariAccess } from '../safari-access.js';
+export { withSafariAccess } from '../safari-access.js';
+
+export function readSafariPlist(filename) {
+  return withSafariAccess(filename, async () => {
+    const bytes = await readFile(filename);
+    return bytes.subarray(0, 8).toString() === 'bplist00'
+      ? bplist.parseBuffer(bytes)[0]
+      : plist.parse(bytes.toString('utf8'));
+  });
+}
+
+/** Canonical bookmark tree, including nested reading-list entries. */
+export async function readSafariBookmarks(filename) {
+  const document = await readSafariPlist(filename);
+  function convert(node, readingList = false) {
+    const isReadingList =
+      readingList ||
+      node.Title === 'com.apple.ReadingList' ||
+      Boolean(node.ReadingList);
+    if (node.WebBookmarkType === 'WebBookmarkTypeLeaf') {
+      if (!node.URLString) {
+        return null;
+      }
+      return {
+        type: 'url',
+        name: node.URIDictionary?.title ?? node.Title ?? node.URLString,
+        url: node.URLString,
+        readingList: isReadingList,
+      };
+    }
+    return {
+      type: 'folder',
+      name: isReadingList ? 'Reading List' : (node.Title ?? ''),
+      children: (node.Children ?? [])
+        .map((child) => convert(child, isReadingList))
+        .filter(Boolean),
+    };
+  }
+  return (document.Children ?? []).map((node) => convert(node)).filter(Boolean);
+}
+
+/** All visits, in Unix microseconds; the source is read through online backup. */
+export function readSafariHistory(filename, domains) {
+  return withSafariAccess(filename, async () => {
+    // Surface an OS access error before SQLite wraps it as SQLITE_CANTOPEN.
+    const file = await open(filename, 'r');
+    await file.close();
+    return readDatabaseSnapshot({
+      sourcePath: filename,
+      read: (db) =>
+        db
+          .prepare(
+            `SELECT i.url, v.title, v.visit_time FROM history_items i
+       JOIN history_visits v ON i.id = v.history_item ORDER BY v.visit_time, v.id`
+          )
+          .all()
+          .filter((row) => matchesDomains(row.url, domains))
+          .map((row) => ({
+            url: row.url,
+            title: row.title ?? '',
+            time: Math.round((row.visit_time + 978307200) * 1000000),
+          })),
+    });
+  });
+}
+
+/** Only an explicitly supplied Safari/Passwords export is read. */
+export async function readSafariPasswords(filename, domains) {
+  const rows = parse(await readFile(filename), {
+    columns: (columns) => {
+      if (
+        !['URL', 'Username', 'Password'].every((column) =>
+          columns.includes(column)
+        )
+      ) {
+        throw new TypeError(
+          'Safari password CSV must have URL, Username and Password columns'
+        );
+      }
+      return columns;
+    },
+    bom: true,
+    skip_empty_lines: true,
+  });
+  return rows
+    .filter((row) => row.URL && matchesDomains(row.URL, domains))
+    .map((row) => {
+      if (
+        typeof row.Username !== 'string' ||
+        typeof row.Password !== 'string'
+      ) {
+        throw new TypeError(
+          'Safari password CSV must have URL, Username and Password columns'
+        );
+      }
+      return {
+        origin: row.URL,
+        username: row.Username,
+        password: row.Password,
+      };
+    });
+}

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

@@ -1,4 +1,4 @@
-import { copyFile, mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { pathExists } from './fs-utils.js';
@@ -11,49 +11,12 @@ import { openSqliteDatabase } from '../browser-cookie-database.js';
  * Read a Chromium SQLite database (History, Top Sites, Login Data, Web Data)
  * while the source browser is running, without ever writing to the source.
  *
- * Chrome keeps these databases open in WAL mode and, on Windows, holds a share
- * lock that stops another process from opening the file at all. Two techniques
- * cover both cases:
- *
- * 1. The SQLite Online Backup API (`better-sqlite3`'s `.backup()`), which
- *    copies a transactionally consistent snapshot even while the source is
- *    being written. This is the same mechanism `browser-cookie-database.js`
- *    relies on for a stable read, and SQLite documents it as the correct way
- *    to snapshot a live database
- *    (https://www.sqlite.org/backup.html).
- * 2. When the source cannot be opened at all (a Windows exclusive lock), the
- *    file and its `-wal`/`-journal` sidecars are copied to a temporary
- *    directory and the copy is opened instead. Copying the sidecars keeps the
- *    committed-but-not-checkpointed pages, so the copy is consistent.
- *
- * Both paths open the source with `readOnly`, so nothing is written back.
+ * SQLite online backup includes committed WAL data without writing to the
+ * source. If a sharing/exclusive lock prevents backup, callers receive guidance
+ * to close the browser or supply a consistent snapshot. A sequential copy of a
+ * live database and its sidecars cannot guarantee consistency.
  */
 
-const SQLITE_SIDECARS = ['-wal', '-shm', '-journal'];
-
-/**
- * Copy a SQLite file and its sidecars into a temporary directory.
- *
- * @param {string} sourcePath
- * @returns {Promise<{snapshotPath: string, cleanup: function(): Promise<void>}>}
- */
-async function copyDatabaseFiles(sourcePath) {
-  const dir = await mkdtemp(path.join(os.tmpdir(), 'browser-commander-snap-'));
-  const base = path.basename(sourcePath);
-  const snapshotPath = path.join(dir, base);
-  await copyFile(sourcePath, snapshotPath);
-  for (const suffix of SQLITE_SIDECARS) {
-    const sidecar = `${sourcePath}${suffix}`;
-    if (await pathExists(sidecar)) {
-      await copyFile(sidecar, `${snapshotPath}${suffix}`);
-    }
-  }
-  return {
-    snapshotPath,
-    cleanup: () => rm(dir, { recursive: true, force: true, maxRetries: 3 }),
-  };
-}
-
 /**
  * Produce a consistent, read-only snapshot copy of a live Chromium database in
  * a temporary directory, then hand its path to a reader. The snapshot is always
@@ -74,7 +37,6 @@ export async function withDatabaseSnapshot({ sourcePath, read }) {
   const cleanupDir = () =>
     rm(dir, { recursive: true, force: true, maxRetries: 3 });
 
-  let copyFallback;
   try {
     // The backup API needs to open the source. It opens read-only, so nothing
     // is written to the user's real database.
@@ -83,31 +45,35 @@ export async function withDatabaseSnapshot({ sourcePath, read }) {
       source = new BetterSqlite3(sourcePath, {
         readonly: true,
         fileMustExist: true,
+        timeout: 1000,
       });
-    } catch {
-      source = null;
-    }
-    if (source) {
-      try {
-        await source.backup(snapshotPath);
-      } finally {
-        source.close();
-      }
-    } else {
-      // The source is locked exclusively (Windows); fall back to copying the
-      // file and its sidecars, then read that copy.
-      await cleanupDir();
-      copyFallback = await copyDatabaseFiles(sourcePath);
+      // 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;
+        },
+      });
+    } 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();
     }
-
-    const readPath = copyFallback?.snapshotPath ?? snapshotPath;
-    return await read(readPath);
+    return await read(snapshotPath);
   } finally {
-    if (copyFallback) {
-      await copyFallback.cleanup();
-    } else {
-      await cleanupDir();
-    }
+    await cleanupDir();
   }
 }
 

package/src/browser/migration/validation.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { physicalPath } from '../browser-profile-files.js';
+import { browserFamily } from '../browser-sources.js';
+import { assertDedicatedUserDataDir } from '../system-browser.js';
+import { validateDomains } from './domains.js';
+
+export function validateMigrationOptions({
+  include,
+  domains,
+  targetBrowser,
+  to,
+  platform,
+  homeDir,
+  environment,
+  classes,
+  includePaymentCards = false,
+}) {
+  if (typeof includePaymentCards !== 'boolean') {
+    throw new TypeError('includePaymentCards must be a boolean');
+  }
+  if (
+    !Array.isArray(include) ||
+    include.some((type) => !classes.includes(type))
+  ) {
+    throw new TypeError(
+      `include must contain supported data classes: ${classes.join(', ')}`
+    );
+  }
+  validateDomains(domains);
+  if (targetBrowser && browserFamily(targetBrowser) !== 'chromium') {
+    throw new TypeError(
+      `Migration target ${targetBrowser} does not yet have a supported target file writer`
+    );
+  }
+  assertDedicatedUserDataDir(to, { platform, homeDir, environment });
+}
+
+export function validateMigrationPaths(source, target) {
+  const sourcePath = physicalPath(source);
+  const targetPath = physicalPath(target);
+  const within = (parent, child) =>
+    child === parent || child.startsWith(`${parent}${path.sep}`);
+  if (within(sourcePath, targetPath) || within(targetPath, sourcePath)) {
+    throw new TypeError(
+      'Migration source and target directories must not overlap'
+    );
+  }
+}

package/src/browser/real-browser.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { findBrowserSource } from './browser-sources.js';
 
 import { startProcess } from '../utilities/subprocess.js';
 import {
@@ -259,6 +260,10 @@ async function waitForExit(browserProcess, timeout) {
 }
 
 async function requestBrowserClose({ engine, browser, originalClose }) {
+  if (engine === 'selenium') {
+    await originalClose();
+    return;
+  }
   if (engine === 'puppeteer') {
     // A connected Puppeteer Browser sends Browser.close and waits for it.
     await originalClose.call(browser);
@@ -278,8 +283,9 @@ function createCloser({
   userDataDir,
   temporaryProfile,
   closeTimeout,
+  closeConnection,
 }) {
-  const originalClose = browser?.close;
+  const originalClose = closeConnection ?? browser?.close;
   let closing;
   const close = () => {
     closing ??= (async () => {
@@ -298,7 +304,7 @@ function createCloser({
     })();
     return closing;
   };
-  if (browser && originalClose) {
+  if (browser && originalClose && engine !== 'selenium') {
     // `browser.close()` means "close the browser" for every caller, so it
     // shuts the spawned process down and deletes a temporary profile too.
     browser.close = close;
@@ -403,12 +409,19 @@ async function spawnOnFreePort({
 /** Reject a launch request before anything touches the disk. */
 function validateLaunchRequest({
   argOptions,
+  channel,
   userDataDir,
   remoteDebuggingPort,
   endpoint,
   attach,
   migrateFrom,
 }) {
+  const source = findBrowserSource(channel);
+  if (source && source.family !== 'chromium') {
+    throw new Error(
+      `${channel} does not support CDP; use its documented WebDriver setup when available`
+    );
+  }
   if (endpoint) {
     throw new Error(
       'launchAndConnectRealBrowser creates its own endpoint; use connectBrowser to attach to an existing endpoint'
@@ -502,13 +515,16 @@ async function runPreLaunchMigration({
   if (!migrateFrom) {
     return { migration: undefined, migratedCookies: [] };
   }
-  const { include, domains, ...from } = migrateFrom;
+  const { include, domains, passwordCsv, includePaymentCards, ...from } =
+    migrateFrom;
   try {
     const report = await migrate({
       from,
       to: path.join(userDataDir, 'Default'),
       include,
       domains,
+      passwordCsv,
+      includePaymentCards,
       targetBrowser: channel,
     });
     const { cookies, ...migration } = report;
@@ -583,6 +599,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
   };
   validateLaunchRequest({
     argOptions,
+    channel,
     userDataDir: requestedUserDataDir,
     remoteDebuggingPort,
     endpoint: cdpEndpoint || wsEndpoint,
@@ -670,6 +687,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       userDataDir,
       temporaryProfile,
       closeTimeout,
+      closeConnection: engine === 'selenium' ? connection.close : undefined,
     });
     return {
       ...connection,

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);
 }