bwb-browser 2.0.4 → 3.1.0

package/lib/diagnose.mjs

@@ -0,0 +1,149 @@
+/**
+ * bwb-browser — Page Diagnostics
+ *
+ * Comprehensive page health check: performance metrics, console errors,
+ * broken resources, meta tags, and network failures.
+ * Combines multiple CDP + JS checks into a single report.
+ */
+
+/**
+ * Run a full diagnostic on the current page.
+ * Returns performance metrics, console errors, broken images, meta tags.
+ */
+export async function diagnosePage(protocol) {
+  const { Runtime, Network, Page } = protocol;
+
+  // Collect console errors during diagnostic
+  const consoleErrors = [];
+  let unsubConsole, unsubException;
+
+  try {
+    await Runtime.enable();
+    unsubConsole = Runtime.consoleAPICalled((params) => {
+      if (params.type === "error" || params.type === "warning") {
+        consoleErrors.push({
+          level: params.type,
+          text: (params.args || []).map(a => a.value !== undefined ? String(a.value) : a.description || "").join(" "),
+        });
+      }
+    });
+    unsubException = Runtime.exceptionThrown((params) => {
+      const d = params.exceptionDetails;
+      consoleErrors.push({
+        level: "exception",
+        text: d?.exception?.description || d?.text || "Unknown exception",
+      });
+    });
+  } catch {}
+
+  // Allow page to settle
+  await new Promise(r => setTimeout(r, 300));
+
+  // Page load performance
+  let performance = {};
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: `JSON.stringify({
+        loadTime: performance.timing ? (performance.timing.loadEventEnd - performance.timing.navigationStart) : null,
+        domContentLoaded: performance.timing ? (performance.timing.domContentLoadedEventEnd - performance.timing.navigationStart) : null,
+        domInteractive: performance.timing ? (performance.timing.domInteractive - performance.timing.navigationStart) : null,
+      })`,
+      returnByValue: true,
+    });
+    performance = JSON.parse(result?.value || "{}");
+  } catch {}
+
+  // Meta tags
+  let meta = {};
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: `JSON.stringify({
+        title: document.title,
+        description: (document.querySelector('meta[name=description]') || {}).content || '',
+        viewport: (document.querySelector('meta[name=viewport]') || {}).content || '',
+        charset: document.characterSet || '',
+        lang: document.documentElement?.lang || '',
+      })`,
+      returnByValue: true,
+    });
+    meta = JSON.parse(result?.value || "{}");
+  } catch {}
+
+  // Broken images
+  let brokenImages = [];
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: `JSON.stringify(
+        Array.from(document.querySelectorAll('img')).filter(i => i.naturalWidth === 0 && i.src).map(i => ({
+          src: i.src.slice(0, 200),
+          alt: i.alt || '(missing)',
+          width: i.width,
+          height: i.height,
+        }))
+      )`,
+      returnByValue: true,
+    });
+    brokenImages = JSON.parse(result?.value || "[]");
+  } catch {}
+
+  // Links check
+  let linkCount = 0;
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: "document.querySelectorAll('a[href]').length",
+    });
+    linkCount = result?.value || 0;
+  } catch {}
+
+  // Input count
+  let inputCount = 0;
+  try {
+    const { result } = await Runtime.evaluate({
+      expression: "document.querySelectorAll('input:not([type=hidden]), textarea, select, button, [role=button]').length",
+    });
+    inputCount = result?.value || 0;
+  } catch {}
+
+  // Current URL
+  let currentUrl = "";
+  try {
+    const { result } = await Runtime.evaluate({ expression: "location.href" });
+    currentUrl = result?.value || "";
+  } catch {}
+
+  // Cleanup
+  try { if (unsubConsole) unsubConsole(); } catch {}
+  try { if (unsubException) unsubException(); } catch {}
+
+  return {
+    url: currentUrl,
+    timestamp: new Date().toISOString(),
+    performance,
+    meta,
+    interactions: {
+      links: linkCount,
+      inputs: inputCount,
+    },
+    issues: {
+      consoleErrors: consoleErrors.slice(0, 20),
+      brokenImages: brokenImages.slice(0, 20),
+      hasBrokenImages: brokenImages.length > 0,
+      hasConsoleErrors: consoleErrors.length > 0,
+    },
+    score: calculateHealthScore(performance, consoleErrors, brokenImages),
+  };
+}
+
+function calculateHealthScore(perf, errors, brokenImgs) {
+  let score = 100;
+
+  // Penalize slow loads
+  if (perf.loadTime > 5000) score -= 20;
+  else if (perf.loadTime > 2000) score -= 10;
+
+  // Penalize errors
+  score -= errors.length * 5;
+  score -= brokenImgs.length * 10;
+
+  return Math.max(0, Math.min(100, score));
+}

package/lib/fingerprint.mjs

@@ -0,0 +1,100 @@
+/**
+ * bwb-browser — Realistic Browser Fingerprint
+ *
+ * Applies standard browser fingerprint countermeasures to reduce
+ * false-positive automation detection in CI/testing environments.
+ *
+ * These techniques are the same ones used by Playwright's Stealth plugin
+ * and Puppeteer Extra — common tools for testing your own site's
+ * bot-detection systems in a realistic browser environment.
+ *
+ * How it works:
+ *   - Override navigator.webdriver → false
+ *   - Set realistic navigator.plugins
+ *   - Configure sensible language preferences
+ *   - Override chrome.runtime references
+ *   - Set a standard desktop User-Agent
+ *
+ * NOTE: Scripts are injected via Page.addScriptToEvaluateOnNewDocument,
+ * which means they only affect pages loaded AFTER applyRealisticProfile
+ * is called. Call before browser_goto for best results.
+ */
+
+/**
+ * Apply a realistic browser fingerprint to reduce automation detection.
+ * Injects anti-fingerprinting scripts before page JS executes.
+ */
+export async function applyRealisticProfile(protocol) {
+  const { Page, Network } = protocol;
+
+  // Inject fingerprint-normalizing script for ALL new documents
+  await Page.addScriptToEvaluateOnNewDocument({
+    source: `
+      // Normalize webdriver flag (standard automation test practice)
+      Object.defineProperty(navigator, 'webdriver', { get: () => false });
+
+      // Set realistic plugin list
+      Object.defineProperty(navigator, 'plugins', {
+        get: () => [
+          { name: 'Chrome PDF Plugin', filename: 'internal-pdf-viewer' },
+          { name: 'Chrome PDF Viewer', filename: 'mhjfbmdgcfjbbpaeojofohoefgiehjai' },
+          { name: 'Native Client', filename: 'internal-nacl-plugin' },
+        ],
+        configurable: true,
+      });
+
+      // Realistic language preferences
+      Object.defineProperty(navigator, 'languages', {
+        get: () => ['en-US', 'en', 'es'],
+        configurable: true,
+      });
+
+      // Remove automation-specific chrome.runtime
+      if (window.chrome) {
+        if (window.chrome.runtime) {
+          delete window.chrome.runtime;
+        }
+        if (!window.chrome.loadTimes) {
+          window.chrome.loadTimes = function() { return {}; };
+        }
+      }
+
+      // Normalize permissions query
+      if (navigator.permissions && navigator.permissions.query) {
+        const origQuery = navigator.permissions.query;
+        navigator.permissions.query = function(params) {
+          if (params && params.name === 'notifications') {
+            return Promise.resolve({ state: 'prompt', onchange: null });
+          }
+          return origQuery.call(this, params);
+        };
+      }
+
+      // Realistic connection type
+      if (navigator.connection) {
+        Object.defineProperty(navigator.connection, 'rtt', { get: () => 100 });
+      }
+    `,
+  });
+
+  // Set a standard desktop user-agent
+  try {
+    await Network.setUserAgentOverride({
+      userAgent:
+        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
+    });
+  } catch {}
+
+  return {
+    status: "profile applied",
+    note: "Only affects pages loaded after this call. Navigate to a new page for the profile to take effect.",
+    techniques: [
+      "navigator.webdriver → false",
+      "navigator.plugins — realistic list",
+      "navigator.languages — configured",
+      "chrome.runtime — normalized",
+      "Permissions query — overridden",
+      "User-Agent — standard desktop",
+    ],
+  };
+}

package/lib/helpers.mjs

@@ -0,0 +1,126 @@
+/**
+ * bwb-browser — Shared interaction helpers
+ *
+ * Functions for navigating, clicking, filling, and waiting for page elements
+ * using raw CDP protocol.
+ */
+
+// ─── Navigation Helper ────────────────────────────────────────────────────────
+
+export async function gotoUrl(page, runtime, url, timeoutMs) {
+  await page.enable();
+
+  const loadPromise = page.loadEventFired().then(() => true);
+  const domPromise = page.domContentEventFired().then(() => true);
+
+  await page.navigate({ url });
+
+  await Promise.race([
+    Promise.all([loadPromise, domPromise]),
+    new Promise(r => setTimeout(() => r(false), timeoutMs)),
+  ]);
+
+  // Small grace for JS framework rendering
+  await new Promise(r => setTimeout(r, 500));
+
+  const { result } = await runtime.evaluate({ expression: "document.title" });
+  return { title: result?.value || "", url };
+}
+
+// ─── Click Helper (uses CDP Input.dispatchMouseEvent) ─────────────────────────
+
+export async function clickElement(page, runtime, input, selector) {
+  const { result } = await runtime.evaluate({
+    expression: `(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return JSON.stringify({ error: 'NOT_FOUND' });
+      const rect = el.getBoundingClientRect();
+      return JSON.stringify({
+        x: rect.x + rect.width / 2,
+        y: rect.y + rect.height / 2,
+        width: rect.width,
+        height: rect.height,
+        tag: el.tagName,
+        text: (el.textContent || '').trim().slice(0, 50),
+      });
+    })()`,
+  });
+
+  let info;
+  try { info = JSON.parse(result.value); } catch {
+    throw new Error(`Element not found: ${selector}`);
+  }
+
+  if (info.error === "NOT_FOUND") {
+    throw new Error(`Element not found: ${selector}`);
+  }
+
+  // Dispatch real mouse events via CDP Input domain (ONLY — no native JS click)
+  const x = Math.round(info.x);
+  const y = Math.round(info.y);
+  await input.dispatchMouseEvent({ type: "mousePressed", x, y, button: "left", clickCount: 1 });
+  await input.dispatchMouseEvent({ type: "mouseReleased", x, y, button: "left", clickCount: 1 });
+
+  return info;
+}
+
+// ─── Fill Helper (uses CDP Input.insertText) ──────────────────────────────────
+
+export async function fillElement(page, runtime, input, selector, text) {
+  const { result } = await runtime.evaluate({
+    expression: `(() => {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return 'NOT_FOUND';
+      el.focus();
+      el.value = '';
+      return 'FOCUSED';
+    })()`,
+    returnByValue: true,
+  });
+
+  if (result.value === "NOT_FOUND") {
+    throw new Error(`Element not found: ${selector}`);
+  }
+
+  // Clear existing text via CDP Input domain
+  await input.dispatchKeyEvent({ type: "keyDown", key: "Control" });
+  await input.dispatchKeyEvent({ type: "keyDown", key: "a" });
+  await input.dispatchKeyEvent({ type: "keyUp", key: "a" });
+  await input.dispatchKeyEvent({ type: "keyUp", key: "Control" });
+  await input.dispatchKeyEvent({ type: "keyDown", key: "Delete" });
+  await input.dispatchKeyEvent({ type: "keyUp", key: "Delete" });
+
+  // Insert text via CDP Input domain
+  await input.insertText({ text });
+}
+
+// ─── waitForSelector Helper ──────────────────────────────────────────────────
+
+export async function waitForSelector(runtime, selector, opts = {}) {
+  const timeout = opts.timeout || 10000;
+  const disappear = opts.disappear || false;
+  const start = Date.now();
+
+  while (Date.now() - start < timeout) {
+    const { result } = await runtime.evaluate({
+      expression: `(() => {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) return JSON.stringify({ status: "NOT_FOUND" });
+        const rect = el.getBoundingClientRect();
+        const hidden = rect.width === 0 || rect.height === 0;
+        const text = (el.textContent || "").trim().slice(0, 200);
+        return JSON.stringify({ status: "FOUND", tag: el.tagName, text, hidden });
+      })()`,
+    });
+
+    const info = JSON.parse(result?.value || "{}");
+
+    if (disappear && info.status === "NOT_FOUND") return true;
+    if (!disappear && info.status === "FOUND" && !info.hidden) return true;
+    if (!disappear && info.status === "FOUND" && !opts.visible) return true;
+
+    await new Promise((r) => setTimeout(r, 200));
+  }
+
+  throw new Error(`browser_waitForSelector: "${selector}" not ${disappear ? "disappeared" : "found"} within ${timeout}ms`);
+}

package/lib/session.mjs

@@ -0,0 +1,88 @@
+/**
+ * bwb-browser — Persistent Browser Sessions
+ *
+ * Save and load browser cookies to/from disk, enabling authenticated sessions
+ * to persist across agent restarts. "Login once, agent works for days."
+ *
+ * Sessions are stored as JSON files in ~/.bwb/sessions/
+ */
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const SESSION_DIR = join(homedir(), ".bwb", "sessions");
+
+function ensureDir() {
+  mkdirSync(SESSION_DIR, { recursive: true });
+}
+
+/**
+ * Save all cookies from the current browser session to a named session file.
+ */
+export async function saveSession(name, protocol) {
+  if (!name || typeof name !== "string") {
+    throw new Error("Session name is required");
+  }
+  // Sanitize name to avoid path traversal
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+  ensureDir();
+
+  const { cookies } = await protocol.Network.getAllCookies();
+  const path = join(SESSION_DIR, `${safeName}.json`);
+  writeFileSync(path, JSON.stringify({
+    name: safeName,
+    cookieCount: cookies.length,
+    savedAt: Date.now(),
+    cookies,
+  }, null, 2));
+
+  return { savedTo: path, cookieCount: cookies.length, name: safeName };
+}
+
+/**
+ * Load cookies from a named session file into the browser.
+ */
+export async function loadSession(name, protocol) {
+  const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const path = join(SESSION_DIR, `${safeName}.json`);
+
+  if (!existsSync(path)) {
+    throw new Error(`Session not found: "${name}". Available sessions: ${listSessions().map(s => s.name).join(", ") || "none"}`);
+  }
+
+  const data = JSON.parse(readFileSync(path, "utf8"));
+
+  if (!data.cookies || !Array.isArray(data.cookies)) {
+    throw new Error(`Invalid session file: ${path}`);
+  }
+
+  // Set all cookies in the browser
+  await protocol.Network.setCookies({ cookies: data.cookies });
+
+  return {
+    loaded: safeName,
+    cookieCount: data.cookies.length,
+    savedAt: new Date(data.savedAt).toISOString(),
+  };
+}
+
+/**
+ * List all saved sessions.
+ */
+export function listSessions() {
+  ensureDir();
+  const files = readdirSync(SESSION_DIR).filter(f => f.endsWith(".json"));
+  return files.map(f => {
+    try {
+      const data = JSON.parse(readFileSync(join(SESSION_DIR, f), "utf8"));
+      return {
+        name: data.name || f.replace(".json", ""),
+        cookieCount: data.cookies?.length || 0,
+        savedAt: data.savedAt ? new Date(data.savedAt).toISOString() : "unknown",
+      };
+    } catch {
+      return { name: f.replace(".json", ""), cookieCount: 0, savedAt: "unknown" };
+    }
+  });
+}