v1.57.8.0 feat: browse js/eval --out render-to-file (canonical Chromium for offline rendering) (#1929)

* feat(browse): js/eval --out render-to-file with write-capability gate Add --out <file> / --raw to js and eval so an evaluate result is written straight to disk (base64 data URLs auto-decoded to bytes, charset-validated before decode, parent dirs created) instead of serialized back through the CLI. --out is modeled as a per-invocation WRITE: it requires write scope, is never dispatchable over the pair-agent tunnel (canDispatchOverTunnel now consults args), and counts as a mutation for watch-mode and tab-ownership. Shared parseOutArgs/hasOutArg/resultToString helpers keep the handler and the gate in sync. Tests cover the parser, render-to-file paths, and tunnel guards. * docs(browse): offline render mode + canonical-Chromium guidance Document the blessed offline-render path (headless, no proxy/Xvfb): visual output via screenshot --selector, bytes a function returns via js --out. Add the puppeteer->browse cheatsheet row, a "don't bundle your own Chromium" note (browse skill + CONTRIBUTING), and the --out/--raw command descriptions. Regenerate browse/SKILL.md, SKILL.md, and gstack/llms.txt from the templates. * chore: bump version and changelog (v1.59.1.0) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: document js/eval --out render-to-file in BROWSER.md reference (v1.59.1.0) The js and eval reference rows in BROWSER.md drifted: every other reference surface (SKILL.md, gstack/llms.txt, browse/SKILL.md) already shows the new [--out <file>] [--raw] flags from v1.59.1.0, but the complete browser reference still showed the pre-feature signatures. Add the flags plus the WRITE-capability / no-tunnel note so the reference matches what shipped. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: re-version 1.59.1.0 -> 1.57.8.0 (natural PATCH from 1.57.7.0) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-01 05:55:37 +02:00 · 2026-06-09 21:02:30 -07:00
parent 1626d4857b
commit 421460f03a
14 changed files with 553 additions and 27 deletions
@@ -106,8 +106,8 @@ export const COMMAND_DESCRIPTIONS: Record<string, { category: string; descriptio
  'media':   { category: 'Reading', description: 'All media elements (images, videos, audio) with URLs, dimensions, types', usage: 'media [--images|--videos|--audio] [selector]' },
  'data':    { category: 'Reading', description: 'Structured data: JSON-LD, Open Graph, Twitter Cards, meta tags', usage: 'data [--jsonld|--og|--meta|--twitter]' },
  // Inspection
-  'js':      { category: 'Inspection', description: 'Run inline JavaScript expression in the page context and return result as string. Same JS sandbox as eval; the only difference is js takes an inline expr while eval reads from a file.', usage: 'js <expr>' },
-  'eval':    { category: 'Inspection', description: 'Run JavaScript from a file in the page context and return result as string. Path must resolve under /tmp or cwd (no traversal). Use eval for multi-line scripts; use js for one-liners.', usage: 'eval <file>' },
+  'js':      { category: 'Inspection', description: 'Run inline JavaScript expression in the page context and return result as string. Same JS sandbox as eval; the only difference is js takes an inline expr while eval reads from a file. With --out <file>, the result is written to disk instead of returned (a base64 data URL is decoded to raw bytes unless --raw is given) — ideal for rasterizing local renders to PNG without serializing megabytes back through the CLI. --out makes the invocation a WRITE (needs write scope, never allowed over the tunnel).', usage: 'js <expr> [--out <file>] [--raw]' },
+  'eval':    { category: 'Inspection', description: 'Run JavaScript from a file in the page context and return result as string. Path must resolve under /tmp or cwd (no traversal). Use eval for multi-line scripts; use js for one-liners. With --out <file>, the result is written to disk (base64 data URL decoded to bytes unless --raw); --out makes the invocation a WRITE (needs write scope, never allowed over the tunnel).', usage: 'eval <file> [--out <file>] [--raw]' },
  'css':     { category: 'Inspection', description: 'Computed CSS value', usage: 'css <sel> <prop>' },
  'attrs':   { category: 'Inspection', description: 'Element attributes as JSON', usage: 'attrs <sel|@ref>' },
  'is':      { category: 'Inspection', description: 'State check on element. Valid <prop> values: visible, hidden, enabled, disabled, checked, editable, focused (case-sensitive). <sel> accepts a CSS selector OR an @ref token from a prior snapshot (e.g. @e3, @c1) — refs are interchangeable with selectors anywhere a selector is expected.', usage: 'is <prop> <sel|@ref>' },
@@ -13,7 +13,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { TEMP_DIR } from './platform';
 import { inspectElement, formatInspectorResult, getModificationHistory } from './cdp-inspector';
-import { validateReadPath } from './path-security';
+import { validateReadPath, validateOutputPath } from './path-security';
 import { stripLoneSurrogates } from './sanitize';
 // Re-export for backward compatibility (tests import from read-commands)
 export { validateReadPath } from './path-security';
@@ -46,6 +46,117 @@ function wrapForEvaluate(code: string): string {
    : `(async()=>(${trimmed}))()`;
 }

+/** Flags split out of `js`/`eval` args by parseOutArgs. */
+export interface OutArgs {
+  outPath?: string;
+  raw: boolean;
+  rest: string[];
+}
+
+/**
+ * Parse `--out <path>` / `--out=<path>` and `--raw` / `--raw=true|false` out of an
+ * arg list, returning the flags plus the remaining positional args (`rest`).
+ *
+ * Single source of truth shared by the js/eval handlers and the write-capability
+ * gate in server.ts, so the two never disagree on what counts as an `--out`
+ * invocation. Throws on malformed usage (repeated `--out`, missing value, bad
+ * `--raw` value) so the user gets a clear error instead of a silent misparse.
+ */
+export function parseOutArgs(args: string[]): OutArgs {
+  let outPath: string | undefined;
+  let raw = false;
+  const rest: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--out') {
+      if (outPath !== undefined) throw new Error('--out specified more than once');
+      const val = args[i + 1];
+      if (val === undefined || val.startsWith('--')) throw new Error('--out requires a file path');
+      outPath = val;
+      i++;
+    } else if (a.startsWith('--out=')) {
+      if (outPath !== undefined) throw new Error('--out specified more than once');
+      const val = a.slice('--out='.length);
+      if (val === '') throw new Error('--out requires a file path');
+      outPath = val;
+    } else if (a === '--raw') {
+      raw = true;
+    } else if (a.startsWith('--raw=')) {
+      const v = a.slice('--raw='.length).toLowerCase();
+      if (v !== 'true' && v !== 'false') throw new Error('--raw must be true or false');
+      raw = v === 'true';
+    } else {
+      rest.push(a);
+    }
+  }
+  return { outPath, raw, rest };
+}
+
+/**
+ * True iff an arg list contains an `--out` flag in any accepted form
+ * (`--out <path>` or `--out=<path>`). Used by the write-capability gate to
+ * decide whether an otherwise-read command (`js`/`eval`) is actually a write
+ * invocation. Mirrors parseOutArgs's `--out` recognition exactly. Never throws —
+ * a malformed `--out=` still counts as an out attempt (fail safe: gate it).
+ */
+export function hasOutArg(args: string[]): boolean {
+  return args.some(a => a === '--out' || a.startsWith('--out='));
+}
+
+/**
+ * Convert an evaluate() result to its string form — the exact conversion `js`/`eval`
+ * used inline before `--out` existed. Kept byte-for-byte: `typeof === 'object'`
+ * (which includes `null`) goes through JSON.stringify (so `null` → `"null"`);
+ * everything else via `String(result ?? '')` (so `undefined` → `''`). JSON.stringify
+ * still throws on circular / BigInt-bearing results, same as before.
+ */
+export function resultToString(result: unknown): string {
+  return typeof result === 'object'
+    ? JSON.stringify(result, null, 2)
+    : String(result ?? '');
+}
+
+/**
+ * Write an evaluate result string to disk for `--out`, returning bytes written.
+ *
+ * When the result is a base64 data URL (`data:<type>;...;base64,<payload>`) and
+ * `raw` is false, decode the payload to raw bytes — this is the Excalidraw / og-image
+ * path where a render function returns a PNG data URL. The header is parsed
+ * case-insensitively and split on the FIRST comma (data URLs can contain commas in
+ * the payload). The payload is validated against the base64 charset before decoding,
+ * because `Buffer.from(_, 'base64')` silently drops invalid characters and would
+ * otherwise write corrupted bytes. `--raw` forces a literal write even for data URLs.
+ *
+ * Non-base64 strings are surrogate-sanitized (matching what the stdout egress path
+ * did before) and written as UTF-8. Parent directories are created — validateOutputPath
+ * gates the location but does not mkdir.
+ */
+export function writeEvalResult(outPath: string, str: string, opts: { raw: boolean }): number {
+  validateOutputPath(outPath);
+  fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+
+  if (!opts.raw && str.startsWith('data:')) {
+    const comma = str.indexOf(',');
+    if (comma !== -1) {
+      const header = str.slice('data:'.length, comma);
+      const tokens = header.split(';').map(t => t.trim().toLowerCase());
+      if (tokens.includes('base64')) {
+        const payload = str.slice(comma + 1).replace(/\s+/g, '');
+        if (!/^[A-Za-z0-9+/]*={0,2}$/.test(payload)) {
+          throw new Error('--out: malformed base64 in data URL (decode would corrupt output)');
+        }
+        const buf = Buffer.from(payload, 'base64');
+        fs.writeFileSync(outPath, buf);
+        return buf.length;
+      }
+    }
+  }
+
+  const buf = Buffer.from(stripLoneSurrogates(str), 'utf-8');
+  fs.writeFileSync(outPath, buf);
+  return buf.length;
+}
+
 /**
 * Extract clean text from a page (strips script/style/noscript/svg).
 * Exported for DRY reuse in meta-commands (diff).
@@ -179,24 +290,36 @@ export async function handleReadCommand(
    }

    case 'js': {
-      const expr = args[0];
-      if (!expr) throw new Error('Usage: browse js <expression>');
+      const { outPath, raw, rest } = parseOutArgs(args);
+      const expr = rest[0];
+      if (!expr) throw new Error('Usage: browse js <expression> [--out <file>] [--raw]');
      if (bm) assertJsOriginAllowed(bm, page.url());
      const wrapped = wrapForEvaluate(expr);
      const result = await target.evaluate(wrapped);
-      return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+      const str = resultToString(result);
+      if (outPath) {
+        const n = writeEvalResult(outPath, str, { raw });
+        return `JS result written: ${outPath} (${n} bytes)`;
+      }
+      return str;
    }

    case 'eval': {
-      const filePath = args[0];
-      if (!filePath) throw new Error('Usage: browse eval <js-file>');
+      const { outPath, raw, rest } = parseOutArgs(args);
+      const filePath = rest[0];
+      if (!filePath) throw new Error('Usage: browse eval <js-file> [--out <file>] [--raw]');
      if (bm) assertJsOriginAllowed(bm, page.url());
      validateReadPath(filePath);
      if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
      const code = fs.readFileSync(filePath, 'utf-8');
      const wrapped = wrapForEvaluate(code);
      const result = await target.evaluate(wrapped);
-      return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+      const str = resultToString(result);
+      if (outPath) {
+        const n = writeEvalResult(outPath, str, { raw });
+        return `Eval result written: ${outPath} (${n} bytes)`;
+      }
+      return str;
    }

    case 'css': {
@@ -14,7 +14,7 @@
 */

 import { BrowserManager } from './browser-manager';
-import { handleReadCommand } from './read-commands';
+import { handleReadCommand, hasOutArg } from './read-commands';
 import { handleWriteCommand } from './write-commands';
 import { handleMetaCommand } from './meta-commands';
 import { handleCookiePickerRoute, hasActivePicker } from './cookie-picker-routes';
@@ -330,9 +330,15 @@ export const TUNNEL_COMMANDS = new Set<string>([
 * without standing up an HTTP listener. Behavior is identical to the inline
 * check; the function canonicalizes the command (so aliases hit the same set)
 * and returns false for null/undefined input.
+ *
+ * `args` is consulted so an `--out` invocation (e.g. `eval --out <file>`) is
+ * NEVER tunnel-dispatchable: `--out` turns an otherwise-readable command into a
+ * local-disk WRITE, and the tunnel surface never grants disk-write capability to
+ * remote paired agents. Omitting `args` preserves the old command-only behavior.
 */
-export function canDispatchOverTunnel(command: string | undefined | null): boolean {
+export function canDispatchOverTunnel(command: string | undefined | null, args?: string[]): boolean {
  if (typeof command !== 'string' || command.length === 0) return false;
+  if (Array.isArray(args) && hasOutArg(args)) return false;
  const cmd = canonicalizeCommand(command);
  return TUNNEL_COMMANDS.has(cmd);
 }
@@ -716,6 +722,19 @@ if (BROWSE_PARENT_PID > 0 && !IS_HEADED_WATCHDOG) {
 import { READ_COMMANDS, WRITE_COMMANDS, META_COMMANDS } from './commands';
 export { READ_COMMANDS, WRITE_COMMANDS, META_COMMANDS };

+/**
+ * Whether an invocation should be treated as a WRITE for capability gating
+ * (scope, watch-mode block, tab ownership, tunnel). A command is a write if it
+ * mutates state (`WRITE_COMMANDS`) OR it carries an `--out` flag — `js`/`eval
+ * --out` writes the evaluate result to local disk, so the capability is
+ * per-invocation, not per-command-name. This deliberately does NOT change
+ * dispatch routing: `js`/`eval` still route to `handleReadCommand`; only the
+ * security gates consult this.
+ */
+function isWriteInvocation(command: string, args: string[]): boolean {
+  return WRITE_COMMANDS.has(command) || hasOutArg(args);
+}
+
 // ─── Inspector State (in-memory) ──────────────────────────────
 let inspectorData: InspectorResult | null = null;
 let inspectorTimestamp: number = 0;
@@ -957,6 +976,19 @@ async function handleCommandInternalImpl(
      };
    }

+    // `--out` writes the evaluate result to local disk, which is a WRITE
+    // capability distinct from the JS-exec (admin) capability js/eval need.
+    // Require write scope so an admin-but-not-write token can't write files.
+    if (hasOutArg(args) && !tokenInfo.scopes.includes('write')) {
+      return {
+        status: 403, json: true,
+        result: JSON.stringify({
+          error: `"--out" writes to disk and requires the "write" scope`,
+          hint: `Your scopes: ${tokenInfo.scopes.join(', ')}. Re-pair with write access to use --out.`,
+        }),
+      };
+    }
+
    // Domain check for navigation commands
    if ((command === 'goto' || command === 'newtab') && args[0]) {
      if (!checkDomain(tokenInfo, args[0])) {
@@ -1011,7 +1043,7 @@ async function handleCommandInternalImpl(
  // Skip for `newtab` — it creates a tab rather than accessing one.
  if (command !== 'newtab' && tokenInfo && tokenInfo.clientId !== 'root' && tokenInfo.tabPolicy === 'own-only') {
    const targetTab = tabId ?? browserManager.getActiveTabId();
-    if (!browserManager.checkTabAccess(targetTab, tokenInfo.clientId, { isWrite: WRITE_COMMANDS.has(command), ownOnly: true })) {
+    if (!browserManager.checkTabAccess(targetTab, tokenInfo.clientId, { isWrite: isWriteInvocation(command, args), ownOnly: true })) {
      return {
        status: 403, json: true,
        result: JSON.stringify({
@@ -1035,8 +1067,9 @@ async function handleCommandInternalImpl(
    };
  }

-  // Block mutation commands while watching (read-only observation mode)
-  if (browserManager.isWatching() && WRITE_COMMANDS.has(command)) {
+  // Block mutation commands while watching (read-only observation mode).
+  // `--out` invocations count as mutations (they write the result to disk).
+  if (browserManager.isWatching() && isWriteInvocation(command, args)) {
    return {
      status: 400, json: true,
      result: JSON.stringify({ error: 'Cannot run mutation commands while watching. Run `$B watch stop` first.' }),
@@ -2650,11 +2683,11 @@ export function buildFetchHandler(cfg: ServerConfig): ServerHandle {
        // Paired remote agents drive the browser but cannot configure the
        // daemon, launch new browsers, import cookies, or rotate tokens.
        if (surface === 'tunnel') {
-          if (!canDispatchOverTunnel(body?.command)) {
+          if (!canDispatchOverTunnel(body?.command, body?.args)) {
            logTunnelDenial(req, url, `disallowed_command:${body?.command}`);
            return new Response(JSON.stringify({
              error: `Command '${body?.command}' is not allowed over the tunnel surface`,
-              hint: `Tunnel commands: ${[...TUNNEL_COMMANDS].sort().join(', ')}`,
+              hint: `Tunnel commands: ${[...TUNNEL_COMMANDS].sort().join(', ')}. Note: --out (disk write) is never allowed over the tunnel.`,
            }), { status: 403, headers: { 'Content-Type': 'application/json' } });
          }
        }