browser-commander 0.31.1 → 0.32.0

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;
@@ -177,38 +236,121 @@ export class ManagedProcess {
     this.stdout = new OutputChannel();
     this.stderr = new OutputChannel();
     this.exitListeners = new Set();
-    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.termination = null;
+    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((result) => {
-        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) {
@@ -233,10 +375,57 @@ export class ManagedProcess {
    * @returns {boolean} Whether a running process was signalled
    */
   kill(signal) {
-    if (this.exitCode !== null) {
+    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.
+    const child = this.runner.child;
+    let resolveExit;
+    if (child?.pid) {
+      this.termination = new Promise((resolve) => {
+        resolveExit = resolve;
+      });
+    }
     this.runner.kill(signal);
+    if (resolveExit) {
+      if (child.exited) {
+        child.exited.then((code) =>
+          resolveExit({ code, signal: child.signalCode ?? null })
+        );
+      } else if (
+        Number.isInteger(child.exitCode) ||
+        typeof child.signalCode === 'string'
+      ) {
+        resolveExit({ code: child.exitCode, signal: child.signalCode });
+      } else {
+        child.once('exit', (code, exitSignal) =>
+          resolveExit({ code, signal: exitSignal })
+        );
+      }
+    }
+    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/e2e/selector-identity.e2e.test.js

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import { it } from 'node:test';
+import { makeBrowserCommander } from '../../src/factory.js';
+import { createEngineAdapter } from '../../src/core/engine-adapter.js';
+import { launchE2EBrowser } from '../helpers/e2e-browser.js';
+
+for (const engine of ['playwright', 'puppeteer', 'selenium']) {
+  it(
+    `${engine} keeps scoped text selectors on the intended element`,
+    { skip: process.env.RUN_E2E !== 'true', timeout: 60000 },
+    async () => {
+      const session = await launchE2EBrowser({ engine });
+      const commander = makeBrowserCommander({
+        page: session.page,
+        verbose: false,
+        debug: false,
+        enableNetworkTracking: false,
+        enableNavigationManager: false,
+      });
+      try {
+        await session.page.setContent(`
+          <nav><button>A</button><button data-qa='duplicate'
+            onclick="window.clicked='nav-2'">B</button></nav>
+          <div class="parent"><section><button>A</button>
+            <button data-qa='duplicate' data-target='B'
+              onclick="window.clicked='B'; this.setAttribute('aria-pressed','true')">B</button>
+            <textarea>Edit</textarea>
+          </section></div>`);
+        for (const exact of [false, true]) {
+          const selector = await commander.findByText({
+            selector: '.parent button',
+            text: 'B',
+            exact,
+          });
+          assert.equal(
+            await commander.getAttribute({
+              selector,
+              attribute: 'data-target',
+            }),
+            'B'
+          );
+          assert.equal(await commander.textContent({ selector }), 'B');
+          assert.equal(await commander.isVisible({ selector }), true);
+          assert.equal(await commander.isEnabled({ selector }), true);
+          await commander.clickButton({ selector, verify: false });
+          assert.equal(await session.page.evaluate(() => window.clicked), 'B');
+        }
+        const editable = await commander.findByText({
+          selector: '.parent textarea',
+          text: 'Edit',
+          exact: true,
+        });
+        await commander.fillTextArea({
+          selector: editable,
+          text: 'Changed',
+          checkEmpty: false,
+          simulateTyping: false,
+        });
+        assert.equal(
+          await session.page.evaluate(
+            () => document.querySelector('.parent textarea').value
+          ),
+          'Changed'
+        );
+      } finally {
+        await commander.destroy();
+        await session.cleanup();
+      }
+    }
+  );
+}
+
+it(
+  'Playwright preserves CSS sibling position across multiple parents',
+  { skip: process.env.RUN_E2E !== 'true', timeout: 60000 },
+  async () => {
+    const session = await launchE2EBrowser({ engine: 'playwright' });
+    const commander = makeBrowserCommander({
+      page: session.page,
+      debug: false,
+      enableNetworkTracking: false,
+      enableNavigationManager: false,
+    });
+    try {
+      await session.page.setContent(
+        '<section><span></span><button>A</button></section><section><button>B</button><button>C</button></section>'
+      );
+      const matches = await commander.querySelectorAll({
+        selector: 'section button:nth-of-type(2)',
+      });
+      assert.equal(matches.length, 1);
+      assert.equal(await matches[0].textContent(), 'C');
+      const adapter = createEngineAdapter(session.page, 'playwright');
+      const adapterMatches = await adapter.querySelectorAll(
+        'section button:nth-of-type(2)'
+      );
+      assert.equal(adapterMatches.length, 1);
+      assert.equal(await adapterMatches[0].textContent(), 'C');
+    } finally {
+      await commander.destroy();
+      await session.cleanup();
+    }
+  }
+);

package/tests/e2e/startup-readiness.e2e.test.js

@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import { it } from 'node:test';
+import { access, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { launchBrowser } from '../../src/browser/launcher.js';
+import { launchAndConnectRealBrowserWithDependencies } from '../../src/browser/real-browser.js';
+import { startProcess } from '../../src/utilities/subprocess.js';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+
+it(
+  'fresh-profile Chrome starts repeatedly with session persistence',
+  { skip: process.env.RUN_E2E !== 'true', timeout: 90000 },
+  async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), 'bc-startup-smoke-'));
+    try {
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const userDataDir = path.join(root, `profile-${attempt}`);
+        const session = await launchBrowser({
+          debug: false,
+          channel: 'chrome',
+          headless: true,
+          userDataDir,
+          persistSessionCookies: true,
+          ...CHROME_LAUNCH_OPTIONS,
+        });
+        try {
+          assert.equal(await session.page.evaluate(() => 2 + 2), 4);
+        } finally {
+          await session.close();
+        }
+        assert.notEqual(session.browserProcess.exitCode, null);
+        await access(userDataDir);
+      }
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+);
+
+it(
+  'failure after real DevTools readiness leaves another Chrome and caller profile intact',
+  { skip: process.env.RUN_E2E !== 'true', timeout: 90000 },
+  async () => {
+    const sibling = await launchBrowser({
+      debug: false,
+      headless: true,
+      ...CHROME_LAUNCH_OPTIONS,
+    });
+    const root = await mkdtemp(path.join(os.tmpdir(), 'bc-owned-startup-'));
+    const marker = path.join(root, 'keep.txt');
+    await writeFile(marker, 'caller profile');
+    try {
+      for (const suppliedProfile of [false, true]) {
+        let child, profile;
+        await assert.rejects(
+          () =>
+            launchAndConnectRealBrowserWithDependencies(
+              {
+                debug: false,
+                headless: true,
+                persistSessionCookies: suppliedProfile,
+                ...(suppliedProfile ? { userDataDir: root } : {}),
+                ...CHROME_LAUNCH_OPTIONS,
+              },
+              {
+                spawnBrowser: (file, args, options) => {
+                  profile = args
+                    .find((arg) => arg.startsWith('--user-data-dir='))
+                    .slice('--user-data-dir='.length);
+                  child = startProcess(file, args, { env: options.env });
+                  return child;
+                },
+                connect: async () => {
+                  throw new Error(
+                    'Injected attachment timeout after endpoint readiness'
+                  );
+                },
+              }
+            ),
+          /Injected attachment timeout/
+        );
+        assert.notEqual(child.exitCode, null);
+        assert.equal(await sibling.page.evaluate(() => 2 + 2), 4);
+        assert.equal(await readFile(marker, 'utf8'), 'caller profile');
+        if (!suppliedProfile) {
+          await assert.rejects(() => access(profile), /ENOENT/);
+        }
+      }
+    } finally {
+      await sibling.close();
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+);

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());
+      }),
+  };
+}