@monoes/monobrowse 1.0.11 → 1.0.13

package/src/__tests__/open-url-navigate-error.test.ts

@@ -7,8 +7,8 @@
  * this checks that response before doing anything else.
  */
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import type { CdpClient } from '../browser/cdp.js';
 import { openUrl } from '../browser/browser.js';
+import type { CdpClient } from '../browser/cdp.js';
 
 afterEach(() => {
   vi.restoreAllMocks();
@@ -43,9 +43,7 @@ describe('openUrl navigation-failure detection', () => {
     await expect(openUrl(client, 'sess-1', 'http://127.0.0.1:1/')).rejects.toThrow(
       /net::ERR_CONNECTION_REFUSED/,
     );
-    expect(calls).toEqual([
-      { method: 'Page.navigate', params: { url: 'http://127.0.0.1:1/' } },
-    ]);
+    expect(calls).toEqual([{ method: 'Page.navigate', params: { url: 'http://127.0.0.1:1/' } }]);
   });
 
   it('rejects the 2 MB URL guard before ever calling Page.navigate', async () => {

package/src/__tests__/output.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 // The module exports a singleton `output` which reads process.stdout.isTTY at
 // construction time. We need to control that, so we reset modules per test.

package/src/__tests__/profiler-heap.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Regression cover for the 0-byte heap snapshot.
+ *
+ * Chrome emits `HeapProfiler.reportHeapSnapshotProgress` with finished:true
+ * BEFORE it streams a single `addHeapSnapshotChunk` (verified against Chrome
+ * 153). startHeapSnapshot used to resolve on that progress event, detach its
+ * chunk listener and write an empty file every time. The stub below replays
+ * that exact ordering, so a regression fails here rather than in a profiling
+ * session nobody notices until DevTools refuses to load the snapshot.
+ */
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { CdpClient } from '../browser/cdp.js';
+import { startHeapSnapshot } from '../browser/profiler.js';
+
+type Listener = (params: Record<string, unknown>, sessionId?: string) => void;
+
+interface StubOptions {
+  /** Chunks Chrome streams, in order. */
+  chunks?: string[];
+  /** sessionId Chrome tags the chunk events with (defaults to the caller's). */
+  chunkSessionId?: string;
+  /** Emit the misleading finished:true progress event before the chunks. */
+  emitProgressFirst?: boolean;
+}
+
+/**
+ * A CdpClient that replays Chrome's real takeHeapSnapshot sequence: progress
+ * events first, then the chunks, and only then the command response.
+ */
+function heapClient(sessionId: string, options: StubOptions = {}) {
+  const { chunks = ['{"snapshot":', '{"node_count":2}', '}'], emitProgressFirst = true } = options;
+  const listeners = new Map<string, Set<Listener>>();
+  const calls: string[] = [];
+
+  const emit = (event: string, params: Record<string, unknown>, sid?: string) => {
+    for (const fn of listeners.get(event) ?? []) fn(params, sid);
+  };
+
+  // Chrome delivers each of these in its own WebSocket frame, so the stub
+  // yields between them. Emitting synchronously would paper over the very
+  // bug this file exists to catch: the buggy implementation resolved on the
+  // progress event, and only lost the chunks because they arrived a turn
+  // later, after its `finally` had detached the listener.
+  const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+
+  const client = {
+    on: vi.fn((event: string, fn: Listener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(fn);
+      return () => listeners.get(event)?.delete(fn);
+    }),
+    send: vi.fn(async (method: string, _params?: unknown, _sid?: string) => {
+      calls.push(method);
+      if (method === 'HeapProfiler.takeHeapSnapshot') {
+        if (emitProgressFirst) {
+          emit(
+            'HeapProfiler.reportHeapSnapshotProgress',
+            { done: 1, total: 1, finished: true },
+            sessionId,
+          );
+          await tick();
+        }
+        for (const chunk of chunks) {
+          emit('HeapProfiler.addHeapSnapshotChunk', { chunk }, options.chunkSessionId ?? sessionId);
+          await tick();
+        }
+      }
+      return {};
+    }),
+  } as unknown as CdpClient;
+
+  return { client, calls, listeners };
+}
+
+const dirs: string[] = [];
+async function outPath(name = 'heap.heapsnapshot'): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'monobrowse-heap-'));
+  dirs.push(dir);
+  return join(dir, name);
+}
+
+afterEach(async () => {
+  await Promise.all(dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })));
+});
+
+let seq = 0;
+const nextSession = () => `sid-${++seq}`;
+
+describe('startHeapSnapshot', () => {
+  it('writes every streamed chunk, not an empty file', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid);
+
+    const written = await startHeapSnapshot(client, sid, path);
+
+    expect(written).toBe(path);
+    const contents = await readFile(path, 'utf8');
+    expect(contents).toBe('{"snapshot":{"node_count":2}}');
+    expect(contents.length).toBeGreaterThan(0);
+  });
+
+  it('does not resolve on the finished progress event that precedes the chunks', async () => {
+    // The regression: with emitProgressFirst the old implementation resolved
+    // before any chunk arrived. Ordering is the whole point of this case.
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid, {
+      emitProgressFirst: true,
+      chunks: ['a'.repeat(64), 'b'.repeat(64)],
+    });
+
+    await startHeapSnapshot(client, sid, path);
+
+    expect((await readFile(path, 'utf8')).length).toBe(128);
+  });
+
+  it('works when Chrome sends no progress events at all', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid, { emitProgressFirst: false, chunks: ['{}'] });
+    await expect(startHeapSnapshot(client, sid, path)).resolves.toBe(path);
+    await expect(readFile(path, 'utf8')).resolves.toBe('{}');
+  });
+
+  it('asks Chrome not to report progress, since nothing consumes it', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid);
+    await startHeapSnapshot(client, sid, path);
+    const take = (client.send as ReturnType<typeof vi.fn>).mock.calls.find(
+      (c) => c[0] === 'HeapProfiler.takeHeapSnapshot',
+    );
+    expect(take?.[1]).toEqual({ reportProgress: false });
+  });
+
+  it('enables and disables the heap profiler around the capture', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client, calls } = heapClient(sid);
+    await startHeapSnapshot(client, sid, path);
+    expect(calls).toEqual([
+      'HeapProfiler.enable',
+      'HeapProfiler.takeHeapSnapshot',
+      'HeapProfiler.disable',
+    ]);
+  });
+
+  it('ignores chunks belonging to another session', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid, { chunkSessionId: 'other-session' });
+    await expect(startHeapSnapshot(client, sid, path)).rejects.toThrow(/no data/i);
+  });
+
+  it('fails loudly instead of writing a 0-byte snapshot', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid, { chunks: [] });
+    await expect(startHeapSnapshot(client, sid, path)).rejects.toThrow(/produced no data/);
+    await expect(readFile(path, 'utf8')).rejects.toThrow();
+  });
+
+  it('detaches its chunk listener once the snapshot is done', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client, listeners } = heapClient(sid);
+    await startHeapSnapshot(client, sid, path);
+    expect(listeners.get('HeapProfiler.addHeapSnapshotChunk')?.size ?? 0).toBe(0);
+  });
+
+  it('releases the in-progress guard after a failure, so a retry is possible', async () => {
+    const failing = {
+      on: vi.fn(() => () => {}),
+      send: vi.fn(async (method: string) => {
+        if (method === 'HeapProfiler.takeHeapSnapshot') throw new Error('target crashed');
+        return {};
+      }),
+    } as unknown as CdpClient;
+
+    const sid = nextSession();
+    await expect(startHeapSnapshot(failing, sid)).rejects.toThrow('target crashed');
+
+    const path = await outPath();
+    const { client } = heapClient(sid);
+    await expect(startHeapSnapshot(client, sid, path)).resolves.toBe(path);
+  });
+});

package/src/__tests__/reap-idle-browser.test.ts

@@ -0,0 +1,276 @@
+/**
+ * #310: a launched Chrome outlives its session, holding its CDP port (9222 by
+ * convention, which other local tools want) with zero targets left to
+ * reattach to. reapIdleLaunchedBrowser() gives that port back.
+ *
+ * No real Chrome is spawned: the CDP HTTP endpoints (/json/version, /json/list)
+ * are served by a local http server that answers exactly like Chrome does
+ * (same approach as browser-launch.test.ts), the browser-level websocket is a
+ * fake `ws` socket (same approach as close-browser.test.ts), and process.kill
+ * is spied on rather than actually signaling anything.
+ *
+ * Fixed port range (23490-23499) chosen to avoid colliding with real services.
+ */
+
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { CdpTarget } from '../browser/types.js';
+
+const BASE = 23490;
+const MINUTE = 60_000;
+
+let lastSocket: FakeWs | null = null;
+
+/** Minimal `ws` stand-in: opens on its own and acknowledges every command,
+ *  so `Browser.close` takes the graceful path without a real browser. */
+class FakeWs {
+  handlers = new Map<string, Array<(...a: unknown[]) => void>>();
+  sent: string[] = [];
+  constructor(public url: string) {
+    lastSocket = this;
+    queueMicrotask(() => this.emit('open'));
+  }
+  on(event: string, fn: (...a: unknown[]) => void): void {
+    if (!this.handlers.has(event)) this.handlers.set(event, []);
+    this.handlers.get(event)!.push(fn);
+  }
+  emit(event: string, ...args: unknown[]): void {
+    for (const fn of [...(this.handlers.get(event) ?? [])]) fn(...args);
+  }
+  send(data: string, cb?: (err?: Error) => void): void {
+    void cb;
+    this.sent.push(data);
+    const { id } = JSON.parse(data) as { id: number };
+    queueMicrotask(() => this.emit('message', Buffer.from(JSON.stringify({ id, result: {} }))));
+  }
+  close(): void {}
+  /** Methods this socket was asked to run, e.g. ['Browser.close']. */
+  methods(): string[] {
+    return this.sent.map((s) => (JSON.parse(s) as { method: string }).method);
+  }
+}
+
+vi.mock('ws', () => ({ WebSocket: FakeWs }));
+
+let tempDir: string;
+let servers: HttpServer[] = [];
+let killSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(async () => {
+  lastSocket = null;
+  tempDir = await mkdtemp(join(tmpdir(), 'monobrowse-reap-test-'));
+  // ref-cache.ts resolves its cache dir from process.cwd() at module load, so
+  // this must be in place before the dynamic import in each test.
+  vi.spyOn(process, 'cwd').mockReturnValue(tempDir);
+  // The browser is "already gone" by the time closeBrowser polls for its exit
+  // (ESRCH on the liveness probe) — the realistic outcome of Browser.close.
+  killSpy = vi.spyOn(process, 'kill').mockImplementation((_pid: unknown, signal?: unknown) => {
+    if (signal === 0) throw Object.assign(new Error('ESRCH'), { code: 'ESRCH' });
+    return true as never;
+  });
+});
+
+afterEach(async () => {
+  await Promise.all(servers.map((s) => new Promise<void>((resolve) => s.close(() => resolve()))));
+  servers = [];
+  vi.restoreAllMocks();
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+/** An http server answering /json/version and /json/list exactly like Chrome. */
+function fakeChrome(port: number, targets: Partial<CdpTarget>[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const s = createHttpServer((req, res) => {
+      if (req.url === '/json/version') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            Browser: 'Chrome/999.0.0.0',
+            webSocketDebuggerUrl: `ws://127.0.0.1:${port}/devtools/browser/fake-browser-id`,
+          }),
+        );
+      } else if (req.url === '/json/list') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(targets));
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+    s.once('error', reject);
+    s.listen(port, '127.0.0.1', () => {
+      servers.push(s);
+      resolve();
+    });
+  });
+}
+
+const PORT_FILE = () => join(tempDir, '.monomind', 'monobrowse', 'active-port.json');
+
+async function writePersistedPort(record: {
+  port: number;
+  pid?: number;
+  launched: boolean;
+  savedAt: number;
+}): Promise<void> {
+  await mkdir(join(tempDir, '.monomind', 'monobrowse'), { recursive: true });
+  await writeFile(PORT_FILE(), JSON.stringify(record), 'utf-8');
+}
+
+async function portFileExists(): Promise<boolean> {
+  return readFile(PORT_FILE(), 'utf-8').then(
+    () => true,
+    () => false,
+  );
+}
+
+async function loadBrowser() {
+  vi.resetModules();
+  return import('../browser/browser.js');
+}
+
+/** A page target as Chrome reports it when NO debugger is attached to it. */
+function idlePageTarget(id: string, port: number): Partial<CdpTarget> {
+  return {
+    id,
+    type: 'page',
+    title: 'Example',
+    url: 'https://example.com/',
+    webSocketDebuggerUrl: `ws://127.0.0.1:${port}/devtools/page/${id}`,
+  };
+}
+
+describe('#310 reapIdleLaunchedBrowser — give back a CDP port nothing is using', () => {
+  it('reaps a launched instance that has had zero targets past the idle threshold', async () => {
+    const port = BASE + 0;
+    await fakeChrome(port, []);
+    await writePersistedPort({
+      port,
+      pid: 54321,
+      launched: true,
+      savedAt: Date.now() - 45 * MINUTE,
+    });
+
+    const { reapIdleLaunchedBrowser } = await loadBrowser();
+    await expect(reapIdleLaunchedBrowser()).resolves.toBe(port);
+
+    expect(lastSocket?.url).toBe(`ws://127.0.0.1:${port}/devtools/browser/fake-browser-id`);
+    expect(lastSocket?.methods()).toContain('Browser.close');
+    // The port file is the session handle — a reaped session must not leave
+    // one behind for the next command to chase.
+    expect(await portFileExists()).toBe(false);
+  });
+
+  it('does NOT reap a launched instance that still has open page targets', async () => {
+    const port = BASE + 1;
+    await fakeChrome(port, [idlePageTarget('AAA', port)]);
+    await writePersistedPort({
+      port,
+      pid: 54322,
+      launched: true,
+      savedAt: Date.now() - 45 * MINUTE,
+    });
+
+    const { reapIdleLaunchedBrowser } = await loadBrowser();
+    await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
+
+    expect(lastSocket).toBeNull();
+    expect(killSpy).not.toHaveBeenCalled();
+    expect(await portFileExists()).toBe(true);
+  });
+
+  it('does NOT reap a browser this tool never launched, however idle or old it is', async () => {
+    // `connect` records launched:false — that browser belongs to the user.
+    const port = BASE + 2;
+    await fakeChrome(port, []);
+    await writePersistedPort({
+      port,
+      pid: 54323,
+      launched: false,
+      savedAt: Date.now() - 48 * 60 * MINUTE,
+    });
+
+    const { reapIdleLaunchedBrowser } = await loadBrowser();
+    await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
+
+    expect(lastSocket).toBeNull();
+    expect(killSpy).not.toHaveBeenCalled();
+    expect(await portFileExists()).toBe(true);
+  });
+
+  it('does NOT reap while a client is still attached to a target', async () => {
+    // Chrome omits webSocketDebuggerUrl from a target that already has a
+    // debugger attached — an in-flight session, not an abandoned browser.
+    const port = BASE + 3;
+    await fakeChrome(port, [
+      { id: 'BBB', type: 'page', title: 'Example', url: 'https://example.com/' },
+    ]);
+    await writePersistedPort({
+      port,
+      pid: 54324,
+      launched: true,
+      savedAt: Date.now() - 45 * MINUTE,
+    });
+
+    const { reapIdleLaunchedBrowser } = await loadBrowser();
+    await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
+
+    expect(lastSocket).toBeNull();
+    expect(await portFileExists()).toBe(true);
+  });
+
+  it('does NOT reap an instance that is still inside the idle threshold', async () => {
+    // A live session can momentarily have no targets (last tab closed, next
+    // command about to open one) — reaping that would break reattach.
+    const port = BASE + 4;
+    await fakeChrome(port, []);
+    await writePersistedPort({ port, pid: 54325, launched: true, savedAt: Date.now() - MINUTE });
+
+    const { reapIdleLaunchedBrowser } = await loadBrowser();
+    await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
+
+    expect(lastSocket).toBeNull();
+    expect(await portFileExists()).toBe(true);
+  });
+
+  it('does NOT reap when the persisted record has no savedAt (age unknowable)', async () => {
+    const port = BASE + 5;
+    await fakeChrome(port, []);
+    await mkdir(join(tempDir, '.monomind', 'monobrowse'), { recursive: true });
+    await writeFile(PORT_FILE(), JSON.stringify({ port, pid: 54326, launched: true }), 'utf-8');
+
+    const { reapIdleLaunchedBrowser } = await loadBrowser();
+    await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
+    expect(lastSocket).toBeNull();
+  });
+
+  it('is a no-op with no persisted session at all', async () => {
+    const { reapIdleLaunchedBrowser } = await loadBrowser();
+    await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
+    expect(killSpy).not.toHaveBeenCalled();
+  });
+
+  it('launchBrowser reaps the stale instance before deciding what to do with the port', async () => {
+    // The wiring that makes the reaper run at all: every launch/attach is a
+    // chance to give back a port a previous session abandoned.
+    const port = BASE + 6;
+    await fakeChrome(port, []);
+    await writePersistedPort({
+      port,
+      pid: 54327,
+      launched: true,
+      savedAt: Date.now() - 45 * MINUTE,
+    });
+
+    const { launchBrowser } = await loadBrowser();
+    // The fake Chrome stays listening, so launchBrowser attaches to it after
+    // the reap rather than spawning a real browser.
+    await expect(launchBrowser({ port })).resolves.toBe(port);
+
+    expect(lastSocket?.methods()).toContain('Browser.close');
+    expect(await portFileExists()).toBe(false);
+  });
+});

package/src/__tests__/ref-cache.test.ts

@@ -1,7 +1,7 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { mkdtemp, readFile, rm, stat } from 'fs/promises';
-import { join } from 'path';
-import { tmpdir } from 'os';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 // We need to mock process.cwd() before importing ref-cache so CACHE_DIR
 // resolves to our temp directory.
@@ -26,7 +26,9 @@ async function importRefCache() {
   return import('../browser/ref-cache.js');
 }
 
-function makeRefs(count = 2): Map<string, { ref: string; role: string; name: string; nodeId: number }> {
+function makeRefs(
+  count = 2,
+): Map<string, { ref: string; role: string; name: string; nodeId: number }> {
   const map = new Map();
   for (let i = 1; i <= count; i++) {
     map.set(`ref${i}`, { ref: `ref${i}`, role: 'button', name: `Button ${i}`, nodeId: i });
@@ -68,7 +70,7 @@ describe('ref-cache', () => {
 
     // Now overwrite the file with invalid JSON
     const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
-    const { writeFile: wf } = await import('fs/promises');
+    const { writeFile: wf } = await import('node:fs/promises');
     await wf(cacheFile, '{{{not valid json!!!');
 
     const loaded = await mod.loadRefCache('t');
@@ -117,7 +119,7 @@ describe('ref-cache', () => {
     const cacheFile = join(tempDir, '.monomind', 'monobrowse', 'ax-snapshot.json');
     const raw = JSON.parse(await readFile(cacheFile, 'utf8'));
     raw.savedAt = Date.now() - mod.REF_CACHE_STALE_MS - 5000;
-    const { writeFile: wf } = await import('fs/promises');
+    const { writeFile: wf } = await import('node:fs/promises');
     await wf(cacheFile, JSON.stringify(raw));
 
     const loaded = await mod.loadRefCache('t1');
@@ -138,13 +140,21 @@ describe('active-port persistence', () => {
     const mod = await importRefCache();
     await mod.saveActivePort(9333);
     expect(await mod.loadActivePort()).toBe(9333);
-    expect(await mod.loadActivePortInfo()).toEqual({ port: 9333, launched: true, savedAt: expect.any(Number) });
+    expect(await mod.loadActivePortInfo()).toEqual({
+      port: 9333,
+      launched: true,
+      savedAt: expect.any(Number),
+    });
   });
 
   it('connect provenance: launched:false survives the round-trip', async () => {
     const mod = await importRefCache();
     await mod.saveActivePort(9229, { launched: false });
-    expect(await mod.loadActivePortInfo()).toEqual({ port: 9229, launched: false, savedAt: expect.any(Number) });
+    expect(await mod.loadActivePortInfo()).toEqual({
+      port: 9229,
+      launched: false,
+      savedAt: expect.any(Number),
+    });
   });
 
   it('clear removes the file; load returns null afterwards', async () => {
@@ -196,11 +206,14 @@ describe('active-port persistence', () => {
 
   it('#115: a non-numeric or non-positive persisted pid is dropped, not trusted', async () => {
     const mod = await importRefCache();
-    const { writeFile, mkdir } = await import('fs/promises');
+    const { writeFile, mkdir } = await import('node:fs/promises');
     const dir = join(process.cwd(), '.monomind', 'monobrowse');
     await mkdir(dir, { recursive: true });
     for (const badPid of ['54321', -1, 0, 1.5, null]) {
-      await writeFile(join(dir, 'active-port.json'), JSON.stringify({ port: 9333, launched: true, pid: badPid }));
+      await writeFile(
+        join(dir, 'active-port.json'),
+        JSON.stringify({ port: 9333, launched: true, pid: badPid }),
+      );
       const info = await mod.loadActivePortInfo();
       expect(info!.pid).toBeUndefined();
     }
@@ -208,7 +221,7 @@ describe('active-port persistence', () => {
 
   it('rejects out-of-range or non-integer persisted ports', async () => {
     const mod = await importRefCache();
-    const { writeFile, mkdir } = await import('fs/promises');
+    const { writeFile, mkdir } = await import('node:fs/promises');
     const dir = join(process.cwd(), '.monomind', 'monobrowse');
     await mkdir(dir, { recursive: true });
     for (const bad of [80, 70000, 1.5, '9222', null]) {