browser-commander 0.24.0 → 0.26.0

package/.jscpd-baseline.json

@@ -20,7 +20,6 @@
     "0caa402c4eae32d8": 1,
     "0fd23be8410c2c95": 1,
     "0fe4f3b5e5e939b3": 1,
-    "119f429fe4d23e4a": 1,
     "126a1cfe8f2264ce": 1,
     "1273365073edd790": 1,
     "13c4b58d3ea0719b": 1,
@@ -210,6 +209,7 @@
     "c225b9d7d519303e": 1,
     "c2c155adbcb46f3c": 1,
     "c30737d62069fc02": 1,
+    "c32010db539b4efb": 1,
     "c3c3569357673af8": 1,
     "c415ffcd004d6518": 1,
     "c461a83b51eb7740": 1,

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.26.0
+
+### Minor Changes
+
+- 8f9ef1c: Add native Safari and Technology Preview W3C WebDriver control through real/common launchers and CLI, with isolated cookie seeding, setup diagnostics and typed unsupported feature errors.
+
+  Update the transitive shell-quote lock entry to fix GHSA-pqg4-j6r4-53mv and unblock npm audit.
+
+## 0.25.0
+
+### Minor Changes
+
+- 4a79d62: Import Safari bookmarks, history and explicit Passwords CSV exports into Chromium profiles. Discover named Safari profiles and modern WebKit cookie stores. Derive desktop browser executable discovery and profile protection from the shared catalogue, fix Opera Local State lookup, and report Yandex Ya Passman encryption limitations. Enforce domain boundaries for migrated cookies, history and passwords, and validate migration paths and options before writing.
+
+  Resolve native Safe Storage credentials from the catalogue and provide service-specific macOS Keychain retry guidance. SQLite stores that cannot be backed up consistently return close-browser/retry guidance instead of copying live database files.
+
+  Match exact hosts and subdomains in cookie-source metadata and automatic source selection, without decoding cookie values or treating domain strings as SQL wildcard patterns.
+
+  Keep Safari profile-catalogue errors alongside readable profiles and cookie sources, including domain-filtered listings.
+
+  Filter associated Login Data notes, security records and origin statistics; re-encrypt retained notes with the target key. Reset copied sync state and report unknown metadata omitted during domain-filtered imports.
+
+  Recognize all 18 migration data classes with explicit unsupported reports. Add separate payment-card consent across native APIs, pre-launch migration, CLI and command streams, plus provider-specific passkey and certificate export limitations without accessing protected stores.
+
+  Translate Firefox history to Chromium with exact microsecond visit dates, domain filtering, immutable snapshots and per-visit malformed-data reports.
+
+  Normalize Firefox schema 16+ cookie expiry from milliseconds to seconds in both installed-profile reading and migration, preserving legacy schemas and session markers.
+
+  Preserve supported Yandex Login Data imports when an unsupported Ya Passman Data store is present, retaining separate encryption diagnostics.
+
+  Omit derived cluster labels, keywords, duplicate-visit records and unknown History metadata with named warnings during domain-filtered imports; preserve them during unfiltered imports.
+
 ## 0.24.0
 
 ### Minor Changes

package/README.md

@@ -462,7 +462,7 @@ const session = await launchRealBrowser({
     browser: 'chrome', // chrome | edge | brave | chromium | firefox
     profile: 'Default',
     include: ['cookies', 'bookmarks', 'history', 'passwords', 'preferences'],
-    domains: ['npmjs.com', 'github.com'], // optional cookie filter
+    domains: ['npmjs.com', 'github.com'], // optional cookies/history/passwords filter
   },
 });
 console.log(session.migration.migrated, session.migration.skipped);
@@ -524,9 +524,12 @@ overrides and managed downloads need CDP and throw on this engine; see
 
 ### listBrowserProfiles(options)
 
-Discover cookie-bearing profiles for Chrome, Edge, Brave, Chromium, and Firefox.
+Discover profiles for the browsers in the shared catalogue, including Safari.
 Pass an optional `browser` to narrow discovery. Each result contains
-`{ browser, name, displayName, path, isDefault }`.
+`{ browser, name, displayName, path, isDefault }`. If Safari's profile catalogue
+cannot be read, a `Profiles` entry carries `error` alongside readable profiles.
+Protected-file errors retain Full Disk Access instructions; cookie-source
+listings preserve the same error even when a domain filter is supplied.
 
 ### readBrowserCookies(options)
 
@@ -589,7 +592,7 @@ const report = await migrateProfile({
     'preferences',
     'extensions',
   ],
-  domains: ['github.com'], // optional cookie filter
+  domains: ['github.com'], // optional cookies/history/passwords filter
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {
@@ -81,9 +81,12 @@
   },
   "dependencies": {
     "better-sqlite3": "^13.0.3",
+    "bplist-parser": "^0.5.0",
     "command-stream": "^1.4.0",
+    "csv-parse": "^7.0.3",
     "links-notation": "^0.22.0",
     "log-lazy": "^1.0.4",
+    "plist": "^5.0.0",
     "test-anywhere": "^0.9.1"
   },
   "devDependencies": {

package/src/browser/attach/snapshot.js

@@ -10,13 +10,11 @@ import {
 import os from 'node:os';
 import path from 'node:path';
 
-import BetterSqlite3 from 'better-sqlite3';
-
+import { browserFamily } from '../browser-sources.js';
 import {
   browserProfileRoot,
   normalizeCookieBrowser,
 } from '../browser-profiles.js';
-import { pathExists } from '../migration/fs-utils.js';
 import { withDatabaseSnapshot } from '../migration/sqlite-snapshot.js';
 import {
   createTemporaryUserDataDir,
@@ -171,28 +169,6 @@ async function prepareTarget(to, sourceRoot, profile) {
   return to;
 }
 
-/**
- * Copy a database snapshot to its place in the target. The Online Backup API
- * snapshot is a single self-contained file; the locked-file fallback is a copy
- * with its `-wal`/`-journal` sidecars, which is folded into one file with
- * another backup (of the temporary copy, never of the source).
- */
-async function copyDatabase(snapshotPath, destination) {
-  const hasSidecar =
-    (await pathExists(`${snapshotPath}-wal`)) ||
-    (await pathExists(`${snapshotPath}-journal`));
-  if (!hasSidecar) {
-    await copyFile(snapshotPath, destination);
-    return;
-  }
-  const database = new BetterSqlite3(snapshotPath, { fileMustExist: true });
-  try {
-    await database.backup(destination);
-  } finally {
-    database.close();
-  }
-}
-
 /** Copy the directory tree below one entry, recording the outcome. */
 class SnapshotCopier {
   constructor(sourceRoot, target) {
@@ -213,7 +189,7 @@ class SnapshotCopier {
       if (await isSqliteFile(source)) {
         await withDatabaseSnapshot({
           sourcePath: source,
-          read: (snapshotPath) => copyDatabase(snapshotPath, destination),
+          read: (snapshotPath) => copyFile(snapshotPath, destination),
         });
         this.copied.databases += 1;
       } else {
@@ -311,9 +287,9 @@ export async function snapshotUserDataDir({
     throw new TypeError('snapshotUserDataDir requires a browser');
   }
   const normalizedBrowser = normalizeCookieBrowser(browser);
-  if (normalizedBrowser === 'firefox') {
+  if (browserFamily(normalizedBrowser) !== 'chromium') {
     throw new Error(
-      'A profile snapshot is only supported for Chromium-family browsers (chrome, chromium, edge, brave): Firefox cannot be driven over CDP by this launcher'
+      'A profile snapshot is only supported for Chromium-family browsers; this launcher uses CDP'
     );
   }
   assertProfileName(profile);

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

@@ -68,15 +68,22 @@ export async function readSafeStoragePassword({
     throw new Error(`No Safe Storage identity is known for ${browser}`);
   }
   if (platform === 'darwin') {
-    const password = await runCommand(
-      'security',
-      ['find-generic-password', '-w', '-s', identity.service],
-      environment
-    );
-    if (!password) {
-      throw new Error(`${identity.service} returned an empty password`);
+    try {
+      const password = await runCommand(
+        'security',
+        ['find-generic-password', '-w', '-s', identity.service],
+        environment
+      );
+      if (!password) {
+        throw new Error(`${identity.service} returned an empty password`);
+      }
+      return password;
+    } catch (cause) {
+      throw new Error(
+        `Could not read ${identity.service} from macOS Keychain. Unlock the login Keychain and allow the app running Browser Commander to access this item, then retry with refresh=true.`,
+        { cause }
+      );
     }
-    return password;
   }
   if (platform === 'linux') {
     return readLinuxSafeStoragePassword(browser, environment, runCommand);

package/src/browser/browser-cookies.js

@@ -1,4 +1,4 @@
-import path from 'node:path';
+import { localStatePathForProfile } from './browser-profile-files.js';
 import os from 'node:os';
 
 import {
@@ -33,6 +33,7 @@ import {
   resolveSourceBrowser,
 } from './browser-profiles.js';
 import { resolveDefaultBrowser } from './default-browser.js';
+import { matchesDomains } from './migration/domains.js';
 import {
   countSafariCookies,
   parseSafariCookies,
@@ -77,10 +78,16 @@ function readDatabaseVersion(database) {
   }
 }
 
-function readFirefoxRows(database, domainFilter) {
+// Firefox schema 16 changed expiry from Unix seconds to milliseconds. Normalize
+// in SQLite before mapping so both installed reading and migration use seconds.
+export function readFirefoxRows(database, domainFilter) {
+  const version = Number(
+    database.prepare('PRAGMA user_version').get()?.user_version ?? 0
+  );
+  const expiry = version >= 16 ? 'expiry / 1000 AS expiry' : 'expiry';
   return queryRows(
     database,
-    `SELECT name, value, host, path, expiry, isSecure, isHttpOnly, sameSite
+    `SELECT name, value, host, path, ${expiry}, isSecure, isHttpOnly, sameSite
        FROM moz_cookies
       ${domainFilter ? 'WHERE host LIKE ?' : ''}
       ORDER BY host, name, path`,
@@ -168,10 +175,7 @@ function chromiumKeyForPrefix(context, prefix) {
           },
           create: () =>
             context.readWindowsEncryptionKey({
-              localStatePath: path.join(
-                path.dirname(context.profile.path),
-                'Local State'
-              ),
+              localStatePath: localStatePathForProfile(context.profile.path),
               environment: context.environment,
               decryptDpapi: context.decryptWindowsDpapi,
             }),
@@ -380,21 +384,22 @@ export function readBrowserCookies(options) {
 function countCookiesByDomain(database, family, domains) {
   const column = family === 'firefox' ? 'host' : 'host_key';
   const table = family === 'firefox' ? 'moz_cookies' : 'cookies';
-  const countFor = (filter) => {
-    const query = filter
-      ? `SELECT COUNT(*) AS n FROM ${table} WHERE ${column} LIKE ?`
-      : `SELECT COUNT(*) AS n FROM ${table}`;
-    const statement = database.prepare(query);
-    const row = filter ? statement.get(`%${filter}%`) : statement.get();
-    return Number(row?.n ?? 0);
-  };
-  const total = countFor(null);
+  const total = Number(
+    database.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get()?.n ?? 0
+  );
   if (!Array.isArray(domains) || domains.length === 0) {
     return { total, byDomain: null };
   }
-  const byDomain = {};
-  for (const domain of domains) {
-    byDomain[domain] = countFor(domain);
+  const byDomain = Object.fromEntries(domains.map((domain) => [domain, 0]));
+  const hosts = database.prepare(
+    `SELECT ${column} AS host, COUNT(*) AS n FROM ${table} GROUP BY ${column}`
+  );
+  for (const { host, n } of hosts.all()) {
+    for (const domain of Object.keys(byDomain)) {
+      if (matchesDomains(host ?? '', [domain])) {
+        byDomain[domain] += Number(n);
+      }
+    }
   }
   return { total, byDomain };
 }
@@ -426,6 +431,16 @@ export async function listCookieSources({
   });
   const sources = [];
   for (const profile of profiles) {
+    const source = {
+      browser: profile.browser,
+      profile: profile.name,
+      path: profile.path,
+      isDefault: profile.isDefault,
+    };
+    if (profile.error) {
+      sources.push({ ...source, error: profile.error });
+      continue;
+    }
     const cookiePath = await findCookieDatabase(
       profile.browser,
       profile.path,
@@ -454,13 +469,7 @@ export async function listCookieSources({
       database?.close();
     }
     if (error) {
-      sources.push({
-        browser: profile.browser,
-        profile: profile.name,
-        path: profile.path,
-        isDefault: profile.isDefault,
-        error,
-      });
+      sources.push({ ...source, error });
       continue;
     }
     // When filtering by domain, skip profiles that hold none of them.
@@ -471,10 +480,7 @@ export async function listCookieSources({
       continue;
     }
     sources.push({
-      browser: profile.browser,
-      profile: profile.name,
-      path: profile.path,
-      isDefault: profile.isDefault,
+      ...source,
       cookies: counts.total,
       byDomain: counts.byDomain,
     });

package/src/browser/browser-profile-files.js

@@ -0,0 +1,31 @@
+import { existsSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+
+/** Opera keeps Local State inside its single-profile root. */
+export function localStatePathForProfile(profileDir) {
+  const own = path.join(profileDir, 'Local State');
+  return existsSync(own)
+    ? own
+    : path.join(path.dirname(profileDir), 'Local State');
+}
+
+/** Resolve existing ancestors even when the target profile does not exist. */
+export function physicalPath(value) {
+  let existing = path.resolve(value);
+  const suffix = [];
+  while (true) {
+    try {
+      return path.join(realpathSync(existing), ...suffix.reverse());
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error.code)) {
+        throw error;
+      }
+      suffix.push(path.basename(existing));
+      const parent = path.dirname(existing);
+      if (parent === existing) {
+        throw error;
+      }
+      existing = parent;
+    }
+  }
+}

package/src/browser/browser-profiles.js

@@ -11,6 +11,7 @@ import {
 } from './browser-sources.js';
 import { resolveDefaultBrowser } from './default-browser.js';
 import { findSafariCookieFile } from './safari-cookies.js';
+import { listSafariProfiles } from './safari-profiles.js';
 
 /**
  * Keywords that select the operating-system default browser instead of a named
@@ -279,16 +280,9 @@ async function listProfilesForBrowser(browser, platform, homeDir, environment) {
   const profiles = [];
   for (const root of roots) {
     if (family === 'safari') {
-      if (await findSafariCookieFile(root)) {
-        return [
-          {
-            browser,
-            name: 'Default',
-            displayName: 'Default',
-            path: root,
-            isDefault: true,
-          },
-        ];
+      const safariProfiles = await listSafariProfiles(browser, root);
+      if (safariProfiles.length) {
+        return safariProfiles;
       }
       continue;
     }
@@ -301,7 +295,7 @@ async function listProfilesForBrowser(browser, platform, homeDir, environment) {
   return profiles;
 }
 
-/** Discover cookie-bearing profiles from installed browsers. */
+/** Discover profiles, retaining per-source errors alongside readable profiles. */
 export async function listBrowserProfiles({
   browser,
   platform = process.platform,
@@ -330,10 +324,11 @@ export async function listBrowserProfiles({
       homeDir,
       environment
     )) {
-      if (seen.has(profile.path)) {
+      const identity = JSON.stringify([profile.path, Boolean(profile.error)]);
+      if (seen.has(identity)) {
         continue;
       }
-      seen.add(profile.path);
+      seen.add(identity);
       profiles.push(profile);
     }
   }
@@ -360,5 +355,8 @@ export async function resolveBrowserProfile(options) {
     const detail = requested ? ` profile "${requested}"` : ' profile';
     throw new Error(`Could not find a cookie database for ${browser}${detail}`);
   }
+  if (selected.error) {
+    throw new Error(selected.error);
+  }
   return selected;
 }

package/src/browser/browser-sources.js

@@ -100,6 +100,8 @@ function templateVariables(platform, homeDir, environment) {
         environment.LOCALAPPDATA ?? pathApi.join(homeDir, 'AppData', 'Local'),
       appData:
         environment.APPDATA ?? pathApi.join(homeDir, 'AppData', 'Roaming'),
+      programFiles: environment.PROGRAMFILES,
+      programFilesX86: environment['PROGRAMFILES(X86)'],
     };
   }
   return {
@@ -133,7 +135,29 @@ function expandTemplate(template, variables, pathApi) {
  * @param {Object} [options.environment=process.env]
  * @returns {string[]}
  */
-export function resolveBrowserRoots(
+export function resolveBrowserRoots(name, options = {}) {
+  const source = normalizeBrowserSource(name);
+  const templates = source.roots?.[options.platform ?? process.platform] ?? [];
+  return resolveTemplates(templates, options);
+}
+
+function resolveTemplates(
+  templates,
+  {
+    platform = process.platform,
+    homeDir = os.homedir(),
+    environment = process.env,
+  } = {}
+) {
+  const pathApi = platformPath(platform);
+  const variables = templateVariables(platform, homeDir, environment);
+  return templates
+    .map((template) => expandTemplate(template, variables, pathApi))
+    .filter((entry) => entry !== undefined);
+}
+
+/** Installed executable candidates, from the same catalogue as profile roots. */
+export function resolveBrowserExecutables(
   name,
   {
     platform = process.platform,
@@ -142,17 +166,23 @@ export function resolveBrowserRoots(
   } = {}
 ) {
   const source = normalizeBrowserSource(name);
-  const templates = source.roots?.[platform] ?? [];
   const pathApi = platformPath(platform);
-  const variables = templateVariables(platform, homeDir, environment);
-  const roots = [];
-  for (const template of templates) {
-    const resolved = expandTemplate(template, variables, pathApi);
-    if (resolved !== undefined) {
-      roots.push(resolved);
+  const candidates = resolveTemplates(source.executables?.[platform] ?? [], {
+    platform,
+    homeDir,
+    environment,
+  });
+  const delimiter = platform === 'win32' ? ';' : path.delimiter;
+  for (const directory of (environment.PATH ?? '')
+    .split(delimiter)
+    .filter(Boolean)) {
+    for (const name of source.executableNames ?? []) {
+      candidates.push(
+        pathApi.join(directory, platform === 'win32' ? `${name}.exe` : name)
+      );
     }
   }
-  return roots;
+  return [...new Set(candidates)];
 }
 
 /** True when a browser stores one profile in the root itself (Opera-style). */