@romanmatena/browsermonitor 2.0.0

package/src/http-server.mjs

@@ -0,0 +1,536 @@
+/**
+ * HTTP server for browsermonitor.
+ *
+ * Provides HTTP API endpoints for LLM/script integration:
+ * - GET /dump - Trigger dump; writes files and returns paths + LLM-oriented description
+ * - GET /status - Current monitor status
+ * - GET /stop, GET /start - Pause/resume collecting
+ * - POST /puppeteer - Generic Puppeteer method call: { "method": "page.goto", "args": ["https://..."] }
+ */
+
+import http from 'http';
+import { C, log } from './utils/colors.mjs';
+import { getFullTimestamp } from './logging/index.mjs';
+import { getComputedStylesFromPage } from './logging/dump.mjs';
+import { printApiHelpTable, API_ENDPOINTS } from './templates/api-help.mjs';
+import { printSectionHeading } from './templates/section-heading.mjs';
+
+/** Default timeout for Puppeteer operations (ms). */
+const PUPPETEER_CALL_TIMEOUT_MS = 30_000;
+
+/** Allowed page.* methods for POST /puppeteer (no evaluate by default for safety). */
+const PAGE_WHITELIST = new Set([
+  'goto', 'click', 'type', 'focus', 'hover', 'select',
+  'content', 'title', 'url',
+  'screenshot', 'pdf',
+  'setViewport', 'setDefaultTimeout', 'setDefaultNavigationTimeout',
+  'waitForSelector', 'waitForTimeout',
+]);
+
+/**
+ * Read request body as UTF-8 string.
+ * @param {http.IncomingMessage} req
+ * @returns {Promise<string>}
+ */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Serialize Puppeteer method return value for JSON response.
+ * @param {unknown} result
+ * @param {string} methodName - e.g. 'goto'
+ * @returns {{ serialized: unknown } | { error: string }}
+ */
+function serializeResult(result, methodName) {
+  if (result === undefined) return { serialized: null };
+  if (Buffer.isBuffer(result)) return { serialized: result.toString('base64') };
+  if (result !== null && typeof result === 'object' && typeof result.url === 'function' && typeof result.status === 'function') {
+    try {
+      return { serialized: { url: result.url(), status: result.status() } };
+    } catch {
+      return { error: 'Failed to serialize response object' };
+    }
+  }
+  try {
+    JSON.stringify(result);
+    return { serialized: result };
+  } catch {
+    return { error: 'Method returns non-serializable value' };
+  }
+}
+
+/**
+ * Create and start the HTTP server for monitor API.
+ * Supports two modes:
+ * - getState(): use a shared state object (for early start before open/join). State can have logBuffer null = no browser.
+ * - Direct options (logBuffer, getPages, ...): classic per-mode server.
+ *
+ * @param {Object} options - Server options
+ * @param {number} options.port - Port to listen on (default: 60001, 0 = disabled)
+ * @param {string} options.host - Host to bind (default: 127.0.0.1)
+ * @param {Function} [options.getState] - () => ({ mode, logBuffer, getPages, getCollectingPaused, setCollectingPaused }) for shared state
+ * @param {string} [options.mode] - Monitor mode when not using getState
+ * @param {Object} [options.logBuffer] - LogBuffer when not using getState
+ * @param {Function} [options.getPages] - When not using getState
+ * @param {Function} [options.getCollectingPaused] - When not using getState
+ * @param {Function} [options.setCollectingPaused] - When not using getState
+ * @param {Function} [options.onDump] - Optional callback when dump is requested
+ * @param {number} [options.defaultPort=60001] - Default port; if port differs, "(changed)" is shown
+ * @returns {http.Server|null} Server instance or null if port is 0
+ */
+export function createHttpServer(options) {
+  const {
+    port = 60001,
+    host = '127.0.0.1',
+    defaultPort = 60001,
+    getState = null,
+    mode = 'unknown',
+    logBuffer,
+    getPages = () => [],
+    getCollectingPaused = () => false,
+    setCollectingPaused = () => {},
+    onDump = null,
+  } = options;
+
+  if (port === 0) {
+    log.dim('HTTP server disabled (port 0)');
+    return null;
+  }
+
+  function state() {
+    if (getState) {
+      const s = getState();
+      return {
+        mode: s.mode ?? 'interactive',
+        logBuffer: s.logBuffer ?? null,
+        getPages: s.getPages ?? (() => []),
+        getCollectingPaused: s.getCollectingPaused ?? (() => false),
+        setCollectingPaused: s.setCollectingPaused ?? (() => {}),
+        switchToTab: s.switchToTab ?? (async () => ({ success: false, error: 'Not available' })),
+        getAllTabs: s.getAllTabs ?? (async () => []),
+      };
+    }
+    return {
+      mode,
+      logBuffer,
+      getPages,
+      getCollectingPaused,
+      setCollectingPaused,
+      switchToTab: async () => ({ success: false, error: 'Not available' }),
+      getAllTabs: async () => [],
+    };
+  }
+
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    const s = state();
+    const noBrowser = !s.logBuffer;
+
+    // GET /dump
+    if (req.url === '/dump' && req.method === 'GET') {
+      if (noBrowser) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          state: s.mode,
+          message: 'No browser connected. Choose open (o) or join (j) in interactive mode, or use --open / --join.',
+          timestamp: getFullTimestamp(),
+          endpoints: { status: 'GET /status', dump: 'GET /dump (after browser connected)' },
+        }, null, 2));
+        return;
+      }
+      try {
+        const statsBeforeDump = s.logBuffer.getStats();
+        const pages = s.getPages();
+        const page = pages.length > 0 ? pages[0] : null;
+
+        await s.logBuffer.dumpBuffersToFiles({
+          dumpCookies: page ? () => s.logBuffer.dumpCookiesFromPage(page) : null,
+          dumpDom: page ? () => s.logBuffer.dumpDomFromPage(page) : null,
+          dumpScreenshot: page ? () => s.logBuffer.dumpScreenshotFromPage(page) : null,
+        });
+
+        if (onDump) onDump();
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: true,
+          timestamp: getFullTimestamp(),
+          message: 'Dump completed. Read the files below.',
+          stats: statsBeforeDump,
+          outputFiles: {
+            consoleLog: s.logBuffer.CONSOLE_LOG,
+            networkLog: s.logBuffer.NETWORK_LOG,
+            networkDir: s.logBuffer.NETWORK_DIR,
+            cookiesDir: s.logBuffer.COOKIES_DIR,
+            domHtml: s.logBuffer.DOM_HTML,
+            screenshot: s.logBuffer.SCREENSHOT,
+          },
+          llm: {
+            instruction: 'Read or download these files to get the current browser state. Do not ask the user to copy/paste from the browser.',
+            files: [
+              { path: s.logBuffer.DOM_HTML, what: 'Current page HTML (JS-modified DOM). Use for element tree and structure.' },
+              { path: s.logBuffer.SCREENSHOT, what: 'Screenshot of the current tab viewport (PNG).' },
+              { path: s.logBuffer.CONSOLE_LOG, what: 'Browser console output (logs, errors, warnings).' },
+              { path: s.logBuffer.NETWORK_LOG, what: 'Network requests overview (one line per request with ID).' },
+              { path: s.logBuffer.NETWORK_DIR, what: 'Directory with one JSON per request: full headers, payload, response (see IDs in network log).' },
+              { path: s.logBuffer.COOKIES_DIR, what: 'Directory with cookies per domain (JSON files).' },
+            ],
+          },
+        }, null, 2));
+      } catch (error) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: false, error: error.message }, null, 2));
+      }
+      return;
+    }
+
+    // GET /status
+    if (req.url === '/status' && req.method === 'GET') {
+      const pages = s.getPages();
+      const collectingPaused = s.getCollectingPaused();
+      const payload = {
+        status: noBrowser ? 'interactive' : 'running',
+        mode: s.mode,
+        timestamp: getFullTimestamp(),
+        monitoredPages: noBrowser ? [] : pages.map(p => {
+          try { return p.url(); } catch { return 'unknown'; }
+        }),
+      };
+      if (!noBrowser) {
+        payload.collecting = collectingPaused ? 'paused' : 'running';
+        payload.stats = s.logBuffer.getStats();
+        payload.outputFiles = {
+          consoleLog: s.logBuffer.CONSOLE_LOG,
+          networkLog: s.logBuffer.NETWORK_LOG,
+          networkDir: s.logBuffer.NETWORK_DIR,
+          cookiesDir: s.logBuffer.COOKIES_DIR,
+          domHtml: s.logBuffer.DOM_HTML,
+          screenshot: s.logBuffer.SCREENSHOT,
+        };
+      } else {
+        payload.message = 'No browser. Use interactive (o/j) or --open / --join.';
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    // GET /stop
+    if (req.url === '/stop' && req.method === 'GET') {
+      s.setCollectingPaused(true);
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        success: true,
+        collecting: 'paused',
+        message: noBrowser ? 'No browser.' : 'Collecting stopped (paused). Use /start to resume.',
+        timestamp: getFullTimestamp(),
+      }, null, 2));
+      return;
+    }
+
+    // GET /start
+    if (req.url === '/start' && req.method === 'GET') {
+      s.setCollectingPaused(false);
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        success: true,
+        collecting: 'running',
+        message: noBrowser ? 'No browser.' : 'Collecting started (resumed).',
+        timestamp: getFullTimestamp(),
+      }, null, 2));
+      return;
+    }
+
+    // GET /clear
+    if (req.url === '/clear' && req.method === 'GET') {
+      if (noBrowser) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          message: 'No browser connected.',
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      s.logBuffer.clearAllBuffers();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        success: true,
+        message: 'Buffers cleared.',
+        timestamp: getFullTimestamp(),
+      }, null, 2));
+      return;
+    }
+
+    // GET /tabs - list all user tabs (for /tab?index=N)
+    if (req.url === '/tabs' && req.method === 'GET') {
+      if (noBrowser) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ tabs: [], message: 'No browser connected.' }, null, 2));
+        return;
+      }
+      try {
+        const tabs = await s.getAllTabs();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ tabs, timestamp: getFullTimestamp() }, null, 2));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }, null, 2));
+      }
+      return;
+    }
+
+    // GET /computed-styles?selector=...
+    if (req.url?.startsWith('/computed-styles') && req.method === 'GET') {
+      const urlObj = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+      const selector = urlObj.searchParams.get('selector') || 'body';
+      if (noBrowser) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          message: 'No browser connected.',
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      const pages = s.getPages();
+      const page = pages.length > 0 ? pages[0] : null;
+      if (!page) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          message: 'No monitored page.',
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      try {
+        const result = await getComputedStylesFromPage(page, selector);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: !result.error,
+          selector,
+          timestamp: getFullTimestamp(),
+          ...result,
+        }, null, 2));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: err.message,
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+      }
+      return;
+    }
+
+    // GET /tab or /tab?index=1
+    if (req.url?.startsWith('/tab') && req.url !== '/tabs' && req.method === 'GET') {
+      const urlObj = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+      const indexParam = urlObj.searchParams.get('index');
+      const index = indexParam ? parseInt(indexParam, 10) : NaN;
+      if (!Number.isInteger(index) || index < 1) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: 'Missing or invalid index. Use /tab?index=1 (1-based tab number).',
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      try {
+        const result = await s.switchToTab(index);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: result.success,
+          url: result.url,
+          error: result.error,
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: err.message,
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+      }
+      return;
+    }
+
+    // POST /puppeteer - generic Puppeteer page method call
+    const pathname = req.url?.split('?')[0];
+    if (pathname === '/puppeteer' && req.method === 'POST') {
+      let body;
+      try {
+        const raw = await readBody(req);
+        body = raw ? JSON.parse(raw) : {};
+      } catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: 'Invalid JSON body',
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      const method = body.method;
+      const args = Array.isArray(body.args) ? body.args : [];
+      const timeout = typeof body.timeout === 'number' ? body.timeout : PUPPETEER_CALL_TIMEOUT_MS;
+      const waitFor = body.waitFor === true; // auto waitForSelector before click/hover
+      if (typeof method !== 'string' || !method.trim()) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: 'Missing or invalid "method" (e.g. "page.goto")',
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      if (!method.startsWith('page.')) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: 'Only "page.*" methods are supported (e.g. "page.goto", "page.click")',
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      const methodName = method.slice(5).trim();
+      if (!methodName || !PAGE_WHITELIST.has(methodName)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: `Method "${method}" not allowed. Whitelist: ${[...PAGE_WHITELIST].sort().join(', ')}`,
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      const pages = s.getPages();
+      const page = pages.length > 0 ? pages[0] : null;
+      if (noBrowser || !page) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: 'No browser or page connected. Use open/join mode first.',
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+        return;
+      }
+      let callArgs = args;
+      if (methodName === 'screenshot') {
+        const opts = (args[0] && typeof args[0] === 'object' && !Array.isArray(args[0]))
+          ? { ...args[0], encoding: args[0].encoding ?? 'base64' }
+          : { encoding: 'base64' };
+        callArgs = [opts];
+      }
+      if (methodName === 'pdf' && args[0] && typeof args[0] === 'object') {
+        callArgs = [{ ...args[0], encoding: args[0].encoding ?? 'base64' }];
+      }
+      try {
+        // Auto waitForSelector before click/hover if requested
+        if (waitFor && ['click', 'hover', 'focus', 'type'].includes(methodName) && callArgs[0]) {
+          const selector = callArgs[0];
+          if (typeof selector === 'string') {
+            await page.waitForSelector(selector, { timeout });
+          }
+        }
+        const fn = page[methodName];
+        if (typeof fn !== 'function') {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            success: false,
+            error: `Page method "${methodName}" is not a function`,
+            timestamp: getFullTimestamp(),
+          }, null, 2));
+          return;
+        }
+        const resultPromise = fn.apply(page, callArgs);
+        const timeoutPromise = new Promise((_, reject) => {
+          setTimeout(() => reject(new Error(`Timeout after ${timeout}ms`)), timeout);
+        });
+        const result = await Promise.race([resultPromise, timeoutPromise]);
+        const serialized = serializeResult(result, methodName);
+        if ('error' in serialized) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({
+            success: false,
+            error: serialized.error,
+            timestamp: getFullTimestamp(),
+          }, null, 2));
+          return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: true,
+          result: serialized.serialized,
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+      } catch (err) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          success: false,
+          error: err.message || String(err),
+          timestamp: getFullTimestamp(),
+        }, null, 2));
+      }
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'Not found',
+      endpoints: API_ENDPOINTS.map(e => `${e.method} ${e.path} - ${e.description}`),
+    }, null, 2));
+  });
+
+  server.listen(port, host, () => {
+    const url = `http://${host}:${port}`;
+    const changed = port !== defaultPort ? ` ${C.red}(changed)${C.reset}` : '';
+    const title = `HTTP API URL: ${url}${changed}`;
+    printSectionHeading(title, '  ');
+  });
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      log.warn(`HTTP server port ${port} is already in use`);
+    } else {
+      log.error(`HTTP server error: ${err.message}`);
+    }
+  });
+
+  return server;
+}
+
+/**
+ * Close the HTTP server gracefully.
+ * @param {http.Server} server - Server to close
+ * @returns {Promise<void>}
+ */
+export function closeHttpServer(server) {
+  return new Promise((resolve) => {
+    if (!server) {
+      resolve();
+      return;
+    }
+    server.close(() => {
+      resolve();
+    });
+  });
+}

package/src/init.mjs

@@ -0,0 +1,162 @@
+/**
+ * browsermonitor init – first-run setup and agent file updates.
+ *
+ * Called by:
+ *   - `browsermonitor init` subcommand (explicit)
+ *   - Auto-init on first run when .browsermonitor/ does not exist
+ *
+ * What it does:
+ *   1. Creates .browsermonitor/ directory structure
+ *   2. Creates settings.json with defaults (prompts for URL if TTY)
+ *   3. Updates CLAUDE.md, AGENTS.md, memory.md with Browser Monitor section
+ *   4. Suggests adding .browsermonitor/ to .gitignore
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import {
+  DEFAULT_SETTINGS,
+  ensureDirectories,
+  getPaths,
+  saveSettings,
+} from './settings.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const BEGIN_TAG_PREFIX = '<!-- BEGIN browser-monitor-llm-section';
+const END_TAG_PREFIX = '<!-- END browser-monitor-llm-section';
+
+const TEMPLATE_PATH = path.resolve(__dirname, 'agents.llm/browser-monitor-section.md');
+
+/**
+ * Replace existing tagged block or append template to a doc file.
+ * Section is identified by BEGIN/END tags.
+ * @param {string} hostDir
+ * @param {string} docFilename - e.g. 'CLAUDE.md', 'AGENTS.md', 'memory.md'
+ * @param {string} templateContent - full block including BEGIN and END tags
+ * @returns {boolean} true if file was updated
+ */
+function replaceOrAppendSection(hostDir, docFilename, templateContent) {
+  const hostPath = path.join(hostDir, docFilename);
+  if (!fs.existsSync(hostPath)) return false;
+
+  const content = fs.readFileSync(hostPath, 'utf8');
+  const trimmedTemplate = templateContent.trimEnd();
+  const beginIndex = content.indexOf(BEGIN_TAG_PREFIX);
+
+  let newContent;
+  if (beginIndex === -1) {
+    newContent = content.trimEnd() + '\n\n' + trimmedTemplate + '\n';
+    console.log(`[browsermonitor] Appended Browser Monitor section to ${docFilename}`);
+  } else {
+    const endTagStartIndex = content.indexOf(END_TAG_PREFIX, beginIndex);
+    if (endTagStartIndex === -1) {
+      console.error(`[browsermonitor] ${docFilename}: BEGIN tag found but no END tag; skipping`);
+      return false;
+    }
+    const afterEndComment = content.indexOf('-->', endTagStartIndex) + 3;
+    const lineEnd = content.indexOf('\n', afterEndComment);
+    const endIndex = lineEnd === -1 ? content.length : lineEnd + 1;
+    newContent = content.slice(0, beginIndex) + trimmedTemplate + '\n' + content.slice(endIndex);
+    console.log(`[browsermonitor] Replaced Browser Monitor section in ${docFilename}`);
+  }
+
+  try {
+    fs.writeFileSync(hostPath, newContent);
+    return true;
+  } catch (err) {
+    console.error(`[browsermonitor] Could not write ${docFilename}:`, err.message);
+    return false;
+  }
+}
+
+/**
+ * Prompt user for default URL (stdin line read).
+ * @param {string} defaultValue
+ * @returns {Promise<string>}
+ */
+function askDefaultUrl(defaultValue) {
+  return new Promise((resolve) => {
+    process.stdout.write(`  Default URL [${defaultValue}]: `);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdin.once('data', (chunk) => {
+      process.stdin.pause();
+      const trimmed = chunk.toString().trim().split('\n')[0].trim();
+      resolve(trimmed || defaultValue);
+    });
+  });
+}
+
+/**
+ * Suggest adding .browsermonitor/ to .gitignore if not already present.
+ * @param {string} projectRoot
+ */
+function suggestGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) return;
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  if (content.includes('.browsermonitor')) return;
+
+  console.log(`[browsermonitor] Tip: add .browsermonitor/ to your .gitignore`);
+}
+
+/**
+ * Run browsermonitor initialization.
+ * @param {string} projectRoot - Absolute path to the project
+ * @param {Object} [options]
+ * @param {boolean} [options.askForUrl=true] - Prompt for default URL
+ * @param {boolean} [options.updateAgentFiles=true] - Update CLAUDE.md/AGENTS.md/memory.md
+ */
+export async function runInit(projectRoot, options = {}) {
+  const { askForUrl = true, updateAgentFiles = true } = options;
+
+  console.log('');
+  console.log('========================================');
+  console.log('  Browser Monitor - Setup');
+  console.log('========================================');
+  console.log('');
+  console.log(`[browsermonitor] Project: ${projectRoot}`);
+  console.log('');
+
+  // 1. Create directory structure
+  ensureDirectories(projectRoot);
+  console.log('[browsermonitor] Created .browsermonitor/ directory structure');
+
+  // 2. Create settings.json if it doesn't exist
+  const { settingsFile } = getPaths(projectRoot);
+  if (!fs.existsSync(settingsFile)) {
+    let defaultUrl = DEFAULT_SETTINGS.defaultUrl;
+    if (askForUrl && process.stdin.isTTY) {
+      defaultUrl = await askDefaultUrl(defaultUrl);
+    }
+    const settings = { ...DEFAULT_SETTINGS, defaultUrl };
+    saveSettings(projectRoot, settings);
+    console.log(`[browsermonitor] Created settings.json (defaultUrl: ${defaultUrl})`);
+  } else {
+    console.log('[browsermonitor] settings.json already exists, skipping');
+  }
+
+  // 3. Update agent files
+  if (updateAgentFiles) {
+    if (!fs.existsSync(TEMPLATE_PATH)) {
+      console.error('[browsermonitor] Agent template not found:', TEMPLATE_PATH);
+    } else {
+      const templateContent = fs.readFileSync(TEMPLATE_PATH, 'utf8');
+      replaceOrAppendSection(projectRoot, 'CLAUDE.md', templateContent);
+      replaceOrAppendSection(projectRoot, 'AGENTS.md', templateContent);
+      replaceOrAppendSection(projectRoot, 'memory.md', templateContent);
+    }
+  }
+
+  // 4. Suggest .gitignore
+  suggestGitignore(projectRoot);
+
+  console.log('');
+  console.log('[browsermonitor] Setup complete.');
+  console.log('  browsermonitor          - Interactive menu (o=open, j=join, q=quit)');
+  console.log('  browsermonitor --open   - Launch Chrome at default URL');
+  console.log('');
+}