browser-commander 0.28.0 → 0.30.0

package/src/browser/persistent-session.js

@@ -5,6 +5,7 @@ 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';
@@ -108,8 +109,22 @@ 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
     ) {
@@ -119,9 +134,13 @@ async function open(options, file, endpoint) {
       ...options,
       cdpEndpoint: endpoint,
       targetId:
-        options.targetId ?? (!options.url ? metadata.targetId : undefined),
+        options.targetId ??
+        (!options.url && !options.urlMatchers?.length
+          ? metadata.targetId
+          : undefined),
+      fallback: !options.targetId,
     });
-    return { session, metadata, reused: true };
+    return { session, metadata, reused: true, adopted };
   }
   const session = await launchAndConnectRealBrowserWithDependencies(
     { ...options, keepOpen: false },
@@ -177,7 +196,7 @@ export async function closeOwnedSession(file, metadata) {
   await fs.rm(file, { force: true });
 }
 async function lifecycle(
-  { session, metadata, reused },
+  { session, metadata, reused, adopted },
   options,
   file,
   endpoint
@@ -212,11 +231,48 @@ async function lifecycle(
     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);
@@ -248,51 +304,65 @@ async function lifecycle(
     close,
     touch,
     reused,
+    adopted: Boolean(adopted),
     cdpEndpoint: endpoint,
     userDataDir: path.resolve(options.userDataDir),
     remoteDebuggingPort: options.remoteDebuggingPort,
     temporaryProfile: false,
   };
   result.reusePage = async (selection = {}) => {
-    if (disconnected) {
-      throw new Error('Persistent controller is detached');
-    }
-    const release = await acquireLease(`${file}.lock`);
+    selecting = true;
     try {
-      const current = await read(file);
-      if (current?.token !== metadata.token) {
-        throw new Error('Persistent session ownership changed');
+      if (disconnected) {
+        throw new Error('Persistent controller is detached');
       }
-      const pages =
-        engine === 'playwright'
-          ? page.context().pages()
-          : await session.browser.pages();
-      const selected = await pickForegroundPage(pages, {
-        targetId:
-          selection.targetId ??
-          (!selection.url ? metadata.targetId : undefined),
-        ...selection,
-      });
-      if (!selected) {
-        throw new Error('No reusable browser page');
+      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();
       }
-      unbind(page);
-      page = selected;
-      bind(page);
-      result.page = page;
-      await remember(page, engine, file, metadata, idleTimeoutMs);
+      return page;
     } finally {
-      await release();
+      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 page;
   };
-  if (!reused) {
-    await startDetachedProcess(process.execPath, [
-      fileURLToPath(new URL('./session-watchdog.js', import.meta.url)),
-      file,
-      metadata.token,
-    ]);
-  }
   return result;
 }
 export async function closeRemoteBrowser(endpoint) {
@@ -350,8 +420,10 @@ export async function connectOrLaunch(settings = {}) {
     owned = await open(options, file, endpoint);
     return await lifecycle(owned, options, file, endpoint);
   } catch (error) {
-    if (owned && !owned.reused) {
-      await owned.session.close().catch(() => {});
+    if (owned) {
+      await (
+        owned.reused ? owned.session.detach() : owned.session.close()
+      ).catch(() => {});
     }
     throw error;
   } finally {

package/src/browser/session-adoption.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { runCommand } from '../utilities/subprocess.js';
+
+/** Match both the dedicated profile and fixed port before adopting ownership. */
+export function matchesSessionProcess(args, options) {
+  if (
+    args.filter((arg) => arg.startsWith('--user-data-dir=')).length !== 1 ||
+    args.filter((arg) => arg.startsWith('--remote-debugging-port=')).length !==
+      1
+  ) {
+    return false;
+  }
+  const profile = args
+    .find((arg) => arg.startsWith('--user-data-dir='))
+    ?.slice(16);
+  const port = args
+    .find((arg) => arg.startsWith('--remote-debugging-port='))
+    ?.slice(24);
+  return (
+    /^(?:google[ -]chrome(?:[ -](?:for testing|stable|beta|unstable|canary|dev))?|chrome|chromium(?:-browser)?|brave(?: browser)?|microsoft edge|msedge)(?:\.exe)?$/i.test(
+      path.basename(args[0] ?? '')
+    ) &&
+    Boolean(profile) &&
+    path.resolve(profile) === path.resolve(options.userDataDir) &&
+    Number(port) === options.remoteDebuggingPort &&
+    !args.some((arg) => arg.startsWith('--type='))
+  );
+}
+export async function findSessionProcess(options) {
+  if (process.platform === 'linux') {
+    for (const name of await fs.readdir('/proc')) {
+      if (!/^\d+$/.test(name)) {
+        continue;
+      }
+      const args = await fs.readFile(`/proc/${name}/cmdline`, 'utf8').then(
+        (text) => text.split('\0'),
+        () => []
+      );
+      if (matchesSessionProcess(args, options)) {
+        return Number(name);
+      }
+    }
+  } else if (process.platform === 'darwin') {
+    const { stdout } = await runCommand('ps', ['-axo', 'pid=,command=']);
+    for (const line of stdout.split('\n')) {
+      const match = line.match(/^\s*(\d+)\s+(.+)$/);
+      if (!match) {
+        continue;
+      }
+      const args = processArguments(match[2]);
+      if (matchesSessionProcess(args, options)) {
+        return Number(match[1]);
+      }
+    }
+  } else if (process.platform === 'win32') {
+    const { stdout } = await runCommand('powershell.exe', [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      'Get-CimInstance Win32_Process | Where-Object { $_.Name -match "^(chrome|chromium|brave|msedge)\\.exe$" } | Select-Object ProcessId,ExecutablePath,CommandLine | ConvertTo-Json -Compress',
+    ]);
+    const records = JSON.parse(stdout || '[]');
+    for (const record of Array.isArray(records) ? records : [records]) {
+      const args = processArguments(record.CommandLine ?? '');
+      args[0] = record.ExecutablePath ?? args[0];
+      if (matchesSessionProcess(args, options)) {
+        return record.ProcessId;
+      }
+    }
+  }
+  throw new Error(
+    'Cannot verify the running browser profile and port for adoption'
+  );
+}
+
+/** Process listings omit argv boundaries; only accept unambiguous managed switches. */
+export function processArguments(command) {
+  if (
+    command.match(/--user-data-dir=/g)?.length !== 1 ||
+    command.match(/--remote-debugging-port=/g)?.length !== 1
+  ) {
+    return [];
+  }
+  const executable = command.match(/^"([^"\n]+)"|^(.*?)(?=\s--)/);
+  const profile = command.match(
+    /--user-data-dir=(?:"([^"\n]+)"|'([^'\n]+)'|(.+?))(?=\s--|$)/
+  );
+  const port = command.match(/--remote-debugging-port=(\d+)(?=\s|$)/);
+  return [
+    executable?.[1] ?? executable?.[2] ?? '',
+    `--user-data-dir=${profile?.[1] ?? profile?.[2] ?? profile?.[3] ?? ''}`,
+    `--remote-debugging-port=${port?.[1] ?? ''}`,
+    ...(command.includes('--type=') ? ['--type=child'] : []),
+  ];
+}

package/src/browser/session-worker.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { connectBrowser } from './connector.js';
 import {
   connectOrLaunch,
   SESSION_METADATA,
@@ -45,6 +46,15 @@ if (options.operation) {
           metadata.targetId = options.targetId;
         }
         await writeSessionMetadata(file, metadata);
+        if (options.closeNewTabs) {
+          const connection = await connectBrowser({
+            cdpEndpoint: `http://127.0.0.1:${metadata.remoteDebuggingPort}`,
+            targetId: metadata.targetId,
+            singleTab: true,
+            noDefaults: true,
+          });
+          await connection.detach();
+        }
       } else {
         throw new TypeError('Unknown session operation');
       }
@@ -65,6 +75,8 @@ if (options.operation) {
       reused: session.reused,
       token: metadata.token,
       targetId: metadata.targetId,
+      idleTimeoutMs: metadata.idleTimeoutMs,
+      adopted: session.adopted,
     })
   );
 }

package/src/cli/args.js

@@ -35,6 +35,9 @@ const BROWSER_OPTIONS = Object.freeze({
   bidi: FLAG,
   'remote-debugging-port': STRING,
   'idle-timeout-ms': STRING,
+  'adopt-existing': FLAG,
+  'close-new-tabs': FLAG,
+  'no-defaults': FLAG,
 });
 
 /** Options accepted by every page command. */

package/src/cli/commands.js

@@ -186,6 +186,9 @@ async function withPageSession(parsed, io, work, { skipUrl = false } = {}) {
             engine: options.engine,
             targetId: options.targetId,
             singleTab: options.singleTab,
+            ...(options.noDefaults !== undefined
+              ? { noDefaults: options.noDefaults }
+              : {}),
             ...(options.serverUrl ? { serverUrl: options.serverUrl } : {}),
             ...(options.driverPath ? { driverPath: options.driverPath } : {}),
             ...(options.bidi !== undefined ? { bidi: options.bidi } : {}),

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

@@ -54,6 +54,13 @@ async function connectSession(state, params) {
     ...endpoint,
     ...(params.targetId ? { targetId: params.targetId } : {}),
     ...(params.urlMatcher ? { url: params.urlMatcher } : {}),
+    ...(params.noDefaults !== undefined
+      ? { noDefaults: params.noDefaults }
+      : {}),
+    ...(params.urlMatchers !== undefined
+      ? { urlMatchers: params.urlMatchers }
+      : {}),
+    ...(params.fallback !== undefined ? { fallback: params.fallback } : {}),
     ...(params.singleTab !== undefined ? { singleTab: params.singleTab } : {}),
     ...(params.driverPath ? { driverPath: params.driverPath } : {}),
     ...(params.bidi !== undefined ? { bidi: params.bidi } : {}),

package/src/cli/sessions.js

@@ -47,6 +47,9 @@ const LAUNCH_PASSTHROUGH = Object.freeze([
   'disableFeatures',
   'keepOpen',
   'idleTimeoutMs',
+  'adoptExisting',
+  'closeNewTabs',
+  'noDefaults',
 ]);
 
 /** Validate an engine name, defaulting to Playwright. */

package/src/core/commander-features.js

@@ -1,4 +1,7 @@
 import { startTrace } from '../traces/recorder.js';
+import { debugEnabled, ensureDebugSession } from '../traces/debug-session.js';
+import { observeCommanderActions } from '../traces/commander-actions.js';
+import { TRACED_INTERACTIONS, interactionTarget } from '../traces/observers.js';
 import { touchSessionPage } from '../browser/persistent-session.js';
 import { dismissOverlays } from '../interactions/overlays.js';
 import {
@@ -15,7 +18,7 @@ const INTERACTIONS = new Set([
   'pressKey',
 ]);
 
-/** Bind capture, persistence and opt-in debugging to the commander lifecycle. */
+/** Bind capture, persistence and automatic debugging to the commander lifecycle. */
 export function attachCommanderFeatures(commander, options, recreate) {
   const { page, engine } = commander;
   const managed = new Set();
@@ -38,27 +41,18 @@ export function attachCommanderFeatures(commander, options, recreate) {
   commander.gif = (frames, animationOptions = {}) =>
     encodeAnimation(frames, { ...animationOptions, format: 'gif' });
   commander.dismissOverlays = (overlays = options.overlays) =>
-    dismissOverlays({ page, engine, overlays });
+    dismissOverlays({
+      page,
+      engine,
+      overlays,
+      onDismiss: options.onOverlayDismiss,
+    });
   commander.startTrace = async (traceOptions = {}) =>
     track(await startTrace({ commander, page, ...traceOptions }));
-  const output =
-    options.debug?.output ??
-    options.output ??
-    process.env.BROWSER_COMMANDER_TRACE;
-  let debug;
-  const ensureDebug = async () => {
-    if (!output || (!options.debug && !process.env.BROWSER_COMMANDER_TRACE)) {
-      return;
-    }
-    debug ??= commander.startTrace({
-      output,
-      mode: 'continuous',
-      network: { har: true },
-      links: { output: `${output}.links`, dom: 'text' },
-      checkpointOnNavigation: true,
-    });
-    await debug;
-  };
+  let debugSession;
+  let detachActions;
+  commander.tracePath = null;
+  const ensureDebug = () => commander.ready;
   for (const name of [...INTERACTIONS, 'goto', 'evaluate', 'count']) {
     const method = commander[name];
     if (!method) {
@@ -76,10 +70,10 @@ export function attachCommanderFeatures(commander, options, recreate) {
   const destroy = commander.destroy;
   commander.destroy = async () => {
     try {
-      if (debug) {
-        await debug;
-      }
+      await commander.ready;
+      await debugSession?.stop();
       await Promise.all([...managed].map((item) => item.stop()));
+      detachActions?.();
     } finally {
       await destroy();
     }
@@ -99,7 +93,21 @@ export function attachCommanderFeatures(commander, options, recreate) {
     touchSessionPage(selected);
     return selected;
   };
-  if (options.debug || process.env.BROWSER_COMMANDER_TRACE) {
-    commander.ready = ensureDebug();
+  if (debugEnabled({ ...options, page })) {
+    detachActions = observeCommanderActions({
+      commander,
+      page,
+      names: TRACED_INTERACTIONS,
+      targetOf: interactionTarget,
+    });
   }
+  commander.ready = ensureDebugSession({
+    ...options,
+    page,
+    engine,
+    commander,
+  }).then((session) => {
+    debugSession = session;
+    commander.tracePath = session?.path ?? null;
+  });
 }

package/src/core/navigation-safety.js

@@ -65,6 +65,7 @@ export function isNavigationError(error) {
   }
 
   const navigationErrorPatterns = [
+    'net::ERR_ABORTED',
     'Execution context was destroyed',
     'detached Frame',
     'Target closed',