barebrowse 0.1.0 → 0.2.0

package/examples/yt-demo.js

@@ -0,0 +1,137 @@
+/**
+ * YouTube headed-mode demo — search and play "Family Portrait Pink"
+ *
+ * SETUP — run this command first in a separate terminal:
+ *
+ *   chromium-browser --remote-debugging-port=9222 \
+ *     --disable-notifications \
+ *     --autoplay-policy=no-user-gesture-required \
+ *     --use-fake-device-for-media-stream \
+ *     --use-fake-ui-for-media-stream \
+ *     --disable-features=MediaRouter
+ *
+ * Then run this script:
+ *
+ *   node examples/yt-demo.js
+ *
+ * Uses Firefox cookies to bypass YouTube consent wall.
+ */
+
+import { connect } from '../src/index.js';
+
+function wait(ms = 2000) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function findRef(snapshot, role, nameFragment) {
+  const escaped = nameFragment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`${role} "[^"]*${escaped}[^"]*".*?\\[ref=([^\\]]+)\\]`, 'i');
+  const m = snapshot.match(re);
+  return m ? m[1] : null;
+}
+
+function printSnap(snapshot, limit = 600) {
+  const t = snapshot.length > limit
+    ? snapshot.slice(0, limit) + `\n... (${snapshot.length - limit} more chars)`
+    : snapshot;
+  console.log(t);
+}
+
+async function main() {
+  console.log('=== YouTube Demo — Family Portrait by Pink ===\n');
+  console.log('Connecting to Chromium on port 9222...\n');
+
+  const page = await connect({ mode: 'headed', port: 9222 });
+
+  try {
+    // Step 1: Inject Firefox cookies for youtube.com (bypasses consent wall)
+    console.log('[1] Injecting Firefox cookies for youtube.com...');
+    await page.injectCookies('https://www.youtube.com', { browser: 'firefox' });
+    await wait(500);
+
+    // Step 2: Navigate to YouTube
+    console.log('[2] Navigating to YouTube...');
+    await page.goto('https://www.youtube.com');
+    await wait(2000);
+
+    // Step 3: Find the search box
+    console.log('[3] Taking snapshot to find search box...');
+    let snap = await page.snapshot();
+
+    let searchRef = findRef(snap, 'combobox', 'Search')
+      || findRef(snap, 'textbox', 'Search')
+      || findRef(snap, 'searchbox', 'Search');
+
+    if (!searchRef) {
+      console.log('  Could not find search box. Snapshot:');
+      printSnap(snap, 1000);
+      return;
+    }
+
+    // Step 4: Type the search query
+    console.log(`[4] Found search box ref=${searchRef}, typing query...`);
+    await page.click(searchRef);
+    await wait(500);
+    await page.type(searchRef, 'Family Portrait Pink', { clear: true });
+    await wait(1000);
+
+    // Step 5: Press Enter to search
+    // YouTube is an SPA — loadEventFired won't fire, so just wait for results to render
+    console.log('[5] Pressing Enter to search...');
+    await page.press('Enter');
+    await wait(3000);
+
+    // Step 6: Find the video in results
+    console.log('[6] Looking for Family Portrait in results...');
+    snap = await page.snapshot();
+
+    let videoRef = findRef(snap, 'link', 'Family Portrait')
+      || findRef(snap, 'link', 'family portrait');
+
+    if (!videoRef) {
+      console.log('  Could not find video link. Trying broader match...');
+      printSnap(snap, 1500);
+      // Try any link with "Pink" in it
+      videoRef = findRef(snap, 'link', 'Pink');
+    }
+
+    if (!videoRef) {
+      console.log('  No matching video found.');
+      return;
+    }
+
+    // Step 7: Click the video (SPA nav — no loadEventFired)
+    console.log(`[7] Found video ref=${videoRef}, clicking to play...`);
+    await page.click(videoRef);
+    await wait(4000);
+
+    // Step 8: Snapshot the video page
+    console.log('[8] Video page snapshot:\n');
+    snap = await page.snapshot();
+    printSnap(snap, 800);
+
+    console.log('\n=== Video should be playing! ===');
+    console.log('Press Ctrl+C to exit when done watching.\n');
+
+    // Keep alive so user can watch
+    await new Promise(() => {});
+  } finally {
+    await page.close();
+  }
+}
+
+main().catch((err) => {
+  if (err.message?.includes('ECONNREFUSED')) {
+    console.error('\nError: Could not connect to Chromium on port 9222.');
+    console.error('Start Chromium first:\n');
+    console.error('  chromium-browser --remote-debugging-port=9222 \\');
+    console.error('    --disable-notifications \\');
+    console.error('    --autoplay-policy=no-user-gesture-required \\');
+    console.error('    --use-fake-device-for-media-stream \\');
+    console.error('    --use-fake-ui-for-media-stream \\');
+    console.error('    --disable-features=MediaRouter\n');
+  } else {
+    console.error('\nError:', err.message || err);
+  }
+  process.exit(1);
+});

package/mcp-server.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * mcp-server.js — MCP server for barebrowse.
+ *
+ * Raw JSON-RPC 2.0 over stdio. No SDK dependency.
+ * 7 tools: browse (one-shot), goto, snapshot, click, type, press, scroll.
+ *
+ * Session tools share a singleton page, lazy-created on first use.
+ * Action tools return 'ok' — agent calls snapshot explicitly to observe.
+ */
+
+import { browse, connect } from './src/index.js';
+
+let _page = null;
+
+async function getPage() {
+  if (!_page) _page = await connect();
+  return _page;
+}
+
+const TOOLS = [
+  {
+    name: 'browse',
+    description: 'One-shot: navigate to a URL and return a pruned ARIA snapshot. Stateless — does not use the session page.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'URL to browse' },
+        mode: { type: 'string', enum: ['headless', 'headed', 'hybrid'], description: 'Browser mode (default: headless)' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'goto',
+    description: 'Navigate the session page to a URL. Returns ok — call snapshot to observe.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'URL to navigate to' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'snapshot',
+    description: 'Get the current ARIA snapshot of the session page. Returns a YAML-like tree with [ref=N] markers on interactive elements.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'click',
+    description: 'Click an element by its ref from the snapshot. Returns ok — call snapshot to observe.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'Element ref from snapshot (e.g. "8")' },
+      },
+      required: ['ref'],
+    },
+  },
+  {
+    name: 'type',
+    description: 'Type text into an element by its ref. Returns ok — call snapshot to observe.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ref: { type: 'string', description: 'Element ref from snapshot' },
+        text: { type: 'string', description: 'Text to type' },
+        clear: { type: 'boolean', description: 'Clear existing content first (default: false)' },
+      },
+      required: ['ref', 'text'],
+    },
+  },
+  {
+    name: 'press',
+    description: 'Press a special key (Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, Space). Returns ok.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key: { type: 'string', description: 'Key name' },
+      },
+      required: ['key'],
+    },
+  },
+  {
+    name: 'scroll',
+    description: 'Scroll the page. Positive deltaY scrolls down, negative scrolls up. Returns ok.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        deltaY: { type: 'number', description: 'Pixels to scroll (positive=down, negative=up)' },
+      },
+      required: ['deltaY'],
+    },
+  },
+];
+
+async function handleToolCall(name, args) {
+  switch (name) {
+    case 'browse':
+      return await browse(args.url, { mode: args.mode });
+
+    case 'goto': {
+      const page = await getPage();
+      await page.goto(args.url);
+      return 'ok';
+    }
+    case 'snapshot': {
+      const page = await getPage();
+      return await page.snapshot();
+    }
+    case 'click': {
+      const page = await getPage();
+      await page.click(args.ref);
+      return 'ok';
+    }
+    case 'type': {
+      const page = await getPage();
+      await page.type(args.ref, args.text, { clear: args.clear });
+      return 'ok';
+    }
+    case 'press': {
+      const page = await getPage();
+      await page.press(args.key);
+      return 'ok';
+    }
+    case 'scroll': {
+      const page = await getPage();
+      await page.scroll(args.deltaY);
+      return 'ok';
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+function jsonrpcResponse(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function jsonrpcError(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+async function handleMessage(msg) {
+  const { id, method, params } = msg;
+
+  if (method === 'initialize') {
+    return jsonrpcResponse(id, {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'barebrowse', version: '0.2.0' },
+    });
+  }
+
+  if (method === 'notifications/initialized') {
+    return null; // notification, no response
+  }
+
+  if (method === 'tools/list') {
+    return jsonrpcResponse(id, { tools: TOOLS });
+  }
+
+  if (method === 'tools/call') {
+    const { name, arguments: args } = params;
+    try {
+      const result = await handleToolCall(name, args || {});
+      return jsonrpcResponse(id, {
+        content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
+      });
+    } catch (err) {
+      return jsonrpcResponse(id, {
+        content: [{ type: 'text', text: `Error: ${err.message}` }],
+        isError: true,
+      });
+    }
+  }
+
+  return jsonrpcError(id, -32601, `Method not found: ${method}`);
+}
+
+// --- Stdio transport ---
+
+let buffer = '';
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', async (chunk) => {
+  buffer += chunk;
+  let newlineIdx;
+  while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+    const line = buffer.slice(0, newlineIdx).trim();
+    buffer = buffer.slice(newlineIdx + 1);
+    if (!line) continue;
+
+    try {
+      const msg = JSON.parse(line);
+      const response = await handleMessage(msg);
+      if (response) {
+        process.stdout.write(response + '\n');
+      }
+    } catch (err) {
+      process.stdout.write(jsonrpcError(null, -32700, `Parse error: ${err.message}`) + '\n');
+    }
+  }
+});
+
+// Clean up on exit
+process.on('SIGINT', async () => {
+  if (_page) await _page.close().catch(() => {});
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  if (_page) await _page.close().catch(() => {});
+  process.exit(0);
+});

package/package.json

@@ -1,19 +1,32 @@
 {
   "name": "barebrowse",
-  "version": "0.1.0",
-  "description": "Authenticated web browsing for autonomous agents via CDP",
+  "version": "0.2.0",
+  "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",
-  "exports": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./bareagent": "./src/bareagent.js"
+  },
+  "bin": {
+    "barebrowse": "./cli.js"
+  },
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js"
+    "test": "node --test test/unit/*.test.js test/integration/*.test.js"
   },
-  "license": "MIT",
-  "files": [
-    "README.md",
-    "LICENSE"
-  ]
+  "keywords": [
+    "browser",
+    "cdp",
+    "chromium",
+    "aria",
+    "accessibility",
+    "web-scraping",
+    "agent",
+    "mcp",
+    "headless"
+  ],
+  "license": "MIT"
 }

package/src/aria.js

@@ -0,0 +1,69 @@
+/**
+ * aria.js — Format ARIA accessibility tree nodes for agent consumption.
+ *
+ * Takes a nested tree (built from CDP's Accessibility.getFullAXTree)
+ * and formats it as readable YAML-like text, similar to Playwright's ariaSnapshot.
+ */
+
+/**
+ * Format a nested ARIA tree as readable text output.
+ *
+ * Output format (one node per line, indented):
+ *   - role "name" [props] [ref=nodeId]
+ *
+ * @param {object} node - Tree node { role, name, properties, children, ignored, nodeId }
+ * @param {number} [depth=0] - Current indentation depth
+ * @returns {string} Formatted ARIA tree text
+ */
+export function formatTree(node, depth = 0) {
+  if (!node) return '';
+
+  // Skip ignored nodes but still process their children
+  if (node.ignored) {
+    return node.children.map((c) => formatTree(c, depth)).join('');
+  }
+
+  // Skip low-level rendering nodes that are noise for agents
+  const SKIP_ROLES = new Set(['InlineTextBox', 'LineBreak']);
+  if (SKIP_ROLES.has(node.role)) return '';
+
+  const indent = '  '.repeat(depth);
+  const lines = [];
+
+  // Build line: "- role "name" [properties] [ref=id]"
+  let line = `${indent}- ${node.role || 'none'}`;
+
+  if (node.name) {
+    line += ` "${node.name}"`;
+  }
+
+  // Notable properties that agents care about
+  const props = node.properties || {};
+  const propParts = [];
+  if (props.checked !== undefined) propParts.push(`checked=${props.checked}`);
+  if (props.disabled) propParts.push('disabled');
+  if (props.expanded !== undefined) propParts.push(`expanded=${props.expanded}`);
+  if (props.level) propParts.push(`level=${props.level}`);
+  if (props.selected) propParts.push('selected');
+  if (props.required) propParts.push('required');
+  if (props.value !== undefined && props.value !== '') propParts.push(`value="${props.value}"`);
+
+  if (propParts.length > 0) {
+    line += ` [${propParts.join(', ')}]`;
+  }
+
+  // Node ID as ref — agents use this to target interactions
+  if (node.nodeId) {
+    line += ` [ref=${node.nodeId}]`;
+  }
+
+  lines.push(line);
+
+  // Recurse into children
+  for (const child of node.children) {
+    const childText = formatTree(child, depth + 1);
+    if (childText) lines.push(childText);
+  }
+
+  return lines.join('\n');
+}