browser-commander 0.27.0 → 0.29.0

package/src/browser/launch-restrictions.json

@@ -17,7 +17,8 @@
         "--disable-session-crashed-bubble",
         "--hide-crash-restore-bubble",
         "--disable-crash-restore"
-      ]
+      ],
+      "disableFeatures": ["SessionRestoreInfobar"]
     },
     {
       "id": "no-infobars",
@@ -60,7 +61,12 @@
     {
       "id": "no-translate",
       "description": "Disable the Translate feature and its bubble.",
-      "disableFeatures": ["Translate"]
+      "disableFeatures": ["Translate"],
+      "preferences": {
+        "translate": {
+          "enabled": false
+        }
+      }
     },
     {
       "id": "no-component-update",
@@ -124,6 +130,24 @@
       "id": "start-maximized",
       "description": "Start with a maximized window.",
       "args": ["--start-maximized"]
+    },
+    {
+      "id": "no-save-bubbles",
+      "description": "Suppress password and payment-card saving bubbles and browser promos.",
+      "disableFeatures": [
+        "AutofillSaveCardUi",
+        "ChromeWhatsNewUI",
+        "PromotionalTabs"
+      ],
+      "preferences": {
+        "credentials_enable_service": false,
+        "profile": {
+          "password_manager_enabled": false
+        },
+        "autofill": {
+          "credit_card_enabled": false
+        }
+      }
     }
   ],
   "presets": {
@@ -142,6 +166,13 @@
       "no-default-browser-check",
       "no-google-services",
       "no-translate"
+    ],
+    "quiet-ui": [
+      "no-first-run",
+      "no-default-browser-check",
+      "no-crash-restore",
+      "no-translate",
+      "no-save-bubbles"
     ]
   }
 }

package/src/browser/launcher.js

@@ -7,6 +7,7 @@ import {
 
 import { assertSupportedEngine } from './connector.js';
 import { emulateMedia } from './media.js';
+import { reserveLoopbackPort } from './debugging-port.js';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
@@ -14,6 +15,7 @@ import {
 } from './launch-options.js';
 import {
   createTemporaryUserDataDir,
+  configureUserDataDir,
   removeUserDataDir,
 } from './profile-directory.js';
 import { launchRealBrowser } from './real-browser.js';
@@ -168,6 +170,7 @@ async function launchWithEngine(options, dependencies) {
     extraArgs,
     ignoreDefaultArgs,
     restrictions,
+    disableFeatures: options.disableFeatures,
   });
   const restrictionEnv = resolveRestrictions(restrictions).env;
   const childEnv =
@@ -177,6 +180,13 @@ async function launchWithEngine(options, dependencies) {
   const temporaryProfile = !requestedUserDataDir;
   const userDataDir =
     requestedUserDataDir ?? (await createTemporaryUserDataDir());
+  await configureUserDataDir(userDataDir, {
+    preferences: {
+      ...resolveRestrictions(restrictions).preferences,
+      ...options.preferences,
+    },
+    localState: options.localState,
+  });
   const engineModule = await (
     dependencies.loadEngineModule ?? loadEngine[engine]
   )();
@@ -307,6 +317,15 @@ export async function launchBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  if (options.keepOpen) {
+    const { connectOrLaunch } = await import('./persistent-session.js');
+    return connectOrLaunch({
+      ...options,
+      userDataDir: options.userDataDir ?? (await createTemporaryUserDataDir()),
+      remoteDebuggingPort:
+        options.remoteDebuggingPort ?? (await reserveLoopbackPort()),
+    });
+  }
   sessionPersistencePath(options);
   if (isSafariChannel(options.channel ?? options.browser)) {
     validateLaunchMode({
@@ -355,7 +374,13 @@ async function launchNonSafariBrowser(options, dependencies) {
     }
   }
   // Validate arguments before anything is started or written to disk.
-  resolveChromeArgs({ args, extraArgs, ignoreDefaultArgs, restrictions });
+  resolveChromeArgs({
+    args,
+    extraArgs,
+    ignoreDefaultArgs,
+    restrictions,
+    disableFeatures: options.disableFeatures,
+  });
   const resolvedStorageState = await loadStorageState(storageState);
 
   if (verbose) {

package/src/browser/persistent-session.js

@@ -0,0 +1,432 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { connectBrowser, pickForegroundPage } from './connector.js';
+import { launchAndConnectRealBrowserWithDependencies } from './real-browser.js';
+import { assertDedicatedUserDataDir } from './system-browser.js';
+import { findSessionProcess } from './session-adoption.js';
+import { startDetachedProcess } from '../utilities/subprocess.js';
+
+export const SESSION_METADATA = '.browser-commander-session.json';
+const activity = new WeakMap();
+export function touchSessionPage(page) {
+  activity.get(page)?.();
+}
+const read = (file) =>
+  fs
+    .readFile(file, 'utf8')
+    .then(JSON.parse)
+    .catch(() => null);
+export async function writeSessionMetadata(file, value) {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, JSON.stringify(value), { mode: 0o600 });
+    await fs.rename(temporary, file);
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+}
+export function probeSession(endpoint) {
+  return fetch(`${endpoint}/json/version`, {
+    signal: AbortSignal.timeout(1000),
+  })
+    .then((r) => (r.ok ? r.json() : null))
+    .catch(() => null);
+}
+export async function acquireLease(file, retries = 50) {
+  let lease;
+  try {
+    lease = await fs.open(file, 'wx', 0o600);
+  } catch (error) {
+    if (error.code !== 'EEXIST') {
+      throw error;
+    }
+    const owner = await read(file);
+    if (retries > 0) {
+      let alive = !owner?.pid;
+      if (owner?.pid) {
+        try {
+          process.kill(owner.pid, 0);
+          alive = true;
+        } catch (error) {
+          alive = error.code !== 'ESRCH';
+        }
+      }
+      if (alive) {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        return acquireLease(file, retries - 1);
+      }
+    }
+    if (!owner?.pid) {
+      throw new Error('Persistent session launch is already in progress', {
+        cause: error,
+      });
+    }
+    let alive = true;
+    try {
+      process.kill(owner.pid, 0);
+    } catch (error) {
+      alive = error.code !== 'ESRCH';
+    }
+    if (alive) {
+      throw new Error('Persistent session launch is already in progress', {
+        cause: error,
+      });
+    }
+    await fs.rm(file);
+    lease = await fs.open(file, 'wx', 0o600);
+  }
+  const token = randomUUID();
+  await lease.writeFile(JSON.stringify({ pid: process.pid, token }));
+  return async () => {
+    await lease.close();
+    if ((await read(file))?.token === token) {
+      await fs.rm(file, { force: true });
+    }
+  };
+}
+function validate(options) {
+  if (
+    !options.userDataDir ||
+    !Number.isInteger(options.remoteDebuggingPort) ||
+    options.remoteDebuggingPort < 1 ||
+    options.remoteDebuggingPort > 65535
+  ) {
+    throw new TypeError(
+      'connectOrLaunch requires a dedicated userDataDir and fixed remoteDebuggingPort'
+    );
+  }
+  if (!Number.isFinite(options.idleTimeoutMs) || options.idleTimeoutMs <= 0) {
+    throw new RangeError('idleTimeoutMs must be positive');
+  }
+  if (!['playwright', 'puppeteer'].includes(options.engine)) {
+    throw new TypeError('Persistent sessions require a Chromium CDP engine');
+  }
+  assertDedicatedUserDataDir(options.userDataDir);
+}
+async function open(options, file, endpoint) {
+  let metadata = await read(file);
+  const version = await probeSession(endpoint);
+  if (version) {
+    let adopted = false;
+    if (!metadata && options.adoptExisting) {
+      const pid = await findSessionProcess(options);
+      metadata = {
+        token: randomUUID(),
+        pid,
+        userDataDir: path.resolve(options.userDataDir),
+        remoteDebuggingPort: options.remoteDebuggingPort,
+        webSocketDebuggerUrl: version.webSocketDebuggerUrl,
+      };
+      adopted = true;
+    }
+    if (
+      !metadata ||
+      path.resolve(metadata.userDataDir ?? '') !==
+        path.resolve(options.userDataDir) ||
+      metadata.remoteDebuggingPort !== options.remoteDebuggingPort ||
+      metadata.webSocketDebuggerUrl !== version.webSocketDebuggerUrl
+    ) {
+      throw new Error('Debugging port belongs to another browser/profile');
+    }
+    const session = await connectBrowser({
+      ...options,
+      cdpEndpoint: endpoint,
+      targetId:
+        options.targetId ??
+        (!options.url && !options.urlMatchers?.length
+          ? metadata.targetId
+          : undefined),
+      fallback: !options.targetId,
+    });
+    return { session, metadata, reused: true, adopted };
+  }
+  const session = await launchAndConnectRealBrowserWithDependencies(
+    { ...options, keepOpen: false },
+    {
+      spawnBrowser: (file, args, settings) =>
+        startDetachedProcess(file, args, settings),
+    }
+  );
+  try {
+    const version = await probeSession(endpoint);
+    if (!version) {
+      throw new Error('Persistent browser endpoint disappeared after launch');
+    }
+    metadata = {
+      token: randomUUID(),
+      pid: session.browserProcess.pid,
+      userDataDir: path.resolve(options.userDataDir),
+      remoteDebuggingPort: options.remoteDebuggingPort,
+      webSocketDebuggerUrl: version.webSocketDebuggerUrl,
+    };
+    return { session, metadata, reused: false };
+  } catch (error) {
+    await session.close();
+    throw error;
+  }
+}
+async function remember(page, engine, file, metadata, idleTimeoutMs) {
+  const cdp =
+    engine === 'playwright'
+      ? await page.context().newCDPSession(page)
+      : await page.target().createCDPSession();
+  try {
+    metadata.targetId = (
+      await cdp.send('Target.getTargetInfo')
+    ).targetInfo.targetId;
+  } finally {
+    await cdp.detach();
+  }
+  metadata.lastActive = Date.now();
+  metadata.idleTimeoutMs = idleTimeoutMs;
+  await writeSessionMetadata(file, metadata);
+}
+export async function closeOwnedSession(file, metadata) {
+  if ((await read(file))?.token !== metadata.token) {
+    return;
+  }
+  const version = await probeSession(
+    `http://127.0.0.1:${metadata.remoteDebuggingPort}`
+  );
+  if (version?.webSocketDebuggerUrl === metadata.webSocketDebuggerUrl) {
+    await closeRemoteBrowser(version.webSocketDebuggerUrl);
+  }
+  await fs.rm(file, { force: true });
+}
+async function lifecycle(
+  { session, metadata, reused, adopted },
+  options,
+  file,
+  endpoint
+) {
+  const { engine, idleTimeoutMs } = options;
+  let page = session.page,
+    disconnected = false,
+    closed = false,
+    activityQueue = Promise.resolve();
+  const touch = () => {
+    activityQueue = activityQueue
+      .then(async () => {
+        const release = await acquireLease(`${file}.lock`);
+        try {
+          const current = await read(file);
+          if (current?.token === metadata.token) {
+            current.lastActive = Date.now();
+            await writeSessionMetadata(file, current);
+          }
+        } finally {
+          await release();
+        }
+      })
+      .catch(() => {});
+  };
+  const bind = (value) => {
+    activity.set(value, touch);
+    value.on?.('framenavigated', touch);
+  };
+  const unbind = (value) => {
+    activity.delete(value);
+    value.off?.('framenavigated', touch);
+  };
+  await remember(page, engine, file, metadata, idleTimeoutMs);
+  if (!reused || adopted) {
+    await startDetachedProcess(process.execPath, [
+      fileURLToPath(new URL('./session-watchdog.js', import.meta.url)),
+      file,
+      metadata.token,
+    ]);
+  }
+  bind(page);
+  const heartbeat = setInterval(
+    touch,
+    Math.max(20, Math.min(30_000, idleTimeoutMs / 3))
+  );
+  heartbeat.unref?.();
+  const tabSource = engine === 'playwright' ? page.context() : session.browser;
+  const tabTasks = new Set();
+  let selecting = false;
+  const closeNewTab = (value) => {
+    const task = Promise.resolve()
+      .then(async () => {
+        const candidate =
+          engine === 'playwright' ? value : await value.page?.();
+        if (candidate && candidate !== page && !disconnected && !selecting) {
+          await candidate.close();
+        }
+      })
+      .catch((error) =>
+        options.log?.debug?.(() => `session tab close: ${error.message}`)
+      );
+    tabTasks.add(task);
+    void task.finally(() => tabTasks.delete(task));
+  };
+  const tabEvent = engine === 'playwright' ? 'page' : 'targetcreated';
+  if (options.closeNewTabs) {
+    tabSource.on?.(tabEvent, closeNewTab);
+  }
+  const detach = async () => {
+    if (disconnected) {
+      return;
+    }
+    clearInterval(heartbeat);
+    tabSource.off?.(tabEvent, closeNewTab);
+    await Promise.allSettled([...tabTasks]);
+    touch();
+    await activityQueue;
+    unbind(page);
+    disconnected = true;
+    try {
+      await session.downloads?.dispose();
+    } finally {
+      await session.detach();
+    }
+  };
+  const close = async () => {
+    if (closed) {
+      return;
+    }
+    if (!disconnected) {
+      await detach().catch(() => {});
+    }
+    const release = await acquireLease(`${file}.lock`);
+    try {
+      await closeOwnedSession(file, metadata);
+    } finally {
+      await release();
+    }
+    closed = true;
+  };
+  const result = {
+    ...session,
+    detach,
+    close,
+    touch,
+    reused,
+    adopted: Boolean(adopted),
+    cdpEndpoint: endpoint,
+    userDataDir: path.resolve(options.userDataDir),
+    remoteDebuggingPort: options.remoteDebuggingPort,
+    temporaryProfile: false,
+  };
+  result.reusePage = async (selection = {}) => {
+    selecting = true;
+    try {
+      if (disconnected) {
+        throw new Error('Persistent controller is detached');
+      }
+      const release = await acquireLease(`${file}.lock`);
+      try {
+        const current = await read(file);
+        if (current?.token !== metadata.token) {
+          throw new Error('Persistent session ownership changed');
+        }
+        const pages =
+          engine === 'playwright'
+            ? page.context().pages()
+            : await session.browser.pages();
+        const selected =
+          (await pickForegroundPage(pages, {
+            targetId:
+              selection.targetId ??
+              (!selection.url && !selection.urlMatchers?.length
+                ? metadata.targetId
+                : undefined),
+            fallback: !selection.targetId,
+            ...selection,
+          })) ??
+          (engine === 'playwright'
+            ? await page.context().newPage()
+            : await session.browser.newPage());
+        unbind(page);
+        page = selected;
+        bind(page);
+        result.page = page;
+        await remember(page, engine, file, metadata, idleTimeoutMs);
+      } finally {
+        await release();
+      }
+      return page;
+    } finally {
+      selecting = false;
+      if (options.closeNewTabs && !disconnected) {
+        const pages =
+          engine === 'playwright'
+            ? page.context().pages()
+            : await session.browser.pages();
+        await Promise.allSettled(
+          pages
+            .filter((candidate) => candidate !== page)
+            .map((candidate) => candidate.close())
+        );
+      }
+    }
+  };
+  return result;
+}
+export async function closeRemoteBrowser(endpoint) {
+  await new Promise((resolve, reject) => {
+    const socket = new globalThis.WebSocket(endpoint);
+    let acknowledged = false;
+    const timer = setTimeout(() => {
+      socket.close();
+      reject(new Error('Browser.close timed out'));
+    }, 3000);
+    socket.onopen = () =>
+      socket.send(JSON.stringify({ id: 1, method: 'Browser.close' }));
+    socket.onclose = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    socket.onerror = () => {
+      // Chrome can close the TCP connection without a WebSocket close frame
+      // after acknowledging Browser.close. Its ensuing close event completes
+      // shutdown; a pre-acknowledgement connection error remains a failure.
+      if (!acknowledged) {
+        clearTimeout(timer);
+        reject(new Error('Browser.close connection failed'));
+      }
+    };
+    socket.onmessage = ({ data }) => {
+      const response = JSON.parse(data);
+      if (response.id !== 1) {
+        return;
+      }
+      if (response.error) {
+        clearTimeout(timer);
+        reject(new Error(response.error.message ?? 'Browser.close failed'));
+        socket.close();
+      } else {
+        acknowledged = true;
+      }
+    };
+  });
+}
+/** Reuse an owned profile/port; detach survives the controller; close terminates it. */
+export async function connectOrLaunch(settings = {}) {
+  const options = {
+    engine: 'playwright',
+    idleTimeoutMs: 30 * 60 * 1000,
+    ...settings,
+  };
+  validate(options);
+  await fs.mkdir(options.userDataDir, { recursive: true, mode: 0o700 });
+  const file = path.join(path.resolve(options.userDataDir), SESSION_METADATA);
+  const release = await acquireLease(`${file}.lock`);
+  const endpoint = `http://127.0.0.1:${options.remoteDebuggingPort}`;
+  let owned;
+  try {
+    owned = await open(options, file, endpoint);
+    return await lifecycle(owned, options, file, endpoint);
+  } catch (error) {
+    if (owned) {
+      await (
+        owned.reused ? owned.session.detach() : owned.session.close()
+      ).catch(() => {});
+    }
+    throw error;
+  } finally {
+    await release();
+  }
+}

package/src/browser/profile-directory.js

@@ -106,6 +106,26 @@ export async function configureUserDataDir(
 ) {
   assertObject(preferences, 'preferences');
   assertObject(localState, 'localState');
+  for (const key of [
+    'session.restore_on_startup',
+    'session.startup_urls',
+    'homepage',
+    'homepage_is_newtabpage',
+    'browser.show_home_button',
+    'extensions.settings',
+    'default_search_provider_data',
+  ]) {
+    let value = preferences;
+    for (const part of key.split('.')) {
+      value = value?.[part];
+    }
+    if (value !== undefined || Object.hasOwn(preferences, key)) {
+      process.emitWarning(
+        `Chrome protects ${key} in Secure Preferences and may reset this value. Use browser settings or managed policy to set it.`,
+        { code: 'PROTECTED_CHROME_PREFERENCE' }
+      );
+    }
+  }
   if (
     defaultBrowserCheck !== undefined &&
     typeof defaultBrowserCheck !== 'boolean'

package/src/browser/real-browser.js

@@ -103,6 +103,7 @@ export function buildRealBrowserArgs({
   remoteDebuggingPort,
   headless = false,
   restrictions = [],
+  disableFeatures = [],
   args = [],
   extraArgs = [],
   automationParity = true,
@@ -127,7 +128,7 @@ export function buildRealBrowserArgs({
     `--user-data-dir=${userDataDir}`,
     `--remote-debugging-port=${remoteDebuggingPort}`,
     ...(headless ? ['--headless=new'] : []),
-    ...resolveRestrictions(restrictions).args,
+    ...resolveRestrictions(restrictions, { disableFeatures }).args,
     ...customArgs,
   ]);
   if (
@@ -642,6 +643,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
   const argOptions = {
     headless,
     restrictions,
+    disableFeatures: options.disableFeatures,
     args,
     extraArgs,
     automationParity,
@@ -700,7 +702,10 @@ export async function launchAndConnectRealBrowserWithDependencies(
   await removingTemporaryProfileOnError(profile, () =>
     configureUserDataDir(userDataDir, {
       defaultBrowserCheck,
-      preferences,
+      preferences: {
+        ...resolveRestrictions(restrictions).preferences,
+        ...preferences,
+      },
       localState,
       profileDirectory: attach?.profile ?? 'Default',
     })

package/src/browser/restrictions.js

@@ -73,11 +73,14 @@ function expand(names) {
  * @param {string[]} [names]
  * @returns {{ids: string[], args: string[], env: Object<string,string>}}
  */
-export function resolveRestrictions(names = []) {
+export function resolveRestrictions(names = [], options = {}) {
   const ids = expand(names);
   const args = [];
-  const disableFeatures = [];
+  const disableFeatures = [
+    ...assertStringArray(options.disableFeatures ?? [], 'disableFeatures'),
+  ];
   const env = {};
+  const preferences = {};
   for (const id of ids) {
     const restriction = LAUNCH_RESTRICTIONS.find((entry) => entry.id === id);
     if (!restriction) {
@@ -91,11 +94,17 @@ export function resolveRestrictions(names = []) {
     args.push(...(restriction.args ?? []));
     disableFeatures.push(...(restriction.disableFeatures ?? []));
     Object.assign(env, restriction.env ?? {});
+    for (const [key, value] of Object.entries(restriction.preferences ?? {})) {
+      preferences[key] =
+        value && typeof value === 'object'
+          ? { ...preferences[key], ...value }
+          : value;
+    }
   }
   if (disableFeatures.length > 0) {
-    args.push(`--disable-features=${disableFeatures.join(',')}`);
+    args.push(`--disable-features=${[...new Set(disableFeatures)].join(',')}`);
   }
-  return { ids, args, env };
+  return { ids, args, env, preferences };
 }
 
 const LIST_SWITCHES = [