browser-commander 0.21.2 → 0.22.0

package/src/cli/args.js

@@ -78,11 +78,17 @@ export const COMMANDS = Object.freeze({
       domain: STRINGS,
     },
   },
+  'cookies sources': {
+    positionals: [],
+    options: { domain: STRINGS },
+  },
   'profile migrate': {
     positionals: [],
     options: {
       from: STRING,
       profile: STRING,
+      'user-data-dir': STRING,
+      'target-browser': STRING,
       to: STRING,
       include: STRING,
       domain: STRINGS,
@@ -92,6 +98,10 @@ export const COMMANDS = Object.freeze({
     positionals: [],
     options: { from: STRING, profile: STRING, to: STRING },
   },
+  'profile sources': {
+    positionals: [],
+    options: { browser: STRING },
+  },
   attach: {
     positionals: [],
     options: { mode: STRING, port: STRING, timeout: STRING },

package/src/cli/commands.js

@@ -210,6 +210,8 @@ async function profileMigrate(parsed, io) {
     await dispatchOnce(io, 'profile.migrate', {
       from: requireOption(options, 'from', 'profile migrate'),
       profile: options.profile,
+      userDataDir: options.userDataDir,
+      targetBrowser: options.targetBrowser,
       to: options.to,
       include: options.include
         ?.split(',')
@@ -220,6 +222,29 @@ async function profileMigrate(parsed, io) {
   );
 }
 
+/**
+ * List the installed browser profiles that hold cookies (names and counts
+ * only, never values), optionally filtered and counted by `--domain`.
+ */
+async function cookieSources(parsed, io) {
+  const { options } = parsed;
+  return done(
+    await dispatchOnce(io, 'cookies.sources', {
+      domains: options.domain,
+    })
+  );
+}
+
+/** List installed browser profiles, optionally for one `--browser`. */
+async function profileSources(parsed, io) {
+  const { options } = parsed;
+  return done(
+    await dispatchOnce(io, 'profile.sources', {
+      browser: options.browser,
+    })
+  );
+}
+
 /** Copy a real profile into `--to` (or a new temporary directory). */
 async function profileSnapshot(parsed, io) {
   const { options } = parsed;
@@ -323,8 +348,10 @@ export const COMMAND_HANDLERS = Object.freeze({
     profile: options.profile,
     domains: options.domain,
   })),
+  'cookies sources': cookieSources,
   'profile migrate': profileMigrate,
   'profile snapshot': profileSnapshot,
+  'profile sources': profileSources,
   attach,
   doctor,
   run,

package/src/cli/high-level-methods.js

@@ -191,12 +191,18 @@ async function importCookies(state, params) {
 }
 
 function migrateProfile(state, params) {
+  // The CLI passes the source browser flat (`--from`, `--profile`,
+  // `--user-data-dir`); migrateProfile expects them grouped under `from`.
   return state.dependencies.migrateProfile({
-    from: params.from,
-    profile: params.profile,
+    from: {
+      browser: requireString(params, 'from'),
+      profile: params.profile,
+      userDataDir: params.userDataDir,
+    },
     to: params.to,
     include: params.include,
     domains: params.domains,
+    targetBrowser: params.targetBrowser,
   });
 }
 
@@ -209,6 +215,24 @@ function snapshotProfile(state, params) {
   });
 }
 
+/** List browsers/profiles holding cookies, with optional per-domain counts. */
+async function cookieSources(state, params) {
+  const domains = params.domains;
+  if (domains !== undefined && !Array.isArray(domains)) {
+    throw invalidParams('domains must be an array of strings');
+  }
+  return { sources: await state.dependencies.listCookieSources({ domains }) };
+}
+
+/** List the installed browser profiles (never cookie values). */
+async function profileSources(state, params) {
+  return {
+    profiles: await state.dependencies.listBrowserProfiles({
+      browser: params.browser,
+    }),
+  };
+}
+
 function relayOf(state) {
   if (!state.relay) {
     throw invalidParams('No extension is attached; call attach first');
@@ -298,8 +322,10 @@ export const HIGH_LEVEL_METHODS = Object.freeze({
   'trace.start': traceStart,
   'trace.stop': traceStop,
   'cookies.import': importCookies,
+  'cookies.sources': cookieSources,
   'profile.migrate': migrateProfile,
   'profile.snapshot': snapshotProfile,
+  'profile.sources': profileSources,
   attach,
   'attach.tabs': attachTabs,
   'attach.send': attachSend,

package/src/cli/modules.js

@@ -64,6 +64,12 @@ export const DEFAULT_DEPENDENCIES = Object.freeze({
   writeTraceViewer,
   readBrowserCookies: async (options) =>
     (await import('../browser/browser-cookies.js')).readBrowserCookies(options),
+  listCookieSources: async (options) =>
+    (await import('../browser/browser-cookies.js')).listCookieSources(options),
+  listBrowserProfiles: async (options) =>
+    (await import('../browser/browser-profiles.js')).listBrowserProfiles(
+      options
+    ),
   loadEngine: (name) => importOptional(name, `The ${name} engine`),
   openInUserBrowser: async (url) =>
     (

package/src/exports.js

@@ -60,8 +60,12 @@ export {
 export { connectBrowser } from './browser/connector.js';
 export {
   listBrowserProfiles,
+  listCookieSources,
   readBrowserCookies,
+  resolveImportSource,
 } from './browser/browser-cookies.js';
+export { resolveDefaultBrowser } from './browser/default-browser.js';
+export { BROWSER_IDS, findBrowserSource } from './browser/browser-sources.js';
 export {
   launchAndConnectRealBrowser,
   launchRealBrowser,

package/tests/helpers/cli-fakes.js

@@ -158,6 +158,27 @@ export function createFakeDependencies() {
       { name: 'sid', value: '1', domain: `.${domainFilter}`, path: '/' },
       { name: 'bad', value: '2', domain: `.${domainFilter}`, path: '/' },
     ],
+    listCookieSources: async ({ domains } = {}) => [
+      {
+        browser: 'chrome',
+        profile: 'Default',
+        path: '/home/user/.config/google-chrome/Default',
+        isDefault: true,
+        cookies: 7,
+        byDomain: domains
+          ? Object.fromEntries(domains.map((d) => [d, 1]))
+          : null,
+      },
+    ],
+    listBrowserProfiles: async ({ browser } = {}) => [
+      {
+        browser: browser ?? 'chrome',
+        name: 'Default',
+        displayName: 'Default',
+        path: `/home/user/.config/${browser ?? 'google-chrome'}/Default`,
+        isDefault: true,
+      },
+    ],
     loadEngine: async (name) => ({ default: new FakeEngine(name) }),
     openInUserBrowser: async (url) => ({ opened: url, command: ['open', url] }),
     migrateProfile: async (options) => ({ migrated: {}, options }),

package/tests/helpers/migration-fixtures.js

@@ -8,7 +8,7 @@
  */
 
 import assert from 'node:assert';
-import { readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import BetterSqlite3 from 'better-sqlite3';
@@ -148,6 +148,35 @@ export async function writeFirefoxCookies(profileDir, rows) {
   return cookiePath;
 }
 
+/**
+ * Write a Linux Firefox-family install under `home` with one default profile,
+ * listed in `profiles.ini`, whose `cookies.sqlite` holds `rows`.
+ *
+ * @param {string} home - Home directory the install lives under
+ * @param {Array<Object>} rows - Cookie rows, as for `writeFirefoxCookies`
+ * @param {Object} [options]
+ * @param {string} [options.root='.mozilla/firefox'] - Install root, relative
+ *   to `home` (a fork such as LibreWolf uses its own)
+ * @param {string} [options.name='default-release'] - Profile name
+ * @returns {Promise<string>} The profile directory
+ */
+export async function writeFirefoxProfile(
+  home,
+  rows,
+  { root = '.mozilla/firefox', name = 'default-release' } = {}
+) {
+  const rootPath = path.join(home, ...root.split('/'));
+  const profileName = `xyz.${name}`;
+  const profilePath = path.join(rootPath, profileName);
+  await mkdir(profilePath, { recursive: true });
+  await writeFile(
+    path.join(rootPath, 'profiles.ini'),
+    `[Profile0]\nName=${name}\nIsRelative=1\nPath=${profileName}\nDefault=1\n`
+  );
+  await writeFirefoxCookies(profilePath, rows);
+  return profilePath;
+}
+
 /**
  * Write a Firefox `places.sqlite` with a toolbar bookmark and, unless
  * `withMenuBookmark` is false, a bookmarks-menu one. Each bookmark has its own

package/tests/unit/browser/browser-cookies-profiledir.test.js

@@ -0,0 +1,36 @@
+import assert from 'node:assert';
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import { readBrowserCookiesWithDependencies } from '../../../src/browser/browser-cookies.js';
+import { writeFirefoxCookies } from '../../helpers/migration-fixtures.js';
+import { useTempDirectories } from '../../helpers/temp-directory.js';
+
+const makeDirectory = useTempDirectories();
+
+describe('readBrowserCookies honours an explicit profileDir', () => {
+  it('reads cookies from the given directory, not the default profile root', async () => {
+    const temporaryDirectory = await makeDirectory('bc-profiledir-');
+    // A custom userDataDir that is NOT under the default profile root.
+    const customProfile = path.join(temporaryDirectory, 'custom', 'profile');
+    await mkdir(customProfile, { recursive: true });
+    await writeFirefoxCookies(customProfile, [
+      { name: 'sid', value: 'abc', host: '.example.com' },
+    ]);
+
+    // homeDir points somewhere with no browser data, so a reader that ignored
+    // profileDir and re-resolved the default profile would find nothing.
+    const emptyHome = path.join(temporaryDirectory, 'empty-home');
+    await mkdir(emptyHome, { recursive: true });
+
+    const cookies = await readBrowserCookiesWithDependencies(
+      { browser: 'firefox', profileDir: customProfile },
+      { platform: 'linux', homeDir: emptyHome }
+    );
+
+    assert.equal(cookies.length, 1);
+    assert.equal(cookies[0].name, 'sid');
+    assert.equal(cookies[0].domain, '.example.com');
+  });
+});

package/tests/unit/browser/browser-cookies.test.js

@@ -37,7 +37,7 @@ import {
   listBrowserProfiles as publicListBrowserProfiles,
   readBrowserCookies as publicReadBrowserCookies,
 } from '../../../src/index.js';
-import { writeFirefoxCookies } from '../../helpers/migration-fixtures.js';
+import { writeFirefoxProfile } from '../../helpers/migration-fixtures.js';
 
 const CHROME_EPOCH_OFFSET_SECONDS = 11_644_473_600;
 const execFile = promisify(execFileCallback);
@@ -134,16 +134,7 @@ async function createChromiumProfile({ homeDir, rows, profile = 'Default' }) {
 }
 
 async function createFirefoxProfile({ homeDir, rows }) {
-  const root = path.join(homeDir, '.mozilla', 'firefox');
-  const profileName = 'fixture.default-release';
-  const profilePath = path.join(root, profileName);
-  await mkdir(profilePath, { recursive: true });
-  await writeFile(
-    path.join(root, 'profiles.ini'),
-    `[Profile0]\nName=default-release\nIsRelative=1\nPath=${profileName}\nDefault=1\n`
-  );
-  const cookiePath = await writeFirefoxCookies(profilePath, rows);
-  return { cookiePath, profilePath, root };
+  return { profilePath: await writeFirefoxProfile(homeDir, rows) };
 }
 
 describe('installed browser cookie import', () => {

package/tests/unit/browser/browser-profiles-sources.test.js

@@ -0,0 +1,150 @@
+import assert from 'node:assert';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import {
+  listBrowserProfiles,
+  resolveBrowserProfile,
+  resolveSourceBrowser,
+} from '../../../src/browser/browser-profiles.js';
+import { writeFirefoxProfile } from '../../helpers/migration-fixtures.js';
+import { useTempDirectories } from '../../helpers/temp-directory.js';
+
+const makeDirectory = useTempDirectories();
+
+/** The browser of every profile `listBrowserProfiles` finds. */
+async function listedBrowsers(options) {
+  const profiles = await listBrowserProfiles(options);
+  return profiles.map((profile) => profile.browser);
+}
+
+async function writeChromiumCookieDatabase(profilePath) {
+  const cookiePath = path.join(profilePath, 'Network', 'Cookies');
+  await mkdir(path.dirname(cookiePath), { recursive: true });
+  await writeFile(cookiePath, 'SQLite format 3\u0000');
+  return cookiePath;
+}
+
+describe('listBrowserProfiles with the expanded catalogue', () => {
+  it('reads an Opera single-profile layout from the root itself', async () => {
+    const temporaryDirectory = await makeDirectory('bc-opera-');
+    const root = path.join(temporaryDirectory, '.config', 'opera');
+    await mkdir(root, { recursive: true });
+    const cookiePath = await writeChromiumCookieDatabase(root);
+
+    const profiles = await listBrowserProfiles({
+      browser: 'opera',
+      platform: 'linux',
+      homeDir: temporaryDirectory,
+      environment: {},
+    });
+
+    assert.deepEqual(profiles, [
+      {
+        browser: 'opera',
+        name: 'Default',
+        displayName: 'Default',
+        path: root,
+        isDefault: true,
+      },
+    ]);
+    assert.ok(cookiePath.startsWith(root));
+  });
+
+  it('discovers a Firefox fork (LibreWolf) by its own root', async () => {
+    const temporaryDirectory = await makeDirectory('bc-librewolf-');
+    const profilePath = await writeFirefoxProfile(
+      temporaryDirectory,
+      [{ name: 'a', value: '1', host: '.example.com' }],
+      { root: '.librewolf', name: 'default' }
+    );
+
+    const profiles = await listBrowserProfiles({
+      browser: 'librewolf',
+      platform: 'linux',
+      homeDir: temporaryDirectory,
+    });
+
+    assert.deepEqual(profiles, [
+      {
+        browser: 'librewolf',
+        name: 'default',
+        displayName: 'default',
+        path: profilePath,
+        isDefault: true,
+      },
+    ]);
+  });
+
+  it('lists Firefox once when its channels share a root', async () => {
+    const temporaryDirectory = await makeDirectory('bc-ffshare-');
+    await writeFirefoxProfile(temporaryDirectory, [
+      { name: 'a', value: '1', host: '.example.com' },
+    ]);
+
+    assert.deepEqual(
+      await listedBrowsers({ platform: 'linux', homeDir: temporaryDirectory }),
+      ['firefox']
+    );
+  });
+
+  it('resolves browser: "default" to the system default browser', async () => {
+    const runCommand = async (command, args) => {
+      if (
+        command === 'xdg-settings' &&
+        args.join(' ') === 'get default-web-browser'
+      ) {
+        return 'firefox.desktop\n';
+      }
+      throw new Error('unexpected command');
+    };
+    assert.equal(
+      await resolveSourceBrowser('default', { platform: 'linux', runCommand }),
+      'firefox'
+    );
+    assert.equal(
+      await resolveSourceBrowser('AUTO', { platform: 'linux', runCommand }),
+      'firefox'
+    );
+  });
+
+  it('lists the default browser profile when browser is "default"', async () => {
+    const temporaryDirectory = await makeDirectory('bc-default-');
+    const profilePath = await writeFirefoxProfile(temporaryDirectory, [
+      { name: 'a', value: '1', host: '.example.com' },
+    ]);
+    const runCommand = async () => 'firefox.desktop\n';
+
+    const resolved = await resolveBrowserProfile({
+      browser: 'default',
+      platform: 'linux',
+      homeDir: temporaryDirectory,
+      runCommand,
+    });
+    assert.equal(resolved.browser, 'firefox');
+    assert.equal(resolved.path, profilePath);
+
+    assert.deepEqual(
+      await listedBrowsers({
+        browser: 'auto',
+        platform: 'linux',
+        homeDir: temporaryDirectory,
+        runCommand,
+      }),
+      ['firefox']
+    );
+  });
+
+  it('reports a clear error when the default browser is unknown', async () => {
+    await assert.rejects(
+      resolveSourceBrowser('default', {
+        platform: 'linux',
+        runCommand: async () => {
+          throw new Error('no xdg');
+        },
+      }),
+      /Could not determine the system default browser/
+    );
+  });
+});

package/tests/unit/browser/browser-sources.test.js

@@ -0,0 +1,154 @@
+// feature-parity: sources.catalogue@native-typed
+import assert from 'node:assert';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import {
+  BROWSER_IDS,
+  browserFamily,
+  defaultBrowserIdentifiers,
+  findBrowserSource,
+  isSingleProfileBrowser,
+  normalizeBrowserId,
+  resolveBrowserRoots,
+  safeStorageIdentity,
+} from '../../../src/browser/browser-sources.js';
+
+describe('browser-sources catalogue', () => {
+  it('keeps the original five browsers resolvable by id and alias', () => {
+    assert.equal(normalizeBrowserId('chrome'), 'chrome');
+    assert.equal(normalizeBrowserId('msedge'), 'edge');
+    assert.equal(normalizeBrowserId('microsoft-edge'), 'edge');
+    assert.equal(normalizeBrowserId('google-chrome'), 'chrome');
+    assert.equal(normalizeBrowserId('CHROME'), 'chrome');
+  });
+
+  it('adds the new source browsers from #114', () => {
+    for (const id of [
+      'opera',
+      'opera-gx',
+      'vivaldi',
+      'arc',
+      'yandex',
+      'chrome-beta',
+      'chrome-dev',
+      'chrome-canary',
+      'edge-beta',
+      'edge-dev',
+      'librewolf',
+      'waterfox',
+      'zen',
+      'floorp',
+      'firefox-developer',
+      'firefox-nightly',
+    ]) {
+      assert.ok(BROWSER_IDS.includes(id), `missing ${id}`);
+      assert.ok(findBrowserSource(id), `unresolvable ${id}`);
+    }
+  });
+
+  it('rejects an unknown browser with the catalogue listed', () => {
+    assert.throws(
+      () => normalizeBrowserId('netscape'),
+      /Unsupported browser: netscape\. Expected one of .*chrome/
+    );
+  });
+
+  it('classifies browser families', () => {
+    assert.equal(browserFamily('chrome'), 'chromium');
+    assert.equal(browserFamily('opera'), 'chromium');
+    assert.equal(browserFamily('firefox'), 'firefox');
+    assert.equal(browserFamily('librewolf'), 'firefox');
+  });
+
+  // POSIX targets join with the host separator, so a Windows host running
+  // these Linux/macOS cases yields backslashes, like every other path here.
+  it('expands per-platform roots with the home directory', () => {
+    assert.deepEqual(
+      resolveBrowserRoots('chrome', {
+        platform: 'linux',
+        homeDir: '/home/me',
+        environment: {},
+      }),
+      [path.join('/home/me', '.config', 'google-chrome')]
+    );
+    assert.deepEqual(
+      resolveBrowserRoots('firefox', {
+        platform: 'darwin',
+        homeDir: '/Users/me',
+      }),
+      [path.join('/Users/me', 'Library', 'Application Support', 'Firefox')]
+    );
+  });
+
+  it('honours XDG_CONFIG_HOME on Linux', () => {
+    assert.deepEqual(
+      resolveBrowserRoots('chromium', {
+        platform: 'linux',
+        homeDir: '/home/me',
+        environment: { XDG_CONFIG_HOME: '/cfg' },
+      }),
+      [path.join('/cfg', 'chromium')]
+    );
+  });
+
+  it('builds Windows roots with backslashes from %APPDATA%/%LOCALAPPDATA%', () => {
+    assert.deepEqual(
+      resolveBrowserRoots('opera', {
+        platform: 'win32',
+        homeDir: 'C:\\Users\\me',
+        environment: { APPDATA: 'C:\\Users\\me\\AppData\\Roaming' },
+      }),
+      ['C:\\Users\\me\\AppData\\Roaming\\Opera Software\\Opera Stable']
+    );
+    assert.deepEqual(
+      resolveBrowserRoots('chrome', {
+        platform: 'win32',
+        homeDir: 'C:\\Users\\me',
+        environment: { LOCALAPPDATA: 'C:\\Users\\me\\AppData\\Local' },
+      }),
+      ['C:\\Users\\me\\AppData\\Local\\Google\\Chrome\\User Data']
+    );
+  });
+
+  it('returns no root where a browser does not run', () => {
+    assert.deepEqual(
+      resolveBrowserRoots('chrome-canary', {
+        platform: 'linux',
+        homeDir: '/home/me',
+      }),
+      []
+    );
+    assert.deepEqual(
+      resolveBrowserRoots('arc', { platform: 'linux', homeDir: '/home/me' }),
+      []
+    );
+  });
+
+  it('marks Opera-style browsers as single-profile', () => {
+    assert.equal(isSingleProfileBrowser('opera'), true);
+    assert.equal(isSingleProfileBrowser('opera-gx'), true);
+    assert.equal(isSingleProfileBrowser('chrome'), false);
+    assert.equal(isSingleProfileBrowser('vivaldi'), false);
+  });
+
+  it('exposes a Safe Storage identity for Chromium and none for Firefox', () => {
+    assert.deepEqual(safeStorageIdentity('brave'), {
+      service: 'Brave Safe Storage',
+      application: 'brave',
+      folder: 'Brave Keys',
+    });
+    assert.equal(safeStorageIdentity('firefox'), undefined);
+  });
+
+  it('exposes default-browser identifiers per platform', () => {
+    assert.deepEqual(defaultBrowserIdentifiers('chrome', 'darwin'), [
+      'com.google.chrome',
+    ]);
+    assert.deepEqual(defaultBrowserIdentifiers('firefox', 'win32'), [
+      'FirefoxHTML',
+      'FirefoxURL',
+    ]);
+    assert.deepEqual(defaultBrowserIdentifiers('chrome', 'nope'), []);
+  });
+});