@specsage/cli 0.1.0

package/lib/browser.js

@@ -0,0 +1,809 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import {
+  setupDialogHandler,
+  hasDialog,
+  getDialogInfo,
+  getDialogPseudoElement,
+  acceptDialog,
+  dismissDialog
+} from "./dialogs.js";
+
+let browser = null;
+let context = null;
+let page = null;
+let lastElements = [];
+let elementKeyToDisplayId = new Map();  // stable_key -> current display ID
+let displayIdToElement = new Map();      // display ID -> element data
+let lastClickedElement = null;           // Track element clicked for focus context
+let pendingClickPromise = null;          // Track click blocked by dialog
+
+// Get the directory where this script lives
+// fileURLToPath decodes URL-encoded characters (e.g. %20 -> space) for paths with spaces
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+
+// Parse --temp-dir argument for isolated video recording directory
+const tempDirArgIndex = process.argv.indexOf('--temp-dir');
+const tmpDir = tempDirArgIndex !== -1 && process.argv[tempDirArgIndex + 1]
+  ? process.argv[tempDirArgIndex + 1]
+  : path.join(scriptDir, '..', 'tmp');
+
+async function init() {
+  const visible = process.argv.includes('--visible');
+  const record = process.argv.includes('--record');
+  const headless = !visible;
+
+  browser = await chromium.launch({
+    headless,
+    args: ['--disable-gpu', '--disable-software-rasterizer']
+  });
+
+  const contextOptions = {
+    viewport: { width: 1280, height: 800 }
+  };
+
+  if (record) {
+    // Ensure tmp directory exists
+    if (!fs.existsSync(tmpDir)) {
+      fs.mkdirSync(tmpDir, { recursive: true });
+    }
+    console.error(`[browser.js] Video recording enabled, temp dir: ${tmpDir}`);
+    contextOptions.recordVideo = {
+      dir: tmpDir,
+      size: { width: 1280, height: 800 }
+    };
+  }
+
+  context = await browser.newContext(contextOptions);
+  page = await context.newPage();
+
+  // Verify video recording is actually working
+  if (record) {
+    const video = page.video();
+    if (video) {
+      console.error('[browser.js] Video recording initialized successfully');
+    } else {
+      console.error('[browser.js] WARNING: Video recording was requested but page.video() returned null');
+    }
+  }
+
+  // Set up dialog handling - captures dialogs for AI to see and respond to
+  setupDialogHandler(page);
+}
+
+function send(response) {
+  process.stdout.write(JSON.stringify(response) + "\n");
+}
+
+// Generate a stable key for an element based on intrinsic properties
+function generateStableKey(elementData) {
+  const parts = [
+    elementData.tagName,
+    elementData.role || '',
+    elementData.name || '',
+    elementData.type || '',
+    elementData.placeholder || '',
+    elementData.ariaLabel || '',
+    elementData.href || '',
+    elementData.domPath || ''
+  ];
+  return parts.join('|');
+}
+
+async function screenshotBase64() {
+  // Small delay to let any pending renders/paints complete
+  await new Promise(r => setTimeout(r, 50));
+  const buf = await page.screenshot();
+  return buf.toString("base64");
+}
+
+/**
+ * Capture screenshot and elements, handling the case where a dialog is blocking.
+ * When a dialog is open, we can't interact with the page, so we return
+ * a placeholder screenshot and only the dialog pseudo-element.
+ */
+async function captureState() {
+  if (hasDialog()) {
+    // Dialog is blocking - can't take screenshot or enumerate elements
+    // Return dialog info so AI knows to handle it
+    const dialogElement = getDialogPseudoElement();
+    return {
+      screenshot_base64: null,  // Can't screenshot while dialog is blocking
+      elements: dialogElement ? [dialogElement] : [],
+      dialog_blocking: true
+    };
+  }
+
+  return {
+    screenshot_base64: await screenshotBase64(),
+    elements: await enumerateElements(),
+    dialog_blocking: false
+  };
+}
+
+async function enumerateElements() {
+  const elements = [];
+
+  // Native interactive elements
+  const nativeSelectors = [
+    'button, [role="button"]',
+    'a, [role="link"]',
+    'input, textarea',
+    'select, [role="combobox"]',
+    '[role="option"]',
+    '[role="menuitem"]',
+    '[role="tab"]',
+    '[role="checkbox"]',
+    '[role="radio"]',
+  ];
+
+  // Scripted interactive elements
+  const scriptedSelectors = [
+    { selector: '[onclick]', source: 'onclick' },
+    { selector: '[data-action]', source: 'data-action' },
+    { selector: '[data-testid]', source: 'data-testid' },
+    { selector: '[tabindex]', source: 'tabindex' },
+  ];
+
+  // Process native elements
+  for (const selector of nativeSelectors) {
+    const locators = page.locator(selector);
+    const count = await locators.count();
+
+    for (let i = 0; i < count; i++) {
+      const el = locators.nth(i);
+
+      try {
+        const isVisible = await el.isVisible();
+        if (!isVisible) continue;
+
+        const box = await el.boundingBox();
+        if (!box) continue;
+
+        const tagName = await el.evaluate(e => e.tagName.toLowerCase());
+        const role = await el.getAttribute('role');
+        const ariaLabel = await el.getAttribute('aria-label');
+        const name = await el.getAttribute('name');
+        const placeholder = await el.getAttribute('placeholder');
+        const type = await el.getAttribute('type');
+        const href = await el.getAttribute('href');
+        const disabled = await el.isDisabled();
+
+        // Get DOM path for stable identification
+        const domPath = await el.evaluate(e => {
+          const parts = [];
+          let node = e;
+          while (node && node.nodeType === Node.ELEMENT_NODE) {
+            let selector = node.tagName.toLowerCase();
+            if (node.id) {
+              selector += `#${node.id}`;
+              parts.unshift(selector);
+              break; // ID is unique, stop here
+            } else {
+              const siblings = node.parentNode ? Array.from(node.parentNode.children).filter(c => c.tagName === node.tagName) : [];
+              if (siblings.length > 1) {
+                const index = siblings.indexOf(node) + 1;
+                selector += `:nth-of-type(${index})`;
+              }
+              parts.unshift(selector);
+            }
+            node = node.parentNode;
+          }
+          return parts.join(' > ');
+        });
+
+        let accessibleName = ariaLabel;
+        if (!accessibleName) {
+          accessibleName = await el.evaluate(e => e.textContent?.trim().substring(0, 100));
+        }
+        if (!accessibleName) {
+          accessibleName = name || placeholder || '';
+        }
+
+        const visibleText = await el.evaluate(e => e.textContent?.trim().substring(0, 100) || '');
+
+        let elementType;
+        const effectiveRole = role || tagName;
+        if (tagName === 'button' || role === 'button') {
+          elementType = 'button';
+        } else if (tagName === 'a' || role === 'link') {
+          elementType = 'link';
+        } else if (tagName === 'input' || tagName === 'textarea') {
+          elementType = 'input';
+        } else if (tagName === 'select' || role === 'combobox') {
+          elementType = 'select';
+        } else if (role === 'option' || role === 'menuitem') {
+          elementType = 'option';
+        } else if (role === 'checkbox') {
+          elementType = 'checkbox';
+        } else if (role === 'radio') {
+          elementType = 'radio';
+        } else if (role === 'tab') {
+          elementType = 'tab';
+        } else {
+          elementType = tagName;
+        }
+
+        // Generate stable key for this element
+        const stableKey = generateStableKey({
+          tagName, role, name, type, placeholder, ariaLabel, href, domPath
+        });
+
+        elements.push({
+          id: null,  // Will be assigned after deduplication
+          stable_key: stableKey,
+          type: elementType,
+          role: effectiveRole,
+          accessible_name: accessibleName || '',
+          visible_text: visibleText,
+          disabled: disabled,
+          input_type: type || null,
+          bounding_box: {
+            x: Math.round(box.x),
+            y: Math.round(box.y),
+            w: Math.round(box.width),
+            h: Math.round(box.height)
+          },
+          mechanism: 'native',
+          source: 'native'
+        });
+      } catch (err) {
+        continue;
+      }
+    }
+  }
+
+  // Process scripted elements
+  for (const { selector, source } of scriptedSelectors) {
+    const locators = page.locator(selector);
+    const count = await locators.count();
+
+    for (let i = 0; i < count; i++) {
+      const el = locators.nth(i);
+
+      try {
+        const isVisible = await el.isVisible();
+        if (!isVisible) continue;
+
+        const box = await el.boundingBox();
+        if (!box) continue;
+
+        const tagName = await el.evaluate(e => e.tagName.toLowerCase());
+        const role = await el.getAttribute('role');
+        const ariaLabel = await el.getAttribute('aria-label');
+        const name = await el.getAttribute('name');
+        const placeholder = await el.getAttribute('placeholder');
+        const type = await el.getAttribute('type');
+        const href = await el.getAttribute('href');
+        const disabled = await el.isDisabled();
+
+        // Get DOM path for stable identification
+        const domPath = await el.evaluate(e => {
+          const parts = [];
+          let node = e;
+          while (node && node.nodeType === Node.ELEMENT_NODE) {
+            let selector = node.tagName.toLowerCase();
+            if (node.id) {
+              selector += `#${node.id}`;
+              parts.unshift(selector);
+              break; // ID is unique, stop here
+            } else {
+              const siblings = node.parentNode ? Array.from(node.parentNode.children).filter(c => c.tagName === node.tagName) : [];
+              if (siblings.length > 1) {
+                const index = siblings.indexOf(node) + 1;
+                selector += `:nth-of-type(${index})`;
+              }
+              parts.unshift(selector);
+            }
+            node = node.parentNode;
+          }
+          return parts.join(' > ');
+        });
+
+        let accessibleName = ariaLabel;
+        if (!accessibleName) {
+          accessibleName = await el.evaluate(e => e.textContent?.trim().substring(0, 100));
+        }
+        if (!accessibleName) {
+          accessibleName = name || placeholder || '';
+        }
+
+        const visibleText = await el.evaluate(e => e.textContent?.trim().substring(0, 100) || '');
+
+        const effectiveRole = role || tagName;
+
+        // Generate stable key for this element
+        const stableKey = generateStableKey({
+          tagName, role, name, type, placeholder, ariaLabel, href, domPath
+        });
+
+        elements.push({
+          id: null,  // Will be assigned after deduplication
+          stable_key: stableKey,
+          type: tagName,
+          role: effectiveRole,
+          accessible_name: accessibleName || '',
+          visible_text: visibleText,
+          disabled: disabled,
+          input_type: type || null,
+          bounding_box: {
+            x: Math.round(box.x),
+            y: Math.round(box.y),
+            w: Math.round(box.width),
+            h: Math.round(box.height)
+          },
+          mechanism: 'scripted',
+          source: source
+        });
+      } catch (err) {
+        continue;
+      }
+    }
+  }
+
+  // Deduplicate by bounding box (some elements match multiple selectors)
+  const seen = new Set();
+  const uniqueElements = [];
+  for (const el of elements) {
+    const key = `${el.bounding_box.x},${el.bounding_box.y},${el.bounding_box.w},${el.bounding_box.h}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      uniqueElements.push(el);
+    }
+  }
+
+  // Disambiguate stable_keys by appending occurrence index for collisions
+  // Group elements by their base stable_key
+  const keyGroups = new Map();
+  for (const el of uniqueElements) {
+    const baseKey = el.stable_key;
+    if (!keyGroups.has(baseKey)) {
+      keyGroups.set(baseKey, []);
+    }
+    keyGroups.get(baseKey).push(el);
+  }
+
+  // For each group with collisions, sort by position (top-to-bottom, left-to-right)
+  // then assign deterministic indices
+  for (const [baseKey, group] of keyGroups) {
+    if (group.length > 1) {
+      group.sort((a, b) => {
+        const yDiff = a.bounding_box.y - b.bounding_box.y;
+        if (Math.abs(yDiff) > 5) return yDiff; // 5px threshold for "same row"
+        return a.bounding_box.x - b.bounding_box.x;
+      });
+    }
+    group.forEach((el, idx) => {
+      el.stable_key = `${baseKey}#${idx}`;
+    });
+  }
+
+  // Assign stable display IDs based on stable_key
+  // Elements that existed before keep their display ID, new elements get the next available ID
+  const usedDisplayIds = new Set();
+  const newElementKeyToDisplayId = new Map();
+
+  // First pass: assign existing display IDs to elements we've seen before
+  for (const el of uniqueElements) {
+    if (elementKeyToDisplayId.has(el.stable_key)) {
+      const existingId = elementKeyToDisplayId.get(el.stable_key);
+      el.id = existingId;
+      usedDisplayIds.add(existingId);
+      newElementKeyToDisplayId.set(el.stable_key, existingId);
+    }
+  }
+
+  // Second pass: assign new display IDs to new elements
+  let nextId = 1;
+  for (const el of uniqueElements) {
+    if (el.id === null) {
+      // Find next available ID
+      while (usedDisplayIds.has(`E${nextId}`)) {
+        nextId++;
+      }
+      el.id = `E${nextId}`;
+      usedDisplayIds.add(el.id);
+      newElementKeyToDisplayId.set(el.stable_key, el.id);
+      nextId++;
+    }
+  }
+
+  // Update the global mappings
+  elementKeyToDisplayId = newElementKeyToDisplayId;
+  displayIdToElement = new Map();
+  for (const el of uniqueElements) {
+    displayIdToElement.set(el.id, el);
+  }
+
+  // Add dialog pseudo-element if one is pending
+  const dialogElement = getDialogPseudoElement();
+  if (dialogElement) {
+    uniqueElements.unshift(dialogElement);
+    displayIdToElement.set(dialogElement.id, dialogElement);
+  }
+
+  lastElements = uniqueElements;
+  return lastElements;
+}
+
+async function debugOverlay(x, y) {
+  await page.evaluate(({ x, y }) => {
+    const id = "__debug_click_overlay__";
+    let el = document.getElementById(id);
+
+    if (!el) {
+      el = document.createElement("div");
+      el.id = id;
+      el.style.position = "fixed";
+      el.style.width = "14px";
+      el.style.height = "14px";
+      el.style.border = "2px solid red";
+      el.style.borderRadius = "50%";
+      el.style.background = "rgba(255,0,0,0.25)";
+      el.style.pointerEvents = "none";
+      el.style.zIndex = "2147483647";
+      document.body.appendChild(el);
+    }
+
+    el.style.left = `${x - 7}px`;
+    el.style.top = `${y - 7}px`;
+  }, { x, y });
+}
+
+// Commands that should be blocked when a dialog is pending
+const DIALOG_BLOCKING_COMMANDS = ['navigate', 'click_element', 'select_option', 'keypress', 'scroll', 'wait', 'capture'];
+
+async function handleCommand(msg) {
+  const { request_id, command, params } = msg;
+
+  try {
+    let result = {};
+
+    // Block certain commands when a dialog is pending
+    if (DIALOG_BLOCKING_COMMANDS.includes(command) && hasDialog()) {
+      const info = getDialogInfo();
+      throw new Error(
+        `Cannot execute ${command}: JavaScript ${info.type} dialog is blocking the page. ` +
+        `Message: "${info.message.substring(0, 100)}". ` +
+        `Use accept_dialog or dismiss_dialog first.`
+      );
+    }
+
+    switch (command) {
+      case "navigate": {
+        if (!params?.url) throw new Error("navigate requires url");
+        lastClickedElement = null; // Clear focus context on navigation
+        await page.goto(params.url, { waitUntil: "load" });
+        // Wait for any post-load JS to execute
+        await new Promise(r => setTimeout(r, 500));
+        result.screenshot_base64 = await screenshotBase64();
+        result.elements = await enumerateElements();
+        break;
+      }
+
+      case "capture": {
+        result.screenshot_base64 = await screenshotBase64();
+        result.elements = await enumerateElements();
+        break;
+      }
+
+      case "click_element": {
+        const { element_id } = params;
+        if (!element_id) throw new Error("click_element requires element_id");
+
+        const element = displayIdToElement.get(element_id);
+        if (!element) throw new Error(`Element not found: ${element_id}`);
+        lastClickedElement = element; // Store for keypress context
+
+        const { x, y, w, h } = element.bounding_box;
+        const centerX = x + w / 2;
+        const centerY = y + h / 2;
+
+        await debugOverlay(centerX, centerY);
+
+        // Set up dialog listener BEFORE clicking to avoid race conditions.
+        // When a dialog appears, Playwright's click() blocks until the dialog
+        // is resolved. We use waitForEvent to detect dialog appearance.
+        const dialogPromise = page.waitForEvent('dialog', { timeout: 300 })
+          .then(() => 'dialog')
+          .catch(() => 'no-dialog');
+
+        // Start the click - this may block if a dialog appears
+        const clickPromise = page.mouse.click(centerX, centerY);
+
+        // Race: either click completes (no dialog) or dialog appears (click blocked)
+        // If dialogPromise wins with 'dialog', the click is blocked on the dialog.
+        // If clickPromise wins, no dialog appeared within the timeout window.
+        // If dialogPromise wins with 'no-dialog', click is still in flight.
+        const raceResult = await Promise.race([
+          clickPromise.then(() => 'click-done'),
+          dialogPromise
+        ]);
+
+        if (raceResult === 'dialog') {
+          // Dialog appeared - click is blocked waiting for dialog resolution.
+          // We intentionally don't await clickPromise here because it won't
+          // resolve until accept_dialog/dismiss_dialog is called. The click
+          // will complete synchronously when the dialog is resolved.
+          // Store the pending click so we can await it after dialog handling.
+          pendingClickPromise = clickPromise;
+
+          const dialogElement = getDialogPseudoElement();
+          result.screenshot_base64 = null; // Can't screenshot while dialog blocks
+          result.elements = dialogElement ? [dialogElement] : [];
+          result.dialog_blocking = true;
+        } else {
+          // Either click completed or timed out waiting for dialog
+          if (raceResult !== 'click-done') {
+            // dialogPromise timed out ('no-dialog'), click still in flight
+            await clickPromise;
+          }
+          // Click is now complete - wait for page to settle
+          await new Promise(r => setTimeout(r, 500));
+          result.screenshot_base64 = await screenshotBase64();
+          result.elements = await enumerateElements();
+        }
+        break;
+      }
+
+      case "select_option": {
+        const { element_id, value } = params;
+        if (!element_id) throw new Error("select_option requires element_id");
+        if (!value) throw new Error("select_option requires value");
+
+        const element = displayIdToElement.get(element_id);
+        if (!element) throw new Error(`Element not found: ${element_id}`);
+
+        // Find the select element by its bounding box center
+        const { x, y, w, h } = element.bounding_box;
+        const centerX = x + w / 2;
+        const centerY = y + h / 2;
+
+        // Use Playwright's selectOption by locating the element at the position
+        const selectEl = page.locator('select').filter({
+          has: page.locator(`text="${value}"`)
+        }).or(page.locator('select')).first();
+
+        // Try to find the exact select element by position
+        const selectAtPoint = await page.evaluateHandle(
+          ({ x, y }) => document.elementFromPoint(x, y)?.closest('select'),
+          { x: centerX, y: centerY }
+        );
+
+        if (selectAtPoint) {
+          await selectAtPoint.selectOption({ label: value });
+        } else {
+          throw new Error(`No select element found at position for ${element_id}`);
+        }
+
+        // Wait for page to settle after selection (form updates, validation)
+        await new Promise(r => setTimeout(r, 500));
+        result.screenshot_base64 = await screenshotBase64();
+        result.elements = await enumerateElements();
+        break;
+      }
+
+      case "keypress": {
+        if (!params?.keys) throw new Error("keypress requires keys");
+
+        // Handle Ctrl+A (select all) as a special case
+        // Use Meta+a on macOS (Command key) and Control+a on other platforms
+        if (params.keys === 'ctrl+a' || params.keys === 'Ctrl+A') {
+          const modifier = process.platform === 'darwin' ? 'Meta' : 'Control';
+          await page.keyboard.press(`${modifier}+a`);
+          await new Promise(r => setTimeout(r, 100));
+          result.screenshot_base64 = await screenshotBase64();
+          result.elements = await enumerateElements();
+          break;
+        }
+
+        // Map special characters to Playwright key names
+        const specialKeyMap = {
+          '\b': 'Backspace',
+          '\n': 'Enter',
+          '\r': 'Enter',
+          '\t': 'Tab',
+          '\x1b': 'Escape',
+          ' ': 'Space',
+        };
+
+        // Detect typing non-numeric text into a number input
+        if (lastClickedElement?.input_type === 'number') {
+          // Allow digits, decimal point, minus sign, and special keys
+          const nonNumericChars = params.keys.replace(/[0-9.\-]/g, '');
+          const hasNonSpecialText = [...nonNumericChars].some(c => !specialKeyMap[c]);
+
+          if (hasNonSpecialText) {
+            throw new Error(
+              `Cannot type text "${params.keys}" into number input (${lastClickedElement.id}). ` +
+              `Number inputs only accept numeric values. ` +
+              `Consider clicking on a text input field instead, or enter only digits.`
+            );
+          }
+        }
+
+        // Type each character, mapping special chars to Playwright key names
+        for (const char of params.keys) {
+          const key = specialKeyMap[char] || char;
+          await page.keyboard.press(key);
+        }
+
+        // Wait for search/autocomplete to settle
+        await new Promise(r => setTimeout(r, 1000));
+        result.screenshot_base64 = await screenshotBase64();
+        result.elements = await enumerateElements();
+        break;
+      }
+
+      case "wait": {
+        if (!params?.ms) throw new Error("wait requires ms");
+        await new Promise(r => setTimeout(r, params.ms));
+        result.screenshot_base64 = await screenshotBase64();
+        result.elements = await enumerateElements();
+        break;
+      }
+
+      case "scroll": {
+        const { direction } = params;
+        if (!direction) throw new Error("scroll requires direction");
+
+        const scrollAmount = 600; // pixels to scroll
+        if (direction === "down") {
+          await page.mouse.wheel(0, scrollAmount);
+        } else if (direction === "up") {
+          await page.mouse.wheel(0, -scrollAmount);
+        } else {
+          throw new Error(`Invalid scroll direction: ${direction}. Must be "up" or "down"`);
+        }
+
+        // Wait for any lazy-loaded content
+        await new Promise(r => setTimeout(r, 300));
+        result.screenshot_base64 = await screenshotBase64();
+        result.elements = await enumerateElements();
+        break;
+      }
+
+      case "accept_dialog": {
+        const { value } = params || {};
+        await acceptDialog(value);
+
+        // If there was a click blocked on this dialog, wait for it to complete
+        if (pendingClickPromise) {
+          await pendingClickPromise;
+          pendingClickPromise = null;
+        }
+
+        // Wait for page to settle after dialog resolution
+        await new Promise(r => setTimeout(r, 500));
+        result.screenshot_base64 = await screenshotBase64();
+        result.elements = await enumerateElements();
+        break;
+      }
+
+      case "dismiss_dialog": {
+        await dismissDialog();
+
+        // If there was a click blocked on this dialog, wait for it to complete
+        if (pendingClickPromise) {
+          await pendingClickPromise;
+          pendingClickPromise = null;
+        }
+
+        // Wait for page to settle after dialog resolution
+        await new Promise(r => setTimeout(r, 500));
+        result.screenshot_base64 = await screenshotBase64();
+        result.elements = await enumerateElements();
+        break;
+      }
+
+      case "quit": {
+        let videoPath = null;
+        if (page) {
+          const video = page.video();
+          if (video) {
+            // Get the path where video will be saved
+            videoPath = await video.path();
+            console.error(`[browser.js] Video will be saved to: ${videoPath}`);
+          } else {
+            console.error('[browser.js] No video object - recording may not have been enabled');
+          }
+        }
+        // Close context - this is when the video file is actually written
+        await context?.close();
+        if (videoPath) {
+          // Verify the file was written
+          if (fs.existsSync(videoPath)) {
+            const stats = fs.statSync(videoPath);
+            console.error(`[browser.js] Video file written: ${videoPath} (${stats.size} bytes)`);
+          } else {
+            console.error(`[browser.js] WARNING: Video file not found after context close: ${videoPath}`);
+          }
+        }
+        await browser.close();
+        send({ request_id, ok: true, result: { video_path: videoPath }, error: null });
+        process.exit(0);
+        return;
+      }
+
+      default:
+        throw new Error(`Unknown command: ${command}`);
+    }
+
+    send({ request_id, ok: true, result, error: null });
+
+  } catch (err) {
+    send({
+      request_id,
+      ok: false,
+      result: {},
+      error: {
+        code: "BROWSER_ERROR",
+        message: err.message
+      }
+    });
+  }
+}
+
+async function main() {
+  await init();
+
+  // Signal readiness to parent process
+  send({ status: "ready" });
+
+  let buffer = "";
+
+  process.stdin.on("data", async chunk => {
+    buffer += chunk.toString();
+
+    while (buffer.includes("\n")) {
+      const idx = buffer.indexOf("\n");
+      const line = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 1);
+
+      if (!line.trim()) continue;
+
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        send({
+          request_id: null,
+          ok: false,
+          result: {},
+          error: { code: "INVALID_JSON", message: "Invalid JSON" }
+        });
+        continue;
+      }
+
+      if (!msg.request_id || !msg.command) {
+        send({
+          request_id: msg.request_id ?? null,
+          ok: false,
+          result: {},
+          error: { code: "INVALID_MESSAGE", message: "Missing request_id or command" }
+        });
+        continue;
+      }
+
+      await handleCommand(msg);
+    }
+  });
+}
+
+// Only run main when executed directly, not when imported as a module
+const __filename = fileURLToPath(import.meta.url);
+if (__filename === process.argv[1]) {
+  main().catch(err => {
+    send({
+      request_id: null,
+      ok: false,
+      result: {},
+      error: { code: "FATAL", message: err.message }
+    });
+    process.exit(1);
+  });
+}