@monoes/monobrowse 1.0.22 → 1.0.25

package/src/cli/session.ts

@@ -23,6 +23,11 @@
  *     its own, exactly as `open` would.
  *   - Any later command with `--port N` acts on that session, which is how a
  *     concurrent caller pins the one `open` handed it.
+ *   - `--session <name>` is the same pin by name: `open`/`connect` record the
+ *     name on the session they start (or re-open the live one of that name),
+ *     every other command acts on the live session of that name and fails
+ *     when there is none. A command with no name never resolves a named
+ *     session, so named sessions only ever see their own commands.
  *   - `close` ends exactly the session it resolved — one browser, one record.
  *
  * Split out of commands.ts, which is now the command catalogue.
@@ -31,6 +36,7 @@
 import { randomUUID } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { SESSION_NAME_RE } from '../browser/ref-cache.js';
 import type { CdpClient, ElementRef, SessionRecord } from '../index.js';
 import { output } from './output.js';
 import type { ParsedFlags } from './types.js';
@@ -49,6 +55,8 @@ export const session: {
   sessionId: string;
   targetId: string;
   port: number;
+  /** `--session <name>`, or '' for the unnamed sessions. */
+  name: string;
   refs: Map<string, ElementRef>;
   /** Saved parent sessionId when inside an iframe — restored by `frame main`. */
   parentSessionId: string;
@@ -57,6 +65,7 @@ export const session: {
   sessionId: '',
   targetId: '',
   port: UNPINNED,
+  name: '',
   refs: new Map(),
   parentSessionId: '',
 };
@@ -86,6 +95,29 @@ export function applySessionPortFlag(flags: ParsedFlags): void {
   if (pinned !== undefined) session.port = pinned;
 }
 
+/**
+ * Select the named session given by `--session`. Like the port pin, it only
+ * ever sets: a batched command without the flag stays on the session an
+ * earlier command in this process named.
+ */
+export function applySessionNameFlag(flags: ParsedFlags): void {
+  const raw = flags.session;
+  if (raw === undefined) return;
+  if (typeof raw !== 'string' || !SESSION_NAME_RE.test(raw)) {
+    throw new Error(
+      `Invalid session name "${String(raw)}" — use 1-64 letters, digits, '.', '_' or '-'.`,
+    );
+  }
+  session.name = raw;
+}
+
+/** The error for a `--session` name no live browser answers to. */
+export function noNamedSessionError(name: string): Error {
+  return new Error(
+    `No live browse session named "${name}" — start one with: monomind browse open <url> --session ${name}`,
+  );
+}
+
 export async function getBrowser() {
   return import('../index.js');
 }
@@ -140,11 +172,32 @@ export function ensureSignalCleanupHandlers(): void {
 //
 // Records whose browser is gone are dropped as we pass them (self-heal): a
 // crashed or manually-killed Chrome must not wedge every later command.
+//
+// `name` selects the session recorded under that `--session` name; without
+// one, only unnamed sessions are candidates — UNLESS there is exactly one
+// other live session, named or not (see `soleOtherLive` below): a command
+// that named nothing still has to resolve to *something* when there is only
+// one browser to mean, or every command run after a named-only `open` (any
+// flag combination that leaves `session.name` unset — e.g. `snapshot`'s `-s`
+// is `--selector`, not `--session`, see withSessionSelector) would silently
+// miss the live named session and launch a brand-new, unrelated Chrome
+// instead — the process this file exists to prevent (#318), just with an
+// empty new tab standing in for the "wrong browser" (issue: named-session
+// snapshot showed Chrome's New Tab instead of the opened page). Ambiguity
+// (two or more other live sessions) is still refused: guessing among several
+// named browsers is exactly the cross-session bleed #318 fixed.
 export async function resolveLiveSession(
   browser: Awaited<ReturnType<typeof getBrowser>>,
-  opts: { strict?: boolean } = {},
+  opts: { strict?: boolean; name?: string } = {},
 ): Promise<SessionRecord | null> {
+  const soleOtherLive: SessionRecord[] = [];
   for (const record of await browser.listSessionRecords()) {
+    if ((record.name ?? '') !== (opts.name ?? '')) {
+      if (opts.name === undefined && soleOtherLive.length < 2 && (await cdpAnswers(record.port))) {
+        soleOtherLive.push(record);
+      }
+      continue;
+    }
     if (await cdpAnswers(record.port)) return record;
     await browser.removeSessionRecord(record.port);
     await browser.clearRefCache(record.port);
@@ -159,10 +212,12 @@ export async function resolveLiveSession(
       );
     }
   }
-  // Nothing native is live. A session opened by a pre-#318 CLI in this
-  // directory may still be — it is the oldest possible candidate, so it is
-  // considered last.
-  return adoptLegacySession(browser);
+  if (opts.name === undefined && soleOtherLive.length === 1) return soleOtherLive[0];
+  // Nothing native is live (or matched). A session opened by a pre-#318 CLI
+  // in this directory may still be — it is the oldest possible candidate, so
+  // it is considered last. It predates names, so a named lookup never adopts
+  // it.
+  return opts.name ? null : adoptLegacySession(browser);
 }
 
 /**
@@ -227,7 +282,7 @@ async function cdpAnswers(port: number): Promise<boolean> {
  */
 export async function launchSessionBrowser(
   browser: Awaited<ReturnType<typeof getBrowser>>,
-  opts: { port?: number; headless: boolean },
+  opts: { port?: number; headless: boolean; name?: string },
 ): Promise<number> {
   const port = opts.port
     ? await browser.launchBrowser({ port: opts.port, headless: opts.headless })
@@ -238,7 +293,7 @@ export async function launchSessionBrowser(
         // belong to this session alone.
         userDataDir: join(tmpdir(), `monomind-browse-${process.pid}-${randomUUID().slice(0, 8)}`),
       });
-  await recordSession(browser, port);
+  await recordSession(browser, port, opts.name);
   ensureSignalCleanupHandlers();
   return port;
 }
@@ -256,15 +311,20 @@ export async function launchSessionBrowser(
 // {pid: undefined} on attach used to CLOBBER a real PID a previous `open`
 // had persisted for this exact port, destroying the only way a later
 // process's closeBrowser() PID-kill fallback could ever find it.
+//
+// `name` labels the session; without one, re-recording keeps the name the
+// session already had, so a `--port` command does not strip it.
 async function recordSession(
   browser: Awaited<ReturnType<typeof getBrowser>>,
   port: number,
+  name?: string,
 ): Promise<void> {
   const pid = browser.getLaunchedPid(port);
   if (pid !== undefined) {
     await browser.saveSessionRecord(port, {
       pid,
       userDataDir: browser.getLaunchedUserDataDir(port),
+      name: name ?? (await browser.loadSessionRecord(port))?.name,
     });
     return;
   }
@@ -277,6 +337,7 @@ async function recordSession(
     launched: existing?.launched,
     pid: existing?.pid,
     userDataDir: existing?.userDataDir,
+    name: name ?? existing?.name,
   });
 }
 
@@ -290,9 +351,16 @@ export async function ensureConnected(port: number, targetId?: string) {
       browser.teardownConsoleCapture(session.sessionId);
       session.client.close();
     }
-    // Pinned port, else the newest live session, else a session of our own —
-    // a command run before any `open` still just works.
-    const pinned = port > 0 ? port : ((await resolveLiveSession(browser))?.port ?? undefined);
+    // Pinned port, else the named session (which must exist), else the
+    // newest live unnamed session, else a session of our own — a command run
+    // before any `open` still just works.
+    let pinned: number | undefined = port > 0 ? port : undefined;
+    if (pinned === undefined && session.name) {
+      pinned = (await resolveLiveSession(browser, { name: session.name }))?.port;
+      if (pinned === undefined) throw noNamedSessionError(session.name);
+    } else if (pinned === undefined) {
+      pinned = (await resolveLiveSession(browser))?.port;
+    }
     session.port = await launchSessionBrowser(browser, { port: pinned, headless: true });
     const conn = await browser.connectToTarget(session.port, targetId);
     session.client = conn.client;
@@ -341,194 +409,6 @@ export async function hydrateRefsFromCache(
   }
 }
 
-// URL patterns that signal an unambiguous login/auth wall.
-// Excludes 'auth', 'oauth', 'sso', 'saml' — their callback/ACS/token paths
-// (/auth/callback, /sso/callback, /saml/acs) are completion endpoints, not walls.
-// DOM detection (password field, CAPTCHA widgets) handles SSO/SAML login pages.
-const ATTENTION_URL_RE =
-  /\/(login|log-in|signin|sign-in|captcha|mfa|2fa|account\/login|accounts\/login|session\/new|users\/sign_in)(?:[/?#]|$)/i;
-
-export async function detectAttentionNeeded(
-  client: CdpClient,
-  sessionId: string,
-  url: string,
-): Promise<'login' | 'captcha' | null> {
-  if (ATTENTION_URL_RE.test(url)) return 'login';
-  try {
-    const hasPassword = await client
-      .send<{ result: { value: boolean } }>(
-        'Runtime.evaluate',
-        {
-          expression: '!!document.querySelector("input[type=password]")',
-          returnByValue: true,
-        },
-        sessionId,
-      )
-      .then((r) => r.result?.value === true)
-      .catch(() => false);
-    if (hasPassword) return 'login';
-
-    const hasCaptcha = await client
-      .send<{ result: { value: boolean } }>(
-        'Runtime.evaluate',
-        {
-          expression:
-            '!!(document.querySelector("iframe[src*=recaptcha]") || document.querySelector("iframe[src*=hcaptcha]") || document.querySelector(".g-recaptcha") || document.querySelector(".h-captcha") || document.querySelector("[data-sitekey]"))',
-          returnByValue: true,
-        },
-        sessionId,
-      )
-      .then((r) => r.result?.value === true)
-      .catch(() => false);
-    if (hasCaptcha) return 'captcha';
-  } catch {
-    /* ignore CDP errors */
-  }
-  return null;
-}
-
-export function waitForEnter(): Promise<void> {
-  if (!process.stdin.isTTY) {
-    // Non-interactive context (MCP server, piped input, CI) — cannot safely read stdin.
-    // Auto-continue after a short grace period so automation isn't blocked.
-    output.printWarning(
-      'Non-interactive mode: auto-continuing in 30s. Switch to headed manually if needed.',
-    );
-    return new Promise((resolve) => setTimeout(resolve, 30_000));
-  }
-  return new Promise((resolve) => {
-    process.stdin.resume();
-    process.stdin.setEncoding('utf8');
-    const onData = () => {
-      process.stdin.pause();
-      process.stdin.off('data', onData);
-      resolve();
-    };
-    process.stdin.once('data', onData);
-  });
-}
-
-export async function switchToHeaded(url: string, port: number): Promise<void> {
-  const browser = await getBrowser();
-
-  // Snapshot cookies from current headless session before closing
-  let savedCookies: unknown[] = [];
-  if (session.client && session.sessionId) {
-    try {
-      savedCookies = await browser.getCookies(session.client, session.sessionId);
-    } catch {
-      /* ignore */
-    }
-    browser.teardownRouteInterception(session.sessionId);
-    browser.stopRequestCapture(session.sessionId);
-    browser.teardownDialogHandling(session.sessionId);
-    browser.teardownConsoleCapture(session.sessionId);
-    session.client.close();
-    session.client = null;
-    session.sessionId = '';
-    session.parentSessionId = '';
-    session.targetId = '';
-  }
-
-  // Kernel-assigned free port and a profile of its own, so this temporary
-  // headed window cannot collide with any other session (#318) — a
-  // neighbouring port (port + 10) could well be another session's.
-  let headedPort = 0;
-  try {
-    headedPort = await browser.launchBrowser({
-      port: 0,
-      headless: false,
-      userDataDir: join(
-        tmpdir(),
-        `monomind-browse-headed-${process.pid}-${randomUUID().slice(0, 8)}`,
-      ),
-    });
-  } catch (err) {
-    // Headed launch failed (no display, locked down env). Restore headless and rethrow.
-    session.port = await browser.launchBrowser({ port, headless: true });
-    const fallback = await browser.connectToTarget(session.port);
-    session.client = fallback.client;
-    session.sessionId = fallback.sessionId;
-    session.targetId = fallback.target.id;
-    session.refs = new Map();
-    throw new Error(
-      `Cannot open headed browser: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-  const conn = await browser.connectToTarget(headedPort);
-  session.client = conn.client;
-  session.sessionId = conn.sessionId;
-  session.targetId = conn.target.id;
-  session.refs = new Map();
-
-  if (savedCookies.length) {
-    try {
-      await browser.setCookies(
-        session.client,
-        session.sessionId,
-        savedCookies as Parameters<typeof browser.setCookies>[2],
-      );
-    } catch {
-      /* ignore */
-    }
-  }
-  await browser.openUrl(session.client, session.sessionId, url);
-
-  output.printInfo(
-    'Browser window opened. Complete the required action (login / CAPTCHA), then press Enter to continue in headless mode...',
-  );
-  await waitForEnter();
-
-  // Capture post-auth cookies
-  const authCookies = await browser
-    .getCookies(session.client, session.sessionId)
-    .catch(() => [] as unknown[]);
-  const authLocalStorage = await browser
-    .getLocalStorage(session.client, session.sessionId)
-    .catch(() => ({}) as Record<string, string>);
-
-  // Close headed session — actually terminate the underlying Chrome process
-  // (Browser.close CDP command, PID-kill fallback), not just our CDP client
-  // connection, so the visible authenticated window doesn't linger forever.
-  browser.teardownRouteInterception(session.sessionId);
-  browser.stopRequestCapture(session.sessionId);
-  browser.teardownDialogHandling(session.sessionId);
-  browser.teardownConsoleCapture(session.sessionId);
-  await browser.closeBrowser(session.client, headedPort);
-  session.client.close();
-  session.client = null;
-  session.sessionId = '';
-  session.parentSessionId = '';
-  session.targetId = '';
-
-  // Relaunch headless and restore session
-  session.port = await browser.launchBrowser({ port, headless: true });
-  const headlessConn = await browser.connectToTarget(session.port);
-  session.client = headlessConn.client;
-  session.sessionId = headlessConn.sessionId;
-  session.targetId = headlessConn.target.id;
-  session.refs = new Map();
-
-  if (authCookies.length) {
-    try {
-      await browser.setCookies(
-        session.client,
-        session.sessionId,
-        authCookies as Parameters<typeof browser.setCookies>[2],
-      );
-    } catch {
-      /* ignore */
-    }
-  }
-  if (authLocalStorage && Object.keys(authLocalStorage).length) {
-    try {
-      await browser.setLocalStorage(session.client, session.sessionId, authLocalStorage);
-    } catch {
-      /* ignore */
-    }
-  }
-}
-
 // Cap on printed output so a command cannot flood a terminal or an agent's
 // context with a whole page. 0 disables truncation.
 export const DEFAULT_EVAL_MAX_OUTPUT = 50_000;