@monoes/monobrowse 1.0.19 → 1.0.22

package/package.json

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

package/src/__tests__/browse-concurrency.test.ts

@@ -0,0 +1,233 @@
+/**
+ * #318: two uncoordinated `browse open` invocations with no `--port` raced on
+ * the shared default CDP port (9222) and the userDataDir derived from it —
+ * one failed outright ("Chrome exited before the CDP endpoint opened on port
+ * 9222"), or both attached to ONE Chrome and a single `browse close` killed
+ * the other caller's browser too.
+ *
+ * This is a real-process test on purpose: the bug lives in the interaction
+ * between two separate CLI processes and the session state they share on
+ * disk, which no in-process unit test can reproduce. It spawns the built CLI
+ * (dist/src/cli.js) against a file:// fixture page, so it is skipped when the
+ * package has not been built or no Chrome/Chromium is installed.
+ */
+
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+import { CHROME_EXECUTABLES } from '../browser/types.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const CLI = join(here, '..', '..', 'dist', 'src', 'cli.js');
+
+function chromeAvailable(): boolean {
+  if (CHROME_EXECUTABLES.some((p) => existsSync(p))) return true;
+  try {
+    return (
+      execFileSync('which', ['google-chrome', 'chromium-browser', 'chromium'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim().length > 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+const runnable = existsSync(CLI) && chromeAvailable();
+
+interface Run {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+function runCli(args: string[], cwd: string, profileRoot: string): Promise<Run> {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CLI, ...args], {
+      cwd,
+      // Per-trial TMPDIR: every browser profile this invocation creates lands
+      // under it, so the sweep in afterEach can identify (and only kill) the
+      // Chrome processes this test started.
+      env: { ...process.env, TMPDIR: profileRoot, CI: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => {
+      stdout += d;
+    });
+    child.stderr.on('data', (d) => {
+      stderr += d;
+    });
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+/** The CDP port `open` reports for the session it started. */
+function reportedPort(run: Run): number | null {
+  const m = /\[port (\d+)\]/.exec(run.stdout);
+  return m ? Number(m[1]) : null;
+}
+
+async function cdpAlive(port: number): Promise<boolean> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+const dirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of dirs.splice(0)) {
+    // Kill anything still running out of this trial's profile root before the
+    // directory goes away — a leaked Chrome would otherwise outlive the run.
+    await new Promise<void>((resolve) => {
+      execFile('pkill', ['-f', dir], () => resolve());
+    });
+    // A killed Chrome keeps writing out its profile for a moment; retry the
+    // removal instead of failing the test on ENOTEMPTY.
+    await rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+  }
+});
+
+describe.skipIf(!runnable)('#318 concurrent browse sessions (real processes)', () => {
+  for (const trial of [1, 2, 3, 4, 5]) {
+    it(`trial ${trial}: two bare \`open\` calls each get their own browser, and each close kills only its own`, async () => {
+      const root = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-318-'));
+      dirs.push(root);
+      const page = join(root, 'fixture.html');
+      await writeFile(page, '<!doctype html><title>Fixture</title><h1>hello</h1>');
+      const url = `file://${page}`;
+
+      // The reported race: two uncoordinated invocations, same cwd, no --port.
+      const [a, b] = await Promise.all([
+        runCli(['open', url], root, root),
+        runCli(['open', url], root, root),
+      ]);
+
+      expect(a.code, `open A failed: ${a.stdout}${a.stderr}`).toBe(0);
+      expect(b.code, `open B failed: ${b.stdout}${b.stderr}`).toBe(0);
+
+      const portA = reportedPort(a);
+      const portB = reportedPort(b);
+      expect(portA, `open A did not report a session port: ${a.stdout}`).not.toBeNull();
+      expect(portB, `open B did not report a session port: ${b.stdout}`).not.toBeNull();
+      expect(portA).not.toBe(portB);
+
+      expect(await cdpAlive(portA!)).toBe(true);
+      expect(await cdpAlive(portB!)).toBe(true);
+
+      // Closing A must leave B's browser running.
+      const closeA = await runCli(['close', '--port', String(portA)], root, root);
+      expect(closeA.code, `close A failed: ${closeA.stdout}${closeA.stderr}`).toBe(0);
+      expect(await cdpAlive(portA!)).toBe(false);
+      expect(await cdpAlive(portB!)).toBe(true);
+
+      const closeB = await runCli(['close', '--port', String(portB)], root, root);
+      expect(closeB.code, `close B failed: ${closeB.stdout}${closeB.stderr}`).toBe(0);
+      expect(await cdpAlive(portB!)).toBe(false);
+    }, 90_000);
+  }
+});
+
+/**
+ * Upgrading monobrowse while a session was open used to strand its Chrome:
+ * the handle lived in `active-port.json`, which the per-port store replaced.
+ * The new CLI adopts that record instead — the same real-process shape as
+ * above, since the whole point is what a *later* process can still do.
+ */
+describe.skipIf(!runnable)('#318 adoption of a pre-#318 session (real processes)', () => {
+  /** Open a session, then rewrite its state as a pre-#318 install left it. */
+  async function openThenDowngradeState(root: string, url: string): Promise<number> {
+    const opened = await runCli(['open', url], root, root);
+    expect(opened.code, `open failed: ${opened.stdout}${opened.stderr}`).toBe(0);
+    const port = reportedPort(opened);
+    expect(port).not.toBeNull();
+
+    const stateDir = join(root, '.monomind', 'monobrowse');
+    const record = await readFile(join(stateDir, 'sessions', `${port}.json`), 'utf8');
+    await writeFile(join(stateDir, 'active-port.json'), record);
+    await rm(join(stateDir, 'sessions'), { recursive: true, force: true });
+    return port!;
+  }
+
+  it('a later command adopts the legacy session, and close then kills that browser', async () => {
+    const root = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-318-legacy-'));
+    dirs.push(root);
+    const page = join(root, 'fixture.html');
+    await writeFile(page, '<!doctype html><title>Fixture</title><h1>hello</h1>');
+    const port = await openThenDowngradeState(root, `file://${page}`);
+
+    // A later, separate process with no --port finds it.
+    const title = await runCli(['get', 'title'], root, root);
+    expect(title.code, `get title failed: ${title.stdout}${title.stderr}`).toBe(0);
+    expect(title.stdout).toContain('Fixture');
+
+    // Adopted: it is an ordinary per-port record now, and the old file is gone.
+    const stateDir = join(root, '.monomind', 'monobrowse');
+    expect(existsSync(join(stateDir, 'sessions', `${port}.json`))).toBe(true);
+    expect(existsSync(join(stateDir, 'active-port.json'))).toBe(false);
+
+    // And `--port` works on it exactly like a native session.
+    const closed = await runCli(['close', '--port', String(port)], root, root);
+    expect(closed.code, `close failed: ${closed.stdout}${closed.stderr}`).toBe(0);
+    expect(await cdpAlive(port)).toBe(false);
+  }, 90_000);
+
+  it('a legacy record whose browser is gone is cleaned up, and the command still works', async () => {
+    const root = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-318-legacy-'));
+    dirs.push(root);
+    const stateDir = join(root, '.monomind', 'monobrowse');
+    await mkdir(stateDir, { recursive: true });
+    // A port nothing is listening on — the state an upgrade finds after the
+    // old browser died (or was killed) with its record left behind.
+    await writeFile(
+      join(stateDir, 'active-port.json'),
+      JSON.stringify({ port: 23499, launched: true, pid: 999999, savedAt: Date.now() }),
+    );
+
+    const closed = await runCli(['close'], root, root);
+    expect(closed.code, `close failed: ${closed.stdout}${closed.stderr}`).toBe(0);
+    expect(closed.stdout).toContain('No active browser session');
+    expect(existsSync(join(stateDir, 'active-port.json'))).toBe(false);
+  }, 60_000);
+
+  it('adoption does not change bare `open`: it still starts a browser of its own', async () => {
+    const root = await mkdtemp(join(process.env.TMPDIR ?? tmpdir(), 'monobrowse-318-legacy-'));
+    dirs.push(root);
+    const page = join(root, 'fixture.html');
+    await writeFile(page, '<!doctype html><title>Fixture</title><h1>hello</h1>');
+    const url = `file://${page}`;
+    const legacyPort = await openThenDowngradeState(root, url);
+
+    const fresh = await runCli(['open', url], root, root);
+    expect(fresh.code, `open failed: ${fresh.stdout}${fresh.stderr}`).toBe(0);
+    const freshPort = reportedPort(fresh);
+    expect(freshPort).not.toBe(legacyPort);
+    // Neither joined nor disturbed: both browsers are up, and the legacy
+    // record is still waiting to be adopted by whoever needs it.
+    expect(await cdpAlive(legacyPort)).toBe(true);
+    expect(await cdpAlive(freshPort!)).toBe(true);
+    expect(existsSync(join(root, '.monomind', 'monobrowse', 'active-port.json'))).toBe(true);
+
+    // Closing the new session leaves the legacy browser alone; a second
+    // close then adopts and ends it.
+    const closeFresh = await runCli(['close', '--port', String(freshPort)], root, root);
+    expect(closeFresh.code).toBe(0);
+    expect(await cdpAlive(legacyPort)).toBe(true);
+
+    const closeLegacy = await runCli(['close'], root, root);
+    expect(closeLegacy.code, `close failed: ${closeLegacy.stdout}${closeLegacy.stderr}`).toBe(0);
+    expect(await cdpAlive(legacyPort)).toBe(false);
+  }, 90_000);
+});

package/src/__tests__/cli-version.test.ts

@@ -0,0 +1,50 @@
+/**
+ * `monobrowse --version` crashed instead of printing a version. (#320)
+ *
+ * `src/cli.ts` read the manifest with `_require('../package.json')`. That path
+ * is right for the SOURCE file — `src/cli.ts` sits one level under the package
+ * root — and wrong for the only file that ever runs it. The package compiles
+ * with `rootDir: "."`, so `src/cli.ts` emits to `dist/src/cli.js`, and
+ * `createRequire(import.meta.url)` resolves relative to THAT file: `../` is
+ * `dist/`, which holds no package.json. Every invocation of the standalone
+ * binary died with `Cannot find module '../package.json'`, in the repo and
+ * from a clean install alike.
+ *
+ * WHY THIS IS A SUBPROCESS TEST. The bug lives entirely in the emitted file's
+ * position on disk. Importing anything from `src/` re-resolves the path from
+ * the source tree, where the broken version was already correct — an in-process
+ * test would have passed against the bug. Only spawning the built `dist/src/
+ * cli.js`, the exact file `bin.monobrowse` points at, can observe it.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(here, '..', '..');
+const distCli = join(pkgRoot, 'dist', 'src', 'cli.js');
+const hasBuild = existsSync(distCli);
+
+describe.skipIf(!hasBuild)('the built monobrowse binary reports its version', () => {
+  const declared = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'))
+    .version as string;
+
+  for (const flag of ['--version', '-V']) {
+    it(`\`monobrowse ${flag}\` exits 0 and prints the package version`, () => {
+      // THE BUG: this threw — exit 1, `✗ Cannot find module '../package.json'`.
+      const out = execFileSync('node', [distCli, flag], { encoding: 'utf8', stdio: 'pipe' });
+
+      expect(out.trim()).toBe(declared);
+      expect(out.trim()).toMatch(/^\d+\.\d+\.\d+/);
+    }, 15_000);
+  }
+});
+
+describe.skipIf(hasBuild)('monobrowse --version subprocess test', () => {
+  it('is skipped because dist/ is not built (run `npm run build`)', () => {
+    expect(hasBuild).toBe(false);
+  });
+});

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

@@ -72,10 +72,10 @@ afterEach(async () => {
 });
 
 async function writePersistedPort(port: number, pid: number, savedAt: number): Promise<void> {
-  const dir = join(tempDir, '.monomind', 'monobrowse');
+  const dir = join(tempDir, '.monomind', 'monobrowse', 'sessions');
   await mkdir(dir, { recursive: true });
   await writeFile(
-    join(dir, 'active-port.json'),
+    join(dir, `${port}.json`),
     JSON.stringify({ port, pid, launched: true, savedAt }),
     'utf-8',
   );

package/src/__tests__/frame-command.test.ts

@@ -20,7 +20,15 @@ const mocks = vi.hoisted(() => {
         sessionId: 'S-PAGE',
         target: { id: 'T-PAGE', url: 'https://x.test' },
       })),
-      loadActivePortInfo: vi.fn(async () => null),
+      listSessionRecords: vi.fn(async () => []),
+      loadSessionRecord: vi.fn(async () => null),
+      loadLegacySessionRecord: vi.fn(async () => null),
+      removeLegacySessionRecord: vi.fn(async () => {}),
+      saveSessionRecord: vi.fn(async () => {}),
+      removeSessionRecord: vi.fn(async () => {}),
+      clearRefCache: vi.fn(async () => {}),
+      getLaunchedPid: vi.fn(() => undefined),
+      getLaunchedUserDataDir: vi.fn(() => undefined),
       loadRefCache: vi.fn(async () => null),
       switchToFrame: vi.fn(
         async (): Promise<{ url: string | null; sessionId: string | null }> => ({
@@ -55,7 +63,9 @@ const ctx = (args: string[]): CommandContext => ({
 
 beforeEach(() => {
   vi.clearAllMocks();
-  mocks.browser.loadActivePortInfo.mockResolvedValue(null);
+  mocks.browser.listSessionRecords.mockResolvedValue([]);
+  mocks.browser.loadSessionRecord.mockResolvedValue(null);
+  mocks.browser.loadLegacySessionRecord.mockResolvedValue(null);
   mocks.browser.loadRefCache.mockResolvedValue(null);
   mocks.browser.switchToFrame.mockResolvedValue({
     url: 'https://f.test/frame',

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

@@ -108,20 +108,22 @@ function fakeChrome(port: number, targets: Partial<CdpTarget>[]): Promise<void>
   });
 }
 
-const PORT_FILE = () => join(tempDir, '.monomind', 'monobrowse', 'active-port.json');
+// Sessions are recorded one file per port (#318).
+const PORT_FILE = (port: number) =>
+  join(tempDir, '.monomind', 'monobrowse', 'sessions', `${port}.json`);
 
 async function writePersistedPort(record: {
   port: number;
   pid?: number;
   launched: boolean;
-  savedAt: number;
+  savedAt?: number;
 }): Promise<void> {
-  await mkdir(join(tempDir, '.monomind', 'monobrowse'), { recursive: true });
-  await writeFile(PORT_FILE(), JSON.stringify(record), 'utf-8');
+  await mkdir(join(tempDir, '.monomind', 'monobrowse', 'sessions'), { recursive: true });
+  await writeFile(PORT_FILE(record.port), JSON.stringify(record), 'utf-8');
 }
 
-async function portFileExists(): Promise<boolean> {
-  return readFile(PORT_FILE(), 'utf-8').then(
+async function portFileExists(port: number): Promise<boolean> {
+  return readFile(PORT_FILE(port), 'utf-8').then(
     () => true,
     () => false,
   );
@@ -161,7 +163,7 @@ describe('#310 reapIdleLaunchedBrowser — give back a CDP port nothing is using
     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);
+    expect(await portFileExists(port)).toBe(false);
   });
 
   it('does NOT reap a launched instance that still has open page targets', async () => {
@@ -179,7 +181,7 @@ describe('#310 reapIdleLaunchedBrowser — give back a CDP port nothing is using
 
     expect(lastSocket).toBeNull();
     expect(killSpy).not.toHaveBeenCalled();
-    expect(await portFileExists()).toBe(true);
+    expect(await portFileExists(port)).toBe(true);
   });
 
   it('does NOT reap a browser this tool never launched, however idle or old it is', async () => {
@@ -198,7 +200,7 @@ describe('#310 reapIdleLaunchedBrowser — give back a CDP port nothing is using
 
     expect(lastSocket).toBeNull();
     expect(killSpy).not.toHaveBeenCalled();
-    expect(await portFileExists()).toBe(true);
+    expect(await portFileExists(port)).toBe(true);
   });
 
   it('does NOT reap while a client is still attached to a target', async () => {
@@ -219,7 +221,7 @@ describe('#310 reapIdleLaunchedBrowser — give back a CDP port nothing is using
     await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
 
     expect(lastSocket).toBeNull();
-    expect(await portFileExists()).toBe(true);
+    expect(await portFileExists(port)).toBe(true);
   });
 
   it('does NOT reap an instance that is still inside the idle threshold', async () => {
@@ -233,14 +235,13 @@ describe('#310 reapIdleLaunchedBrowser — give back a CDP port nothing is using
     await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
 
     expect(lastSocket).toBeNull();
-    expect(await portFileExists()).toBe(true);
+    expect(await portFileExists(port)).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');
+    await writePersistedPort({ port, pid: 54326, launched: true });
 
     const { reapIdleLaunchedBrowser } = await loadBrowser();
     await expect(reapIdleLaunchedBrowser()).resolves.toBeNull();
@@ -271,6 +272,6 @@ describe('#310 reapIdleLaunchedBrowser — give back a CDP port nothing is using
     await expect(launchBrowser({ port })).resolves.toBe(port);
 
     expect(lastSocket?.methods()).toContain('Browser.close');
-    expect(await portFileExists()).toBe(false);
+    expect(await portFileExists(port)).toBe(false);
   });
 });