browser-commander 0.31.2 → 0.32.1

package/src/browser/real-browser.js

@@ -9,7 +9,9 @@ import { findBrowserSource } from './browser-sources.js';
 import { launchSafari } from './safari-launch.js';
 import { isSafariChannel } from './safari-support.js';
 
-import { startProcess } from '../utilities/subprocess.js';
+import { interruptionMode, startProcess } from '../utilities/subprocess.js';
+import { installHandoff } from './browser-handoff.js';
+import { closeRemoteBrowser } from './cdp-browser-endpoint.js';
 import { withDeadline } from '../traces/deadline.js';
 import {
   applyAutomationParityArgs,
@@ -256,8 +258,16 @@ export async function waitForCdpEndpoint({
   }
 }
 
-function spawnWithStartProcess(executablePath, args, { env, verbose }) {
-  return startProcess(executablePath, args, { env, forwardOutput: verbose });
+function spawnWithStartProcess(
+  executablePath,
+  args,
+  { env, verbose, interruption }
+) {
+  return startProcess(executablePath, args, {
+    env,
+    forwardOutput: verbose,
+    interruption,
+  });
 }
 
 async function waitForExit(browserProcess, timeout) {
@@ -310,12 +320,20 @@ function createCloser({
   closeTimeout,
   closeConnection,
   verbose,
+  handoffState = {},
 }) {
   const originalClose = closeConnection ?? browser?.close;
   let closing;
   const close = () => {
     closing ??= (async () => {
-      if (browserProcess.exitCode === null && originalClose) {
+      if (browserProcess.exitCode === null && handoffState.detached) {
+        // The engine connection was handed off; ask the browser directly.
+        await withDeadline(
+          closeRemoteBrowser(handoffState.webSocketDebuggerUrl),
+          closeTimeout,
+          'browser close'
+        ).catch(() => {});
+      } else if (browserProcess.exitCode === null && originalClose) {
         // A signal can sever the engine transport while its close RPC is pending.
         // Keep the existing close budget active until owned-process cleanup runs.
         await withDeadline(
@@ -348,6 +366,14 @@ function createCloser({
   return close;
 }
 
+/**
+ * Selenium attaches through a chromedriver the launch starts; the driver
+ * follows the browser's interruption ownership (issue #174).
+ */
+function driverInterruption(engine, interruption) {
+  return engine === 'selenium' ? { interruption } : {};
+}
+
 /**
  * Spawn a genuine installed Chrome-family browser with a dedicated profile,
  * wait for its loopback CDP endpoint, and attach through {@link connectBrowser}.
@@ -400,6 +426,7 @@ async function spawnOnFreePort({
   argOptions,
   env,
   verbose,
+  interruption,
   userDataDir,
   startupTimeout,
   dependencies,
@@ -421,6 +448,7 @@ async function spawnOnFreePort({
       browserProcess = await spawnBrowser(executablePath, browserArgs, {
         env,
         verbose: false,
+        interruption,
       });
     } catch (error) {
       throw launchFailure(error, {
@@ -650,8 +678,10 @@ export async function launchAndConnectRealBrowserWithDependencies(
     preferences,
     localState,
     firstRun,
+    interruption: requestedInterruption,
     ...connectionOptions
   } = options;
+  const interruption = interruptionMode(requestedInterruption);
   const argOptions = {
     headless,
     restrictions,
@@ -731,6 +761,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       argOptions,
       env: childEnv,
       verbose,
+      interruption,
       userDataDir,
       startupTimeout,
       dependencies,
@@ -756,9 +787,11 @@ export async function launchAndConnectRealBrowserWithDependencies(
       engine,
       cdpEndpoint: resolvedCdpEndpoint,
       ...connectionOptions,
+      ...driverInterruption(engine, interruption),
       seedCookies,
       verbose,
     });
+    const handoffState = { detached: false };
     const close = createCloser({
       engine,
       browser: connection.browser,
@@ -768,8 +801,9 @@ export async function launchAndConnectRealBrowserWithDependencies(
       closeTimeout,
       closeConnection: engine === 'selenium' ? connection.close : undefined,
       verbose,
+      handoffState,
     });
-    return await installSessionPersistence(
+    const session = await installSessionPersistence(
       {
         ...connection,
         close,
@@ -785,6 +819,23 @@ export async function launchAndConnectRealBrowserWithDependencies(
       },
       options
     );
+    return installHandoff(
+      session,
+      {
+        engine,
+        cdpEndpoint: resolvedCdpEndpoint,
+        userDataDir,
+        temporaryProfile,
+        remoteDebuggingPort: launched.port,
+        executablePath,
+        pid: () => browserProcess.pid,
+        connectedBrowser: () => connection.browser,
+        // The browser outlives this controller: no SIGINT forwarding, and
+        // its handle no longer keeps this program running.
+        release: () => browserProcess.detach?.(),
+      },
+      handoffState
+    );
   } catch (error) {
     if (browserProcess.exitCode === null) {
       browserProcess.kill();

package/src/browser/session-persistence.js

@@ -54,11 +54,15 @@ export async function installSessionPersistence(result, options) {
   const persistAndClose = () =>
     (closing ??= (async () => {
       try {
-        const state = await saveStorageState(result.page);
-        await writeRestrictedState(file, {
-          cookies: state.cookies.filter((cookie) => !(cookie.expires > 0)),
-          origins: [],
-        });
+        // A handed-off session no longer has an engine connection to save
+        // from; the controller that reconnects owns persistence.
+        if (!result.detached) {
+          const state = await saveStorageState(result.page);
+          await writeRestrictedState(file, {
+            cookies: state.cookies.filter((cookie) => !(cookie.expires > 0)),
+            origins: [],
+          });
+        }
       } finally {
         await close();
       }

package/src/browser/webdriver.js

@@ -30,6 +30,7 @@ import path from 'node:path';
 import { createWebDriverPage } from '../core/webdriver-page.js';
 import { isVerboseEnabled } from '../core/logger.js';
 import {
+  interruptionMode,
   runCommand as defaultRunCommand,
   startProcess as defaultStartProcess,
 } from '../utilities/subprocess.js';
@@ -483,6 +484,7 @@ async function teardown({
  * @param {Object<string,string>} [options.env] - Extra environment for the driver and browser
  * @param {number} [options.startupTimeout=30000]
  * @param {boolean} [options.verbose=false] - Mirror the driver server's output
+ * @param {'managed'|'caller'} [options.interruption='managed'] - Who handles Ctrl+C for the driver server and the browser under it; see `startProcess`
  * @param {Object} [dependencies] - Injected selenium modules, runCommand, startProcess, fetch, reservePort, environment, platform (tests)
  * @returns {Promise<{driver: Object, page: Object, close: function(): Promise<void>, serverUrl: string, driverProcess: Object, driverPath: string, driverSource: string, browser: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>, bidi: boolean}>}
  */
@@ -564,6 +566,7 @@ async function launchWebDriverOnce(options, dependencies) {
     startupTimeout = 30_000,
     verbose = false,
     debuggerAddress,
+    interruption,
   } = options;
   assertBrowser(browser);
   const safari = isSafariChannel(browser);
@@ -607,7 +610,11 @@ async function launchWebDriverOnce(options, dependencies) {
     driverProcess = startProcess(
       resolved.driverPath,
       buildDriverServerArgs(browser, port),
-      { env: childEnv, forwardOutput: verbose }
+      {
+        env: childEnv,
+        forwardOutput: verbose,
+        interruption: interruptionMode(interruption),
+      }
     );
     for (const stream of [driverProcess.stdout, driverProcess.stderr]) {
       stream?.on('data', (chunk) => {

package/src/exports.js

@@ -70,6 +70,12 @@ export {
   launchAndConnectRealBrowser,
   launchRealBrowser,
 } from './browser/real-browser.js';
+export {
+  BROWSER_HANDOFF_VERSION,
+  BrowserHandoffError,
+  reconnectBrowser,
+} from './browser/browser-handoff.js';
+export { INTERRUPTION_MODES } from './utilities/subprocess.js';
 export {
   classifyDifferences,
   compareCommandLines,

package/src/utilities/subprocess.js

@@ -1,3 +1,4 @@
+import { constants as osConstants } from 'node:os';
 import { ProcessRunner } from 'command-stream/process-runner';
 
 /** Start an explicitly persistent process, with no parent-owned pipes or signal forwarding. */
@@ -8,15 +9,7 @@ export async function startDetachedProcess(file, args = [], options = {}) {
     runner.child.once('spawn', resolve);
     runner.child.once('error', reject);
   });
-  const child = runner.child;
-  // command-stream starts noninteractive children in their own process
-  // group. Release its controller-owned cancellation registry while retaining
-  // the child's exit listeners. Keep this adapter isolated until it exposes a
-  // public detach operation; normal subprocesses retain managed cancellation.
-  runner._child = null;
-  runner._abortController = null;
-  runner.finished = true;
-  runner._cleanup();
+  const child = releaseRunner(runner);
   Promise.resolve(runner).catch(() => {});
   child.stderrTail = '';
   child.stderr?.on('data', (chunk) => {
@@ -25,11 +18,65 @@ export async function startDetachedProcess(file, args = [], options = {}) {
   child.on('error', (error) => {
     child.spawnError = error;
   });
-  child.unref();
+  unrefChild(child);
+  return child;
+}
+
+/**
+ * Release a started runner from command-stream's process-wide cancellation
+ * registry and return its raw child. command-stream 2.x has no public per-run
+ * opt-out: every runner joins a global set whose SIGINT handler forwards the
+ * signal to the child's process group. command-stream starts noninteractive
+ * children in their own process group, so once released nothing but the caller
+ * signals the child. Its exit listeners are retained.
+ */
+function releaseRunner(runner) {
+  const child = runner.child;
+  runner._child = null;
+  runner._abortController = null;
+  runner.finished = true;
+  runner._cleanup();
+  return child;
+}
+
+function unrefChild(child) {
+  child.unref?.();
   child.stdout?.unref?.();
   child.stderr?.unref?.();
   child.stdin?.unref?.();
-  return child;
+}
+
+/** Who answers a terminal interrupt (SIGINT) for a started process. */
+export const INTERRUPTION_MODES = Object.freeze(['managed', 'caller']);
+
+/** Validate an `interruption` option, returning the effective mode. */
+export function interruptionMode(value = 'managed') {
+  if (!INTERRUPTION_MODES.includes(value)) {
+    throw new TypeError(
+      `interruption must be one of ${INTERRUPTION_MODES.join(', ')}, got ${String(value)}`
+    );
+  }
+  return value;
+}
+
+function signalExitCode(signal) {
+  return 128 + (osConstants.signals[signal] ?? 1);
+}
+
+/** Signal a process and its process group, ignoring an already-gone one. */
+export function signalProcessTree(pid, signal) {
+  let delivered = false;
+  for (const target of process.platform === 'win32' ? [pid] : [-pid, pid]) {
+    try {
+      process.kill(target, signal);
+      delivered = true;
+    } catch (error) {
+      if (error.code !== 'ESRCH') {
+        throw error;
+      }
+    }
+  }
+  return delivered;
 }
 
 /**
@@ -128,18 +175,27 @@ export async function runCommand(file, args = [], options = {}) {
  * rely on (`pid`, `exitCode`, `kill()`, `stderr`/`stdout` `data` events and an
  * `exit` event), plus an `exited` promise.
  *
+ * By default (`interruption: 'managed'`) command-stream owns interruption: its
+ * process-wide SIGINT handler forwards Ctrl+C to the child's process group.
+ * With `interruption: 'caller'` the child is released from that registry right
+ * after it starts, so the embedding program's own SIGINT handler decides
+ * whether to stop, detach or keep the child (issue #174). Output streaming,
+ * `exited`, and `kill()` (which still awaits the actual exit) keep working.
+ *
  * @param {string} file - Executable path
  * @param {string[]} args - Exact arguments
  * @param {Object} [options]
  * @param {Object<string,string>} [options.env] - Environment for the child only
  * @param {boolean} [options.forwardOutput=false] - Mirror the child's output to this process
  * @param {number} [options.killGrace=2000] - Milliseconds between SIGTERM and SIGKILL
+ * @param {'managed'|'caller'} [options.interruption='managed'] - Who answers SIGINT
  * @returns {ManagedProcess}
  */
 export function startProcess(file, args = [], options = {}) {
   const { env, cwd, forwardOutput = false, killGrace = 2000 } = options;
+  const interruption = interruptionMode(options.interruption);
   const runner = runnerFor(file, args, { env, cwd, killGrace, capture: false });
-  return new ManagedProcess(runner, { forwardOutput });
+  return new ManagedProcess(runner, { forwardOutput, killGrace, interruption });
 }
 
 class OutputChannel {
@@ -168,7 +224,10 @@ class OutputChannel {
 
 /** Handle for a process started by {@link startProcess}. */
 export class ManagedProcess {
-  constructor(runner, { forwardOutput }) {
+  constructor(
+    runner,
+    { forwardOutput, killGrace = 2000, interruption = 'managed' }
+  ) {
     this.runner = runner;
     this.exitCode = null;
     this.signalCode = null;
@@ -178,46 +237,120 @@ export class ManagedProcess {
     this.stderr = new OutputChannel();
     this.exitListeners = new Set();
     this.termination = null;
-    runner.on('stdout', (chunk) => {
-      if (forwardOutput) {
-        process.stdout.write(chunk);
-      }
-      this.stdout.emit(chunk);
-    });
-    runner.on('stderr', (chunk) => {
-      this.stderrTail = (this.stderrTail + String(chunk)).slice(-8192);
-      if (forwardOutput) {
-        process.stderr.write(chunk);
-      }
-      this.stderr.emit(chunk);
+    this.killGrace = killGrace;
+    this.interruption = interruption;
+    this.detached = false;
+    this.child = null;
+    this.forwardOutput = forwardOutput;
+    runner.on('stdout', (chunk) => this.receiveStdout(chunk));
+    runner.on('stderr', (chunk) => this.receiveStderr(chunk));
+    let settle;
+    const settled = new Promise((resolve) => {
+      settle = resolve;
     });
+    this.settle = settle;
     runner.start();
-    this.exited = Promise.resolve(runner)
-      .catch((error) => {
-        this.spawnError = error;
-        return { code: error?.code ?? 1 };
-      })
-      .then(async (result) => {
-        const actualExit = await this.termination;
-        if (actualExit) {
-          result = {
-            ...result,
-            code: actualExit.code ?? result.code,
-            signal: actualExit.signal,
-          };
-        }
-        this.exitCode = typeof result.code === 'number' ? result.code : 1;
-        this.signalCode = result.signal ?? null;
-        for (const listener of this.exitListeners) {
-          listener(this.exitCode);
+    Promise.resolve(runner).then(
+      (result) => {
+        // A released runner resolves without a result; its raw child reports.
+        if (!this.child) {
+          settle(result);
         }
-        return this.exitCode;
+      },
+      (error) => {
+        this.spawnError = error;
+        settle({ code: error?.code ?? 1 });
+      }
+    );
+    this.exited = settled.then(async (result) => {
+      const actualExit = await this.termination;
+      if (actualExit) {
+        result = {
+          ...result,
+          code: actualExit.code ?? result.code,
+          signal: actualExit.signal,
+        };
+      }
+      this.exitCode = typeof result.code === 'number' ? result.code : 1;
+      this.signalCode = result.signal ?? null;
+      for (const listener of this.exitListeners) {
+        listener(this.exitCode);
+      }
+      return this.exitCode;
+    });
+    if (interruption === 'caller') {
+      this.release();
+    }
+  }
+
+  receiveStdout(chunk) {
+    if (this.forwardOutput) {
+      process.stdout.write(chunk);
+    }
+    this.stdout.emit(chunk);
+  }
+
+  receiveStderr(chunk) {
+    this.stderrTail = (this.stderrTail + String(chunk)).slice(-8192);
+    if (this.forwardOutput) {
+      process.stderr.write(chunk);
+    }
+    this.stderr.emit(chunk);
+  }
+
+  /**
+   * Take the child out of command-stream's SIGINT forwarding while this handle
+   * keeps observing its output and exit.
+   */
+  release() {
+    if (this.exitCode !== null || this.termination) {
+      return false;
+    }
+    if (this.child) {
+      return true;
+    }
+    const child = this.runner.child;
+    if (!child?.pid) {
+      return false;
+    }
+    releaseRunner(this.runner);
+    this.child = child;
+    this.interruption = 'caller';
+    child.stdout?.on('data', (chunk) => this.receiveStdout(chunk));
+    child.stderr?.on('data', (chunk) => this.receiveStderr(chunk));
+    const report = (code, signal) =>
+      this.settle({
+        code: Number.isInteger(code) ? code : signalExitCode(signal),
+        signal: signal ?? null,
       });
+    if (Number.isInteger(child.exitCode) || child.signalCode) {
+      report(child.exitCode, child.signalCode);
+    } else {
+      child.once('exit', report);
+    }
+    return true;
+  }
+
+  /**
+   * Leave the process running independently of this program: release it from
+   * command-stream's SIGINT forwarding and stop its handle and pipes from
+   * keeping the event loop alive. Exit observation keeps working while this
+   * program runs, and {@link kill} still stops it. Idempotent.
+   *
+   * @returns {boolean} Whether a running process is now detached
+   */
+  detach() {
+    if (!this.release()) {
+      return false;
+    }
+    this.detached = true;
+    unrefChild(this.child);
+    return true;
   }
 
   /** Operating system process id, once spawned. */
   get pid() {
-    return this.runner.pid;
+    return this.child?.pid ?? this.runner.pid;
   }
 
   on(event, listener) {
@@ -245,6 +378,9 @@ export class ManagedProcess {
     if (this.exitCode !== null || this.termination) {
       return false;
     }
+    if (this.child) {
+      return this.killReleased(signal ?? 'SIGTERM');
+    }
     // command-stream resolves cancellation immediately and removes the child's
     // listeners. Retain its handle and observe the real exit after signalling,
     // so launchers cannot delete profiles while Chrome still writes to them.
@@ -274,4 +410,22 @@ export class ManagedProcess {
     }
     return true;
   }
+
+  /** Stop a released child directly; command-stream no longer tracks it. */
+  killReleased(signal) {
+    const { child } = this;
+    if (!signalProcessTree(child.pid, signal)) {
+      return false;
+    }
+    if (signal !== 'SIGKILL') {
+      const escalation = setTimeout(() => {
+        if (this.exitCode === null) {
+          signalProcessTree(child.pid, 'SIGKILL');
+        }
+      }, this.killGrace);
+      escalation.unref?.();
+      this.exited.then(() => clearTimeout(escalation));
+    }
+    return true;
+  }
 }

package/tests/e2e/browser-handoff.e2e.test.js

@@ -0,0 +1,94 @@
+/**
+ * Issue #174: an embedding supervisor owns Ctrl+C for the browser it launched,
+ * hands the exact browser and tab to its next run, and that run closes it.
+ */
+// feature-parity: process.interruption@native-typed sessions.handoff@native-typed
+import assert from 'node:assert/strict';
+import { readFile, mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import {
+  reconnectBrowser,
+  waitForPidExit,
+} from '../../src/browser/browser-handoff.js';
+import { startProcess } from '../../src/utilities/subprocess.js';
+import { repoPath } from '../helpers/repo.js';
+
+const SUPERVISOR = repoPath(
+  'experiments',
+  'issue-174',
+  'browser-supervisor.mjs'
+);
+
+/** Run the supervisor, which interrupts itself after opening a page. */
+async function interruptSupervisor(mode, engine) {
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'bc-e2e-174-'));
+  const handoffFile = path.join(directory, 'handoff.json');
+  try {
+    const supervisor = startProcess(process.execPath, [
+      SUPERVISOR,
+      mode,
+      engine,
+      handoffFile,
+    ]);
+    const exitCode = await supervisor.exited;
+    const pid = Number(await readFile(`${handoffFile}.pid`, 'utf8'));
+    const handoff = await readFile(handoffFile, 'utf8').catch(() => null);
+    return { exitCode, pid, handoff, stderr: supervisor.stderrTail };
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+describe(
+  'browser hand-off across an embedding supervisor (issue #174)',
+  {
+    skip:
+      (!process.env.RUN_E2E && 'set RUN_E2E=true') ||
+      (process.platform === 'win32' && 'SIGINT forwarding is Unix-only'),
+    timeout: 120000,
+  },
+  () => {
+    it('by default Ctrl+C reaches Chrome before the embedder can keep it', async () => {
+      const { exitCode, pid, handoff } = await interruptSupervisor(
+        'managed',
+        'playwright'
+      );
+      assert.equal(exitCode, 130);
+      assert.equal(handoff, null);
+      assert.equal(await waitForPidExit(pid, 10000), true);
+    });
+
+    for (const engine of ['playwright', 'puppeteer', 'selenium']) {
+      it(`${engine}: keeps the exact tab across Ctrl+C and closes it later`, async () => {
+        const { exitCode, pid, handoff, stderr } = await interruptSupervisor(
+          'caller',
+          engine
+        );
+        assert.equal(exitCode, 130, stderr);
+        assert.ok(handoff, stderr);
+        const descriptor = JSON.parse(handoff);
+        assert.equal(descriptor.pid, pid);
+        try {
+          assert.equal(await waitForPidExit(pid, 500), false);
+          const session = await reconnectBrowser(handoff);
+          const title =
+            engine === 'selenium'
+              ? await session.browser.getTitle()
+              : await session.page.title();
+          assert.equal(title, 'waiting for a human');
+          await session.close();
+          assert.equal(await waitForPidExit(pid, 1000), true);
+          await assert.rejects(readFile(descriptor.userDataDir), {
+            code: 'ENOENT',
+          });
+        } finally {
+          if (!(await waitForPidExit(pid, 0))) {
+            process.kill(-pid, 'SIGKILL');
+          }
+        }
+      });
+    }
+  }
+);

package/tests/helpers/fake-cdp-endpoint.js

@@ -0,0 +1,64 @@
+/**
+ * A fake DevTools HTTP endpoint for hand-off tests (issue #174): it answers
+ * `/json/version` with a browser WebSocket URL and accepts `Browser.close`
+ * on that WebSocket, so detach/reconnect/close run without a browser.
+ */
+import http from 'node:http';
+import { acceptUpgrade } from '../../src/browser/attach/websocket.js';
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.browserId='browser-1'] - Identity in webSocketDebuggerUrl
+ * @param {Function} [options.onBrowserClose] - Called when Browser.close arrives
+ * @returns {Promise<Object>} `{ endpoint, webSocketDebuggerUrl, closes, setBrowserId, close }`
+ */
+export async function startFakeCdpEndpoint({
+  browserId = 'browser-1',
+  onBrowserClose = () => {},
+} = {}) {
+  const closes = [];
+  let currentId = browserId;
+  const server = http.createServer((request, response) => {
+    if (request.url !== '/json/version') {
+      response.writeHead(404).end();
+      return;
+    }
+    response.setHeader('content-type', 'application/json');
+    response.end(
+      JSON.stringify({
+        Browser: 'FakeChrome/1.0',
+        webSocketDebuggerUrl: `ws://127.0.0.1:${port}/devtools/browser/${currentId}`,
+      })
+    );
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+  server.on('upgrade', (request, socket, head) => {
+    const connection = acceptUpgrade(request, socket, head);
+    connection?.on('message', (text) => {
+      const message = JSON.parse(text);
+      if (message.method === 'Browser.close') {
+        closes.push(request.url);
+        connection.send(JSON.stringify({ id: message.id, result: {} }));
+        onBrowserClose();
+        socket.end();
+      }
+    });
+  });
+  return {
+    endpoint: `http://127.0.0.1:${port}`,
+    get webSocketDebuggerUrl() {
+      return `ws://127.0.0.1:${port}/devtools/browser/${currentId}`;
+    },
+    closes,
+    /** Pretend another browser now listens on the same port. */
+    setBrowserId: (id) => {
+      currentId = id;
+    },
+    close: () =>
+      new Promise((resolve) => {
+        server.closeAllConnections?.();
+        server.close(() => resolve());
+      }),
+  };
+}