@inamul_hasan/vouch 1.0.0

package/dist/index.js

@@ -0,0 +1,1389 @@
+#!/usr/bin/env node
+
+// src/cli/commands.ts
+import { Command } from "commander";
+import * as fs7 from "fs";
+
+// src/cli/runner.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+
+// src/types/index.ts
+var TERMINAL_ACTIONS = ["complete", "fail"];
+var DEFAULT_CONFIG = {
+  provider: "openai",
+  model: "gpt-4o",
+  viewportWidth: 1280,
+  viewportHeight: 800,
+  headless: false,
+  maxRetries: 3,
+  actionDelay: 200,
+  stepTimeout: 3e4,
+  report: true,
+  reportDir: "./.vouch/reports",
+  recordVideo: false,
+  videoDir: "./.vouch/videos"
+};
+
+// src/engine/prompts.ts
+var VISION_QA_SYSTEM_PROMPT = `QA engine. Input: instruction, UI tree, history. Output: JSON only.
+Grid: 0-1000. Format: role "name" v="val" @x,y
+Rules: fix typos, self-heal from history, detect validation errors, use 'complete' when done, 'fail' if stuck.
+{"reasoning":"...","action":"click|type|wait|scroll|hover|keypress|select|upload|complete|fail","x":0,"y":0,"textPayload":"","detectedValidationError":""}`;
+function buildUserMessage(stepInstruction, historyLedger, screenReaderOutput) {
+  const parts = [];
+  parts.push(`INSTRUCTION: ${stepInstruction}`);
+  if (screenReaderOutput) {
+    parts.push(`
+${screenReaderOutput}`);
+  }
+  if (historyLedger.length > 0) {
+    parts.push(`
+HISTORY:`);
+    for (const e of historyLedger) {
+      parts.push(
+        `#${e.attempt}: ${e.action}@${e.x},${e.y}${e.textPayload ? ` t=${e.textPayload}` : ""} -> ${e.success ? "OK" : "FAIL"}${e.error ? ` err=${e.error}` : ""}${e.detectedValidationError ? ` val=${e.detectedValidationError}` : ""}`
+      );
+    }
+  }
+  parts.push("\nRespond with JSON.");
+  return parts.join("\n");
+}
+
+// src/engine/providers/openai.ts
+import OpenAI from "openai";
+
+// src/engine/providers/base.ts
+var BaseProvider = class {
+  /**
+   * Parses the raw AI response text into a validated VisionQAResponse.
+   */
+  parseResponse(raw) {
+    let cleaned = raw.trim();
+    if (cleaned.startsWith("```")) {
+      cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, "").replace(/\n?```\s*$/, "");
+    }
+    cleaned = cleaned.replace(/,\s*([\]}])/g, "$1");
+    let parsed;
+    try {
+      parsed = JSON.parse(cleaned);
+    } catch {
+      const match = cleaned.match(/\{[\s\S]*\}/);
+      if (match) {
+        const extracted = match[0].replace(/,\s*([\]}])/g, "$1");
+        parsed = JSON.parse(extracted);
+      } else {
+        throw new Error(
+          `Failed to parse AI response as JSON:
+${raw.slice(0, 500)}`
+        );
+      }
+    }
+    return {
+      reasoning: String(parsed.reasoning ?? ""),
+      action: String(parsed.action ?? "fail"),
+      x: Math.round(Number(parsed.x ?? 500)),
+      y: Math.round(Number(parsed.y ?? 500)),
+      textPayload: String(parsed.textPayload ?? ""),
+      detectedValidationError: String(parsed.detectedValidationError ?? "")
+    };
+  }
+  /**
+   * Checks if accumulated text contains a complete JSON object.
+   * Returns true when we can safely stop streaming.
+   * Uses brace-depth tracking with proper string/escape handling.
+   */
+  hasCompleteJSON(text) {
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    let started = false;
+    for (const ch of text) {
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\" && inString) {
+        escape = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = !inString;
+        continue;
+      }
+      if (inString) continue;
+      if (ch === "{") {
+        depth++;
+        started = true;
+      } else if (ch === "}") {
+        depth--;
+        if (started && depth === 0) return true;
+      }
+    }
+    return false;
+  }
+};
+
+// src/engine/providers/openai.ts
+var OpenAIProvider = class extends BaseProvider {
+  client;
+  model;
+  constructor(apiKey, model = "gpt-4o", baseUrl) {
+    super();
+    this.client = new OpenAI({
+      apiKey,
+      ...baseUrl ? { baseURL: baseUrl } : {}
+    });
+    this.model = model;
+  }
+  async analyze(systemPrompt, stepInstruction, screenReaderOutput, historyLedger) {
+    const userMessage = buildUserMessage(stepInstruction, historyLedger, screenReaderOutput);
+    const stream = await this.client.chat.completions.create({
+      model: this.model,
+      max_tokens: 300,
+      temperature: 0.1,
+      stream: true,
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userMessage }
+      ]
+    });
+    let accumulated = "";
+    for await (const chunk of stream) {
+      const delta = chunk.choices[0]?.delta?.content ?? "";
+      accumulated += delta;
+      if (this.hasCompleteJSON(accumulated)) {
+        stream.controller.abort();
+        break;
+      }
+    }
+    if (!accumulated.trim()) throw new Error("OpenAI returned empty response");
+    return this.parseResponse(accumulated);
+  }
+};
+
+// src/engine/providers/anthropic.ts
+import Anthropic from "@anthropic-ai/sdk";
+var AnthropicProvider = class extends BaseProvider {
+  client;
+  model;
+  constructor(apiKey, model = "claude-sonnet-4-20250514", baseUrl) {
+    super();
+    this.client = new Anthropic({
+      apiKey,
+      ...baseUrl ? { baseURL: baseUrl } : {}
+    });
+    this.model = model;
+  }
+  async analyze(systemPrompt, stepInstruction, screenReaderOutput, historyLedger) {
+    const userMessage = buildUserMessage(
+      stepInstruction,
+      historyLedger,
+      screenReaderOutput
+    );
+    const stream = this.client.messages.stream({
+      model: this.model,
+      max_tokens: 300,
+      temperature: 0.1,
+      system: systemPrompt,
+      messages: [{ role: "user", content: userMessage }]
+    });
+    let accumulated = "";
+    for await (const event of stream) {
+      if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
+        accumulated += event.delta.text;
+        if (this.hasCompleteJSON(accumulated)) {
+          stream.abort();
+          break;
+        }
+      }
+    }
+    if (!accumulated.trim()) {
+      throw new Error("Anthropic returned no text content");
+    }
+    return this.parseResponse(accumulated);
+  }
+};
+
+// src/engine/providers/google.ts
+import { GoogleGenerativeAI } from "@google/generative-ai";
+var GoogleProvider = class extends BaseProvider {
+  genAI;
+  model;
+  constructor(apiKey, model = "gemini-2.0-flash") {
+    super();
+    this.genAI = new GoogleGenerativeAI(apiKey);
+    this.model = model;
+  }
+  async analyze(systemPrompt, stepInstruction, screenReaderOutput, historyLedger) {
+    const userMessage = buildUserMessage(
+      stepInstruction,
+      historyLedger,
+      screenReaderOutput
+    );
+    const generativeModel = this.genAI.getGenerativeModel({
+      model: this.model,
+      systemInstruction: systemPrompt
+    });
+    const result = await generativeModel.generateContentStream([
+      { text: userMessage }
+    ]);
+    let accumulated = "";
+    for await (const chunk of result.stream) {
+      const text = chunk.text();
+      if (text) {
+        accumulated += text;
+        if (this.hasCompleteJSON(accumulated)) {
+          break;
+        }
+      }
+    }
+    if (!accumulated.trim()) throw new Error("Google Gemini returned empty response");
+    return this.parseResponse(accumulated);
+  }
+};
+
+// src/engine/providers/ollama.ts
+var OllamaProvider = class extends BaseProvider {
+  baseUrl;
+  model;
+  constructor(model = "llava", baseUrl = "http://localhost:11434") {
+    super();
+    this.model = model;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  async analyze(systemPrompt, stepInstruction, screenReaderOutput, historyLedger) {
+    const userMessage = buildUserMessage(
+      stepInstruction,
+      historyLedger,
+      screenReaderOutput
+    );
+    const controller = new AbortController();
+    const response = await fetch(`${this.baseUrl}/api/chat`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      signal: controller.signal,
+      body: JSON.stringify({
+        model: this.model,
+        stream: true,
+        keep_alive: "5m",
+        options: {
+          temperature: 0.1,
+          num_predict: 300
+        },
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userMessage }
+        ]
+      })
+    });
+    if (!response.ok) {
+      const errText = await response.text();
+      throw new Error(`Ollama request failed (${response.status}): ${errText}`);
+    }
+    const raw = await this.streamUntilJSON(response, controller);
+    if (!raw) throw new Error("Ollama returned empty response");
+    return this.parseResponse(raw);
+  }
+  /**
+   * Reads the streaming response token-by-token.
+   * As soon as the accumulated text contains a complete JSON object
+   * (balanced braces), we abort the connection and return immediately.
+   * This saves significant inference time on trailing tokens.
+   */
+  async streamUntilJSON(response, controller) {
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("No response body from Ollama");
+    const decoder = new TextDecoder();
+    let accumulated = "";
+    let braceDepth = 0;
+    let inString = false;
+    let escape = false;
+    let jsonStarted = false;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const chunk = decoder.decode(value, { stream: true });
+        const lines = chunk.split("\n").filter((l) => l.trim());
+        for (const line of lines) {
+          try {
+            const data = JSON.parse(line);
+            const token = data.message?.content ?? "";
+            accumulated += token;
+            for (const ch of token) {
+              if (escape) {
+                escape = false;
+                continue;
+              }
+              if (ch === "\\" && inString) {
+                escape = true;
+                continue;
+              }
+              if (ch === '"') {
+                inString = !inString;
+                continue;
+              }
+              if (inString) continue;
+              if (ch === "{") {
+                braceDepth++;
+                jsonStarted = true;
+              } else if (ch === "}") {
+                braceDepth--;
+                if (jsonStarted && braceDepth === 0) {
+                  controller.abort();
+                  return accumulated;
+                }
+              }
+            }
+            if (data.done) {
+              return accumulated;
+            }
+          } catch {
+          }
+        }
+      }
+    } catch (err) {
+      if (err?.name === "AbortError") {
+        return accumulated;
+      }
+      if (accumulated.trim()) return accumulated;
+      throw err;
+    } finally {
+      reader.releaseLock();
+    }
+    return accumulated;
+  }
+};
+
+// src/engine/vision.ts
+function createProvider(config) {
+  const providers = {
+    openai: () => {
+      if (!config.apiKey)
+        throw new Error(
+          "OpenAI API key is required. Set VOUCH_API_KEY or provider.apiKey in config."
+        );
+      return new OpenAIProvider(config.apiKey, config.model, config.baseUrl);
+    },
+    anthropic: () => {
+      if (!config.apiKey)
+        throw new Error(
+          "Anthropic API key is required. Set VOUCH_API_KEY or provider.apiKey in config."
+        );
+      return new AnthropicProvider(config.apiKey, config.model, config.baseUrl);
+    },
+    google: () => {
+      if (!config.apiKey)
+        throw new Error(
+          "Google API key is required. Set VOUCH_API_KEY or provider.apiKey in config."
+        );
+      return new GoogleProvider(config.apiKey, config.model);
+    },
+    ollama: () => {
+      return new OllamaProvider(
+        config.model,
+        config.baseUrl || "http://localhost:11434"
+      );
+    }
+  };
+  const factory = providers[config.provider];
+  if (!factory) {
+    throw new Error(
+      `Unknown AI provider: "${config.provider}". Supported: openai, anthropic, google, ollama`
+    );
+  }
+  return factory();
+}
+var VisionQAEngine = class {
+  provider;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.provider = createProvider(config);
+  }
+  /**
+   * Analyze the page using screen reader output and step instruction.
+   */
+  async analyze(stepInstruction, screenReaderOutput, historyLedger) {
+    return this.provider.analyze(
+      VISION_QA_SYSTEM_PROMPT,
+      stepInstruction,
+      screenReaderOutput,
+      historyLedger
+    );
+  }
+  /**
+   * Convert normalized coordinates (0-1000) to pixel coordinates.
+   */
+  toPixelCoords(normalizedX, normalizedY, viewportWidth, viewportHeight) {
+    return {
+      pixelX: Math.round(normalizedX / 1e3 * viewportWidth),
+      pixelY: Math.round(normalizedY / 1e3 * viewportHeight)
+    };
+  }
+  /**
+   * Checks if the response indicates a terminal action.
+   */
+  isTerminal(response) {
+    return TERMINAL_ACTIONS.includes(response.action);
+  }
+  /**
+   * Checks if the response contains a validation error.
+   */
+  hasValidationError(response) {
+    return response.detectedValidationError.length > 0;
+  }
+};
+
+// src/browser/controller.ts
+import puppeteer from "puppeteer";
+import { PuppeteerScreenRecorder } from "puppeteer-screen-recorder";
+import * as fs from "fs";
+import * as path from "path";
+var SKIP_ROLES = /* @__PURE__ */ new Set([
+  "none",
+  "generic",
+  "InlineTextBox",
+  "LineBreak",
+  "paragraph",
+  "Section",
+  "group",
+  "document",
+  "WebArea",
+  "main",
+  "navigation",
+  "banner",
+  "contentinfo",
+  "complementary",
+  "list",
+  "listitem",
+  "StaticText",
+  "rootWebArea"
+]);
+var BrowserController = class {
+  browser = null;
+  page = null;
+  cdpClient = null;
+  config;
+  recorder = null;
+  videoPath = null;
+  constructor(config) {
+    this.config = config;
+  }
+  async launch() {
+    this.browser = await puppeteer.launch({
+      headless: this.config.headless,
+      defaultViewport: {
+        width: this.config.viewportWidth,
+        height: this.config.viewportHeight
+      },
+      args: [
+        "--no-sandbox",
+        "--disable-setuid-sandbox",
+        "--disable-dev-shm-usage",
+        "--disable-extensions",
+        "--disable-background-networking",
+        "--disable-sync",
+        "--disable-translate",
+        "--metrics-recording-only",
+        "--no-first-run",
+        `--window-size=${this.config.viewportWidth},${this.config.viewportHeight}`
+      ]
+    });
+    const pages = await this.browser.pages();
+    this.page = pages[0] || await this.browser.newPage();
+    this.page.setDefaultNavigationTimeout(this.config.stepTimeout);
+    this.page.setDefaultTimeout(this.config.stepTimeout);
+    this.cdpClient = await this.page.createCDPSession();
+    if (this.config.recordVideo) {
+      if (!fs.existsSync(this.config.videoDir)) {
+        fs.mkdirSync(this.config.videoDir, { recursive: true });
+      }
+      this.videoPath = path.join(
+        this.config.videoDir,
+        `vouch-recording-${Date.now()}.mp4`
+      );
+      this.recorder = new PuppeteerScreenRecorder(this.page);
+      await this.recorder.start(this.videoPath);
+    }
+  }
+  async close() {
+    if (this.recorder) {
+      try {
+        await this.recorder.stop();
+      } catch {
+      }
+      this.recorder = null;
+    }
+    if (this.cdpClient) {
+      try {
+        await this.cdpClient.detach();
+      } catch {
+      }
+      this.cdpClient = null;
+    }
+    if (this.browser) {
+      try {
+        await this.browser.close();
+      } catch {
+      }
+      this.browser = null;
+      this.page = null;
+    }
+  }
+  getVideoPath() {
+    return this.videoPath;
+  }
+  async navigate(url) {
+    this.assertPage();
+    await this.page.goto(url, { waitUntil: "domcontentloaded" });
+    await this.sleep(150);
+  }
+  async click(pixelX, pixelY) {
+    this.assertPage();
+    await this.page.mouse.click(pixelX, pixelY);
+    await this.sleep(50);
+  }
+  async type(pixelX, pixelY, text) {
+    this.assertPage();
+    await this.page.mouse.click(pixelX, pixelY, { count: 3 });
+    await this.sleep(50);
+    await this.page.keyboard.press("Backspace");
+    await this.page.keyboard.type(text, { delay: 0 });
+    await this.sleep(50);
+  }
+  async wait(ms) {
+    await this.sleep(ms);
+  }
+  getViewportSize() {
+    return {
+      width: this.config.viewportWidth,
+      height: this.config.viewportHeight
+    };
+  }
+  getPage() {
+    this.assertPage();
+    return this.page;
+  }
+  /**
+   * Uses Chrome DevTools Protocol Accessibility API to read the page
+   * like a screen reader. Returns a textual description of all visible
+   * interactive elements with their normalized (0-1000) coordinates.
+   *
+   * Performance: reuses persistent CDP session and batches box model lookups.
+   */
+  async getScreenReaderOutput() {
+    this.assertPage();
+    const client = this.cdpClient;
+    const { nodes } = await client.send("Accessibility.getFullAXTree");
+    const { width: vw, height: vh } = this.getViewportSize();
+    const skipRoles = SKIP_ROLES;
+    const relevant = [];
+    for (const node of nodes) {
+      const role = node.role?.value;
+      const name = node.name?.value?.trim();
+      if (!role || skipRoles.has(role) || !name || name === "") continue;
+      const backendNodeId = node.backendDOMNodeId;
+      if (!backendNodeId) continue;
+      relevant.push({ role, name, value: node.value?.value, backendNodeId });
+    }
+    const boxPromises = relevant.map(
+      (n) => client.send("DOM.getBoxModel", { backendNodeId: n.backendNodeId }).then((r) => r.model).catch(() => null)
+    );
+    const boxes = await Promise.allSettled(boxPromises);
+    const results = [];
+    for (let i = 0; i < relevant.length; i++) {
+      const settled = boxes[i];
+      if (settled.status !== "fulfilled" || !settled.value) continue;
+      const model = settled.value;
+      const quad = model.content;
+      const centerX = (quad[0] + quad[4]) / 2;
+      const centerY = (quad[1] + quad[5]) / 2;
+      if (centerX < 0 || centerY < 0 || centerX > vw || centerY > vh) continue;
+      const normX = Math.round(centerX / vw * 1e3);
+      const normY = Math.round(centerY / vh * 1e3);
+      const n = relevant[i];
+      let desc = `${n.role} "${n.name}"`;
+      if (n.value) desc += ` v="${n.value}"`;
+      desc += ` @${normX},${normY}`;
+      results.push(desc);
+    }
+    return results.length > 0 ? "UI:\n" + results.join("\n") : "UI: empty";
+  }
+  assertPage() {
+    if (!this.page) {
+      throw new Error("Browser not launched. Call launch() first.");
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve3) => setTimeout(resolve3, ms));
+  }
+};
+
+// src/actions/coordinator.ts
+var ActionCoordinator = class {
+  engine;
+  browser;
+  config;
+  constructor(engine, browser, config) {
+    this.engine = engine;
+    this.browser = browser;
+    this.config = config;
+  }
+  /**
+   * Execute a single test step with self-healing retries.
+   */
+  async executeStep(step, isLastStep) {
+    const startTime = Date.now();
+    const history = [];
+    if (step.type === "comment") {
+      return { step, status: "skipped", duration: 0, attempts: [] };
+    }
+    if (step.type === "navigate") {
+      try {
+        const url = step.meta?.url ?? step.instruction;
+        await this.browser.navigate(url);
+        return {
+          step,
+          status: "passed",
+          duration: Date.now() - startTime,
+          attempts: []
+        };
+      } catch (err) {
+        return {
+          step,
+          status: "failed",
+          duration: Date.now() - startTime,
+          attempts: [],
+          error: err instanceof Error ? err.message : String(err)
+        };
+      }
+    }
+    if (step.type === "wait") {
+      const ms = parseInt(step.meta?.duration ?? "2000", 10);
+      await this.browser.wait(ms);
+      return {
+        step,
+        status: "passed",
+        duration: Date.now() - startTime,
+        attempts: []
+      };
+    }
+    for (let attempt = 1; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        const screenReader = await this.browser.getScreenReaderOutput();
+        const instruction = step.type === "assert" ? `VERIFY: "${step.instruction}". If confirmed true/visible, respond "complete". If not, respond "fail" with reasoning.` : step.instruction;
+        const response = await this.engine.analyze(
+          instruction,
+          screenReader,
+          history
+        );
+        const entry = {
+          attempt,
+          action: response.action,
+          x: response.x,
+          y: response.y,
+          textPayload: response.textPayload || void 0,
+          timestamp: Date.now(),
+          success: false,
+          detectedValidationError: response.detectedValidationError || void 0
+        };
+        if (response.action === "complete") {
+          entry.success = true;
+          history.push(entry);
+          return {
+            step,
+            status: "passed",
+            duration: Date.now() - startTime,
+            attempts: history
+          };
+        }
+        if (response.action === "fail") {
+          entry.success = false;
+          entry.error = response.reasoning;
+          history.push(entry);
+          if (attempt < this.config.maxRetries) {
+            await this.browser.wait(this.config.actionDelay);
+            continue;
+          }
+          return {
+            step,
+            status: "failed",
+            duration: Date.now() - startTime,
+            attempts: history,
+            error: response.reasoning
+          };
+        }
+        if (step.type === "assert") {
+          entry.success = false;
+          entry.error = `Invalid action for assert step: "${response.action}". You must respond "complete" or "fail".`;
+          history.push(entry);
+          continue;
+        }
+        await this.dispatchAction(response);
+        await this.browser.wait(this.config.actionDelay);
+        if (response.detectedValidationError) {
+          entry.success = false;
+          entry.error = `Validation error: ${response.detectedValidationError}`;
+          history.push(entry);
+          continue;
+        }
+        if (response.action === "wait") {
+          entry.success = true;
+          history.push(entry);
+          continue;
+        }
+        entry.success = true;
+        history.push(entry);
+        return {
+          step,
+          status: "passed",
+          duration: Date.now() - startTime,
+          attempts: history
+        };
+      } catch (err) {
+        history.push({
+          attempt,
+          action: "fail",
+          x: 0,
+          y: 0,
+          timestamp: Date.now(),
+          success: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+    return {
+      step,
+      status: "failed",
+      duration: Date.now() - startTime,
+      attempts: history,
+      error: `Step failed after ${this.config.maxRetries} attempts. Last errors: ${history.filter((h) => h.error).map((h) => h.error).join(" | ")}`
+    };
+  }
+  /**
+   * Dispatch any action to the browser — extensible, not a fixed set.
+   */
+  async dispatchAction(response) {
+    const { width, height } = this.browser.getViewportSize();
+    const { pixelX, pixelY } = this.engine.toPixelCoords(
+      response.x,
+      response.y,
+      width,
+      height
+    );
+    const page = this.browser.getPage();
+    const elementHandle = await page.evaluateHandle((x, y) => document.elementFromPoint(x, y), pixelX, pixelY).catch(() => null);
+    switch (response.action) {
+      case "click":
+        await this.browser.click(pixelX, pixelY);
+        break;
+      case "type":
+        await this.browser.type(pixelX, pixelY, response.textPayload);
+        break;
+      case "wait":
+        await this.browser.wait(2e3);
+        break;
+      case "scroll":
+        await page.mouse.wheel({ deltaY: response.y > 500 ? 300 : -300 });
+        break;
+      case "hover":
+        await page.mouse.move(pixelX, pixelY);
+        break;
+      case "keypress":
+        await page.keyboard.press(response.textPayload);
+        break;
+      case "select":
+        await this.browser.click(pixelX, pixelY);
+        break;
+      case "upload":
+        if (elementHandle && response.textPayload) {
+          const el = elementHandle.asElement();
+          if (el) {
+            await el.uploadFile(response.textPayload);
+          } else {
+            await this.browser.click(pixelX, pixelY);
+          }
+        }
+        break;
+      default:
+        await this.browser.click(pixelX, pixelY);
+        break;
+    }
+    if (elementHandle) {
+      await elementHandle.dispose().catch(() => {
+      });
+    }
+  }
+};
+
+// src/parser/vch-parser.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+function parseVchFile(filePath) {
+  const absolutePath = path2.resolve(filePath);
+  if (!fs2.existsSync(absolutePath)) {
+    throw new Error(`Test file not found: ${absolutePath}`);
+  }
+  const content = fs2.readFileSync(absolutePath, "utf-8");
+  const lines = content.split("\n");
+  let suiteName = path2.basename(filePath, ".vch");
+  const steps = [];
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    const lineNumber = i + 1;
+    if (!trimmed) continue;
+    if (trimmed.startsWith("#")) {
+      steps.push({
+        lineNumber,
+        raw,
+        instruction: trimmed.slice(1).trim(),
+        type: "comment"
+      });
+      continue;
+    }
+    if (trimmed.startsWith(">")) {
+      const metaContent = trimmed.slice(1).trim();
+      const colonIndex = metaContent.indexOf(":");
+      if (colonIndex > 0) {
+        const key = metaContent.slice(0, colonIndex).trim().toLowerCase();
+        const value = metaContent.slice(colonIndex + 1).trim();
+        if (key === "name") {
+          suiteName = value;
+        }
+      }
+      continue;
+    }
+    if (trimmed.startsWith("@navigate")) {
+      const url = trimmed.replace(/^@navigate\s+/, "").trim();
+      steps.push({
+        lineNumber,
+        raw,
+        instruction: url,
+        type: "navigate",
+        meta: { url }
+      });
+      continue;
+    }
+    if (trimmed.startsWith("@wait")) {
+      const ms = trimmed.replace(/^@wait\s+/, "").trim();
+      steps.push({
+        lineNumber,
+        raw,
+        instruction: `Wait for ${ms}ms`,
+        type: "wait",
+        meta: { duration: ms }
+      });
+      continue;
+    }
+    if (trimmed.startsWith("@assert")) {
+      const assertion = trimmed.replace(/^@assert\s+/, "").trim();
+      steps.push({
+        lineNumber,
+        raw,
+        instruction: assertion,
+        type: "assert"
+      });
+      continue;
+    }
+    if (trimmed.startsWith("@if")) {
+      const condition = trimmed.replace(/^@if\s+/, "").trim();
+      steps.push({
+        lineNumber,
+        raw,
+        instruction: condition,
+        type: "conditional"
+      });
+      continue;
+    }
+    steps.push({
+      lineNumber,
+      raw,
+      instruction: trimmed,
+      type: "action"
+    });
+  }
+  return {
+    name: suiteName,
+    filePath: absolutePath,
+    steps
+  };
+}
+
+// src/reporter/json-reporter.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+function generateJSONReport(result, reportDir) {
+  if (!fs3.existsSync(reportDir)) {
+    fs3.mkdirSync(reportDir, { recursive: true });
+  }
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const filename = `vouch-report-${timestamp}.json`;
+  const filePath = path3.join(reportDir, filename);
+  const reportData = JSON.stringify(result, null, 2);
+  fs3.writeFileSync(filePath, reportData, "utf-8");
+  return filePath;
+}
+
+// src/cli/runner.ts
+function loadConfig(overrides = {}) {
+  let fileConfig = {};
+  const configPath = path4.resolve("vouch.config.json");
+  if (fs4.existsSync(configPath)) {
+    try {
+      const raw = fs4.readFileSync(configPath, "utf-8");
+      fileConfig = JSON.parse(raw);
+    } catch {
+    }
+  }
+  const envConfig = {};
+  if (process.env.VOUCH_PROVIDER)
+    envConfig.provider = process.env.VOUCH_PROVIDER;
+  if (process.env.VOUCH_MODEL) envConfig.model = process.env.VOUCH_MODEL;
+  if (process.env.VOUCH_API_KEY) envConfig.apiKey = process.env.VOUCH_API_KEY;
+  if (process.env.VOUCH_BASE_URL)
+    envConfig.baseUrl = process.env.VOUCH_BASE_URL;
+  if (process.env.VOUCH_HEADLESS)
+    envConfig.headless = process.env.VOUCH_HEADLESS === "true";
+  return {
+    ...DEFAULT_CONFIG,
+    ...fileConfig,
+    ...envConfig,
+    ...overrides
+  };
+}
+async function runTestFile(filePath, config, logger) {
+  const suite = parseVchFile(filePath);
+  logger.suiteStart(suite);
+  const engine = new VisionQAEngine(config);
+  const browser = new BrowserController(config);
+  const coordinator = new ActionCoordinator(engine, browser, config);
+  const result = {
+    suite,
+    results: [],
+    startTime: Date.now(),
+    endTime: 0,
+    totalPassed: 0,
+    totalFailed: 0,
+    totalSkipped: 0
+  };
+  try {
+    logger.info("Launching browser...");
+    await browser.launch();
+    logger.info("Browser ready.");
+    const actionSteps = suite.steps.filter((s) => s.type !== "comment");
+    for (let i = 0; i < suite.steps.length; i++) {
+      const step = suite.steps[i];
+      const isLastActionStep = step === actionSteps[actionSteps.length - 1];
+      logger.stepStart(step);
+      const stepResult = await coordinator.executeStep(step, isLastActionStep);
+      result.results.push(stepResult);
+      switch (stepResult.status) {
+        case "passed":
+          result.totalPassed++;
+          break;
+        case "failed":
+          result.totalFailed++;
+          break;
+        case "skipped":
+          result.totalSkipped++;
+          break;
+      }
+      logger.stepEnd(stepResult);
+    }
+  } catch (err) {
+    logger.error(
+      `Fatal error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  } finally {
+    await browser.close();
+    logger.info("Browser closed.");
+    const video = browser.getVideoPath();
+    if (video) {
+      logger.info(`Video saved: ${path4.resolve(video)}`);
+    }
+  }
+  result.endTime = Date.now();
+  if (config.report) {
+    const reportFile = generateJSONReport(result, config.reportDir);
+    logger.info(`Report generated: ${path4.resolve(reportFile)}`);
+  }
+  logger.suiteEnd(result);
+  return result;
+}
+
+// src/cli/init.ts
+import * as fs5 from "fs";
+import * as path5 from "path";
+async function initProject(quiet = false) {
+  let chalk2 = void 0;
+  let figures2 = void 0;
+  let p = null;
+  try {
+    chalk2 = await import("chalk");
+    figures2 = await import("figures");
+    if (!quiet) {
+      p = await import("@clack/prompts");
+    }
+  } catch (e) {
+  }
+  const c = chalk2?.default ?? chalk2;
+  const f = figures2?.default ?? figures2;
+  const configContent = JSON.stringify(DEFAULT_CONFIG, null, 2);
+  if (!fs5.existsSync("vouch.config.json")) {
+    fs5.writeFileSync("vouch.config.json", configContent, "utf-8");
+    if (p) p.log.success("Created vouch.config.json");
+    else if (!quiet && c && f)
+      console.log(c.green(`  ${f.tick} Created vouch.config.json`));
+  } else {
+    if (!quiet && c && f)
+      console.log(
+        c.yellow(`  ${f.warning} vouch.config.json already exists, skipping.`)
+      );
+  }
+  const exampleDir = "examples";
+  if (!fs5.existsSync(exampleDir)) {
+    fs5.mkdirSync(exampleDir, { recursive: true });
+  }
+  const exampleTest = `> name: Example Login Flow
+# This is an example Vouch test file
+
+@navigate https://example.com/login
+
+click on the email input field
+type test@example.com into the email field
+click on the password input field
+type SecurePassword123! into the password field
+
+click the Sign In button
+
+@assert Dashboard heading is visible
+`;
+  const examplePath = path5.join(exampleDir, "demo.vch");
+  if (!fs5.existsSync(examplePath)) {
+    fs5.writeFileSync(examplePath, exampleTest, "utf-8");
+    if (p) p.log.success(`Created ${examplePath}`);
+    else if (!quiet && c && f)
+      console.log(c.green(`  ${f.tick} Created ${examplePath}`));
+  }
+}
+
+// src/cli/interactive.ts
+import * as fs6 from "fs";
+import * as path6 from "path";
+
+// src/cli/logger.ts
+var chalk;
+var figures;
+var ora;
+async function loadLoggerDeps() {
+  chalk = await import("chalk");
+  figures = await import("figures");
+  ora = await import("ora");
+}
+function createLogger() {
+  const c = chalk?.default ?? chalk;
+  const f = figures?.default ?? figures;
+  const o = ora?.default ?? ora;
+  let currentSpinner = null;
+  return {
+    info(msg) {
+      if (currentSpinner) {
+        currentSpinner.info(c.dim(msg));
+        currentSpinner.start();
+        return;
+      }
+      if (c && f) console.log(c.dim(`  ${f.pointerSmall} ${msg}`));
+      else console.log(`  > ${msg}`);
+    },
+    error(msg) {
+      if (currentSpinner) {
+        currentSpinner.fail(c.red(msg));
+        currentSpinner = null;
+        return;
+      }
+      if (c && f) console.log(c.red(`  ${f.cross} ${msg} `));
+      else console.error(`  X ${msg}`);
+    },
+    suiteStart(suite) {
+      console.log();
+      if (c) {
+        console.log(c.bold.green(`  \u{1F578}\uFE0F ${suite.name}`));
+        console.log(c.dim(`  ${suite.filePath}`));
+        console.log(
+          c.dim(
+            `  ${suite.steps.filter((s) => s.type !== "comment").length} steps`
+          )
+        );
+      } else {
+        console.log(`  \u{1F578}\uFE0F ${suite.name}
+  ${suite.filePath}`);
+      }
+      console.log();
+    },
+    suiteEnd(result) {
+      const duration = ((result.endTime - result.startTime) / 1e3).toFixed(2);
+      console.log();
+      if (c && f) {
+        console.log(c.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+        if (result.totalFailed === 0) {
+          console.log(
+            c.bold.green(`  ${f.tick} All ${result.totalPassed} steps passed`) + c.dim(` (${duration}s)`)
+          );
+        } else {
+          console.log(
+            c.bold.green(`  ${f.cross} ${result.totalFailed} failed`) + c.dim(` | `) + c.green(`${result.totalPassed} passed`) + c.dim(` (${duration}s)`)
+          );
+        }
+      } else {
+        console.log(
+          `  ${result.totalFailed === 0 ? "Passed" : "Failed"}: ${result.totalPassed} passed, ${result.totalFailed} failed (${duration}s)`
+        );
+      }
+      console.log();
+    },
+    stepStart(step) {
+      if (step.type === "comment") return;
+      if (c && o) {
+        const prefix = step.type === "navigate" ? "\u{1F310}" : step.type === "assert" ? "\u{1F50D}" : step.type === "wait" ? "\u23F3" : "\u{1F3AF}";
+        currentSpinner = o({
+          text: c.dim(`${prefix} L${step.lineNumber}: `) + c.green(step.instruction),
+          color: "green",
+          spinner: "dots"
+        }).start();
+      } else {
+        process.stdout.write(`  L${step.lineNumber}: ${step.instruction}  `);
+      }
+    },
+    stepEnd(result) {
+      if (result.step.type === "comment") return;
+      const durationStr = `${(result.duration / 1e3).toFixed(1)}s`;
+      if (currentSpinner) {
+        if (result.status === "passed") {
+          currentSpinner.succeed(
+            currentSpinner.text + c.dim(` ${durationStr}`)
+          );
+        } else if (result.status === "failed") {
+          currentSpinner.fail(currentSpinner.text + c.dim(` ${durationStr}`));
+          if (result.error)
+            console.log(c.dim(`     \u2514\u2500 `) + c.red(result.error.slice(0, 120)));
+        } else {
+          currentSpinner.stopAndPersist({
+            symbol: c.dim(f.arrowRight),
+            text: currentSpinner.text + c.dim(" skipped")
+          });
+        }
+        currentSpinner = null;
+      } else {
+        if (result.status === "passed") {
+          if (c && f) console.log(c.green(f.tick) + c.dim(` ${durationStr}`));
+          else console.log(` OK ${durationStr}`);
+        } else if (result.status === "failed") {
+          if (c && f) {
+            console.log(c.red(f.cross) + c.dim(` ${durationStr}`));
+            if (result.error)
+              console.log(c.green(`     \u2514\u2500 ${result.error.slice(0, 120)}`));
+          } else {
+            console.log(` FAIL ${durationStr}`);
+            if (result.error)
+              console.log(`     \u2514\u2500 ${result.error.slice(0, 120)}`);
+          }
+        } else {
+          if (c && f) console.log(c.dim(f.arrowRight + " skipped"));
+          else console.log(" skipped");
+        }
+      }
+    }
+  };
+}
+
+// src/cli/interactive.ts
+function findVchFiles(dir, fileList = []) {
+  try {
+    const files = fs6.readdirSync(dir);
+    for (const file of files) {
+      if (file === "node_modules" || file === ".git" || file === "dist" || file === ".vouch" || file.startsWith("."))
+        continue;
+      const fullPath = path6.join(dir, file);
+      const stat = fs6.statSync(fullPath);
+      if (stat.isDirectory()) {
+        findVchFiles(fullPath, fileList);
+      } else if (file.endsWith(".vch")) {
+        fileList.push(fullPath);
+      }
+    }
+  } catch (e) {
+  }
+  return fileList;
+}
+async function runInteractiveMenu() {
+  const chalk2 = await import("chalk");
+  const p = await import("@clack/prompts");
+  const c = chalk2.default ?? chalk2;
+  console.clear();
+  console.log(
+    c.bold.white(`
+ \u2584\u2584   \u2584\u2584 \u2584\u2584\u2584\u2584\u2584\u2584\u2584 \u2584\u2584   \u2584\u2584 \u2584\u2584\u2584\u2584\u2584\u2584\u2584 \u2584\u2584   \u2584\u2584
+\u2588  \u2588 \u2588  \u2588       \u2588  \u2588 \u2588  \u2588       \u2588  \u2588 \u2588  \u2588
+\u2588  \u2588 \u2588  \u2588   \u2584   \u2588  \u2588 \u2588  \u2588       \u2588  \u2588\u2584\u2588  \u2588
+\u2588  \u2588\u2584\u2588  \u2588  \u2588 \u2588  \u2588  \u2588\u2584\u2588  \u2588     \u2584\u2584\u2588       \u2588
+\u2588       \u2588  \u2588\u2584\u2588  \u2588       \u2588    \u2588  \u2588   \u2584   \u2588
+\u2580     \u2584\u2584\u2588       \u2588       \u2588    \u2588\u2584\u2584\u2588  \u2588 \u2588  \u2588
+ \u2580\u2584\u2584\u2584\u2580  \u2580\u2584\u2584\u2584\u2584\u2584\u2584\u2584\u2580\u2584\u2584\u2584\u2584\u2584\u2584\u2584\u2580\u2584\u2584\u2584\u2584\u2584\u2584\u2584\u2580\u2584\u2584\u2580 \u2580\u2584\u2584\u2580
+  `)
+  );
+  console.log(c.dim("        The future of visual web automation\n"));
+  p.intro(c.bgWhite(c.black(" Welcome to Vouch ")));
+  if (!fs6.existsSync("vouch.config.json")) {
+    await initProject(true);
+  }
+  const testFiles = findVchFiles(process.cwd());
+  const relativeFiles = testFiles.map((f) => path6.relative(process.cwd(), f));
+  const action = await p.select({
+    message: "What would you like to do?",
+    options: [
+      {
+        label: "\u25B6 Run specific tests",
+        value: "run_selected",
+        hint: "Choose files to run"
+      },
+      {
+        label: "\u25B6 Run all tests",
+        value: "run_all",
+        hint: "Execute all .vch files"
+      },
+      {
+        label: "\u{1F680} Initialize examples",
+        value: "init",
+        hint: "Create example tests"
+      },
+      { label: "\u274C Exit", value: "exit" }
+    ]
+  });
+  if (action === "exit" || p.isCancel(action)) {
+    p.outro("Goodbye!");
+    process.exit(0);
+  }
+  if (action === "init") {
+    await initProject(false);
+    p.outro("Examples initialized! Run 'vouch' again to execute tests.");
+    process.exit(0);
+  }
+  let selectedFiles = [];
+  if (action === "run_all") {
+    if (relativeFiles.length === 0) {
+      p.log.warn("No .vch files found in the current directory.");
+      process.exit(0);
+    }
+    selectedFiles = relativeFiles;
+  } else if (action === "run_selected") {
+    if (relativeFiles.length === 0) {
+      p.log.warn("No .vch files found in the current directory.");
+      process.exit(0);
+    }
+    const files = await p.multiselect({
+      message: "Select test files (type to search)",
+      options: relativeFiles.map((f) => ({
+        label: path6.basename(f),
+        // Just show file name
+        value: f,
+        hint: path6.dirname(f) === "." ? void 0 : path6.dirname(f)
+      })),
+      required: true
+    });
+    if (p.isCancel(files)) process.exit(0);
+    selectedFiles = files;
+  }
+  const config = loadConfig();
+  p.outro("Starting tests...");
+  const logger = createLogger();
+  let totalFailed = 0;
+  for (const file of selectedFiles) {
+    const result = await runTestFile(file, config, logger);
+    totalFailed += result.totalFailed;
+  }
+  process.exit(totalFailed > 0 ? 1 : 0);
+}
+
+// src/cli/commands.ts
+async function ensureConfigExists() {
+  if (!fs7.existsSync("vouch.config.json")) {
+    await initProject(true);
+  }
+}
+function createCLI() {
+  const program = new Command();
+  program.name("vouch").description("\u{1F578}\uFE0F Vouch \u2014 Zero-selector, vision-driven web automation").version("1.0.0");
+  program.action(async () => {
+    await ensureConfigExists();
+    await runInteractiveMenu();
+  });
+  program.command("run").description("Execute a .vch file").argument("<file>", "Path to the .vch file").option(
+    "-p, --provider <provider>",
+    "AI provider (openai, anthropic, google, ollama)"
+  ).option("-m, --model <model>", "AI model identifier").option("-k, --api-key <key>", "API key for the AI provider").option("--base-url <url>", "Base URL override").option("--headless", "Run browser in headless mode").option("--no-headless", "Run browser in headed mode").option("--retries <n>", "Max retries per step", parseInt).option("--viewport <WxH>", "Viewport size (e.g., 1280x800)").option("--no-report", "Skip JSON report generation").option("--report-dir <dir>", "JSON report output directory").action(async (file, options) => {
+    await ensureConfigExists();
+    await loadLoggerDeps();
+    const chalk2 = await import("chalk");
+    const boxen = await import("boxen");
+    const c = chalk2.default ?? chalk2;
+    const b = boxen.default ?? boxen;
+    console.log(
+      b(c.bold.white("\u{1F578}\uFE0F VOUCH") + c.dim(" \u2014 Vision-Driven Automation"), {
+        padding: { top: 0, bottom: 0, left: 2, right: 2 },
+        borderStyle: "round",
+        borderColor: "white",
+        dimBorder: true
+      })
+    );
+    const overrides = {};
+    if (options.provider)
+      overrides.provider = options.provider;
+    if (options.model) overrides.model = options.model;
+    if (options.apiKey) overrides.apiKey = options.apiKey;
+    if (options.baseUrl) overrides.baseUrl = options.baseUrl;
+    if (typeof options.headless === "boolean")
+      overrides.headless = options.headless;
+    if (options.retries) overrides.maxRetries = options.retries;
+    if (options.reportDir) overrides.reportDir = options.reportDir;
+    if (options.report === false) overrides.report = false;
+    if (options.viewport) {
+      const [w, h] = options.viewport.split("x").map(Number);
+      if (w && h) {
+        overrides.viewportWidth = w;
+        overrides.viewportHeight = h;
+      }
+    }
+    const config = loadConfig(overrides);
+    const logger = createLogger();
+    logger.info(
+      `Provider: ${c.cyan(config.provider)} | Model: ${c.cyan(config.model)}`
+    );
+    logger.info(
+      `Viewport: ${config.viewportWidth}x${config.viewportHeight} | Headless: ${config.headless}`
+    );
+    logger.info(
+      `Max retries: ${config.maxRetries} | Action delay: ${config.actionDelay}ms`
+    );
+    const result = await runTestFile(file, config, logger);
+    process.exit(result.totalFailed > 0 ? 1 : 0);
+  });
+  program.command("init").description("Initialize a new Vouch project with example files").action(async () => {
+    await loadLoggerDeps();
+    await initProject(false);
+  });
+  return program;
+}
+
+// src/index.ts
+async function main() {
+  const program = createCLI();
+  await program.parseAsync(process.argv);
+}
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map