@monoes/monobrowse 1.0.25 → 1.0.27

package/package.json

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

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

@@ -5,12 +5,13 @@
  * launchBrowser would ever exec a browser binary, so these run fast and
  * don't depend on Chrome being installed in CI.
  *
- * Fixed port range (23470-23479) chosen to avoid colliding with real
- * services; each test binds/tears down its own listeners.
+ * Fixed port range (23460-23489) chosen to avoid colliding with real
+ * services and with reap-idle-browser.test.ts's 23490-23499, which runs in a
+ * parallel worker; each test binds/tears down its own listeners.
  */
 
 import { execFileSync } from 'node:child_process';
-import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, 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';
@@ -310,25 +311,33 @@ describe.skipIf(process.platform === 'win32')(
 // 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.
+// CDP endpoint ever opens. Like real Chrome on a fixed port, it writes no
+// DevToolsActivePort; it announces its browser websocket on stderr, with an
+// id unique to this process that /json/version reports too.
 const FAKE_CHROME_FIXED_PORT = `#!/usr/bin/env node
 ${FIXTURE_WATCHDOG}const { createServer } = require('node:http');
+const { randomUUID } = require('node:crypto');
 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 ws = 'ws://127.0.0.1:' + port + '/devtools/browser/' + randomUUID();
 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' }) : '[]');
+  res.end(
+    req.url === '/json/version'
+      ? JSON.stringify({ Browser: 'Chrome/999.0.0.0', webSocketDebuggerUrl: ws })
+      : '[]',
+  );
 });
 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');
+  process.stderr.write('\\nDevTools listening on ' + ws + '\\n');
 });
 `;
 
@@ -385,5 +394,68 @@ describe.skipIf(process.platform === 'win32')(
       expect(dirs[0]).toBeTruthy();
       expect(dirs[1]).toBeTruthy();
     }, 15000);
+
+    it('a launch whose Chrome is still booting does not adopt a concurrent launch that took the port', async () => {
+      // The loaded-machine shape of the race above, made deterministic: both
+      // launches probe the port as free, the "fast" Chrome binds it first,
+      // and the "slow" one is still starting when its poll finds a Chrome
+      // answering there. That Chrome is not the slow launch's own, so it
+      // must not be returned — nor may the slow launch record its own pid
+      // (about to exit on the lost bind) under the fast launch's port.
+      const dir = fixtureDir('monobrowse-adopt-');
+      const fast = join(dir, 'fast-chrome.cjs');
+      const slow = join(dir, 'slow-chrome.cjs');
+      writeFileSync(fast, fixedPortChrome(500));
+      writeFileSync(slow, fixedPortChrome(2500));
+      chmodSync(fast, 0o755);
+      chmodSync(slow, 0o755);
+      // Below BASE: this file's fixed ports, clear of the kernel's
+      // ephemeral range, where another test's listen(0) server can land on
+      // the candidate the slow launch scans on to.
+      const port = BASE - 10;
+
+      let results: PromiseSettledResult<number>[] = [];
+      try {
+        results = await Promise.allSettled([
+          launchBrowser({ port, executablePath: fast, launchTimeoutMs: 10_000 }),
+          launchBrowser({ port, executablePath: slow, launchTimeoutMs: 10_000 }),
+        ]);
+      } finally {
+        for (const r of results) {
+          const pid = r.status === 'fulfilled' ? getLaunchedPid(r.value) : undefined;
+          if (pid) {
+            try {
+              process.kill(pid, 'SIGKILL');
+            } catch {
+              /* already gone */
+            }
+          }
+        }
+      }
+
+      const [fastResult, slowResult] = results;
+      expect(fastResult).toEqual({ status: 'fulfilled', value: port });
+      if (slowResult.status === 'rejected') throw slowResult.reason;
+      expect(slowResult.value).not.toBe(port);
+      // The pid tracked for the port is the Chrome that actually serves it.
+      const fastDir = getLaunchedUserDataDir(port)!;
+      expect(fastDir).toBeTruthy();
+      expect(getLaunchedPid(port)).toBe(Number(readFileSync(join(fastDir, 'pid'), 'utf8')));
+    }, 20_000);
   },
 );
+
+/** FAKE_CHROME_FIXED_PORT that waits `delayMs` before binding, and records
+ *  its own pid in its profile dir. */
+function fixedPortChrome(delayMs: number): string {
+  return FAKE_CHROME_FIXED_PORT.replace(
+    'mkdirSync(dir, { recursive: true });',
+    `mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'pid'), String(process.pid));`,
+  )
+    .replace(
+      "server.listen(port, '127.0.0.1', () => {",
+      "setTimeout(() => server.listen(port, '127.0.0.1', () => {",
+    )
+    .replace(/\}\);\n$/, `}), ${delayMs});\n`);
+}

package/src/__tests__/launch-close-settle.test.ts

@@ -27,11 +27,18 @@
  *      manual repro. vi.useFakeTimers() (used throughout close-browser.test.ts)
  *      cannot catch this class of bug, because fake timers do not model real
  *      event-loop-drain semantics — hence a dedicated, real-timer test here.
+ *
+ * Ports come from the OS (listen on 0), never a fixed number (#351): these
+ * tests used 23495-23497, inside reap-idle-browser.test.ts's 23490-23499
+ * range, whose fake Chrome endpoints run in a parallel worker. A spawn that
+ * failed on 23495 while that file had 23495 bound looked like a lost launch
+ * race to launchBrowser, which moved on and reported port 23496 instead.
  */
 
 import { spawn } from 'node:child_process';
 import { chmodSync, writeFileSync } from 'node:fs';
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -88,6 +95,19 @@ afterEach(async () => {
   await rm(tempDir, { recursive: true, force: true });
 });
 
+/** A port nothing is listening on, picked by the kernel from its ephemeral
+ *  range — which the fixed-port fixtures of other test files stay below. */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address() as { port: number };
+      server.close(() => resolve(port));
+    });
+  });
+}
+
 async function writePersistedPort(port: number, pid: number, savedAt: number): Promise<void> {
   const dir = join(tempDir, '.monomind', 'monobrowse');
   await mkdir(dir, { recursive: true });
@@ -118,21 +138,22 @@ describe('#314: launchBrowser settles instead of hanging when Chrome fails to st
     // "file not found" that launchBrowser would reject before ever exec'ing.
     writeFileSync(fake, 'not an executable\n');
     chmodSync(fake, 0o644);
+    const port = await freePort();
 
     const start = Date.now();
     await expect(
-      launchBrowser({ executablePath: fake, port: 23495, launchTimeoutMs: 3000 }),
-    ).rejects.toThrow(/Chrome failed to start on port 23495/);
+      launchBrowser({ executablePath: fake, port, launchTimeoutMs: 10_000 }),
+    ).rejects.toThrow(`Chrome failed to start on port ${port}: `);
     // Without a child 'error' listener, this used to depend entirely on
     // whether something outside this function happened to intercept the
     // resulting uncaught exception (a bare node:test process has nothing
     // that does — see the module doc comment); where it happened not to
     // crash the process outright, the promise still only ever settled by
     // burning the full launchTimeoutMs. The fix rejects as soon as the
-    // spawn error fires, so this must land in well under a second, not
-    // ride the 3000ms timeout out.
-    expect(Date.now() - start).toBeLessThan(1000);
-  }, 8000);
+    // spawn error fires, so this must land well inside the 10s timeout
+    // rather than ride it out — with room for a loaded machine.
+    expect(Date.now() - start).toBeLessThan(5000);
+  }, 20_000);
 
   it('rejects with a clear message when Chrome exits immediately instead of opening its CDP port', async () => {
     vi.resetModules();
@@ -140,18 +161,19 @@ describe('#314: launchBrowser settles instead of hanging when Chrome fails to st
     const fake = join(tempDir, 'chrome.sh');
     writeFileSync(fake, '#!/bin/sh\nexit 1\n');
     chmodSync(fake, 0o755);
+    const port = await freePort();
 
     await expect(
-      launchBrowser({ executablePath: fake, port: 23496, launchTimeoutMs: 3000 }),
-    ).rejects.toThrow(/Chrome exited before the CDP endpoint opened on port 23496/);
-  }, 8000);
+      launchBrowser({ executablePath: fake, port, launchTimeoutMs: 10_000 }),
+    ).rejects.toThrow(`Chrome exited before the CDP endpoint opened on port ${port} `);
+  }, 20_000);
 });
 
 describe('#314: closeBrowser settles under the real event loop, not fake timers', () => {
   it('resolves promptly when nothing else is pinning the event loop', async () => {
     vi.resetModules();
     const { closeBrowser } = await import('../browser/browser.js');
-    const port = 23497;
+    const port = await freePort();
 
     // A real, short-lived child — not Chrome, just something with a genuine,
     // observable exit so process.kill(pid, 0) behaves for real and there is

package/src/browser/actions-eval.ts

@@ -0,0 +1,118 @@
+import type { CdpClient } from './cdp.js';
+
+export async function pushState(client: CdpClient, sessionId: string, url: string): Promise<void> {
+  // Try Next.js router first, then fallback to history.pushState
+  await evaluateJs(
+    client,
+    sessionId,
+    `
+    (function() {
+      const url = ${JSON.stringify(url)};
+      if (window.next && window.next.router) {
+        window.next.router.push(url).catch(function() {});
+        return;
+      } else {
+        history.pushState({}, '', url);
+        window.dispatchEvent(new PopStateEvent('popstate'));
+      }
+    })()
+  `,
+  );
+}
+
+export async function addInitScript(
+  client: CdpClient,
+  sessionId: string,
+  script: string,
+): Promise<string> {
+  const result = await client.send<{ identifier: string }>(
+    'Page.addScriptToEvaluateOnNewDocument',
+    {
+      source: script,
+    },
+    sessionId,
+  );
+  return result.identifier;
+}
+
+export async function removeInitScript(
+  client: CdpClient,
+  sessionId: string,
+  identifier: string,
+): Promise<void> {
+  await client.send('Page.removeScriptToEvaluateOnNewDocument', { identifier }, sessionId);
+}
+
+// Default cap on how long an evaluateJs() call waits for Runtime.evaluate to
+// resolve. Because this always passes `awaitPromise: true`, an expression
+// like `new Promise(() => {})` never settles — the underlying CdpClient.send()
+// has no timeout of its own (the CDP_RESPONSE_SIZE_LIMIT in cdp.ts only guards
+// the HTTP /json/* endpoints, not WebSocket command responses), so without
+// this the caller (e.g. the `eval` CLI command) would hang forever with
+// nothing to kill it.
+const DEFAULT_EVAL_TIMEOUT_MS = 30_000;
+
+export async function evaluateJs(
+  client: CdpClient,
+  sessionId: string,
+  expression: string,
+  timeoutMs: number = DEFAULT_EVAL_TIMEOUT_MS,
+): Promise<unknown> {
+  const evalPromise = client.send<{
+    result: { value?: unknown; type: string; description?: string };
+    exceptionDetails?: { text: string; exception?: { description?: string } };
+  }>(
+    'Runtime.evaluate',
+    {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+    },
+    sessionId,
+  );
+
+  // 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(
+      `JS evaluation error: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`,
+    );
+  }
+
+  return result.result?.value;
+}
+
+export async function readClipboard(client: CdpClient, sessionId: string): Promise<string> {
+  const result = await evaluateJs(client, sessionId, 'navigator.clipboard.readText()');
+  return result as string;
+}
+
+export async function writeClipboard(
+  client: CdpClient,
+  sessionId: string,
+  text: string,
+): Promise<void> {
+  // Cap to 100 KB to prevent OOM when serializing the CDP expression
+  const safeText = text.length > 102_400 ? text.slice(0, 102_400) : text;
+  await evaluateJs(client, sessionId, `navigator.clipboard.writeText(${JSON.stringify(safeText)})`);
+}

package/src/browser/actions-form.ts

@@ -0,0 +1,218 @@
+import { resolve } from 'node:path';
+import { pressKeyCombo, typeText } from './actions-keyboard.js';
+import { clickPoint } from './actions-mouse.js';
+import type { CdpClient } from './cdp.js';
+import { getElementBox, getObjectIdForRef } from './snapshot.js';
+import type { ClickOptions, ElementRef } from './types.js';
+
+export async function clickElement(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef,
+  options: ClickOptions = {},
+): Promise<void> {
+  const box = await getElementBox(client, sessionId, ref);
+
+  if (box) {
+    await clickPoint(client, sessionId, box.x, box.y, options);
+    return;
+  }
+
+  // Fallback: use JS click via objectId
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (objectId) {
+    await client.send(
+      'Runtime.callFunctionOn',
+      {
+        functionDeclaration: 'function() { this.click(); }',
+        objectId,
+        returnByValue: true,
+      },
+      sessionId,
+    );
+    return;
+  }
+
+  throw new Error(`Cannot click ref @${ref.ref}: element not found in DOM`);
+}
+
+export async function fillElement(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef,
+  value: string,
+): Promise<void> {
+  const box = await getElementBox(client, sessionId, ref);
+
+  if (box) {
+    // Click to focus
+    await clickPoint(client, sessionId, box.x, box.y);
+  }
+
+  // Select all and replace
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (objectId) {
+    const fillSelectResult = await client.send<{
+      result: unknown;
+      exceptionDetails?: { text: string; exception?: { description?: string } };
+    }>(
+      'Runtime.callFunctionOn',
+      {
+        functionDeclaration: `function() {
+        this.focus();
+        if (this.tagName === 'INPUT' || this.tagName === 'TEXTAREA') {
+          this.select();
+        } else if (this.isContentEditable) {
+          const range = document.createRange();
+          range.selectNodeContents(this);
+          const sel = window.getSelection();
+          if (sel) { sel.removeAllRanges(); sel.addRange(range); }
+        }
+      }`,
+        objectId,
+        returnByValue: true,
+      },
+      sessionId,
+    );
+    if (fillSelectResult.exceptionDetails) {
+      throw new Error(
+        `fillElement select-all failed: ${fillSelectResult.exceptionDetails.exception?.description ?? fillSelectResult.exceptionDetails.text}`,
+      );
+    }
+  } else if (box) {
+    // Fallback for elements without a resolvable objectId: keyboard select-all clears existing content
+    const mod = process.platform === 'darwin' ? 4 : 2;
+    await pressKeyCombo(client, sessionId, 'a', mod);
+  }
+
+  if (!objectId && !box) throw new Error(`Cannot fill ref @${ref.ref}: element not found in DOM`);
+
+  // Type the value character by character for natural input
+  await typeText(client, sessionId, value);
+}
+
+export async function selectOption(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef,
+  value: string,
+): Promise<void> {
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (!objectId) throw new Error(`Cannot select: ref @${ref.ref} not found in DOM`);
+
+  const selectResult = await client.send<{
+    result: unknown;
+    exceptionDetails?: { text: string; exception?: { description?: string } };
+  }>(
+    'Runtime.callFunctionOn',
+    {
+      functionDeclaration: `function(value) {
+      if (this.tagName !== 'SELECT') throw new Error('Not a select element');
+      for (const opt of this.options) {
+        if (opt.value === value || opt.textContent.trim() === value) {
+          this.value = opt.value;
+          this.dispatchEvent(new Event('change', { bubbles: true }));
+          return;
+        }
+      }
+      throw new Error('Option not found: ' + value);
+    }`,
+      objectId,
+      arguments: [{ value }],
+      returnByValue: true,
+    },
+    sessionId,
+  );
+  if (selectResult.exceptionDetails) {
+    throw new Error(
+      `selectOption failed: ${selectResult.exceptionDetails.exception?.description ?? selectResult.exceptionDetails.text}`,
+    );
+  }
+}
+
+export async function checkElement(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef,
+  checked = true,
+): Promise<void> {
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (!objectId) throw new Error(`Cannot check: ref @${ref.ref} not found in DOM`);
+
+  const checkResult = await client.send<{
+    result: unknown;
+    exceptionDetails?: { text: string; exception?: { description?: string } };
+  }>(
+    'Runtime.callFunctionOn',
+    {
+      functionDeclaration: `function(checked) {
+      if (this.checked !== checked) {
+        this.click();
+      }
+    }`,
+      objectId,
+      arguments: [{ value: checked }],
+      returnByValue: true,
+    },
+    sessionId,
+  );
+  if (checkResult.exceptionDetails) {
+    throw new Error(
+      `checkElement failed: ${checkResult.exceptionDetails.exception?.description ?? checkResult.exceptionDetails.text}`,
+    );
+  }
+}
+
+export async function focusElement(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef,
+): Promise<void> {
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (objectId) {
+    await client.send(
+      'Runtime.callFunctionOn',
+      {
+        functionDeclaration: 'function() { this.focus(); }',
+        objectId,
+        returnByValue: true,
+      },
+      sessionId,
+    );
+    return;
+  }
+  const box = await getElementBox(client, sessionId, ref);
+  if (box) {
+    await clickPoint(client, sessionId, box.x, box.y);
+  } else {
+    throw new Error(`Cannot focus ref @${ref.ref}: element not found in DOM`);
+  }
+}
+
+export async function typeIntoElement(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef,
+  text: string,
+): Promise<void> {
+  await focusElement(client, sessionId, ref);
+  await typeText(client, sessionId, text);
+}
+
+export async function uploadFile(
+  client: CdpClient,
+  sessionId: string,
+  ref: ElementRef,
+  filePaths: string[],
+): Promise<void> {
+  if (!ref.backendDOMNodeId) throw new Error(`Cannot upload: ref @${ref.ref} has no DOM node`);
+
+  await client.send(
+    'DOM.setFileInputFiles',
+    {
+      files: filePaths.map((f) => resolve(f)),
+      backendNodeId: ref.backendDOMNodeId,
+    },
+    sessionId,
+  );
+}