vibecheck-ai 2.0.2 → 5.0.0

package/bin/runners/reality/flows.js

@@ -0,0 +1,122 @@
+/**
+ * Flow Pack Loader
+ * Loads and normalizes YAML/JSON flow packs from .vibecheck/flows/
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+let yaml;
+function ensureYaml() {
+  if (yaml) return yaml;
+  try {
+    yaml = require("yaml");
+    return yaml;
+  } catch {
+    try {
+      yaml = require("js-yaml");
+      return yaml;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function listFlowFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(dir)) {
+    const p = path.join(dir, f);
+    if (fs.statSync(p).isFile()) {
+      if (f.endsWith(".yaml") || f.endsWith(".yml") || f.endsWith(".json")) {
+        out.push(p);
+      }
+    }
+  }
+  return out.sort();
+}
+
+function normalizeFlow(flow, sourcePath) {
+  if (!flow || typeof flow !== "object") return null;
+  if (!flow.id) flow.id = path.basename(sourcePath).replace(/\.(ya?ml|json)$/, "");
+  if (!flow.name) flow.name = flow.id;
+  if (!Array.isArray(flow.steps)) flow.steps = [];
+  if (!Array.isArray(flow.assertions)) flow.assertions = [];
+  if (!Array.isArray(flow.cleanup)) flow.cleanup = [];
+  if (!flow.vars || typeof flow.vars !== "object") flow.vars = {};
+  if (!flow.preconditions) flow.preconditions = {};
+  if (!flow.danger) flow.danger = {};
+  flow.__source = sourcePath;
+  return flow;
+}
+
+function parseFlowFile(filePath) {
+  const content = fs.readFileSync(filePath, "utf8");
+  
+  if (filePath.endsWith(".json")) {
+    return JSON.parse(content);
+  }
+  
+  const y = ensureYaml();
+  if (!y) {
+    throw new Error(
+      `YAML parser not found. Install with: npm i -D yaml\nOr use JSON flow files instead.`
+    );
+  }
+  
+  // js-yaml uses load(), yaml package uses parse()
+  if (typeof y.load === "function") {
+    return y.load(content);
+  }
+  return y.parse(content);
+}
+
+/**
+ * Load flow packs from directory
+ * @param {Object} options
+ * @param {string} options.flowsDir - Directory containing flow files
+ * @param {string[]} options.requested - Specific flow IDs/names to load (empty = all)
+ * @param {boolean} options.debug - Enable debug logging
+ * @returns {Object[]} Array of normalized flow objects
+ */
+function loadFlowPacks({ flowsDir, requested, debug }) {
+  const files = listFlowFiles(flowsDir);
+  
+  if (debug && files.length === 0) {
+    console.log(`[reality] No flow files found in ${flowsDir}`);
+  }
+
+  const flows = [];
+  for (const file of files) {
+    try {
+      const parsed = parseFlowFile(file);
+      const flow = normalizeFlow(parsed, file);
+      if (flow) {
+        flows.push(flow);
+        if (debug) {
+          console.log(`[reality] Loaded flow: ${flow.id} (${flow.steps.length} steps)`);
+        }
+      }
+    } catch (e) {
+      if (debug) {
+        console.warn(`[reality] Failed to parse flow ${file}: ${e.message}`);
+      }
+    }
+  }
+
+  // Filter by requested if provided
+  if (!requested || requested.length === 0) return flows;
+
+  const req = new Set(requested.map((s) => s.toLowerCase()));
+  return flows.filter((f) => {
+    const id = String(f.id || "").toLowerCase();
+    const name = String(f.name || "").toLowerCase();
+    const file = path.basename(f.__source || "").toLowerCase();
+    for (const r of req) {
+      if (id.includes(r) || name.includes(r) || file.includes(r)) return true;
+    }
+    return false;
+  });
+}
+
+module.exports = { loadFlowPacks, parseFlowFile, normalizeFlow };

package/bin/runners/reality/report.js

@@ -0,0 +1,378 @@
+/**
+ * Reality Mode Report Generators
+ * HTML Report, Timeline, JUnit XML, SARIF
+ */
+
+function esc(s) {
+  return String(s ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function badge(status) {
+  const s = String(status || "").toLowerCase();
+  if (s === "success" || s === "pass") return `<span class="b b-ok">${esc(status)}</span>`;
+  if (s === "skipped") return `<span class="b b-skip">skipped</span>`;
+  if (s === "blocked") return `<span class="b b-block">blocked</span>`;
+  if (s === "unknown") return `<span class="b b-warn">unknown</span>`;
+  if (s === "fail" || s === "error") return `<span class="b b-bad">${esc(status)}</span>`;
+  return `<span class="b b-warn">${esc(status)}</span>`;
+}
+
+function writeHtmlReport(results) {
+  const score = results.score ?? 0;
+  const grade = score >= 90 ? "A" : score >= 80 ? "B" : score >= 70 ? "C" : score >= 60 ? "D" : "F";
+  const verdict = score >= 80 ? "✅ Ready to ship" : score >= 60 ? "⚠️ Needs work" : "❌ Not shippable";
+  const scoreColor = score >= 80 ? "#22c55e" : score >= 60 ? "#eab308" : "#ef4444";
+
+  const flowsHtml = (results.flows || []).map(f => {
+    const steps = (f.steps || []).slice(0, 50).map(s => `
+      <div class="row">
+        <div class="k">${esc(s.action)} <span class="dim">${esc(s.name || "")}</span></div>
+        <div class="v">${badge(s.status)} ${s.danger?.dangerous ? `<span class="danger-tag">⚠️ destructive</span>` : ""} <span class="dim">${esc(s.error || "")}</span></div>
+      </div>
+    `).join("");
+
+    const asserts = (f.assertions || []).map(a => `
+      <div class="row">
+        <div class="k">${esc(a.type)} ${a.critical ? `<span class="critical-tag">critical</span>` : ""}</div>
+        <div class="v">${badge(a.status)} <span class="dim">${esc(a.message || "")}</span></div>
+      </div>
+    `).join("");
+
+    return `
+      <div class="card">
+        <div class="card-h">
+          <div>
+            <div class="t">${esc(f.name || f.id)}</div>
+            <div class="dim">${esc(f.source || "")}</div>
+          </div>
+          <div>${badge(f.status)} <span class="dim">${Math.round((f.durationMs || 0) / 1000)}s</span></div>
+        </div>
+        <div class="split">
+          <div>
+            <div class="h2">Steps (${(f.steps || []).length})</div>
+            ${steps || `<div class="dim">No steps</div>`}
+          </div>
+          <div>
+            <div class="h2">Assertions (${(f.assertions || []).length})</div>
+            ${asserts || `<div class="dim">No assertions</div>`}
+          </div>
+        </div>
+      </div>
+    `;
+  }).join("");
+
+  const routesHtml = (results.routes || []).slice(0, 50).map(r => `
+    <div class="row">
+      <div class="k mono">${esc(r.path)}</div>
+      <div class="v">${badge(r.status)} <span class="dim">${r.httpStatus || ""}</span></div>
+    </div>
+  `).join("");
+
+  const errHtml = (results.errors || []).slice(0, 30).map(e => `
+    <div class="err">[${esc(e.type)}] ${esc(e.message)} <span class="dim">${esc(e.url || "")}</span></div>
+  `).join("");
+
+  const cov = results.coverage || {};
+  
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Reality Mode Report - vibecheck</title>
+  <style>
+    *{box-sizing:border-box}
+    body{margin:0;font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#0b0b0f;color:#eaeaf0;line-height:1.5}
+    .wrap{max-width:1100px;margin:0 auto;padding:28px}
+    .top{display:flex;justify-content:space-between;align-items:flex-end;gap:16px;flex-wrap:wrap}
+    .title{font-size:22px;font-weight:800}
+    .dim{color:#9aa0aa;font-size:12px}
+    .mono{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace}
+    .score{display:flex;gap:14px;align-items:center;background:#11131a;border:1px solid #222634;border-radius:16px;padding:18px 20px}
+    .num{font-size:48px;font-weight:900;line-height:1;color:${scoreColor}}
+    .meta{display:flex;flex-direction:column;gap:2px}
+    .grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:10px;margin-top:14px}
+    .stat{background:#11131a;border:1px solid #222634;border-radius:14px;padding:12px}
+    .stat .v{font-weight:800;font-size:18px}
+    .card{background:#0f1118;border:1px solid #222634;border-radius:16px;margin-top:14px;overflow:hidden}
+    .card-h{display:flex;justify-content:space-between;align-items:center;padding:14px 16px;background:#11131a;border-bottom:1px solid #222634}
+    .t{font-weight:800}
+    .split{display:grid;grid-template-columns:1fr 1fr;gap:10px;padding:14px 16px}
+    @media(max-width:700px){.split{grid-template-columns:1fr}}
+    .h2{font-size:12px;font-weight:800;color:#c8ccd6;margin-bottom:8px;text-transform:uppercase;letter-spacing:0.5px}
+    .row{display:flex;justify-content:space-between;gap:10px;border-bottom:1px solid #171a24;padding:8px 0;align-items:center}
+    .row:last-child{border-bottom:none}
+    .k{font-size:12px;overflow:hidden;text-overflow:ellipsis}
+    .v{font-size:12px;text-align:right;white-space:nowrap}
+    .b{font-size:11px;font-weight:800;padding:3px 8px;border-radius:999px;border:1px solid transparent;text-transform:uppercase}
+    .b-ok{background:rgba(34,197,94,.12);border-color:rgba(34,197,94,.25);color:#22c55e}
+    .b-bad{background:rgba(239,68,68,.12);border-color:rgba(239,68,68,.25);color:#ef4444}
+    .b-warn{background:rgba(234,179,8,.12);border-color:rgba(234,179,8,.25);color:#eab308}
+    .b-skip{background:rgba(59,130,246,.10);border-color:rgba(59,130,246,.25);color:#60a5fa}
+    .b-block{background:rgba(244,63,94,.10);border-color:rgba(244,63,94,.25);color:#fb7185}
+    .danger-tag{font-size:10px;color:#fb7185;margin-left:4px}
+    .critical-tag{font-size:10px;color:#f59e0b;background:rgba(245,158,11,.15);padding:2px 6px;border-radius:4px;margin-left:4px}
+    .err{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:12px;color:#fca5a5;padding:8px 0;border-bottom:1px solid #171a24}
+    .err:last-child{border-bottom:none}
+    a{color:#60a5fa;text-decoration:none}
+    a:hover{text-decoration:underline}
+    .footer{margin-top:20px;padding-top:16px;border-top:1px solid #222634;text-align:center}
+  </style>
+</head>
+<body>
+<div class="wrap">
+  <div class="top">
+    <div>
+      <div class="title">🔍 Reality Mode Report</div>
+      <div class="dim">${esc(results.meta?.baseUrl)} • ${esc(results.meta?.startedAt)} • ${Math.round((results.duration || 0)/1000)}s</div>
+    </div>
+    <div class="score">
+      <div class="num">${score}</div>
+      <div class="meta">
+        <div><b>Grade:</b> ${grade}</div>
+        <div class="dim">${esc(verdict)}</div>
+      </div>
+    </div>
+  </div>
+
+  <div class="grid">
+    <div class="stat"><div class="dim">Routes Working</div><div class="v">${cov.routesWorking || 0}/${cov.routesDiscovered || 0}</div></div>
+    <div class="stat"><div class="dim">Elements Working</div><div class="v">${cov.elementsWorking || 0}/${cov.elementsDiscovered || 0}</div></div>
+    <div class="stat"><div class="dim">Forms Discovered</div><div class="v">${cov.formsDiscovered || 0}</div></div>
+    <div class="stat"><div class="dim">Flows Executed</div><div class="v">${(results.flows || []).length}</div></div>
+    <div class="stat"><div class="dim">Errors Captured</div><div class="v">${(results.errors || []).length}</div></div>
+  </div>
+
+  ${flowsHtml || `<div class="card"><div class="card-h"><div class="t">Flows</div></div><div style="padding:14px 16px" class="dim">No flows ran. Add flow packs to .vibecheck/flows/ or use --flows-dir</div></div>`}
+
+  ${(results.routes || []).length ? `
+    <div class="card">
+      <div class="card-h"><div class="t">Routes Discovered</div><span class="dim">${(results.routes || []).length}</span></div>
+      <div style="padding:0 16px;max-height:300px;overflow-y:auto">${routesHtml}</div>
+    </div>` : ""}
+
+  ${(results.errors || []).length ? `
+    <div class="card">
+      <div class="card-h"><div class="t">Errors</div>${badge("error")}</div>
+      <div style="padding:0 16px;max-height:250px;overflow-y:auto">${errHtml}</div>
+    </div>` : ""}
+
+  <div class="footer dim">
+    Generated by vibecheck Reality Mode • <a href="https://vibecheckai.dev">vibecheckai.dev</a>
+  </div>
+</div>
+</body>
+</html>`;
+}
+
+function writeTimelineHtml(results) {
+  const items = (results.timeline || []).map((t, idx) => `
+    <div class="it ${esc(t.status)}">
+      <div class="h">
+        <div class="num">${idx + 1}</div>
+        <div class="info">
+          <div><b>${esc(t.flowId)}</b> • step ${esc(t.step)} • <span class="action">${esc(t.action)}</span> <span class="dim">${esc(t.name)}</span></div>
+          <div class="dim">${esc(t.url)}</div>
+        </div>
+        <div>${badge(t.status)}</div>
+      </div>
+      <div class="shots">
+        ${t.before ? `<a href="${esc(t.before)}" target="_blank">📷 before</a>` : ""}
+        ${t.after ? `<a href="${esc(t.after)}" target="_blank">📷 after</a>` : ""}
+      </div>
+    </div>
+  `).join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+  <title>Reality Timeline - vibecheck</title>
+  <style>
+    *{box-sizing:border-box}
+    body{margin:0;font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#0b0b0f;color:#eaeaf0;line-height:1.5}
+    .wrap{max-width:1100px;margin:0 auto;padding:24px}
+    h2{margin:0 0 8px 0;font-size:20px}
+    .dim{color:#9aa0aa;font-size:12px}
+    .it{background:#0f1118;border:1px solid #222634;border-radius:14px;padding:12px 14px;margin-top:10px}
+    .h{display:flex;gap:12px;align-items:center}
+    .num{width:28px;height:28px;background:#1e2130;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:12px;font-weight:800;flex-shrink:0}
+    .info{flex:1;min-width:0}
+    .action{color:#60a5fa}
+    .shots{margin-top:8px;font-size:12px;padding-left:40px}
+    a{color:#60a5fa;margin-right:12px;text-decoration:none}
+    a:hover{text-decoration:underline}
+    .b{font-size:10px;font-weight:800;padding:2px 6px;border-radius:999px;text-transform:uppercase}
+    .b-ok{background:rgba(34,197,94,.12);color:#22c55e}
+    .b-bad{background:rgba(239,68,68,.12);color:#ef4444}
+    .b-warn{background:rgba(234,179,8,.12);color:#eab308}
+    .b-skip{background:rgba(59,130,246,.10);color:#60a5fa}
+    .b-block{background:rgba(244,63,94,.10);color:#fb7185}
+  </style>
+</head>
+<body>
+<div class="wrap">
+  <h2>🧭 Reality Timeline</h2>
+  <div class="dim" style="margin-bottom:16px">${esc(results.meta?.baseUrl)} • ${esc(results.meta?.startedAt)} • ${(results.timeline || []).length} steps</div>
+  ${items || `<div class="dim">No timeline items recorded.</div>`}
+</div>
+</body>
+</html>`;
+}
+
+function writeJUnitXml(results) {
+  const ts = new Date().toISOString();
+  const flows = results.flows || [];
+  let tests = 0;
+  let failures = 0;
+
+  let cases = "";
+
+  for (const f of flows) {
+    for (const s of (f.steps || [])) {
+      tests++;
+      const name = `Step: ${f.id} / ${s.action} ${s.name || ""}`.trim();
+      if (s.status === "error" || s.status === "blocked") {
+        failures++;
+        cases += `    <testcase name="${esc(name)}" classname="reality.steps" time="${((s.durationMs || 0) / 1000).toFixed(2)}">
+      <failure message="${esc(s.error || s.status)}">${esc(s.error || s.status)}</failure>
+    </testcase>\n`;
+      } else {
+        cases += `    <testcase name="${esc(name)}" classname="reality.steps" time="${((s.durationMs || 0) / 1000).toFixed(2)}"/>\n`;
+      }
+    }
+
+    for (const a of (f.assertions || [])) {
+      if (a.status === "skip") continue;
+      tests++;
+      const name = `Assert: ${f.id} / ${a.type}`;
+      if (a.status === "fail") {
+        failures++;
+        cases += `    <testcase name="${esc(name)}" classname="reality.assertions">
+      <failure message="${esc(a.message)}">${esc(a.message)}</failure>
+    </testcase>\n`;
+      } else {
+        cases += `    <testcase name="${esc(name)}" classname="reality.assertions"/>\n`;
+      }
+    }
+  }
+
+  // Routes as test cases
+  for (const r of (results.routes || [])) {
+    tests++;
+    const name = `Route: ${r.path}`;
+    if (r.status !== "success") {
+      failures++;
+      cases += `    <testcase name="${esc(name)}" classname="reality.routes">
+      <failure message="HTTP ${r.httpStatus || 0}">${esc(r.error || `HTTP ${r.httpStatus}`)}</failure>
+    </testcase>\n`;
+    } else {
+      cases += `    <testcase name="${esc(name)}" classname="reality.routes"/>\n`;
+    }
+  }
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="vibecheck Reality Mode" tests="${tests}" failures="${failures}" timestamp="${ts}" time="${((results.duration || 0) / 1000).toFixed(2)}">
+  <testsuite name="Reality Explorer" tests="${tests}" failures="${failures}" time="${((results.duration || 0) / 1000).toFixed(2)}">
+    <properties>
+      <property name="score" value="${results.score || 0}"/>
+      <property name="baseUrl" value="${esc(results.meta?.baseUrl || "")}"/>
+    </properties>
+${cases}  </testsuite>
+</testsuites>`;
+}
+
+function writeSarif(results, baseUrl) {
+  const sarifResults = [];
+  const rules = new Map();
+
+  function addRule(id, name, level) {
+    if (rules.has(id)) return;
+    rules.set(id, {
+      id,
+      shortDescription: { text: name },
+      fullDescription: { text: name },
+      defaultConfiguration: { level },
+      helpUri: "https://vibecheckai.dev/docs/reality-mode",
+    });
+  }
+
+  // Step failures
+  for (const f of (results.flows || [])) {
+    for (const s of (f.steps || [])) {
+      if (s.status === "error" || s.status === "blocked") {
+        addRule("reality/step-failed", "Flow step failed", "warning");
+        sarifResults.push({
+          ruleId: "reality/step-failed",
+          level: "warning",
+          message: { text: `${f.id}: ${s.action} failed - ${s.error || s.status}` },
+          locations: [{ physicalLocation: { artifactLocation: { uri: baseUrl } } }],
+        });
+      }
+    }
+    
+    for (const a of (f.assertions || [])) {
+      if (a.status === "fail") {
+        const level = a.critical ? "error" : "warning";
+        addRule("reality/assertion-failed", "Assertion failed", level);
+        sarifResults.push({
+          ruleId: "reality/assertion-failed",
+          level,
+          message: { text: `${f.id}: ${a.type} - ${a.message}` },
+          locations: [{ physicalLocation: { artifactLocation: { uri: baseUrl } } }],
+        });
+      }
+    }
+  }
+
+  // Route errors
+  for (const r of (results.routes || [])) {
+    if (r.status !== "success") {
+      addRule("reality/route-error", "Route error", "warning");
+      sarifResults.push({
+        ruleId: "reality/route-error",
+        level: "warning",
+        message: { text: `Route ${r.path} failed: HTTP ${r.httpStatus || 0}` },
+        locations: [{ physicalLocation: { artifactLocation: { uri: baseUrl + (r.path || "") } } }],
+      });
+    }
+  }
+
+  // Console/page errors
+  for (const e of (results.errors || [])) {
+    addRule("reality/runtime-error", "Runtime error detected", "error");
+    sarifResults.push({
+      ruleId: "reality/runtime-error",
+      level: "error",
+      message: { text: `[${e.type}] ${e.message}` },
+      locations: [{ physicalLocation: { artifactLocation: { uri: e.url || baseUrl } } }],
+    });
+  }
+
+  return {
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [{
+      tool: {
+        driver: {
+          name: "vibecheck Reality Mode",
+          version: "2.0.0",
+          informationUri: "https://vibecheckai.dev",
+          rules: Array.from(rules.values()),
+        },
+      },
+      results: sarifResults,
+      invocations: [{
+        executionSuccessful: sarifResults.filter(r => r.level === "error").length === 0,
+        endTimeUtc: new Date().toISOString(),
+      }],
+    }],
+  };
+}
+
+module.exports = { writeHtmlReport, writeTimelineHtml, writeJUnitXml, writeSarif };

package/bin/runners/reality/session.js

@@ -0,0 +1,193 @@
+/**
+ * Reality Mode Session Runner
+ * Manages Playwright browser session, telemetry, and orchestrates flow execution.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const { loadFlowPacks } = require("./flows");
+const { runFlowPlan } = require("./engine");
+const { writeHtmlReport, writeTimelineHtml, writeJUnitXml, writeSarif } = require("./report");
+
+function safeBaseUrl(url) {
+  return String(url || "").replace(/\/+$/, "");
+}
+
+async function runRealitySession(opts) {
+  const baseUrl = safeBaseUrl(opts.url);
+  const outputDir = path.resolve(opts.output);
+
+  const artifacts = {
+    outputDir,
+    screenshotsDir: path.join(outputDir, "screenshots"),
+    videosDir: path.join(outputDir, "videos"),
+  };
+
+  fs.mkdirSync(artifacts.outputDir, { recursive: true });
+  fs.mkdirSync(artifacts.screenshotsDir, { recursive: true });
+  fs.mkdirSync(artifacts.videosDir, { recursive: true });
+
+  // Lazy require Playwright
+  let chromium;
+  try {
+    ({ chromium } = require("playwright"));
+  } catch {
+    try {
+      const pw = require("@playwright/test");
+      chromium = pw.chromium;
+    } catch {
+      throw new Error("Playwright not available. Run: npm i -D playwright && npx playwright install chromium");
+    }
+  }
+
+  const startedAt = Date.now();
+
+  const browser = await chromium.launch({ headless: !!opts.headless });
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 720 },
+    recordVideo: { dir: artifacts.videosDir },
+  });
+
+  await context.tracing.start({ screenshots: true, snapshots: true });
+
+  const page = await context.newPage();
+
+  // Telemetry buffers for assertions
+  const telemetry = {
+    console: [],
+    pageErrors: [],
+    requests: [],
+    responses: [],
+  };
+
+  page.on("console", (msg) => {
+    telemetry.console.push({
+      type: msg.type(),
+      text: msg.text(),
+      url: page.url(),
+      ts: Date.now(),
+    });
+  });
+
+  page.on("pageerror", (err) => {
+    telemetry.pageErrors.push({
+      message: err?.message || String(err),
+      url: page.url(),
+      ts: Date.now(),
+    });
+  });
+
+  page.on("request", (req) => {
+    telemetry.requests.push({
+      url: req.url(),
+      method: req.method(),
+      resourceType: req.resourceType(),
+      ts: Date.now(),
+    });
+  });
+
+  page.on("response", async (res) => {
+    telemetry.responses.push({
+      url: res.url(),
+      status: res.status(),
+      method: res.request().method(),
+      ts: Date.now(),
+    });
+  });
+
+  // Load flow packs
+  const flowsDir = opts.flowsDir
+    ? path.resolve(opts.flowsDir)
+    : path.join(process.cwd(), ".vibecheck", "flows");
+
+  const flowPacks = loadFlowPacks({
+    flowsDir,
+    requested: opts.flows,
+    debug: !!opts.debug,
+  });
+
+  // Build execution plan
+  const plan = {
+    baseUrl,
+    auth: opts.auth,
+    danger: !!opts.danger,
+    timeout: opts.timeout,
+    maxPages: opts.maxPages,
+    flows: flowPacks,
+    outputDir,
+    artifacts,
+    debug: !!opts.debug,
+  };
+
+  const results = await runFlowPlan({
+    plan,
+    page,
+    context,
+    telemetry,
+  });
+
+  results.duration = Date.now() - startedAt;
+
+  // Stop trace
+  const tracePath = path.join(outputDir, "trace.zip");
+  await context.tracing.stop({ path: tracePath }).catch(() => {});
+
+  await context.close().catch(() => {});
+  await browser.close().catch(() => {});
+
+  // Write outputs
+  const jsonPath = path.join(outputDir, "explorer-results.json");
+  fs.writeFileSync(jsonPath, JSON.stringify(results, null, 2));
+
+  const reportPath = path.join(outputDir, "reality-report.html");
+  fs.writeFileSync(reportPath, writeHtmlReport(results));
+
+  const timelinePath = path.join(outputDir, "timeline.html");
+  fs.writeFileSync(timelinePath, writeTimelineHtml(results));
+
+  if (opts.junit) {
+    const junitPath = path.join(outputDir, "junit-results.xml");
+    fs.writeFileSync(junitPath, writeJUnitXml(results));
+  }
+
+  if (opts.sarif) {
+    const sarifPath = path.join(outputDir, "reality-results.sarif");
+    fs.writeFileSync(sarifPath, JSON.stringify(writeSarif(results, baseUrl), null, 2));
+  }
+
+  // Console summary
+  const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+  };
+
+  const score = results.score ?? 0;
+  const scoreColor = score >= 80 ? c.green : score >= 60 ? c.yellow : c.red;
+
+  console.log(`\n${c.bold}${c.cyan}══════════════════════════════════════════════════════════${c.reset}`);
+  console.log(`  ${c.bold}REALITY MODE COMPLETE${c.reset}`);
+  console.log(`${c.bold}${c.cyan}══════════════════════════════════════════════════════════${c.reset}`);
+  console.log(`  ${c.bold}Score:${c.reset} ${scoreColor}${score}/100${c.reset}`);
+  console.log(`  📊 Routes:   ${results.coverage?.routesWorking || 0}/${results.coverage?.routesDiscovered || 0} working`);
+  console.log(`  🔘 Elements: ${results.coverage?.elementsWorking || 0}/${results.coverage?.elementsDiscovered || 0} working`);
+  console.log(`  📝 Forms:    ${results.coverage?.formsDiscovered || 0} discovered`);
+  console.log(`  🧭 Flows:    ${results.flows?.length || 0} executed`);
+  console.log(`  ❌ Errors:   ${(results.errors?.length || 0)} captured`);
+  console.log(`  ${c.bold}📄 Report:${c.reset}   ${reportPath}`);
+  console.log(`  ${c.bold}🧭 Timeline:${c.reset} ${timelinePath}`);
+  console.log(`  ${c.bold}🔍 Trace:${c.reset}    ${tracePath}`);
+  console.log(`${c.bold}${c.cyan}══════════════════════════════════════════════════════════${c.reset}\n`);
+
+  return {
+    score,
+    exitCode: 0,
+  };
+}
+
+module.exports = { runRealitySession };