@ulpi/browse 0.1.0

package/src/commands/meta.ts

@@ -0,0 +1,358 @@
+/**
+ * Meta commands — tabs, server control, screenshots, chain, diff, snapshot, sessions
+ */
+
+import type { BrowserManager } from '../browser-manager';
+import type { SessionManager, Session } from '../session-manager';
+import { handleSnapshot } from '../snapshot';
+import { DEFAULTS } from '../constants';
+import * as Diff from 'diff';
+import * as fs from 'fs';
+
+const LOCAL_DIR = process.env.BROWSE_LOCAL_DIR || '/tmp';
+
+export async function handleMetaCommand(
+  command: string,
+  args: string[],
+  bm: BrowserManager,
+  shutdown: () => Promise<void> | void,
+  sessionManager?: SessionManager,
+  currentSession?: Session
+): Promise<string> {
+  switch (command) {
+    // ─── Tabs ──────────────────────────────────────────
+    case 'tabs': {
+      const tabs = await bm.getTabListWithTitles();
+      return tabs.map(t =>
+        `${t.active ? '→ ' : '  '}[${t.id}] ${t.title || '(untitled)'} — ${t.url}`
+      ).join('\n');
+    }
+
+    case 'tab': {
+      const id = parseInt(args[0], 10);
+      if (isNaN(id)) throw new Error('Usage: browse tab <id>');
+      bm.switchTab(id);
+      return `Switched to tab ${id}`;
+    }
+
+    case 'newtab': {
+      const url = args[0];
+      const id = await bm.newTab(url);
+      return `Opened tab ${id}${url ? ` → ${url}` : ''}`;
+    }
+
+    case 'closetab': {
+      const id = args[0] ? parseInt(args[0], 10) : undefined;
+      await bm.closeTab(id);
+      return `Closed tab${id ? ` ${id}` : ''}`;
+    }
+
+    // ─── Server Control ────────────────────────────────
+    case 'status': {
+      const page = bm.getPage();
+      const tabs = bm.getTabCount();
+      const lines = [
+        `Status: healthy`,
+        `URL: ${page.url()}`,
+        `Tabs: ${tabs}`,
+        `PID: ${process.pid}`,
+        `Uptime: ${Math.floor(process.uptime())}s`,
+      ];
+      if (sessionManager) {
+        lines.push(`Sessions: ${sessionManager.getSessionCount()}`);
+      }
+      if (currentSession) {
+        lines.push(`Session: ${currentSession.id}`);
+      }
+      return lines.join('\n');
+    }
+
+    case 'url': {
+      return bm.getCurrentUrl();
+    }
+
+    case 'stop': {
+      setTimeout(() => shutdown(), 100);
+      return 'Server stopped';
+    }
+
+    case 'restart': {
+      console.log('[browse] Restart requested. Exiting for CLI to restart.');
+      setTimeout(() => shutdown(), 100);
+      return 'Restarting...';
+    }
+
+    // ─── Sessions ───────────────────────────────────────
+    case 'sessions': {
+      if (!sessionManager) return '(session management not available)';
+      const list = sessionManager.listSessions();
+      if (list.length === 0) return '(no active sessions)';
+      return list.map(s =>
+        `  [${s.id}] ${s.tabs} tab(s) — ${s.url} — idle ${s.idleSeconds}s`
+      ).join('\n');
+    }
+
+    case 'session-close': {
+      if (!sessionManager) throw new Error('Session management not available');
+      const id = args[0];
+      if (!id) throw new Error('Usage: browse session-close <id>');
+      await sessionManager.closeSession(id);
+      return `Session "${id}" closed`;
+    }
+
+    // ─── Visual ────────────────────────────────────────
+    case 'screenshot': {
+      const page = bm.getPage();
+      const annotate = args.includes('--annotate');
+      const filteredArgs = args.filter(a => a !== '--annotate');
+      const screenshotPath = filteredArgs[0] || `${LOCAL_DIR}/browse-screenshot.png`;
+
+      if (annotate) {
+        const viewport = page.viewportSize() || { width: 1920, height: 1080 };
+        const annotations = await page.evaluate((vp) => {
+          const INTERACTIVE = ['a', 'button', 'input', 'select', 'textarea', 'details', 'summary'];
+          const INTERACTIVE_ROLES = ['button', 'link', 'textbox', 'checkbox', 'radio', 'combobox',
+            'listbox', 'menuitem', 'option', 'searchbox', 'slider', 'switch', 'tab'];
+          const results: Array<{ x: number; y: number; desc: string }> = [];
+          const scrollX = window.scrollX;
+          const scrollY = window.scrollY;
+
+          const candidates = document.querySelectorAll(
+            INTERACTIVE.join(',') + ',[role],[onclick],[tabindex],[data-action]'
+          );
+
+          for (let i = 0; i < candidates.length && results.length < 200; i++) {
+            const el = candidates[i] as HTMLElement;
+            if (el.offsetWidth === 0 && el.offsetHeight === 0) continue;
+
+            const tag = el.tagName.toLowerCase();
+            const role = el.getAttribute('role') || '';
+            const isInteractive = INTERACTIVE.includes(tag) || INTERACTIVE_ROLES.includes(role);
+            if (!isInteractive && !el.hasAttribute('onclick') &&
+                !el.hasAttribute('tabindex') && !el.hasAttribute('data-action') &&
+                getComputedStyle(el).cursor !== 'pointer') continue;
+
+            const rect = el.getBoundingClientRect();
+            if (rect.right < 0 || rect.left > vp.width) continue;
+            if (rect.width < 5 || rect.height < 5) continue;
+
+            const text = (el.textContent || '').trim().slice(0, 40).replace(/\s+/g, ' ');
+            const desc = `${tag}${role ? '[' + role + ']' : ''} "${text}"`;
+            results.push({ x: rect.left + scrollX, y: rect.top + scrollY, desc });
+          }
+          return results;
+        }, viewport);
+
+        const legend: string[] = [];
+        const badges = annotations.map((a, i) => {
+          const num = i + 1;
+          legend.push(`${num}. ${a.desc}`);
+          return { num, x: a.x, y: a.y };
+        });
+
+        try {
+          await page.evaluate((items: Array<{ num: number; x: number; y: number }>) => {
+            const container = document.createElement('div');
+            container.id = '__browse_annotate__';
+            container.style.cssText = 'position:absolute;top:0;left:0;width:0;height:0;z-index:2147483647;pointer-events:none;';
+            for (const b of items) {
+              const el = document.createElement('div');
+              el.style.cssText = `position:absolute;top:${b.y}px;left:${b.x}px;width:20px;height:20px;border-radius:50%;background:#e11d48;color:#fff;font:bold 11px/20px sans-serif;text-align:center;border:1px solid #fff;box-shadow:0 1px 3px rgba(0,0,0,.4);`;
+              el.textContent = String(b.num);
+              container.appendChild(el);
+            }
+            document.body.appendChild(container);
+          }, badges);
+
+          await page.screenshot({ path: screenshotPath, fullPage: true });
+        } finally {
+          await page.evaluate(() => {
+            document.getElementById('__browse_annotate__')?.remove();
+          }).catch(() => {});
+        }
+
+        return `Screenshot saved: ${screenshotPath}\n\nLegend:\n${legend.join('\n')}`;
+      }
+
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+      return `Screenshot saved: ${screenshotPath}`;
+    }
+
+    case 'pdf': {
+      const page = bm.getPage();
+      const pdfPath = args[0] || `${LOCAL_DIR}/browse-page.pdf`;
+      await page.pdf({ path: pdfPath, format: 'A4' });
+      return `PDF saved: ${pdfPath}`;
+    }
+
+    case 'responsive': {
+      const page = bm.getPage();
+      const prefix = args[0] || `${LOCAL_DIR}/browse-responsive`;
+      const viewports = [
+        { name: 'mobile', width: 375, height: 812 },
+        { name: 'tablet', width: 768, height: 1024 },
+        { name: 'desktop', width: 1920, height: 1080 },
+      ];
+      const originalViewport = page.viewportSize();
+      const results: string[] = [];
+
+      try {
+        for (const vp of viewports) {
+          await page.setViewportSize({ width: vp.width, height: vp.height });
+          const path = `${prefix}-${vp.name}.png`;
+          await page.screenshot({ path, fullPage: true });
+          results.push(`${vp.name} (${vp.width}x${vp.height}): ${path}`);
+        }
+      } finally {
+        if (originalViewport) {
+          await page.setViewportSize(originalViewport).catch(() => {});
+        }
+      }
+
+      return results.join('\n');
+    }
+
+    // ─── Chain ─────────────────────────────────────────
+    case 'chain': {
+      const jsonStr = args[0];
+      if (!jsonStr) throw new Error('Usage: echo \'[["goto","url"],["text"]]\' | browse chain');
+
+      let commands: string[][];
+      try {
+        commands = JSON.parse(jsonStr);
+      } catch {
+        throw new Error('Invalid JSON. Expected: [["command", "arg1", "arg2"], ...]');
+      }
+
+      if (!Array.isArray(commands)) throw new Error('Expected JSON array of commands');
+
+      const results: string[] = [];
+      const { handleReadCommand } = await import('./read');
+      const { handleWriteCommand } = await import('./write');
+
+      const WRITE_SET = new Set(['goto','back','forward','reload','click','fill','select','hover','type','press','scroll','wait','viewport','cookie','header','useragent','upload','dialog-accept','dialog-dismiss','emulate']);
+      const READ_SET  = new Set(['text','html','links','forms','accessibility','js','eval','css','attrs','state','dialog','console','network','cookies','storage','perf','devices']);
+
+      const sessionBuffers = currentSession?.buffers;
+
+      for (const cmd of commands) {
+        const [name, ...cmdArgs] = cmd;
+        try {
+          let result: string;
+          if (WRITE_SET.has(name))      result = await handleWriteCommand(name, cmdArgs, bm);
+          else if (READ_SET.has(name))  result = await handleReadCommand(name, cmdArgs, bm, sessionBuffers);
+          else                          result = await handleMetaCommand(name, cmdArgs, bm, shutdown, sessionManager, currentSession);
+          results.push(`[${name}] ${result}`);
+        } catch (err: any) {
+          results.push(`[${name}] ERROR: ${err.message}`);
+        }
+      }
+
+      return results.join('\n\n');
+    }
+
+    // ─── Diff ──────────────────────────────────────────
+    case 'diff': {
+      const [url1, url2] = args;
+      if (!url1 || !url2) throw new Error('Usage: browse diff <url1> <url2>');
+
+      const extractText = () => {
+        const body = document.body;
+        if (!body) return '';
+        const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'SVG']);
+        const lines: string[] = [];
+        const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT, {
+          acceptNode(node) {
+            let el = node.parentElement;
+            while (el && el !== body) {
+              if (SKIP.has(el.tagName)) return NodeFilter.FILTER_REJECT;
+              const style = getComputedStyle(el);
+              if (style.display === 'none' || style.visibility === 'hidden') return NodeFilter.FILTER_REJECT;
+              el = el.parentElement;
+            }
+            return NodeFilter.FILTER_ACCEPT;
+          },
+        });
+        let node: Node | null;
+        while ((node = walker.nextNode())) {
+          const text = (node.textContent || '').trim();
+          if (text) lines.push(text);
+        }
+        return lines.join('\n');
+      };
+
+      const previousTabId = bm.getActiveTabId();
+      const tempTabId = await bm.newTab(url1);
+      const tempPage = bm.getPage();
+
+      let text1: string;
+      let text2: string;
+      try {
+        text1 = await tempPage.evaluate(extractText);
+        await tempPage.goto(url2, { waitUntil: 'domcontentloaded', timeout: DEFAULTS.COMMAND_TIMEOUT_MS });
+        text2 = await tempPage.evaluate(extractText);
+      } finally {
+        await bm.closeTab(tempTabId);
+        if (bm.hasTab(previousTabId)) {
+          bm.switchTab(previousTabId);
+        }
+      }
+
+      const changes = Diff.diffLines(text1, text2);
+      const output: string[] = [`--- ${url1}`, `+++ ${url2}`, ''];
+
+      for (const part of changes) {
+        const prefix = part.added ? '+' : part.removed ? '-' : ' ';
+        const lines = part.value.split('\n').filter(l => l.length > 0);
+        for (const line of lines) {
+          output.push(`${prefix} ${line}`);
+        }
+      }
+
+      return output.join('\n');
+    }
+
+    // ─── Snapshot ─────────────────────────────────────
+    case 'snapshot': {
+      return await handleSnapshot(args, bm);
+    }
+
+    // ─── Snapshot Diff ──────────────────────────────
+    case 'snapshot-diff': {
+      const previous = bm.getLastSnapshot();
+      if (!previous) {
+        return 'No previous snapshot to compare against. Run "snapshot" first.';
+      }
+
+      const snapshotArgs = bm.getLastSnapshotOpts();
+      const current = await handleSnapshot(snapshotArgs, bm);
+
+      if (!current || current === '(no accessible elements found)' || current === '(no interactive elements found)') {
+        return 'Current page has no accessible elements to compare.';
+      }
+
+      const stripRefs = (text: string) => text.replace(/@e\d+ /g, '');
+      const changes = Diff.diffLines(stripRefs(previous), stripRefs(current));
+      const output: string[] = ['--- previous snapshot', '+++ current snapshot', ''];
+      let hasChanges = false;
+
+      for (const part of changes) {
+        if (part.added || part.removed) hasChanges = true;
+        const prefix = part.added ? '+' : part.removed ? '-' : ' ';
+        const lines = part.value.split('\n').filter(l => l.length > 0);
+        for (const line of lines) {
+          output.push(`${prefix} ${line}`);
+        }
+      }
+
+      if (!hasChanges) {
+        return 'No changes detected between snapshots.';
+      }
+
+      return output.join('\n');
+    }
+
+    default:
+      throw new Error(`Unknown meta command: ${command}`);
+  }
+}

package/src/commands/read.ts

@@ -0,0 +1,304 @@
+/**
+ * Read commands — extract data from pages without side effects
+ *
+ * text, html, links, forms, accessibility, js, eval, css, attrs, state,
+ * console, network, cookies, storage, perf
+ */
+
+import type { BrowserManager } from '../browser-manager';
+import { listDevices } from '../browser-manager';
+import type { SessionBuffers } from '../buffers';
+import * as fs from 'fs';
+
+export async function handleReadCommand(
+  command: string,
+  args: string[],
+  bm: BrowserManager,
+  buffers?: SessionBuffers
+): Promise<string> {
+  const page = bm.getPage();
+
+  switch (command) {
+    case 'text': {
+      // TreeWalker-based extraction — never appends to the live DOM,
+      // so MutationObservers are not triggered.
+      return await page.evaluate(() => {
+        const body = document.body;
+        if (!body) return '';
+        const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'SVG']);
+        const lines: string[] = [];
+        const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT, {
+          acceptNode(node) {
+            let el = node.parentElement;
+            while (el && el !== body) {
+              if (SKIP.has(el.tagName)) return NodeFilter.FILTER_REJECT;
+              const style = getComputedStyle(el);
+              if (style.display === 'none' || style.visibility === 'hidden') return NodeFilter.FILTER_REJECT;
+              el = el.parentElement;
+            }
+            return NodeFilter.FILTER_ACCEPT;
+          },
+        });
+        let node: Node | null;
+        while ((node = walker.nextNode())) {
+          const text = (node.textContent || '').trim();
+          if (text) lines.push(text);
+        }
+        return lines.join('\n');
+      });
+    }
+
+    case 'html': {
+      const selector = args[0];
+      if (selector) {
+        const resolved = bm.resolveRef(selector);
+        if ('locator' in resolved) {
+          return await resolved.locator.innerHTML({ timeout: 5000 });
+        }
+        return await page.innerHTML(resolved.selector);
+      }
+      return await page.content();
+    }
+
+    case 'links': {
+      const links = await page.evaluate(() =>
+        [...document.querySelectorAll('a[href]')].map(a => ({
+          text: a.textContent?.trim().slice(0, 120) || '',
+          href: (a as HTMLAnchorElement).href,
+        })).filter(l => l.text && l.href)
+      );
+      return links.map(l => `${l.text} → ${l.href}`).join('\n');
+    }
+
+    case 'forms': {
+      const forms = await page.evaluate(() => {
+        return [...document.querySelectorAll('form')].map((form, i) => {
+          const fields = [...form.querySelectorAll('input, select, textarea')].map(el => {
+            const input = el as HTMLInputElement;
+            return {
+              tag: el.tagName.toLowerCase(),
+              type: input.type || undefined,
+              name: input.name || undefined,
+              id: input.id || undefined,
+              placeholder: input.placeholder || undefined,
+              required: input.required || undefined,
+              value: input.value || undefined,
+              options: el.tagName === 'SELECT'
+                ? [...(el as HTMLSelectElement).options].map(o => ({ value: o.value, text: o.text }))
+                : undefined,
+            };
+          });
+          return {
+            index: i,
+            action: form.action || undefined,
+            method: form.method || 'get',
+            id: form.id || undefined,
+            fields,
+          };
+        });
+      });
+      return JSON.stringify(forms, null, 2);
+    }
+
+    case 'accessibility': {
+      const snapshot = await page.locator("body").ariaSnapshot();
+      return snapshot;
+    }
+
+    case 'js': {
+      const expr = args[0];
+      if (!expr) throw new Error('Usage: browse js <expression>');
+      const result = await page.evaluate(expr);
+      return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+    }
+
+    case 'eval': {
+      const filePath = args[0];
+      if (!filePath) throw new Error('Usage: browse eval <js-file>');
+      if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
+      const code = fs.readFileSync(filePath, 'utf-8');
+      const result = await page.evaluate(code);
+      return typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+    }
+
+    case 'css': {
+      const [selector, property] = args;
+      if (!selector || !property) throw new Error('Usage: browse css <selector> <property>');
+      const resolved = bm.resolveRef(selector);
+      if ('locator' in resolved) {
+        const value = await resolved.locator.evaluate(
+          (el, prop) => getComputedStyle(el).getPropertyValue(prop),
+          property
+        );
+        return value;
+      }
+      const value = await page.evaluate(
+        ([sel, prop]) => {
+          const el = document.querySelector(sel);
+          if (!el) return { __notFound: true, selector: sel };
+          return getComputedStyle(el).getPropertyValue(prop);
+        },
+        [resolved.selector, property]
+      );
+      if (typeof value === 'object' && value !== null && '__notFound' in value) {
+        throw new Error(`Element not found: ${(value as any).selector}`);
+      }
+      return value as string;
+    }
+
+    case 'state': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse state <selector>');
+      const resolved = bm.resolveRef(selector);
+      const locator = 'locator' in resolved
+        ? resolved.locator
+        : page.locator(resolved.selector);
+
+      const state: Record<string, unknown> = {};
+
+      // Core state checks — each wrapped individually since not all
+      // apply to every element type (e.g. isChecked only for checkbox/radio)
+      try { state.visible = await locator.isVisible(); } catch { state.visible = null; }
+      try { state.enabled = await locator.isEnabled(); } catch { state.enabled = null; }
+      try { state.checked = await locator.isChecked(); } catch { state.checked = null; }
+      try { state.editable = await locator.isEditable(); } catch { state.editable = null; }
+
+      // Properties that require evaluate — grouped in one call for efficiency
+      try {
+        const domProps = await locator.evaluate((el) => {
+          const input = el as HTMLInputElement;
+          return {
+            focused: document.activeElement === el,
+            tag: el.tagName.toLowerCase(),
+            type: input.type || null,
+            value: input.value ?? null,
+          };
+        });
+        Object.assign(state, domProps);
+      } catch {
+        state.focused = null;
+        state.tag = null;
+        state.type = null;
+        state.value = null;
+      }
+
+      // Bounding box — null when element is not visible
+      try { state.boundingBox = await locator.boundingBox(); } catch { state.boundingBox = null; }
+
+      return JSON.stringify(state, null, 2);
+    }
+
+    case 'attrs': {
+      const selector = args[0];
+      if (!selector) throw new Error('Usage: browse attrs <selector>');
+      const resolved = bm.resolveRef(selector);
+      if ('locator' in resolved) {
+        const attrs = await resolved.locator.evaluate((el) => {
+          const result: Record<string, string> = {};
+          for (const attr of el.attributes) {
+            result[attr.name] = attr.value;
+          }
+          return result;
+        });
+        return JSON.stringify(attrs, null, 2);
+      }
+      const attrs = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return { __notFound: true, selector: sel };
+        const result: Record<string, string> = {};
+        for (const attr of el.attributes) {
+          result[attr.name] = attr.value;
+        }
+        return result;
+      }, resolved.selector);
+      if (typeof attrs === 'object' && attrs !== null && '__notFound' in attrs) {
+        throw new Error(`Element not found: ${(attrs as any).selector}`);
+      }
+      return JSON.stringify(attrs, null, 2);
+    }
+
+    case 'dialog': {
+      const last = bm.getLastDialog();
+      if (!last) return '(no dialog detected)';
+      return JSON.stringify(last, null, 2);
+    }
+
+    case 'console': {
+      const cb = (buffers || bm.getBuffers()).consoleBuffer;
+      if (args[0] === '--clear') {
+        cb.length = 0;
+        return 'Console buffer cleared.';
+      }
+      if (cb.length === 0) return '(no console messages)';
+      return cb.map(e =>
+        `[${new Date(e.timestamp).toISOString()}] [${e.level}] ${e.text}`
+      ).join('\n');
+    }
+
+    case 'network': {
+      const nb = (buffers || bm.getBuffers()).networkBuffer;
+      if (args[0] === '--clear') {
+        nb.length = 0;
+        return 'Network buffer cleared.';
+      }
+      if (nb.length === 0) return '(no network requests)';
+      return nb.map(e =>
+        `${e.method} ${e.url} → ${e.status || 'pending'} (${e.duration || '?'}ms, ${e.size || '?'}B)`
+      ).join('\n');
+    }
+
+    case 'cookies': {
+      const cookies = await page.context().cookies();
+      return JSON.stringify(cookies, null, 2);
+    }
+
+    case 'storage': {
+      if (args[0] === 'set' && args[1]) {
+        const key = args[1];
+        const value = args[2] || '';
+        await page.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value]);
+        return `Set localStorage["${key}"] = "${value}"`;
+      }
+      const storage = await page.evaluate(() => ({
+        localStorage: { ...localStorage },
+        sessionStorage: { ...sessionStorage },
+      }));
+      return JSON.stringify(storage, null, 2);
+    }
+
+    case 'perf': {
+      const timings = await page.evaluate(() => {
+        const nav = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
+        if (!nav) return 'No navigation timing data available.';
+        return {
+          dns: Math.round(nav.domainLookupEnd - nav.domainLookupStart),
+          tcp: Math.round(nav.connectEnd - nav.connectStart),
+          ssl: Math.round(nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0),
+          ttfb: Math.round(nav.responseStart - nav.requestStart),
+          download: Math.round(nav.responseEnd - nav.responseStart),
+          domParse: Math.round(nav.domInteractive - nav.responseEnd),
+          domReady: Math.round(nav.domContentLoadedEventEnd - nav.startTime),
+          load: Math.round(nav.loadEventEnd - nav.startTime),
+          total: Math.round(nav.loadEventEnd - nav.startTime),
+        };
+      });
+      if (typeof timings === 'string') return timings;
+      return Object.entries(timings)
+        .map(([k, v]) => `${k.padEnd(12)} ${v}ms`)
+        .join('\n');
+    }
+
+    case 'devices': {
+      const filter = args.join(' ').toLowerCase();
+      const all = listDevices();
+      const filtered = filter ? all.filter(d => d.toLowerCase().includes(filter)) : all;
+      if (filtered.length === 0) {
+        return `No devices matching "${filter}". Run "browse devices" to see all.`;
+      }
+      return filtered.join('\n');
+    }
+
+    default:
+      throw new Error(`Unknown read command: ${command}`);
+  }
+}