@monoes/monobrowse 1.0.22 → 1.0.25

package/src/cli/attention-wall.ts

@@ -0,0 +1,202 @@
+/**
+ * Login / CAPTCHA walls — how `open` notices one, and the round trip to a
+ * visible browser window that lets a person get past it before the session
+ * carries on headless with the cookies and localStorage they earned.
+ *
+ * Split out of session.ts, which keeps the session runtime itself.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { CdpClient } from '../index.js';
+import { output } from './output.js';
+import { getBrowser, session } from './session.js';
+
+// 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 */
+    }
+  }
+}

package/src/cli/commands-session.ts

@@ -8,17 +8,16 @@
  * differently: it must never kill a Chrome it did not launch.
  */
 
+import { detectAttentionNeeded, switchToHeaded } from './attention-wall.js';
 import { output } from './output.js';
 import {
   adoptLegacySession,
-  detectAttentionNeeded,
   ensureConnected,
   getBrowser,
   launchSessionBrowser,
   pinnedPort,
   resolveLiveSession,
   session,
-  switchToHeaded,
 } from './session.js';
 import type { Command, CommandContext, CommandResult } from './types.js';
 
@@ -39,7 +38,13 @@ export const openCommand: Command = {
       description: 'Force visible browser window',
       default: false,
     },
-    { name: 'session', short: 's', type: 'string', description: 'Session name to restore' },
+    {
+      name: 'session',
+      short: 's',
+      type: 'string',
+      description:
+        'Named session: re-open the live one with this name or start it, and restore saved state of that name if any',
+    },
     { name: 'state', type: 'string', description: 'State file to load' },
   ],
   action: async (ctx: CommandContext): Promise<CommandResult> => {
@@ -48,10 +53,14 @@ export const openCommand: Command = {
 
     // No --port means "start a session of my own on a free port" (#318) —
     // never "join whatever is on 9222", which is what made two uncoordinated
-    // `open` calls race for one browser and one profile directory.
-    const port = pinnedPort(ctx.flags);
-    const forceHeaded = ctx.flags.headed as boolean;
+    // `open` calls race for one browser and one profile directory. A
+    // --session name re-opens the live session of that name, if there is one.
     const browser = await getBrowser();
+    const name = session.name || undefined;
+    const port =
+      pinnedPort(ctx.flags) ??
+      (name ? (await resolveLiveSession(browser, { name }))?.port : undefined);
+    const forceHeaded = ctx.flags.headed as boolean;
 
     if (session.client) {
       const prevSid = session.sessionId;
@@ -91,7 +100,7 @@ export const openCommand: Command = {
 
     // Starts this session's own browser (and records it) unless --port named
     // one to attach to — see the session rule in session.ts.
-    session.port = await launchSessionBrowser(browser, { port, headless: !forceHeaded });
+    session.port = await launchSessionBrowser(browser, { port, headless: !forceHeaded, name });
     const conn = await browser.connectToTarget(session.port);
     session.client = conn.client;
     session.sessionId = conn.sessionId;
@@ -107,8 +116,10 @@ export const openCommand: Command = {
     }
     if (ctx.flags.state) {
       await browser.loadStateFile(session.client, session.sessionId, ctx.flags.state as string);
-    } else if (ctx.flags.session) {
-      await browser.loadSession(session.client, session.sessionId, ctx.flags.session as string);
+    } else if (name && (await browser.listSessions()).includes(name)) {
+      // Saved state of the same name (`state save <name>`) is restored; a
+      // name with none is simply a fresh named session.
+      await browser.loadSession(session.client, session.sessionId, name);
     }
 
     await browser.openUrl(session.client, session.sessionId, url);
@@ -228,7 +239,7 @@ export const closeCommand: Command = {
             port: pinned,
             launched: true,
           })
-        : await resolveLiveSession(browser, { strict: false });
+        : await resolveLiveSession(browser, { strict: false, name: session.name || undefined });
       if (persisted?.launched) {
         try {
           const conn = await browser.connectToTarget(persisted.port);
@@ -271,7 +282,9 @@ export const closeCommand: Command = {
         output.printInfo(
           persisted
             ? `Detached from browser on port ${persisted.port} (attached via connect — left running)`
-            : 'No active browser session',
+            : session.name
+              ? `No live browse session named "${session.name}"`
+              : 'No active browser session',
         );
       }
       if (persisted) {
@@ -370,7 +383,7 @@ export const connectCommand: Command = {
     // launches a browser of its own instead of reusing this session.
     // launched:false marks this browser as someone else's — close must never
     // kill it, and a dead endpoint must not be silently relaunched.
-    await browser.saveSessionRecord(port, { launched: false });
+    await browser.saveSessionRecord(port, { launched: false, name: session.name || undefined });
     const url = await browser.getCurrentUrl(session.client, session.sessionId);
     const title = await browser.getCurrentTitle(session.client, session.sessionId);
     output.printSuccess(`Connected: ${title} (${url})`);

package/src/cli/commands.ts

@@ -90,7 +90,7 @@ import {
 } from './commands-trace.js';
 import { output } from './output.js';
 import { createPlatformCommand } from './platform.js';
-import { applySessionPortFlag } from './session.js';
+import { applySessionNameFlag, applySessionPortFlag } from './session.js';
 import type { Command, CommandContext, CommandResult } from './types.js';
 
 // Re-exported for direct unit testing — these were exported from this file
@@ -230,16 +230,33 @@ const PORT_OPTION = {
   description: 'Act on the browse session on this CDP port (default: the newest live session)',
 } as const;
 
+const SESSION_OPTION = {
+  name: 'session',
+  short: 's',
+  type: 'string',
+  description: 'Act on the live browse session with this name (open/connect start it)',
+} as const;
+
 function withSessionSelector(cmd: Command): Command {
   const action = cmd.action;
+  const options = cmd.options?.some((o) => o.name === 'port')
+    ? (cmd.options ?? [])
+    : [...(cmd.options ?? []), { ...PORT_OPTION }];
   return {
     ...cmd,
-    options: cmd.options?.some((o) => o.name === 'port')
-      ? cmd.options
-      : [...(cmd.options ?? []), { ...PORT_OPTION }],
+    // `snapshot`/`scroll` already use -s for --selector: long form only there.
+    options: options.some((o) => o.name === 'session')
+      ? options
+      : [
+          ...options,
+          options.some((o) => o.short === 's')
+            ? { ...SESSION_OPTION, short: undefined }
+            : { ...SESSION_OPTION },
+        ],
     action: action
       ? async (ctx: CommandContext) => {
           applySessionPortFlag(ctx.flags);
+          applySessionNameFlag(ctx.flags);
           return action(ctx);
         }
       : undefined,
@@ -324,10 +341,7 @@ const browseCommand: Command = {
   name: 'browse',
   description: 'Native browser automation via Chrome DevTools Protocol',
   subcommands,
-  options: [
-    { ...PORT_OPTION },
-    { name: 'session', short: 's', type: 'string', description: 'Named session to use' },
-  ],
+  options: [{ ...PORT_OPTION }, { ...SESSION_OPTION }],
   examples: [
     { command: 'monomind browse open https://example.com', description: 'Open a URL' },
     {