@monoes/monobrowse 1.0.16 → 1.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monobrowse",
-  "version": "1.0.16",
+  "version": "1.0.19",
   "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
   "type": "module",
   "bin": {

package/src/__tests__/browser-launch.test.ts

@@ -9,10 +9,13 @@
  * services; each test binds/tears down its own listeners.
  */
 
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
 import { createServer as createTcpServer, type Socket, type Server as TcpServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { launchBrowser } from '../browser/browser.js';
+import { getLaunchedPid, getLaunchedUserDataDir, launchBrowser } from '../browser/browser.js';
 
 const BASE = 23470;
 
@@ -111,3 +114,141 @@ describe('launchBrowser — port scan/attach decisions', () => {
     );
   }, 15000); // generous margin — 10 candidates, each a fast isTcpPortOpen check
 });
+
+// A stand-in for the Chrome binary: like real Chrome given
+// --remote-debugging-port=0, it binds a kernel-assigned port and only then
+// writes that port to <user-data-dir>/DevToolsActivePort.
+const FAKE_CHROME = `#!/usr/bin/env node
+const { createServer } = require('node:http');
+const { writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+const dir = process.argv.find((a) => a.startsWith('--user-data-dir=')).slice('--user-data-dir='.length);
+const server = createServer((req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(req.url === '/json/version' ? JSON.stringify({ Browser: 'Chrome/999.0.0.0' }) : '[]');
+});
+// Start slower than launchBrowser's first poll, so a stale file is read first.
+setTimeout(() => server.listen(0, '127.0.0.1', () => {
+  writeFileSync(join(dir, 'DevToolsActivePort'), server.address().port + '\\n/devtools/browser/fake');
+}), 600);
+`;
+
+describe.skipIf(process.platform === 'win32')(
+  'launchBrowser — port 0 (Chrome picks the port)',
+  () => {
+    it('returns the port its own Chrome reported, never another CDP endpoint', async () => {
+      const dir = mkdtempSync(join(tmpdir(), 'monobrowse-port0-'));
+      const exe = join(dir, 'fake-chrome.cjs');
+      writeFileSync(exe, FAKE_CHROME);
+      chmodSync(exe, 0o755);
+      const profile = join(dir, 'profile');
+      // A Chrome-looking endpoint that is NOT ours, named by a stale
+      // DevToolsActivePort left in the profile dir by an earlier run.
+      const foreign = BASE + 5;
+      const s = createHttpServer((req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(req.url === '/json/version' ? JSON.stringify({ Browser: 'Chrome/1.0' }) : '[]');
+      });
+      s.on('connection', (sock) => sockets.push(sock));
+      await new Promise<void>((resolve) => s.listen(foreign, '127.0.0.1', () => resolve()));
+      servers.push(s);
+      mkdirSync(profile);
+      writeFileSync(join(profile, 'DevToolsActivePort'), `${foreign}\n/devtools/browser/stale`);
+
+      let port: number | undefined;
+      try {
+        port = await launchBrowser({ port: 0, userDataDir: profile, executablePath: exe });
+        expect(port).not.toBe(foreign);
+        expect(port).toBeGreaterThan(0);
+        expect(getLaunchedPid(port)).toBeTypeOf('number');
+      } finally {
+        const pid = port === undefined ? undefined : getLaunchedPid(port);
+        if (pid) process.kill(pid, 'SIGKILL');
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it('refuses port 0 without a dedicated userDataDir', async () => {
+      await expect(launchBrowser({ port: 0 })).rejects.toThrow(/requires a dedicated userDataDir/);
+    });
+  },
+);
+
+// A stand-in for the Chrome binary that, unlike FAKE_CHROME above, actually
+// binds the FIXED port it is given via --remote-debugging-port (real Chrome,
+// launched with no --port flag, always resolves to the same literal default
+// port too — see cli/commands.ts's `port` option default). If the bind
+// fails (another process already has it), it exits the way real Chrome does
+// when a concurrent launch wins the same "free-looking" port: before its
+// CDP endpoint ever opens.
+const FAKE_CHROME_FIXED_PORT = `#!/usr/bin/env node
+const { createServer } = require('node:http');
+const { writeFileSync, mkdirSync } = require('node:fs');
+const { join } = require('node:path');
+const port = Number(
+  process.argv.find((a) => a.startsWith('--remote-debugging-port=')).slice('--remote-debugging-port='.length),
+);
+const dir = process.argv.find((a) => a.startsWith('--user-data-dir=')).slice('--user-data-dir='.length);
+const server = createServer((req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(req.url === '/json/version' ? JSON.stringify({ Browser: 'Chrome/999.0.0.0' }) : '[]');
+});
+server.on('error', () => {
+  process.exit(21);
+});
+server.listen(port, '127.0.0.1', () => {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'DevToolsActivePort'), port + '\\n/devtools/browser/fake');
+});
+`;
+
+describe.skipIf(process.platform === 'win32')(
+  'launchBrowser — concurrent launches with no explicit --port (TOCTOU race)',
+  () => {
+    it('two concurrent launches racing for the same default port both succeed, on different ports and profiles', async () => {
+      const dir = mkdtempSync(join(tmpdir(), 'monobrowse-concurrent-'));
+      const exe = join(dir, 'fake-chrome.cjs');
+      writeFileSync(exe, FAKE_CHROME_FIXED_PORT);
+      chmodSync(exe, 0o755);
+      // Both calls target the SAME literal port on purpose: that is exactly
+      // what two real `monomind browse open` invocations with no --port flag
+      // do, since the CLI's `port` option always defaults to the same value
+      // whether or not the user passed it (cli/commands.ts:288).
+      const port = BASE + 10;
+
+      let ports: number[] = [];
+      try {
+        ports = await Promise.all([
+          launchBrowser({ port, executablePath: exe, launchTimeoutMs: 5000 }),
+          launchBrowser({ port, executablePath: exe, launchTimeoutMs: 5000 }),
+        ]);
+      } finally {
+        for (const p of ports) {
+          const pid = getLaunchedPid(p);
+          if (pid) {
+            try {
+              process.kill(pid, 'SIGKILL');
+            } catch {
+              /* already gone */
+            }
+          }
+        }
+        rmSync(dir, { recursive: true, force: true });
+      }
+
+      expect(ports).toHaveLength(2);
+      // The old probe-then-launch race let both calls observe the same
+      // candidate as free and spawn Chrome on it — one bind wins, the
+      // other's Chrome exits before its CDP endpoint opens and the whole
+      // launchBrowser() call rejects. Both resolving at all is the
+      // regression check; landing on different ports (rather than one
+      // silently adopting the other's browser) proves the scan actually
+      // moved on instead of colliding.
+      expect(ports[0]).not.toBe(ports[1]);
+      const dirs = ports.map((p) => getLaunchedUserDataDir(p));
+      expect(dirs[0]).not.toBe(dirs[1]);
+      expect(dirs[0]).toBeTruthy();
+      expect(dirs[1]).toBeTruthy();
+    }, 15000);
+  },
+);

package/src/__tests__/report-exit-code.test.ts

@@ -0,0 +1,207 @@
+/**
+ * `monobrowse report` exited 0, and printed nothing at all, on a page that
+ * FAILED its budgets — while the report JSON it had already written on disk
+ * said `"verdict": "fail"`. Anything gating on exit status (CI, an agent, a
+ * shell `&&` chain) saw green on a broken page, which defeats the entire
+ * point of the budgets feature.
+ *
+ * Two things combined to cause it:
+ *
+ *   1. closeBrowser() could hang. Its timers were unref'd, so once Chrome's
+ *      CDP socket went away nothing was left holding the event loop open and
+ *      Node exited before those timers ever fired. (browser.ts; the poll-loop
+ *      half of this is #314's launch-close-settle.test.ts.)
+ *
+ *   2. commands-report.ts awaited that teardown in a `finally` positioned
+ *      BETWEEN producing the result and printing it. So a hung teardown took
+ *      the verdict down with it: the print never ran, `exitCode: 1` was never
+ *      returned, and Node drained the loop and exited 0.
+ *
+ * (1) alone is not enough to make this safe — any future teardown hang would
+ * silently reintroduce it. (2) is the ordering fix: print the verdict and fix
+ * process.exitCode BEFORE teardown, so a teardown that never settles can no
+ * longer turn a failing page green.
+ *
+ * WHY THIS IS A SUBPROCESS TEST. The bug only exists in the semantics of a
+ * real process exit — "the event loop drained while a promise was still
+ * pending, so Node exited with the code it had". An in-process test cannot
+ * observe that: vitest's own runner pins the event loop, so the hang simply
+ * becomes a pending promise and the exit code is never consulted. (#314's
+ * test says the same thing about fake timers.) So this spawns a real `node`
+ * and asserts the code the OS sees.
+ *
+ * WHY IT NEEDS NO CHROME. The suite is deliberately browser-free (see the
+ * monobrowse note in .github/workflows/tests.yml) and this keeps it that way.
+ * The child imports the REAL built commands-report.js, but next to stub
+ * `session.js` / `report/index.js` modules in a temp sandbox — commands-report
+ * has only those two static imports, and output.js has none, so copying three
+ * files reproduces its module graph exactly with no loader hooks and no
+ * Node-version-specific API. The stub's closeBrowser() is the hang, modelled
+ * as a promise that never settles — which is precisely what an unref'd timer
+ * on a dead socket degrades into.
+ *
+ * Requires `npm run build` (CI's monobrowse job builds before `npm test`).
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const distCli = join(here, '..', '..', 'dist', 'src', 'cli');
+const hasBuild = existsSync(join(distCli, 'commands-report.js'));
+
+let sandbox: string;
+
+beforeEach(async () => {
+  sandbox = await mkdtemp(join(tmpdir(), 'monobrowse-report-exit-'));
+});
+
+afterEach(async () => {
+  await rm(sandbox, { recursive: true, force: true });
+});
+
+/** Stub `cli/session.js`. `closeBrowser` is the failure under test. */
+function sessionStub(mode: 'hang' | 'clean'): string {
+  const close =
+    mode === 'hang'
+      ? // Never settles — a teardown that is wedged forever. An unref'd timer
+        // racing a dead socket degrades into exactly this.
+        'closeBrowser: () => new Promise(() => {}),'
+      : 'closeBrowser: async () => {},';
+  return `
+export const session = {
+  client: null, sessionId: '', targetId: '', port: 9222,
+  refs: new Map(), parentSessionId: '',
+};
+export async function ensureConnected(port) {
+  session.client = {}; session.sessionId = 'stub-session';
+  return { client: session.client, sessionId: session.sessionId };
+}
+export function print(line) { console.log(line); }
+export async function getBrowser() {
+  return {
+    // Non-undefined so the teardown branch actually runs (it is skipped for
+    // a browser this process did not launch).
+    getLaunchedPid: () => 4242,
+    stopRequestCapture: () => {},
+    teardownConsoleCapture: () => {},
+    ${close}
+    clearActivePort: async () => {},
+    clearRefCache: async () => {},
+  };
+}
+export function ensureSignalCleanupHandlers() {}
+`;
+}
+
+/** Stub `report/index.js` — a run that FAILED its budgets. */
+const reportStub = `
+const report = {
+  verdict: 'fail',
+  failures: [{ budget: 'maxConsoleErrors', expected: '<= 0', actual: 3, detail: 'boom' }],
+  notes: [],
+  trend: undefined,
+  diff: undefined,
+};
+export async function runReport() {
+  return {
+    report,
+    htmlPath: '/stub/r.html',
+    jsonPath: '/stub/r.json',
+    summary: '✗ FAIL — 1 budget failure(s)',
+    historyDir: undefined,
+    flake: undefined,
+  };
+}
+export const runReportRepeated = runReport;
+export async function readHistory() { return { dir: '/stub', runs: [] }; }
+export function toJsonReport(r) { return r; }
+`;
+
+/** Harness: mirrors cli.ts's real shape — `main().then(() => process.exit(...))`,
+ *  NOT a top-level await. That distinction is the whole bug: with a top-level
+ *  await Node notices the unsettled promise and exits 13, but cli.ts's promise
+ *  chain simply never runs its `.then`, so the loop drains and the process
+ *  exits with whatever process.exitCode holds — 0, unless someone set it. */
+const harness = `
+import { reportCommand } from './cli/commands-report.js';
+
+async function main() {
+  const result = await reportCommand.action({
+    args: ['http://127.0.0.1:1/broken.html'],
+    flags: { out: '/stub/r.html' },
+    cwd: process.cwd(),
+    interactive: false,
+  });
+  // Only reached when teardown settles. cli.ts does exactly this.
+  if (result && !result.success) process.exitCode = result.exitCode ?? 1;
+}
+
+main()
+  .then(() => { process.exit(process.exitCode ?? 0); })
+  .catch((err) => { console.error(err?.message ?? String(err)); process.exit(1); });
+`;
+
+async function runChild(mode: 'hang' | 'clean'): Promise<{
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}> {
+  await mkdir(join(sandbox, 'cli'), { recursive: true });
+  await mkdir(join(sandbox, 'report'), { recursive: true });
+  await cp(join(distCli, 'commands-report.js'), join(sandbox, 'cli', 'commands-report.js'));
+  await cp(join(distCli, 'output.js'), join(sandbox, 'cli', 'output.js'));
+  await writeFile(join(sandbox, 'cli', 'session.js'), sessionStub(mode), 'utf-8');
+  await writeFile(join(sandbox, 'report', 'index.js'), reportStub, 'utf-8');
+  await writeFile(join(sandbox, 'run.mjs'), harness, 'utf-8');
+
+  return await new Promise((resolve) => {
+    const child = spawn(process.execPath, [join(sandbox, 'run.mjs')], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: sandbox,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => (stdout += String(d)));
+    child.stderr.on('data', (d) => (stderr += String(d)));
+    // A hung teardown must still let the process EXIT (by draining), so if
+    // the child is genuinely still alive here the test should fail loudly
+    // rather than hang the suite.
+    const kill = setTimeout(() => child.kill('SIGKILL'), 15_000);
+    child.on('close', (code) => {
+      clearTimeout(kill);
+      resolve({ code, stdout, stderr });
+    });
+  });
+}
+
+describe.skipIf(!hasBuild)('report exit code survives a hung browser teardown', () => {
+  it('exits non-zero and prints the verdict even when closeBrowser never settles', async () => {
+    const { code, stdout, stderr } = await runChild('hang');
+
+    // THE BUG: this was 0 — a failing page reported as success, with the
+    // process exiting cleanly because the loop drained mid-teardown.
+    expect(code).toBe(1);
+    // ...and the verdict was never printed at all.
+    expect(stderr + stdout).toContain('FAIL');
+    expect(stdout).toContain('maxConsoleErrors');
+  }, 30_000);
+
+  it('still exits non-zero on the normal path where teardown completes', async () => {
+    const { code, stdout, stderr } = await runChild('clean');
+
+    expect(code).toBe(1);
+    expect(stderr + stdout).toContain('FAIL');
+  }, 30_000);
+});
+
+describe.skipIf(hasBuild)('report exit code subprocess test', () => {
+  it('is skipped because dist/ is not built (run `npm run build`)', () => {
+    expect(hasBuild).toBe(false);
+  });
+});

package/src/browser/actions.ts

@@ -680,18 +680,27 @@ export async function evaluateJs(
     sessionId,
   );
 
-  const result = await (timeoutMs > 0
-    ? Promise.race([
-        evalPromise,
-        new Promise<never>((_, reject) => {
-          const t = setTimeout(
-            () => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)),
-            timeoutMs,
-          );
-          t.unref?.();
-        }),
-      ])
-    : evalPromise);
+  // Not unref'd (same rule as CdpClient.send): this timer settles the awaited
+  // race, so it has to hold the event loop open while the evaluation is in
+  // flight. Cleared in the finally so a fast evaluation does not keep the
+  // process alive for the rest of timeoutMs.
+  let evalTimer: ReturnType<typeof setTimeout> | undefined;
+  let result: Awaited<typeof evalPromise>;
+  try {
+    result = await (timeoutMs > 0
+      ? Promise.race([
+          evalPromise,
+          new Promise<never>((_, reject) => {
+            evalTimer = setTimeout(
+              () => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)),
+              timeoutMs,
+            );
+          }),
+        ])
+      : evalPromise);
+  } finally {
+    clearTimeout(evalTimer);
+  }
 
   if (result.exceptionDetails) {
     throw new Error(

package/src/browser/bridge.ts

@@ -237,13 +237,16 @@ export class BridgeTransport implements CdpTransport {
     const envelope: BridgeEnvelope = { id, type, params };
     if (this.tabId) envelope.tabId = this.tabId;
     return new Promise<BridgeReply>((resolve, reject) => {
+      // Not unref'd (same rule as CdpClient.send): this timer settles a
+      // promise the caller awaits, so it must count toward keeping the event
+      // loop alive — otherwise a dead bridge socket lets Node exit 0 rather
+      // than surfacing the timeout. Cleared on every settle path below.
       let timer: ReturnType<typeof setTimeout> | undefined;
       if (timeoutMs > 0) {
         timer = setTimeout(() => {
           this.pending.delete(id);
           reject(new Error(`bridge ${type} timed out after ${timeoutMs}ms`));
         }, timeoutMs);
-        timer.unref?.();
       }
       this.pending.set(id, (reply) => {
         if (timer) clearTimeout(timer);