@romanmatena/browsermonitor 2.0.0

package/src/intro.mjs

@@ -0,0 +1,36 @@
+/**
+ * Shared app intro – shown once at startup for all modes.
+ * Title, logo-style branding, what it is, why, what follows, repo.
+ */
+
+import { C } from './utils/colors.mjs';
+import { printCliCommandsTable } from './templates/cli-commands.mjs';
+
+const TITLE = 'Browser Monitor';
+const TAGLINE = 'Browser console, network & DOM capture for debugging and LLM workflows';
+const NPM_URL = 'https://www.npmjs.com/package/browsermonitor';
+const GITHUB_URL = 'https://github.com/romanmatena/browsermonitor';
+
+export function printAppIntro() {
+  console.log('');
+  console.log(`${C.bold}${C.brightCyan}  ═══════════════════════════════════════════════════════════════════════════  ${C.reset}`);
+  console.log(`${C.bold}${C.brightCyan}                                                                              ${C.reset}`);
+  console.log(`${C.bold}${C.brightCyan}    ${C.white}${TITLE}${C.reset}${C.bold}${C.brightCyan}                                                                    ${C.reset}`);
+  console.log(`${C.bold}${C.brightCyan}    ${C.dim}npm ${NPM_URL}${C.reset}${C.bold}${C.brightCyan}  ${C.reset}`);
+  console.log(`${C.bold}${C.brightCyan}    ${C.dim}github ${GITHUB_URL}${C.reset}${C.bold}${C.brightCyan}${' '.repeat(12)}${C.reset}`);
+  console.log(`${C.bold}${C.brightCyan}                                                                              ${C.reset}`);
+  console.log(`${C.bold}${C.brightCyan}  ═══════════════════════════════════════════════════════════════════════════  ${C.reset}`);
+  console.log('');
+  console.log(`  ${C.dim}${TAGLINE}${C.reset}`);
+  console.log('');
+  console.log(`  ${C.cyan}What it is${C.reset}   Connects to Chrome and records console output, network requests,`);
+  console.log(`  ${C.dim}             cookies, and the current page HTML. Logs go to files (on demand or live).${C.reset}`);
+  console.log('');
+  console.log(`  ${C.cyan}Why use it${C.reset}   Debug frontend apps without copy-paste. LLM agents can trigger a dump`);
+  console.log(`  ${C.dim}             and read the files to get the live DOM and traffic.${C.reset}`);
+  console.log('');
+  console.log(`  ${C.cyan}What’s next${C.reset}   Choose a mode: ${C.green}interactive${C.reset} (menu), ${C.green}open${C.reset} (launch Chrome), or`);
+  console.log(`  ${C.dim}             ${C.green}join${C.reset} (attach to existing). Then use the browser; dump to write logs.${C.reset}`);
+  console.log('');
+  printCliCommandsTable({ showEntry: true, showUsage: true });
+}

package/src/logging/LogBuffer.mjs

@@ -0,0 +1,178 @@
+/**
+ * LogBuffer – in-memory or realtime buffers for console, network, and request details.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { C, log } from '../utils/colors.mjs';
+import { DEFAULT_IGNORE_PATTERNS } from './constants.mjs';
+import { HMR_PATTERNS } from './constants.mjs';
+import { getTimestamp, getFullTimestamp } from './timestamps.mjs';
+import {
+  dumpBuffersToFiles as doDumpBuffersToFiles,
+  dumpCookiesFromPage as doDumpCookiesFromPage,
+  dumpDomFromPage as doDumpDomFromPage,
+  dumpScreenshotFromPage as doDumpScreenshotFromPage,
+  DOM_DUMP_MAX_BYTES,
+} from './dump.mjs';
+
+/**
+ * LogBuffer class - manages logging buffers for a monitoring session.
+ */
+export class LogBuffer {
+  static DOM_DUMP_MAX_BYTES = DOM_DUMP_MAX_BYTES;
+
+  constructor(options = {}) {
+    const {
+      outputDir = process.cwd(),
+      paths = null,
+      lazyMode = true,
+      ignorePatterns = [],
+    } = options;
+
+    this.outputDir = outputDir;
+    this.lazyMode = lazyMode;
+
+    if (paths) {
+      this.CONSOLE_LOG = paths.consoleLog;
+      this.NETWORK_LOG = paths.networkLog;
+      this.NETWORK_DIR = paths.networkDir;
+      this.COOKIES_DIR = paths.cookiesDir;
+      this.DOM_HTML = paths.domHtml;
+      this.SCREENSHOT = paths.screenshot;
+    } else {
+      // Fallback: use .browsermonitor/.puppeteer/ structure relative to outputDir
+      const bmPuppeteerDir = path.join(outputDir, '.browsermonitor', '.puppeteer');
+      this.CONSOLE_LOG = path.join(bmPuppeteerDir, 'console.log');
+      this.NETWORK_LOG = path.join(bmPuppeteerDir, 'network.log');
+      this.NETWORK_DIR = path.join(bmPuppeteerDir, 'network-log');
+      this.COOKIES_DIR = path.join(bmPuppeteerDir, 'cookies');
+      this.DOM_HTML = path.join(bmPuppeteerDir, 'dom.html');
+      this.SCREENSHOT = path.join(bmPuppeteerDir, 'screenshot.png');
+    }
+
+    this.consoleBuffer = [];
+    this.networkBuffer = [];
+    this.requestDetails = new Map();
+    this.requestCounter = 0;
+
+    this.ignorePatterns = [...DEFAULT_IGNORE_PATTERNS, ...ignorePatterns];
+  }
+
+  nextRequestId() {
+    this.requestCounter++;
+    return String(this.requestCounter).padStart(3, '0');
+  }
+
+  shouldIgnore(message) {
+    return this.ignorePatterns.some(p => message.includes(p));
+  }
+
+  isHmr(message) {
+    return HMR_PATTERNS.some(p => message.includes(p));
+  }
+
+  logConsole(message) {
+    if (this.lazyMode) {
+      this.consoleBuffer.push(message);
+    } else {
+      console.log(message);
+      fs.appendFileSync(this.CONSOLE_LOG, message + '\n');
+    }
+  }
+
+  clearConsoleBuffer() {
+    if (this.lazyMode) {
+      this.consoleBuffer.length = 0;
+      log.dim(`Console buffer cleared (${getTimestamp()})`);
+    } else {
+      fs.writeFileSync(this.CONSOLE_LOG, '');
+    }
+  }
+
+  printConsoleSeparator(title) {
+    const line = '='.repeat(80);
+    this.logConsole(line);
+    this.logConsole(`[${getTimestamp()}] *** ${title} ***`);
+    this.logConsole(line);
+  }
+
+  logNetwork(message) {
+    if (this.lazyMode) {
+      this.networkBuffer.push(message);
+    } else {
+      fs.appendFileSync(this.NETWORK_LOG, message + '\n');
+    }
+  }
+
+  clearNetworkDir() {
+    if (fs.existsSync(this.NETWORK_DIR)) {
+      fs.rmSync(this.NETWORK_DIR, { recursive: true });
+    }
+    fs.mkdirSync(this.NETWORK_DIR, { recursive: true });
+  }
+
+  printNetworkSeparator(title) {
+    const line = '='.repeat(80);
+    this.logNetwork(line);
+    this.logNetwork(`[${getFullTimestamp()}] ${title}`);
+    this.logNetwork(line);
+  }
+
+  saveRequestDetail(id, data) {
+    if (this.lazyMode) {
+      this.requestDetails.set(id, data);
+    } else {
+      const filePath = path.join(this.NETWORK_DIR, `${id}.json`);
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+    }
+  }
+
+  updateRequestDetail(id, updates) {
+    if (this.lazyMode) {
+      const existing = this.requestDetails.get(id) || {};
+      this.requestDetails.set(id, { ...existing, ...updates });
+    } else {
+      const filePath = path.join(this.NETWORK_DIR, `${id}.json`);
+      try {
+        const existing = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        const updated = { ...existing, ...updates };
+        fs.writeFileSync(filePath, JSON.stringify(updated, null, 2));
+      } catch (e) {
+        this.saveRequestDetail(id, updates);
+      }
+    }
+  }
+
+  clearAllBuffers() {
+    this.consoleBuffer.length = 0;
+    this.networkBuffer.length = 0;
+    this.requestDetails.clear();
+    this.requestCounter = 0;
+    log.success(`All buffers cleared (${getTimestamp()})`);
+  }
+
+  getStats() {
+    return {
+      consoleEntries: this.consoleBuffer.length,
+      networkEntries: this.networkBuffer.length,
+      requestDetails: this.requestDetails.size,
+    };
+  }
+
+  async dumpBuffersToFiles(options = {}) {
+    return doDumpBuffersToFiles(this, options);
+  }
+
+  async dumpCookiesFromPage(page) {
+    return doDumpCookiesFromPage(this, page);
+  }
+
+  async dumpDomFromPage(page) {
+    return doDumpDomFromPage(this, page);
+  }
+
+  async dumpScreenshotFromPage(page) {
+    return doDumpScreenshotFromPage(this, page);
+  }
+}

package/src/logging/constants.mjs

@@ -0,0 +1,19 @@
+/**
+ * Constants for console filtering and HMR detection.
+ */
+
+/** Default patterns to ignore in console output. */
+export const DEFAULT_IGNORE_PATTERNS = [
+  'IndexedDBStorage',
+  'BackendSync',
+  'heartbeat',
+  'Sending ping',
+  'Received pong',
+];
+
+/** HMR (Hot Module Replacement) patterns to detect reloads. */
+export const HMR_PATTERNS = [
+  '[vite] hot updated',
+  '[vite] page reloaded',
+  '[vite] connected',
+];

package/src/logging/dump.mjs

@@ -0,0 +1,207 @@
+/**
+ * Dump actions: write buffers and page data (cookies, DOM) to files.
+ * Used by LogBuffer; can be called with any LogBuffer instance.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { C, log } from '../utils/colors.mjs';
+import { getTimestamp, getFullTimestamp } from './timestamps.mjs';
+
+/** Max size for DOM dump (bytes). Larger output is truncated. */
+export const DOM_DUMP_MAX_BYTES = 2 * 1024 * 1024; // 2MB
+
+/**
+ * Write all in-memory buffers to files and clear buffers.
+ * @param {import('./LogBuffer.mjs').LogBuffer} logBuffer
+ * @param {Object} options - { dumpCookies?: () => Promise<void>, dumpDom?: () => Promise<void>, dumpScreenshot?: () => Promise<void> }
+ * @returns {Promise<Object>} Stats before dump
+ */
+export async function dumpBuffersToFiles(logBuffer, options = {}) {
+  const { dumpCookies, dumpDom, dumpScreenshot } = options;
+  const timestamp = getTimestamp();
+  const statsBeforeDump = logBuffer.getStats();
+
+  log.section('Dumping Buffers');
+
+  if (logBuffer.consoleBuffer.length > 0) {
+    fs.writeFileSync(logBuffer.CONSOLE_LOG, logBuffer.consoleBuffer.join('\n') + '\n');
+    log.success(`${C.brightCyan}${logBuffer.consoleBuffer.length}${C.reset}${C.green} console entries → ${logBuffer.CONSOLE_LOG}${C.reset}`);
+  } else {
+    fs.writeFileSync(logBuffer.CONSOLE_LOG, '');
+    log.dim('Console buffer is empty');
+  }
+
+  if (logBuffer.networkBuffer.length > 0) {
+    fs.writeFileSync(logBuffer.NETWORK_LOG, logBuffer.networkBuffer.join('\n') + '\n');
+    log.success(`${C.brightCyan}${logBuffer.networkBuffer.length}${C.reset}${C.green} network entries → ${logBuffer.NETWORK_LOG}${C.reset}`);
+  } else {
+    fs.writeFileSync(logBuffer.NETWORK_LOG, '');
+  }
+
+  logBuffer.clearNetworkDir();
+  if (logBuffer.requestDetails.size > 0) {
+    for (const [id, data] of logBuffer.requestDetails) {
+      const filePath = path.join(logBuffer.NETWORK_DIR, `${id}.json`);
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+    }
+    log.success(`${C.brightCyan}${logBuffer.requestDetails.size}${C.reset}${C.green} request details → ${logBuffer.NETWORK_DIR}/${C.reset}`);
+  }
+
+  if (dumpCookies) await dumpCookies();
+  if (dumpDom) await dumpDom();
+  if (dumpScreenshot) await dumpScreenshot();
+
+  log.success(`Dump completed at ${timestamp}`);
+  logBuffer.clearAllBuffers();
+
+  return statsBeforeDump;
+}
+
+/**
+ * Dump cookies from a browser page into logBuffer.COOKIES_DIR.
+ * @param {import('./LogBuffer.mjs').LogBuffer} logBuffer
+ * @param {import('puppeteer').Page} page
+ * @returns {Promise<void>}
+ */
+export async function dumpCookiesFromPage(logBuffer, page) {
+  if (!page) {
+    log.dim('No page to dump cookies from');
+    return;
+  }
+
+  try {
+    const client = await page.createCDPSession();
+    const { cookies } = await client.send('Network.getAllCookies');
+    await client.detach();
+
+    if (cookies.length === 0) {
+      log.dim('No cookies found');
+      return;
+    }
+
+    const cookiesByDomain = new Map();
+    for (const c of cookies) {
+      const domain = c.domain.replace(/^\./, '');
+      if (!cookiesByDomain.has(domain)) cookiesByDomain.set(domain, []);
+      cookiesByDomain.get(domain).push(c);
+    }
+
+    if (fs.existsSync(logBuffer.COOKIES_DIR)) fs.rmSync(logBuffer.COOKIES_DIR, { recursive: true });
+    fs.mkdirSync(logBuffer.COOKIES_DIR, { recursive: true });
+
+    const timestamp = getFullTimestamp();
+    for (const [domain, domainCookies] of cookiesByDomain) {
+      const safeDomain = domain.replace(/[^a-zA-Z0-9.-]/g, '_');
+      const cookieFile = path.join(logBuffer.COOKIES_DIR, `${safeDomain}.json`);
+      const cookieData = {
+        timestamp,
+        domain,
+        currentUrl: page.url(),
+        count: domainCookies.length,
+        cookies: domainCookies.map(c => ({
+          name: c.name,
+          value: c.value,
+          domain: c.domain,
+          path: c.path,
+          expires: c.expires ? new Date(c.expires * 1000).toISOString() : 'Session',
+          httpOnly: c.httpOnly,
+          secure: c.secure,
+          sameSite: c.sameSite || 'None',
+        })),
+      };
+      fs.writeFileSync(cookieFile, JSON.stringify(cookieData, null, 2));
+    }
+
+    log.success(`${C.brightCyan}${cookies.length}${C.reset}${C.green} cookies (${cookiesByDomain.size} domains) → ${logBuffer.COOKIES_DIR}/${C.reset}`);
+  } catch (e) {
+    log.error(`Error dumping cookies: ${e.message}`);
+  }
+}
+
+/**
+ * Dump current document HTML (JS-modified DOM) to logBuffer.DOM_HTML.
+ * @param {import('./LogBuffer.mjs').LogBuffer} logBuffer
+ * @param {import('puppeteer').Page} page
+ * @returns {Promise<void>}
+ */
+export async function dumpDomFromPage(logBuffer, page) {
+  if (!page) {
+    log.dim('No page to dump DOM from');
+    return;
+  }
+
+  try {
+    const html = await page.evaluate(() => document.documentElement.outerHTML);
+    const maxBytes = DOM_DUMP_MAX_BYTES;
+    let content = html;
+    const byteLength = Buffer.byteLength(html, 'utf8');
+    if (byteLength > maxBytes) {
+      content = content.slice(0, Math.floor(maxBytes / 2)) + '\n\n<!-- ... TRUNCATED for size ... -->\n';
+      log.dim(`DOM truncated to ~${Math.round(maxBytes / 1024)}KB (was ${Math.round(byteLength / 1024)}KB)`);
+    }
+    fs.writeFileSync(logBuffer.DOM_HTML, content, 'utf8');
+    log.success(`${C.green}DOM (current HTML) → ${logBuffer.DOM_HTML}${C.reset}`);
+    log.dim(`LLM: current page HTML / element structure is in: ${logBuffer.DOM_HTML}`);
+  } catch (e) {
+    log.error(`Error dumping DOM: ${e.message}`);
+  }
+}
+
+/**
+ * Capture screenshot of the current page viewport.
+ * @param {import('./LogBuffer.mjs').LogBuffer} logBuffer
+ * @param {import('puppeteer').Page} page
+ * @returns {Promise<void>}
+ */
+export async function dumpScreenshotFromPage(logBuffer, page) {
+  if (!page) {
+    log.dim('No page to capture screenshot from');
+    return;
+  }
+
+  try {
+    await page.screenshot({ path: logBuffer.SCREENSHOT, type: 'png' });
+    log.success(`${C.green}Screenshot → ${logBuffer.SCREENSHOT}${C.reset}`);
+  } catch (e) {
+    log.error(`Error capturing screenshot: ${e.message}`);
+  }
+}
+
+/**
+ * Get computed CSS styles for the first element matching a selector.
+ * Uses window.getComputedStyle in the page context (via page.evaluate).
+ *
+ * @param {import('puppeteer').Page} page
+ * @param {string} selector - CSS selector (e.g. 'body', '.my-class', '#id')
+ * @returns {Promise<{ selector: string, tagName: string, computed: Record<string, string> } | { error: string }>}
+ */
+export async function getComputedStylesFromPage(page, selector) {
+  if (!page) {
+    return { error: 'No page' };
+  }
+
+  try {
+    const result = await page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) {
+        return { error: `No element matching selector: ${sel}` };
+      }
+      const cs = window.getComputedStyle(el);
+      const computed = {};
+      for (let i = 0; i < cs.length; i++) {
+        const prop = cs[i];
+        computed[prop] = cs.getPropertyValue(prop);
+      }
+      return {
+        selector: sel,
+        tagName: el.tagName.toLowerCase(),
+        computed,
+      };
+    }, selector);
+
+    return result;
+  } catch (e) {
+    return { error: e.message };
+  }
+}

package/src/logging/index.mjs

@@ -0,0 +1,13 @@
+/**
+ * Logging submodule – buffer management, timestamps, dump actions.
+ *
+ * - constants.mjs  – DEFAULT_IGNORE_PATTERNS, HMR_PATTERNS
+ * - timestamps.mjs  – getTimestamp, getFullTimestamp
+ * - dump.mjs        – dumpBuffersToFiles, dumpCookiesFromPage, dumpDomFromPage
+ * - LogBuffer.mjs   – LogBuffer class
+ */
+
+export { DEFAULT_IGNORE_PATTERNS, HMR_PATTERNS } from './constants.mjs';
+export { getTimestamp, getFullTimestamp } from './timestamps.mjs';
+export { LogBuffer } from './LogBuffer.mjs';
+export { DOM_DUMP_MAX_BYTES } from './dump.mjs';

package/src/logging/timestamps.mjs

@@ -0,0 +1,13 @@
+/**
+ * Timestamp helpers for console and file output.
+ */
+
+/** HH:MM:SS.mmm for console output */
+export function getTimestamp() {
+  return new Date().toISOString().substring(11, 23);
+}
+
+/** Full ISO timestamp for file output */
+export function getFullTimestamp() {
+  return new Date().toISOString();
+}

package/src/monitor/README.md

@@ -0,0 +1,10 @@
+# Monitor submodule
+
+Sdílené moduly pro režimy join, open a interactive.
+
+- **page-monitoring.mjs** – připojení console/network listenerů na stránku (sdílené pro join i open).
+- **tab-selection.mjs** – výběr tabu (askUserToSelectPage, ensureKeypressEvents).
+- **interactive-mode.mjs** – interaktivní menu (o = open, j = join, q = quit), výběr projektového adresáře, výběr Chrome instance.
+- **index.mjs** – re-exporty pro přehled API.
+
+Veřejné API (`runJoinMode`, `runOpenMode`, `runInteractiveMode`) zůstává v `../monitor.mjs` kvůli absenci cyklických závislostí.

package/src/monitor/index.mjs

@@ -0,0 +1,18 @@
+/**
+ * Monitor submodule – re-exports and shared pieces.
+ * Public API (runJoinMode, runOpenMode, runInteractiveMode) lives in ../monitor.mjs
+ * to avoid circular deps. This index documents the monitor/ layout:
+ *
+ * - page-monitoring.mjs    – shared console/network listeners for a page
+ * - tab-selection.mjs      – askUserToSelectPage, ensureKeypressEvents
+ * - interactive-mode.mjs   – runInteractiveMode(options, deps), getChromeInstances, askProjectDirForOpen
+ */
+
+export { setupPageMonitoring } from './page-monitoring.mjs';
+export { askUserToSelectPage, ensureKeypressEvents } from './tab-selection.mjs';
+export {
+  runInteractiveMode,
+  getChromeInstances,
+  askProjectDirForOpen,
+  askUserToSelectChromeInstance,
+} from './interactive-mode.mjs';