@monoes/monobrowse 1.0.2 → 1.0.4

package/dist/src/cli/commands.js

@@ -6,14 +6,41 @@ import { output } from './output.js';
 import { createActionCommand } from './action.js';
 import { createPlatformCommand } from './platform.js';
 // Runtime state (single session per CLI process)
+const DEFAULT_PORT = 9222;
 let _client = null;
 let _sessionId = '';
 let _targetId = '';
-let _port = 9222;
+let _port = DEFAULT_PORT;
 let _refs = new Map();
 async function getBrowser() {
     return import('../index.js');
 }
+// Each CLI invocation is a fresh process, so this module's `_port` variable
+// is always freshly initialized to DEFAULT_PORT — a `--port 9333` passed to
+// an earlier `open` command has no effect on this process's own default.
+// Resolve the persisted "active port" (written by `open --port N`, read via
+// ref-cache.ts's saveActivePort/loadActivePort) so subsequent commands
+// attach to the browser the user actually opened instead of silently
+// launching/attaching to a second, unrelated Chrome instance on 9222.
+async function resolveDefaultPort(browser) {
+    const persisted = await browser.loadActivePortInfo();
+    if (!persisted)
+        return DEFAULT_PORT;
+    if (!persisted.launched) {
+        // connect-origin port: the browser belongs to someone else. If it died,
+        // relaunching our own headless Chrome on that port would squat the
+        // user's debug port and silently swap which browser commands act on —
+        // fail loudly instead.
+        try {
+            await fetch(`http://127.0.0.1:${persisted.port}/json/version`, { signal: AbortSignal.timeout(1500) });
+        }
+        catch {
+            await browser.clearActivePort();
+            throw new Error(`Connected browser on port ${persisted.port} is gone — re-run \`connect\` (or \`open\` to launch a fresh one).`);
+        }
+    }
+    return persisted.port;
+}
 async function ensureConnected(port, targetId) {
     const browser = await getBrowser();
     if (!_client || !_client.isConnected()) {
@@ -24,15 +51,45 @@ async function ensureConnected(port, targetId) {
             browser.teardownConsoleCapture(_sessionId);
             _client.close();
         }
-        _port = await browser.launchBrowser({ port, headless: true });
+        const effectivePort = port === DEFAULT_PORT ? await resolveDefaultPort(browser) : port;
+        _port = await browser.launchBrowser({ port: effectivePort, headless: true });
         const conn = await browser.connectToTarget(_port, targetId);
         _client = conn.client;
         _sessionId = conn.sessionId;
         _targetId = conn.target.id;
         _refs = new Map();
+        await hydrateRefsFromCache(browser, _targetId, conn.target.url);
     }
     return { client: _client, sessionId: _sessionId, targetId: _targetId };
 }
+// Each CLI invocation is a fresh process, so the in-memory _refs Map built by
+// a prior `snapshot` command is gone by the time a later `find`/`click`/etc.
+// command runs. Rehydrate it from the on-disk ref cache (written by
+// captureSnapshot call sites below) so refs resolved by a previous process
+// remain usable. Falls back silently to an empty Map if no cache exists.
+//
+// The cached `url` field (captured at snapshot time) is compared against the
+// browser's CURRENT url (`currentUrl`, from the just-fetched target info).
+// A stale `backendDOMNodeId` can still successfully resolve via
+// DOM.getBoxModel even after a same-tab SPA navigation or DOM mutation
+// changed what's actually at those coordinates — so a mismatch here means
+// EVERY ref in the cache is potentially pointing at the wrong element. We
+// hard-invalidate (skip hydration entirely, so any @eN lookup fails loudly
+// via resolveRef's "not found" error) rather than the weaker 30s time-based
+// staleness check below, which only warns.
+async function hydrateRefsFromCache(browser, targetId, currentUrl) {
+    const cached = await browser.loadRefCache(targetId);
+    if (!cached)
+        return;
+    if (currentUrl && cached.url && currentUrl !== cached.url) {
+        output.printError(`Stale references — page has navigated (cache: ${cached.url} → current: ${currentUrl}). Re-run snapshot before using @eN refs.`);
+        return; // leave _refs empty — do not attempt to resolve refs against a different page
+    }
+    _refs = cached.refs;
+    if (cached.stale) {
+        output.printWarning(`AX ref cache is ${Math.round(cached.ageMs / 1000)}s old — page may have changed since the last snapshot; re-run snapshot if refs don't resolve as expected`);
+    }
+}
 // 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.
@@ -122,11 +179,14 @@ async function switchToHeaded(url, port) {
     // Capture post-auth cookies
     const authCookies = await browser.getCookies(_client, _sessionId).catch(() => []);
     const authLocalStorage = await browser.getLocalStorage(_client, _sessionId).catch(() => ({}));
-    // Close headed session
+    // 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(_sessionId);
     browser.stopRequestCapture(_sessionId);
     browser.teardownDialogHandling(_sessionId);
     browser.teardownConsoleCapture(_sessionId);
+    await browser.closeBrowser(_client, headedPort);
     _client.close();
     _client = null;
     _sessionId = '';
@@ -151,6 +211,17 @@ async function switchToHeaded(url, port) {
         catch { /* ignore */ }
     }
 }
+/**
+ * Sanitize an image-format flag. The host CLI (monomind) defines a GLOBAL
+ * --format flag for output shaping (text|json|table, default 'text') that
+ * leaks into subcommand flags — so ctx.flags.format arrives as 'text' even
+ * when the user never passed it, and Chrome rejects it with
+ * "CDP error -32602: Invalid image format". Only trust values that are real
+ * image formats; otherwise fall back to the subcommand's own default.
+ */
+function imageFormat(value, allowed, fallback) {
+    return allowed.includes(value) ? value : fallback;
+}
 function print(msg) {
     process.stdout.write(msg + '\n');
 }
@@ -205,11 +276,18 @@ const openCommand = {
             _refs = new Map();
         }
         _port = await browser.launchBrowser({ port, headless: !forceHeaded });
+        // Persist the active port so subsequent CLI invocations (each a fresh
+        // process) default to attaching here instead of hardcoded 9222.
+        await browser.saveActivePort(_port);
         const conn = await browser.connectToTarget(_port);
         _client = conn.client;
         _sessionId = conn.sessionId;
         _targetId = conn.target.id;
         _refs = new Map();
+        // A snapshot taken before this navigation is no longer valid for the new
+        // page — drop the persisted ref cache so a stale process's weak
+        // time-based check can't resurrect it before the next explicit snapshot.
+        await browser.clearRefCache();
         if (ctx.flags.state && ctx.flags.session) {
             output.printWarning('Both --state and --session provided; --state takes precedence');
         }
@@ -261,12 +339,10 @@ const snapshotCommand = {
             selector: ctx.flags.selector,
         });
         _refs = result.refs;
+        await browser.saveRefCache(_targetId, result.url, _refs);
         const applyOutputLimits = (text) => {
-            let out = text;
             const maxOutput = ctx.flags['max-output'];
-            if (maxOutput && out.length > maxOutput) {
-                out = out.slice(0, maxOutput) + `\n[... truncated at ${maxOutput} chars]`;
-            }
+            let out = maxOutput ? truncateForOutput(text, maxOutput) : text;
             if (ctx.flags['content-boundaries']) {
                 const nonce = Math.random().toString(36).slice(2, 10);
                 out = `MONOMIND_PAGE_CONTENT nonce=${nonce} origin=${result.url}\n${out}\nEND_MONOMIND_PAGE_CONTENT nonce=${nonce}`;
@@ -464,16 +540,31 @@ const waitCommand = {
             const rawTimeout = Math.min(ctx.flags.timeout ?? 30000, MAX_DOWNLOAD_TIMEOUT);
             const finalPath = await new Promise((resolve, reject) => {
                 let guid = '';
+                let settled = false;
                 // C2: capture off() functions to avoid listener leaks
                 const offBegin = client.on('Browser.downloadWillBegin', (params) => { guid = params.guid; });
                 let offProgress;
                 // cleanup defined before setTimeout so the timeout callback can call it
                 let tid;
-                const cleanup = () => { clearTimeout(tid); offBegin?.(); offProgress?.(); };
-                tid = setTimeout(() => { cleanup(); reject(new Error('Download timed out')); }, rawTimeout);
+                let pollTid;
+                const cleanup = () => { clearTimeout(tid); clearInterval(pollTid); offBegin?.(); offProgress?.(); };
+                const finish = (path) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve(path);
+                };
+                const fail = (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    reject(err);
+                };
+                tid = setTimeout(() => fail(new Error('Download timed out')), rawTimeout);
                 offProgress = client.on('Browser.downloadProgress', async (params) => {
                     if (params.guid === guid && params.state === 'completed') {
-                        cleanup();
                         const { readdir, rename, rmdir } = await import('fs/promises');
                         const files = await readdir(downloadDir);
                         if (files.length > 0) {
@@ -481,18 +572,45 @@ const waitCommand = {
                             await mkdir(dirname(savePath), { recursive: true });
                             await rename(src, savePath);
                             await rmdir(downloadDir).catch(() => { }); // I1: cleanup temp dir
-                            resolve(savePath);
+                            finish(savePath);
                         }
                         else {
                             await rmdir(downloadDir).catch(() => { }); // I1: cleanup temp dir
-                            reject(new Error('Download completed but no file found'));
+                            fail(new Error('Download completed but no file found'));
                         }
                     }
                     else if (params.guid === guid && params.state === 'canceled') {
-                        cleanup();
-                        reject(new Error('Download was canceled'));
+                        fail(new Error('Download was canceled'));
                     }
                 });
+                // Fallback for the empty-guid race: this process's listener attaches
+                // AFTER a separate `click` process may have already started (and even
+                // finished) the download — so downloadWillBegin/downloadProgress for it
+                // were never observed here. While guid is still empty, poll the expected
+                // output path directly: if it already exists with a stable, non-zero
+                // size across two consecutive checks, treat the download as complete.
+                let lastSize = -1;
+                let stableReads = 0;
+                pollTid = setInterval(async () => {
+                    if (settled || guid)
+                        return; // a real CDP event has taken over
+                    try {
+                        const { stat } = await import('fs/promises');
+                        const st = await stat(savePath);
+                        if (st.isFile() && st.size > 0 && st.size === lastSize) {
+                            stableReads++;
+                            if (stableReads >= 2)
+                                finish(savePath);
+                        }
+                        else {
+                            stableReads = 0;
+                        }
+                        lastSize = st.size;
+                    }
+                    catch {
+                        // savePath not present yet — keep polling until timeout
+                    }
+                }, 300);
             });
             output.printSuccess(`Download saved: ${finalPath}`);
             return { success: true, data: { path: finalPath } };
@@ -536,7 +654,7 @@ const screenshotCommand = {
             result = await browser.captureScreenshot(client, sessionId, {
                 path: ctx.args[0],
                 fullPage: ctx.flags.full,
-                format: ctx.flags.format,
+                format: imageFormat(ctx.flags.format, ['png', 'jpeg', 'webp'], 'png'),
                 quality: ctx.flags.quality,
                 annotate,
                 refs: annotate ? _refs : undefined,
@@ -780,6 +898,9 @@ const navigateCommand = {
         else {
             throw new Error(`Unknown direction: ${direction}. Use: back|forward|reload`);
         }
+        // Refs captured before this navigation may now point at different content.
+        _refs = new Map();
+        await browser.clearRefCache();
         output.printSuccess(`Navigated: ${direction}`);
         return { success: true };
     },
@@ -935,6 +1056,7 @@ const stateCommand = {
                 await browser.clearLocalStorage(c, sid);
                 await browser.clearSessionStorage(c, sid);
                 _refs = new Map();
+                await browser.clearRefCache();
                 output.printSuccess('Browser state cleared (cookies, localStorage, sessionStorage, refs)');
                 return { success: true };
             }
@@ -1111,12 +1233,25 @@ const networkCommand = {
         return { success: true };
     },
 };
+// Default output cap for eval when --max-output isn't passed explicitly —
+// print(String(result)) had NO limit at all (unlike snapshot's --max-output),
+// so e.g. `eval "document.documentElement.outerHTML"` could dump megabytes
+// straight into an agent's context. An explicit --max-output still overrides
+// this default.
+const DEFAULT_EVAL_MAX_OUTPUT = 50_000;
+function truncateForOutput(text, maxOutput) {
+    if (!(maxOutput > 0) || text.length <= maxOutput)
+        return text;
+    return text.slice(0, maxOutput) + `\n[... truncated at ${maxOutput} chars]`;
+}
 const evalCommand = {
     name: 'eval',
     description: 'Evaluate JavaScript in page context. Usage: monomind browse eval "document.title"',
     options: [
         { name: 'json', type: 'boolean', description: 'Output as JSON', default: false },
         { name: 'stdin', type: 'boolean', description: 'Read JS expression from stdin (heredoc-friendly for multiline scripts)', default: false },
+        { name: 'max-output', type: 'number', description: `Truncate printed output to N characters (default ${DEFAULT_EVAL_MAX_OUTPUT}; 0 disables truncation)` },
+        { name: 'timeout', type: 'number', description: 'Max ms to wait for evaluation to settle (default 30000)' },
     ],
     action: async (ctx) => {
         const { client, sessionId } = await ensureConnected(_port);
@@ -1130,12 +1265,14 @@ const evalCommand = {
         }
         if (!expr)
             throw new Error('Usage: monomind browse eval "<expression>" (or pipe with --stdin)');
-        const result = await browser.evaluateJs(client, sessionId, expr);
+        const timeoutMs = ctx.flags.timeout;
+        const result = await browser.evaluateJs(client, sessionId, expr, timeoutMs);
+        const maxOutput = ctx.flags['max-output'] ?? DEFAULT_EVAL_MAX_OUTPUT;
         if (ctx.flags.json) {
-            print(JSON.stringify({ data: result }));
+            print(truncateForOutput(JSON.stringify({ data: result }), maxOutput));
         }
         else {
-            print(String(result ?? ''));
+            print(truncateForOutput(String(result ?? ''), maxOutput));
         }
         return { success: true, data: { result } };
     },
@@ -1176,10 +1313,66 @@ const closeCommand = {
             _sessionId = '';
             _targetId = '';
             _refs = new Map();
+            // Session is gone — forget the persisted port and stale refs so later
+            // invocations don't chase a dead endpoint (or the wrong elements).
+            await browser.clearActivePort();
+            await browser.clearRefCache();
             output.printSuccess('Browser session closed');
         }
         else {
-            output.printInfo('No active browser session');
+            // Each CLI invocation is a fresh process, so `close` almost always
+            // lands here. The persisted port file is the real session handle:
+            // if monobrowse LAUNCHED that browser (open), gracefully Browser.close
+            // it — otherwise every open→close cycle leaks a headless Chrome. If we
+            // merely ATTACHED to it (connect, launched:false), never kill it: it's
+            // the user's own browser. Either way, forget the port and refs.
+            const browser = await getBrowser();
+            const persisted = await browser.loadActivePortInfo();
+            if (persisted?.launched) {
+                try {
+                    const conn = await browser.connectToTarget(persisted.port);
+                    try {
+                        await browser.closeBrowser(conn.client, persisted.port);
+                    }
+                    finally {
+                        // Always drop our websocket — a hung Browser.close must not keep
+                        // this CLI process's event loop alive.
+                        try {
+                            conn.client.close();
+                        }
+                        catch { /* already gone */ }
+                    }
+                    // closeBrowser has no PID fallback in a fresh process (launchedPids
+                    // is per-process) — re-probe so we report what actually happened.
+                    // Poll briefly: Browser.close is acknowledged before the process
+                    // actually exits, so a single immediate probe false-alarms.
+                    let stillUp = true;
+                    const probeDeadline = Date.now() + 3000;
+                    while (stillUp && Date.now() < probeDeadline) {
+                        try {
+                            await fetch(`http://127.0.0.1:${persisted.port}/json/version`, { signal: AbortSignal.timeout(800) });
+                            await new Promise(r => setTimeout(r, 300));
+                        }
+                        catch {
+                            stillUp = false;
+                        }
+                    }
+                    if (stillUp)
+                        output.printWarning(`Browser on port ${persisted.port} did not exit — kill it manually if needed`);
+                    else
+                        output.printSuccess(`Closed browser on port ${persisted.port}`);
+                }
+                catch {
+                    output.printInfo(`No browser answering on port ${persisted.port} — nothing to close`);
+                }
+            }
+            else {
+                output.printInfo(persisted
+                    ? `Detached from browser on port ${persisted.port} (attached via connect — left running)`
+                    : 'No active browser session');
+            }
+            await browser.clearActivePort();
+            await browser.clearRefCache();
         }
         return { success: true };
     },
@@ -2318,6 +2511,7 @@ const diffCommand = {
             await browser.waitFor(client, sessionId, { load: 'load', timeout: 15000 });
             const snap2 = await browser.captureSnapshot(client, sessionId, { interactiveOnly: ctx.flags.interactive });
             _refs = snap2.refs;
+            await browser.saveRefCache(_targetId, snap2.url, _refs);
             // Text diff
             const lines1 = snap1.text.split('\n');
             const lines2 = snap2.text.split('\n');
@@ -2356,6 +2550,10 @@ const pushstateCommand = {
         if (!url)
             throw new Error('Usage: monomind browse pushstate <url>');
         await browser.pushState(client, sessionId, url);
+        // SPA navigation changes what's on the page without a full page load —
+        // refs captured before this pushState call may now resolve to different content.
+        _refs = new Map();
+        await browser.clearRefCache();
         output.printSuccess(`pushState: ${url}`);
         return { success: true };
     },
@@ -2390,6 +2588,52 @@ function tokenizeBatchCommand(input) {
         tokens.push(current);
     return tokens;
 }
+/**
+ * Splits one line of a `batch` command string into a subcommand name, its
+ * args, and any recognized leading flags.
+ *
+ * `eval` is special-cased: its sole argument is a raw JS expression, which
+ * legitimately contains its own string-literal quotes (e.g.
+ * `eval document.querySelector('a')`). tokenizeBatchCommand's shell-style
+ * word-splitting treats `'...'`/`"..."` as grouping delimiters and discards
+ * them — correct for a value like `fill @e1 "some text"`, but for `eval` it
+ * silently deletes the expression's own quotes, turning a string literal
+ * into a bare (undefined) identifier reference and producing a
+ * ReferenceError instead of evaluating the intended expression. For `eval`,
+ * only its own known --flags are consumed from the front; everything after
+ * them is taken verbatim as one argument, untouched by tokenization.
+ *
+ * Exported for direct unit testing — not part of the CLI's public API.
+ */
+export function parseBatchCommandLine(cmdStr) {
+    const trimmed = cmdStr.trim();
+    const evalMatch = trimmed.match(/^eval\b\s*/);
+    if (!evalMatch) {
+        const parts = tokenizeBatchCommand(trimmed);
+        return { subName: parts[0], subArgs: parts.slice(1), flags: {} };
+    }
+    let rest = trimmed.slice(evalMatch[0].length);
+    const flags = {};
+    let consumedAnother = true;
+    while (consumedAnother) {
+        consumedAnother = false;
+        const withValue = rest.match(/^--(max-output|timeout)\s+(-?\d+)\s*/);
+        if (withValue) {
+            flags[withValue[1]] = Number(withValue[2]);
+            rest = rest.slice(withValue[0].length);
+            consumedAnother = true;
+            continue;
+        }
+        const boolFlag = rest.match(/^--(json|stdin)\b\s*/);
+        if (boolFlag) {
+            flags[boolFlag[1]] = true;
+            rest = rest.slice(boolFlag[0].length);
+            consumedAnother = true;
+            continue;
+        }
+    }
+    return { subName: 'eval', subArgs: [rest], flags };
+}
 const batchCommand = {
     name: 'batch',
     description: 'Execute multiple commands. Usage: monomind browse batch "open url" "snapshot -i" "click @e1"',
@@ -2403,9 +2647,7 @@ const batchCommand = {
             throw new Error('Usage: monomind browse batch "cmd1" "cmd2" ...');
         const results = [];
         for (const cmdStr of commands) {
-            const parts = tokenizeBatchCommand(cmdStr);
-            const subName = parts[0];
-            const subArgs = parts.slice(1);
+            const { subName, subArgs, flags: preParsedFlags } = parseBatchCommandLine(cmdStr);
             const subCmd = browseCommand.subcommands?.find((s) => s.name === subName);
             if (!subCmd?.action) {
                 const err = `Unknown command: ${subName}`;
@@ -2415,7 +2657,7 @@ const batchCommand = {
                 continue;
             }
             try {
-                const parsedFlags = { _: [] };
+                const parsedFlags = { _: [], ...preParsedFlags };
                 const consumedIndices = new Set();
                 // Parse --flags from subArgs, tracking which indices are flag names/values
                 for (let i = 0; i < subArgs.length; i++) {
@@ -2525,7 +2767,7 @@ const removeinitscriptCommand = {
 };
 const connectCommand = {
     name: 'connect',
-    description: 'Connect to existing Chrome instance. Usage: monomind browse connect [--port 9222] [--target <id>] [--auto-connect]',
+    description: 'Connect to existing Chrome instance; later commands reuse this session (note: `open` without --port still launches on its own default). Usage: monomind browse connect [--port 9222] [--target <id>] [--auto-connect]',
     options: [
         { name: 'port', short: 'p', type: 'number', description: 'CDP port', default: 9222 },
         { name: 'target', type: 'string', description: 'Target ID to attach to' },
@@ -2588,6 +2830,12 @@ const connectCommand = {
         _targetId = conn.target.id;
         _port = port;
         _refs = new Map();
+        // Persist the port like `open` does — without this, the NEXT CLI process
+        // (each command is a fresh process) resolves the hardcoded default and
+        // tries to launch its own Chrome on 9222 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.saveActivePort(port, { launched: false });
         const url = await browser.getCurrentUrl(_client, _sessionId);
         const title = await browser.getCurrentTitle(_client, _sessionId);
         output.printSuccess(`Connected: ${title} (${url})`);
@@ -2611,7 +2859,7 @@ const recordCommand = {
         switch (action) {
             case 'start':
                 await browser.startRecording(client, sessionId, {
-                    format: ctx.flags.format,
+                    format: imageFormat(ctx.flags.format, ['jpeg', 'png'], 'jpeg'),
                     quality: ctx.flags.quality,
                 });
                 output.printSuccess('Recording started');
@@ -2627,12 +2875,12 @@ const recordCommand = {
             case 'restart': {
                 const prevStatus = browser.getRecordingStatus(sessionId);
                 let prevPath;
-                if (prevStatus.recording) {
+                if (prevStatus.recording || prevStatus.autoStopped) {
                     prevPath = await browser.stopRecording(client, sessionId, ctx.args[1]);
                     output.printInfo(`Previous recording saved: ${prevPath}`);
                 }
                 await browser.startRecording(client, sessionId, {
-                    format: ctx.flags.format,
+                    format: imageFormat(ctx.flags.format, ['jpeg', 'png'], 'jpeg'),
                     quality: ctx.flags.quality,
                 });
                 output.printSuccess('Recording restarted');
@@ -2643,7 +2891,7 @@ const recordCommand = {
                 if (ctx.flags.json)
                     print(JSON.stringify({ data: status }));
                 else
-                    print(`Recording: ${status.recording} | Frames: ${status.frames}`);
+                    print(`Recording: ${status.recording} | Frames: ${status.frames}${status.autoStopped ? ' (auto-stopped: buffer limit reached — run "record stop" to save)' : ''}`);
                 return { success: true, data: status };
             }
             default: