browser-commander 0.21.0 → 0.21.2

package/.jscpd.json

@@ -11,7 +11,8 @@
     "**/.changeset/**",
     "**/package-lock.json",
     "**/pnpm-lock.yaml",
-    "**/yarn.lock"
+    "**/yarn.lock",
+    "**/tests/fixtures/traces/conformance/**"
   ],
   "reporters": ["console", "html"],
   "output": "./reports/jscpd"

package/.prettierignore

@@ -7,3 +7,4 @@ package-lock.json
 .eslintcache
 CLAUDE.md
 reports
+tests/fixtures/traces/conformance/expected

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.21.2
+
+### Patch Changes
+
+- 917d611: Keep the real-browser launcher under the ESLint complexity limit, fail `npm run lint` on any warning, and record that `node-pty`'s install script (pulled in by `command-stream`) stays blocked.
+
+## 0.21.1
+
+### Patch Changes
+
+- 4caa385: Suppress Chromium's default-browser prompt through profile settings on fresh and snapshot launches, and expose configurable Preferences and Local State values.
+
+  Update the locked brace-expansion dependency to 5.0.12 to resolve its CPU and stack exhaustion advisories.
+
+  Retry transient Windows credential-lock EPERM within the existing bounded deadline, preserving the underlying error when contention persists.
+
+  Accept a `monotonic` clock in `startTrace` and use the injected `now` for interaction durations, so a trace recorded with a fixed clock is byte-for-byte reproducible; the Python and Rust recorders are checked against such a recording.
+
+  Escape recorded text in the offline trace viewer. A recorded page's URL, title, form control values and event fields were inserted into the viewer as HTML, so a page could run script in the viewer of whoever opened its trace.
+
 ## 0.21.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "bin": {
@@ -27,7 +27,7 @@
     "test:e2e:api-coverage": "node scripts/run-tests.mjs --env RUN_E2E=true tests/e2e/api-coverage.e2e.test.js",
     "test:e2e:google-probe": "node scripts/run-tests.mjs --env RUN_E2E=true --env RUN_GOOGLE_PROBE=true tests/e2e/google-signin-probe.e2e.test.js",
     "test:all": "npm run test:unit && npm run test:e2e",
-    "lint": "eslint .",
+    "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -97,10 +97,13 @@
     "playwright": "^1.62.1",
     "prettier": "^3.9.6",
     "puppeteer": "^25.10.0",
-    "selenium-webdriver": "^4.49.0"
+    "selenium-webdriver": "^4.49.0",
+    "typescript": "^5.9.3",
+    "yaml": "^2.9.1"
   },
   "allowScripts": {
     "better-sqlite3@13.0.3": true,
+    "node-pty": false,
     "puppeteer": false
   }
 }

package/src/browser/attach/snapshot.js

@@ -155,9 +155,9 @@ function isInside(child, parent) {
   );
 }
 
-async function prepareTarget(to, sourceRoot) {
+async function prepareTarget(to, sourceRoot, profile) {
   if (!to) {
-    return await createTemporaryUserDataDir();
+    return await createTemporaryUserDataDir({ profileDirectory: profile });
   }
   if (isInside(to, sourceRoot)) {
     throw new Error(
@@ -328,7 +328,7 @@ export async function snapshotUserDataDir({
     );
   }
 
-  const target = await prepareTarget(to, sourceRoot);
+  const target = await prepareTarget(to, sourceRoot, profile);
   try {
     return await copyProfile({
       sourceRoot,
@@ -361,7 +361,7 @@ async function copyProfile({ sourceRoot, profile, target, source }) {
     });
   }
   await copier.copyDirectory(profile);
-  await prepareUserDataDir(target);
+  await prepareUserDataDir(target, { profileDirectory: profile });
   await markExitedCleanly(path.join(target, profile));
 
   return {

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

@@ -162,13 +162,21 @@ async function wait(milliseconds) {
 
 async function acquireCredentialLock(lockPath, cachedPath, options) {
   const startedAt = options.now();
+  let contention;
   while (options.now() - startedAt <= LOCK_WAIT_MILLISECONDS) {
     try {
       return await open(lockPath, 'wx', 0o600);
     } catch (error) {
-      if (error.code !== 'EEXIST') {
+      // Windows can report EPERM while another process's unlinked lock is
+      // still pending deletion. Retry within the same bounded lock deadline.
+      // Preserve the original error if it proves to be permanent.
+      if (
+        error.code !== 'EEXIST' &&
+        !(options.platform === 'win32' && error.code === 'EPERM')
+      ) {
         throw error;
       }
+      contention = error;
       const cached = await readFreshJson(
         cachedPath,
         options.ttlSeconds,
@@ -184,7 +192,9 @@ async function acquireCredentialLock(lockPath, cachedPath, options) {
       await wait(50);
     }
   }
-  throw new Error('timed out waiting for another cookie credential reader');
+  throw new Error('timed out waiting for another cookie credential reader', {
+    cause: contention,
+  });
 }
 
 async function loadOrCreateCredential({
@@ -194,6 +204,7 @@ async function loadOrCreateCredential({
   create,
   now,
   metadata,
+  platform = process.platform,
 }) {
   if (!cache.enabled) {
     return { key: Buffer.from(await create()), savedAt: now() / 1000 };
@@ -214,6 +225,7 @@ async function loadOrCreateCredential({
     now,
     refresh,
     ttlSeconds: cache.ttlSeconds,
+    platform,
   });
   if (acquired.cached) {
     return {

package/src/browser/profile-directory.js

@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -14,6 +14,7 @@ export const FIRST_RUN_SENTINEL = 'First Run';
 
 /** Chrome's profile-wide settings file, next to the profile directories. */
 export const LOCAL_STATE_FILE = 'Local State';
+export const PREFERENCES_FILE = path.join('Default', 'Preferences');
 
 /**
  * Local State written into a brand-new user data directory.
@@ -51,11 +52,111 @@ export const TEMPORARY_PROFILE_PREFIX = 'browser-commander-profile-';
  * @param {string} userDataDir
  * @returns {Promise<string>} The same directory
  */
-export async function prepareUserDataDir(userDataDir) {
+function assertObject(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${name} must be a JSON object`);
+  }
+}
+
+function deepMerge(target, source) {
+  for (const [key, value] of Object.entries(source)) {
+    if (['__proto__', 'prototype', 'constructor'].includes(key)) {
+      throw new TypeError(`profile setting key ${key} is not allowed`);
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      target[key] = deepMerge(
+        target[key] &&
+          typeof target[key] === 'object' &&
+          !Array.isArray(target[key])
+          ? target[key]
+          : {},
+        value
+      );
+    } else {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+async function mergeJsonFile(file, defaults, overrides) {
+  let current = {};
+  try {
+    current = JSON.parse(await readFile(file, 'utf8'));
+    assertObject(current, file);
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+  const merged = deepMerge(deepMerge(current, defaults), overrides);
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, JSON.stringify(merged));
+}
+
+/** Merge launch settings into a fresh, migrated, or snapshotted profile. */
+export async function configureUserDataDir(
+  userDataDir,
+  {
+    defaultBrowserCheck,
+    preferences = {},
+    localState = {},
+    profileDirectory = 'Default',
+  } = {}
+) {
+  assertObject(preferences, 'preferences');
+  assertObject(localState, 'localState');
+  if (
+    defaultBrowserCheck !== undefined &&
+    typeof defaultBrowserCheck !== 'boolean'
+  ) {
+    throw new TypeError('defaultBrowserCheck must be a boolean');
+  }
+  if (
+    typeof profileDirectory !== 'string' ||
+    !profileDirectory ||
+    path.basename(profileDirectory) !== profileDirectory ||
+    profileDirectory === '.' ||
+    profileDirectory === '..'
+  ) {
+    throw new TypeError('profileDirectory must be one profile directory name');
+  }
+  const profilePreferences = deepMerge(
+    { browser: { check_default_browser: false } },
+    preferences
+  );
+  assertObject(profilePreferences.browser, 'preferences.browser');
+  if (defaultBrowserCheck !== undefined) {
+    profilePreferences.browser.check_default_browser = defaultBrowserCheck;
+  }
+  await mergeJsonFile(
+    path.join(userDataDir, profileDirectory, 'Preferences'),
+    {},
+    profilePreferences
+  );
+  const check = profilePreferences.browser?.check_default_browser === true;
+  await mergeJsonFile(
+    path.join(userDataDir, LOCAL_STATE_FILE),
+    {
+      browser: {
+        default_browser_infobar_declined_count: check ? 0 : 5,
+        default_browser_declined_count: check ? 0 : 5,
+      },
+    },
+    localState
+  );
+}
+
+export async function prepareUserDataDir(userDataDir, options = {}) {
+  if (options.firstRun !== undefined && typeof options.firstRun !== 'boolean') {
+    throw new TypeError('firstRun must be a boolean');
+  }
   await mkdir(userDataDir, { recursive: true });
-  await writeFile(path.join(userDataDir, FIRST_RUN_SENTINEL), '', {
-    flag: 'a',
-  });
+  if (options.firstRun !== true) {
+    await writeFile(path.join(userDataDir, FIRST_RUN_SENTINEL), '', {
+      flag: 'a',
+    });
+  }
   try {
     await writeFile(
       path.join(userDataDir, LOCAL_STATE_FILE),
@@ -67,6 +168,7 @@ export async function prepareUserDataDir(userDataDir) {
       throw error;
     }
   }
+  await configureUserDataDir(userDataDir, options);
   return userDataDir;
 }
 
@@ -79,11 +181,12 @@ export async function prepareUserDataDir(userDataDir) {
  */
 export async function createTemporaryUserDataDir({
   parent = os.tmpdir(),
+  ...options
 } = {}) {
   const userDataDir = await mkdtemp(
     path.join(parent, TEMPORARY_PROFILE_PREFIX)
   );
-  return await prepareUserDataDir(userDataDir);
+  return await prepareUserDataDir(userDataDir, options);
 }
 
 /**

package/src/browser/real-browser.js

@@ -21,6 +21,7 @@ import {
   watchDevToolsOutput,
 } from './debugging-port.js';
 import {
+  configureUserDataDir,
   createTemporaryUserDataDir,
   prepareUserDataDir,
   removeUserDataDir,
@@ -324,6 +325,9 @@ function createCloser({
  * @param {string[]} [options.restrictions] - Opt-in restrictions from launch-restrictions.json, such as 'no-extensions'
  * @param {string[]} [options.args] - Additional browser arguments
  * @param {string[]} [options.extraArgs] - Additional browser arguments appended after args
+ * @param {boolean} [options.defaultBrowserCheck=false] - Allow the disposable browser to ask to become the default
+ * @param {Object} [options.preferences] - Deep-merged into Default/Preferences before launch
+ * @param {Object} [options.localState] - Deep-merged into Local State before launch
  * @param {Object<string,string>} [options.env] - Extra environment for the browser process only
  * @param {boolean} [options.automationParity=true] - Add the AutomationControlled off switch when a custom argument turns the feature on
  * @param {number} [options.startupTimeout=30000] - CDP readiness timeout in milliseconds
@@ -455,6 +459,7 @@ async function prepareProfile({
   requestedUserDataDir,
   argOptions,
   snapshot,
+  firstRun,
 }) {
   if (attach) {
     const snapshotLaunch = await prepareSnapshotLaunch({
@@ -469,8 +474,8 @@ async function prepareProfile({
   }
   return {
     userDataDir: requestedUserDataDir
-      ? await prepareUserDataDir(requestedUserDataDir)
-      : await createTemporaryUserDataDir(),
+      ? await prepareUserDataDir(requestedUserDataDir, { firstRun })
+      : await createTemporaryUserDataDir({ firstRun }),
   };
 }
 
@@ -516,6 +521,28 @@ async function runPreLaunchMigration({
   }
 }
 
+function mergeSeedCookies(seedCookies, migratedCookies) {
+  return migratedCookies.length > 0
+    ? [...(seedCookies ?? []), ...migratedCookies]
+    : seedCookies;
+}
+
+// Runs a launch step and, if it throws, removes the profile this launch
+// created before rethrowing. A caller-supplied profile is never removed.
+async function removingTemporaryProfileOnError(
+  { userDataDir, temporaryProfile },
+  step
+) {
+  try {
+    return await step();
+  } catch (error) {
+    if (temporaryProfile) {
+      await removeUserDataDir(userDataDir);
+    }
+    throw error;
+  }
+}
+
 export async function launchAndConnectRealBrowserWithDependencies(
   options = {},
   dependencies = {}
@@ -541,6 +568,10 @@ export async function launchAndConnectRealBrowserWithDependencies(
     wsEndpoint,
     migrateFrom,
     attach,
+    defaultBrowserCheck,
+    preferences,
+    localState,
+    firstRun,
     ...connectionOptions
   } = options;
   const argOptions = {
@@ -573,6 +604,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
     requestedUserDataDir,
     argOptions,
     snapshot: dependencies.snapshotUserDataDir,
+    firstRun,
   });
   const childEnv = browserEnvironment(restrictions, env);
 
@@ -584,9 +616,20 @@ export async function launchAndConnectRealBrowserWithDependencies(
     migrate: dependencies.migrateProfile ?? migrateProfile,
   });
 
-  let launched;
-  try {
-    launched = await spawnOnFreePort({
+  // Migration and snapshot attach can copy a preference that enables the
+  // default-browser infobar, so apply launch settings after either copy.
+  const profile = { userDataDir, temporaryProfile };
+  await removingTemporaryProfileOnError(profile, () =>
+    configureUserDataDir(userDataDir, {
+      defaultBrowserCheck,
+      preferences,
+      localState,
+      profileDirectory: attach?.profile ?? 'Default',
+    })
+  );
+
+  const launched = await removingTemporaryProfileOnError(profile, () =>
+    spawnOnFreePort({
       requestedPort: remoteDebuggingPort,
       portAttempts,
       executablePath,
@@ -596,13 +639,8 @@ export async function launchAndConnectRealBrowserWithDependencies(
       userDataDir,
       startupTimeout,
       dependencies,
-    });
-  } catch (error) {
-    if (temporaryProfile) {
-      await removeUserDataDir(userDataDir);
-    }
-    throw error;
-  }
+    })
+  );
   const { browserProcess, cdpEndpoint: resolvedCdpEndpoint } = launched;
   if (temporaryProfile) {
     // The profile goes away with the browser, also when the user closes the
@@ -614,10 +652,10 @@ export async function launchAndConnectRealBrowserWithDependencies(
 
   try {
     const connect = dependencies.connect ?? connectBrowser;
-    const seedCookies =
-      migratedCookies.length > 0
-        ? [...(connectionOptions.seedCookies ?? []), ...migratedCookies]
-        : connectionOptions.seedCookies;
+    const seedCookies = mergeSeedCookies(
+      connectionOptions.seedCookies,
+      migratedCookies
+    );
     const connection = await connect({
       engine,
       cdpEndpoint: resolvedCdpEndpoint,

package/src/cli/args.js

@@ -27,6 +27,10 @@ const BROWSER_OPTIONS = Object.freeze({
   launch: STRING,
   restriction: STRINGS,
   arg: STRINGS,
+  pref: STRINGS,
+  'local-state': STRINGS,
+  'default-browser-check': FLAG,
+  'first-run': FLAG,
 });
 
 /** Options accepted by every page command. */
@@ -182,6 +186,45 @@ export function requireOption(options, name, command) {
  * `--restriction` → `restrictions`), with unset options left out.
  */
 export function launchParams(options) {
+  const settings = (entries, flag) => {
+    if (entries === undefined) {
+      return undefined;
+    }
+    const result = {};
+    for (const entry of entries) {
+      const separator = entry.indexOf('=');
+      const path = entry.slice(0, separator).split('.');
+      if (
+        separator < 1 ||
+        path.some(
+          (part) =>
+            !part || ['__proto__', 'prototype', 'constructor'].includes(part)
+        )
+      ) {
+        throw new UsageError(`${flag} requires a dotted key=value`);
+      }
+      let value = entry.slice(separator + 1);
+      try {
+        value = JSON.parse(value);
+      } catch {
+        // Unquoted CLI text is a string.
+      }
+      let parent = result;
+      for (const part of path.slice(0, -1)) {
+        parent[part] ??= {};
+        if (
+          !parent[part] ||
+          typeof parent[part] !== 'object' ||
+          Array.isArray(parent[part])
+        ) {
+          throw new UsageError(`${flag} has a conflicting key: ${entry}`);
+        }
+        parent = parent[part];
+      }
+      parent[path.at(-1)] = value;
+    }
+    return result;
+  };
   const params = {
     engine: options.engine,
     browser: options.browser,
@@ -191,6 +234,10 @@ export function launchParams(options) {
     launch: options.launch,
     restrictions: options.restriction,
     args: options.arg,
+    preferences: settings(options.pref, '--pref'),
+    localState: settings(options.localState, '--local-state'),
+    defaultBrowserCheck: options.defaultBrowserCheck,
+    firstRun: options.firstRun,
   };
   return Object.fromEntries(
     Object.entries(params).filter(([, value]) => value !== undefined)

package/src/cli/sessions.js

@@ -34,6 +34,10 @@ const LAUNCH_PASSTHROUGH = Object.freeze([
   'env',
   'startupTimeout',
   'attach',
+  'preferences',
+  'localState',
+  'defaultBrowserCheck',
+  'firstRun',
 ]);
 
 /** Validate an engine name, defaulting to Playwright. */

package/src/traces/bundle.js

@@ -32,7 +32,7 @@ export const TRACE_DIRECTORY_MODE = 0o700;
 /**
  * Open a bundle for writing.
  *
- * @param {Object} options - `{output, limits, strict, now, onEvent}`
+ * @param {Object} options - `{output, limits, strict, now, monotonic, onEvent}`
  * @returns {Promise<Object>} The bundle writer
  */
 export async function openTraceBundle(options = {}) {
@@ -41,6 +41,7 @@ export async function openTraceBundle(options = {}) {
     strict = false,
     limits = {},
     now = () => Date.now(),
+    monotonic = () => performance.now(),
     onEvent = null,
   } = options;
 
@@ -119,7 +120,7 @@ export async function openTraceBundle(options = {}) {
     const record = {
       sequence: ++sequence,
       at: new Date(now()).toISOString(),
-      monotonicMs: Math.round(performance.now()),
+      monotonicMs: Math.round(monotonic()),
       ...event,
     };
     const line = `${JSON.stringify(record)}\n`;

package/src/traces/observers.js

@@ -51,7 +51,7 @@ export function interactionTarget(argument) {
 /**
  * Subscribe to everything a running trace listens to.
  *
- * @param {Object} options - `{commander, page, eventSources, record, note, identity}`
+ * @param {Object} options - `{commander, page, eventSources, record, note, identity, now}`
  * @param {Object} [options.commander] - The commander being traced, when there
  *   is one; interactions and managed downloads are reached through it
  * @param {Object} options.page - The page being traced
@@ -61,10 +61,19 @@ export function interactionTarget(argument) {
  * @param {Object} [options.identity] - Trace identity, see `identity.js`; the
  *   navigation observer is what moves it on to the next navigation, and the
  *   interaction observer is what names an action (issue #93)
+ * @param {Function} [options.now] - Wall clock in milliseconds, for durations
  * @returns {Function[]} One detach function per attached observer
  */
 export function attachTimelineObservers(options) {
-  const { commander, page, eventSources, record, note, identity } = options;
+  const {
+    commander,
+    page,
+    eventSources,
+    record,
+    note,
+    identity,
+    now = () => Date.now(),
+  } = options;
   const detachers = [];
 
   function subscribe(source, attach) {
@@ -234,7 +243,7 @@ export function attachTimelineObservers(options) {
       }
       originals.set(name, original);
       commander[name] = async (...args) => {
-        const startedMs = Date.now();
+        const startedMs = now();
         const target = interactionTarget(args[0]);
         // Named before the call, so everything the action causes can be traced
         // back to it even when the action itself ends in an exception.
@@ -245,7 +254,7 @@ export function attachTimelineObservers(options) {
             actionId,
             action: name,
             target,
-            durationMs: Date.now() - startedMs,
+            durationMs: now() - startedMs,
             ok: true,
           });
           return result;
@@ -254,7 +263,7 @@ export function attachTimelineObservers(options) {
             actionId,
             action: name,
             target,
-            durationMs: Date.now() - startedMs,
+            durationMs: now() - startedMs,
             ok: false,
             error: error.message,
           });

package/src/traces/recorder.js

@@ -110,6 +110,7 @@ export async function startTrace(options = {}) {
     commanderVersion = null,
     log = commander?.log,
     now = () => Date.now(),
+    monotonic,
   } = options;
 
   if (!page) {
@@ -150,6 +151,7 @@ export async function startTrace(options = {}) {
     limits,
     strict,
     now,
+    monotonic,
     onEvent: (event) => linksSink?.event(event),
   });
   const startedAt = new Date(now()).toISOString();
@@ -323,6 +325,7 @@ export async function startTrace(options = {}) {
     record,
     note,
     identity,
+    now,
   });
 
   // Registered before the first record, so a navigation that starts in the same