vibecheck-ai 2.0.2 → 5.0.0

package/bin/runners/reality/engine.js

@@ -0,0 +1,917 @@
+/**
+ * Reality Mode Execution Engine
+ * Step execution, danger classification, assertions, surface discovery
+ */
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+function uuid() {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return crypto.randomBytes(16).toString("hex");
+  }
+}
+
+function randomEmail() {
+  return `reality+${Date.now()}_${Math.floor(Math.random() * 1e6)}@example.com`;
+}
+
+function template(str, vars) {
+  if (typeof str !== "string") return str;
+  return str.replace(/\{\{([^}]+)\}\}/g, (_, key) => {
+    const k = String(key || "").trim();
+    if (k === "$timestamp") return String(Date.now());
+    if (k === "$uuid") return uuid();
+    if (k === "$randomEmail") return randomEmail();
+    if (k === "$isoDate") return new Date().toISOString();
+    if (k.startsWith("env.")) return process.env[k.slice(4)] || "";
+    if (k.startsWith("stored.")) return vars?.[k] ?? "";
+    return vars?.[k] != null ? String(vars[k]) : "";
+  });
+}
+
+// ============================================================================
+// Danger Classification System
+// ============================================================================
+
+const DANGER_TEXT_PATTERNS = [
+  /\bdelete\b/i,
+  /\bremove\b/i,
+  /\bdestroy\b/i,
+  /\bdeactivate\b/i,
+  /\bterminate\b/i,
+  /\bclose\s*account\b/i,
+  /\bcancel\s*subscription\b/i,
+  /\breset\s*all\b/i,
+  /\bwipe\b/i,
+  /\berase\b/i,
+  /\birreversible\b/i,
+  /\bpermanently\b/i,
+  /\bcannot\s*be\s*undone\b/i,
+  /\brevoke\b/i,
+  /\bdisconnect\b/i,
+  /\bunlink\b/i,
+];
+
+const DANGER_CLASS_PATTERNS = [
+  /\bbtn-danger\b/,
+  /\bdestructive\b/,
+  /\bdelete-/,
+  /\bdanger-/,
+  /\bremove-/,
+];
+
+function classifyDanger({ text, className, ariaLabel, role, url, method }) {
+  const signals = [];
+  let score = 0;
+
+  const t = `${text || ""}`.toLowerCase();
+  const cls = `${className || ""}`.toLowerCase();
+  const aria = `${ariaLabel || ""}`.toLowerCase();
+  const r = `${role || ""}`.toLowerCase();
+  const u = `${url || ""}`.toLowerCase();
+  const m = `${method || ""}`.toUpperCase();
+
+  // Text patterns
+  for (const pattern of DANGER_TEXT_PATTERNS) {
+    if (pattern.test(t) || pattern.test(aria)) {
+      signals.push({ type: "text", value: pattern.source, weight: 0.3 });
+      score += 0.3;
+    }
+  }
+
+  // Class patterns
+  for (const pattern of DANGER_CLASS_PATTERNS) {
+    if (pattern.test(cls)) {
+      signals.push({ type: "class", value: pattern.source, weight: 0.25 });
+      score += 0.25;
+    }
+  }
+
+  // ARIA patterns
+  if (r === "alertdialog") {
+    signals.push({ type: "aria", value: "role=alertdialog", weight: 0.2 });
+    score += 0.2;
+  }
+
+  // Network patterns (DELETE method or destructive endpoints)
+  if (m === "DELETE") {
+    signals.push({ type: "network", value: "DELETE method", weight: 0.4 });
+    score += 0.4;
+  }
+  if (/\/delete\b|\/destroy\b|\/deactivate\b|\/remove\b/.test(u)) {
+    signals.push({ type: "network", value: "destructive endpoint", weight: 0.35 });
+    score += 0.35;
+  }
+
+  const dangerous = score >= 0.25;
+  const reason = signals.length > 0 ? signals[0].type : "none";
+
+  return {
+    dangerous,
+    score: Math.min(1, score),
+    signals,
+    reason,
+  };
+}
+
+// ============================================================================
+// Screenshots & DOM Snapshots
+// ============================================================================
+
+async function screenshot(page, outPath) {
+  try {
+    await page.screenshot({ path: outPath, fullPage: true });
+  } catch {
+    // Non-fatal
+  }
+}
+
+async function domSnapshot(page) {
+  try {
+    return await page.evaluate(() => {
+      const el = document.activeElement;
+      return {
+        url: location.href,
+        title: document.title,
+        active: el ? { tag: el.tagName, id: el.id, name: el.getAttribute("name") } : null,
+        bodyTextSample: document.body?.innerText?.slice(0, 500) || "",
+      };
+    });
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Navigation Helpers
+// ============================================================================
+
+async function safeGoto(page, url, timeout) {
+  const started = Date.now();
+  try {
+    const res = await page.goto(url, { waitUntil: "domcontentloaded", timeout });
+    await page.waitForLoadState("networkidle", { timeout: Math.min(timeout, 5000) }).catch(() => {});
+    const status = res ? res.status() : 0;
+    return { ok: status >= 200 && status < 400, status, ms: Date.now() - started };
+  } catch (e) {
+    return { ok: false, status: 0, ms: Date.now() - started, error: String(e?.message || e).slice(0, 180) };
+  }
+}
+
+async function findLocator(page, target) {
+  return page.locator(target).first();
+}
+
+// ============================================================================
+// Surface Discovery
+// ============================================================================
+
+async function discoverSurface({ page, baseUrl, timeout, maxPages }) {
+  const discovered = {
+    routes: [],
+    elements: [],
+    forms: [],
+  };
+
+  // Visit base
+  const home = await safeGoto(page, baseUrl, timeout);
+  if (home.status) {
+    discovered.routes.push({ path: "/", status: home.ok ? "success" : "error", httpStatus: home.status });
+  }
+
+  // Extract routes
+  const routes = await page.evaluate(() => {
+    const out = new Set();
+    document.querySelectorAll("a[href]").forEach(a => {
+      const href = a.getAttribute("href") || "";
+      if (!href || href.startsWith("http") || href.startsWith("//") || href.includes("#")) return;
+      if (href.startsWith("/")) out.add(href);
+    });
+    // Common SPA routes
+    ["/dashboard", "/app", "/account", "/settings", "/profile", "/projects", "/analytics", "/billing"].forEach(r => out.add(r));
+    return Array.from(out);
+  }).catch(() => []);
+
+  const queue = routes.slice(0, maxPages * 2);
+  const seen = new Set(["/", baseUrl]);
+
+  for (const route of queue.slice(0, maxPages)) {
+    if (seen.has(route)) continue;
+    seen.add(route);
+
+    const res = await safeGoto(page, baseUrl + route, timeout);
+    discovered.routes.push({
+      path: route,
+      status: res.ok ? "success" : "error",
+      httpStatus: res.status || 0,
+      error: res.error,
+    });
+
+    // Discover elements on this page
+    const pageEls = await page.evaluate(() => {
+      const pickText = (el) => (el.textContent || el.getAttribute("aria-label") || "").trim().slice(0, 80);
+      const els = Array.from(document.querySelectorAll('button, [role="button"], input[type="submit"], a[href], [data-testid]'));
+      return els.slice(0, 100).map((el, idx) => ({
+        tag: el.tagName.toLowerCase(),
+        text: pickText(el),
+        id: el.id || "",
+        testid: el.getAttribute("data-testid") || "",
+        className: el.className || "",
+        ariaLabel: el.getAttribute("aria-label") || "",
+        href: el.getAttribute("href") || "",
+        index: idx,
+      }));
+    }).catch(() => []);
+
+    for (const e of pageEls) {
+      if (!e.text && !e.testid && !e.id) continue;
+      discovered.elements.push({ ...e, page: route });
+    }
+
+    // Discover forms
+    const forms = await page.evaluate(() => {
+      const forms = Array.from(document.querySelectorAll("form"));
+      return forms.slice(0, 20).map((form, idx) => {
+        const fields = Array.from(form.querySelectorAll("input, textarea, select")).slice(0, 30).map((f) => ({
+          name: f.getAttribute("name") || f.id || "",
+          type: f.getAttribute("type") || f.tagName.toLowerCase(),
+          required: !!f.required,
+        }));
+        return {
+          selector: form.id ? `#${form.id}` : form.getAttribute("data-testid") ? `[data-testid="${form.getAttribute("data-testid")}"]` : `form:nth-of-type(${idx + 1})`,
+          fields,
+        };
+      });
+    }).catch(() => []);
+
+    for (const f of forms) discovered.forms.push({ ...f, page: route });
+  }
+
+  // Dedupe
+  discovered.routes = dedupe(discovered.routes, r => r.path);
+  discovered.elements = dedupe(discovered.elements, e => `${e.page}|${e.tag}|${e.testid}|${e.id}|${e.text}`);
+  discovered.forms = dedupe(discovered.forms, f => `${f.page}|${f.selector}`);
+
+  return discovered;
+}
+
+function dedupe(arr, keyFn) {
+  const seen = new Set();
+  const out = [];
+  for (const x of arr) {
+    const k = keyFn(x);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(x);
+  }
+  return out;
+}
+
+// ============================================================================
+// Flow Plan Execution
+// ============================================================================
+
+async function runFlowPlan({ plan, page, context, telemetry }) {
+  const results = {
+    meta: {
+      baseUrl: plan.baseUrl,
+      startedAt: new Date().toISOString(),
+      danger: plan.danger,
+      maxPages: plan.maxPages,
+      timeout: plan.timeout,
+    },
+    discovery: null,
+    coverage: {
+      routesDiscovered: 0,
+      routesWorking: 0,
+      elementsDiscovered: 0,
+      elementsWorking: 0,
+      formsDiscovered: 0,
+      formsWorking: 0,
+    },
+    flows: [],
+    routes: [],
+    elements: [],
+    forms: [],
+    errors: [],
+    network: [],
+    console: [],
+    timeline: [],
+    score: 0,
+    duration: 0,
+  };
+
+  // Discovery pass
+  const discovery = await discoverSurface({
+    page,
+    baseUrl: plan.baseUrl,
+    timeout: plan.timeout,
+    maxPages: plan.maxPages,
+  });
+
+  results.discovery = {
+    routes: discovery.routes.length,
+    elements: discovery.elements.length,
+    forms: discovery.forms.length,
+  };
+
+  results.routes = discovery.routes;
+  results.elements = discovery.elements;
+  results.forms = discovery.forms;
+
+  results.coverage.routesDiscovered = discovery.routes.length;
+  results.coverage.routesWorking = discovery.routes.filter(r => r.status === "success").length;
+  results.coverage.elementsDiscovered = discovery.elements.length;
+  results.coverage.formsDiscovered = discovery.forms.length;
+
+  // Collect telemetry
+  results.console = telemetry.console.slice(-500);
+  results.errors = [
+    ...telemetry.pageErrors.map(e => ({ type: "uncaught", message: e.message, url: e.url, ts: e.ts })),
+    ...telemetry.console.filter(m => m.type === "error").map(m => ({ type: "console", message: m.text, url: m.url, ts: m.ts })),
+  ];
+  results.network = telemetry.responses.slice(-500);
+
+  // Run Flow Packs
+  const flowVarsBase = makeBaseVars(plan);
+  const flowsToRun = Array.isArray(plan.flows) ? plan.flows : [];
+
+  for (const flow of flowsToRun) {
+    const flowResult = await runSingleFlow({
+      flow,
+      plan,
+      page,
+      context,
+      telemetry,
+      varsBase: flowVarsBase,
+      results,
+    });
+    results.flows.push(flowResult);
+  }
+
+  // Count working elements from successful flow steps
+  let elementWorking = 0;
+  for (const f of results.flows) {
+    for (const s of (f.steps || [])) {
+      if ((s.action === "click" || s.action === "fill") && s.status === "success") elementWorking++;
+    }
+  }
+  results.coverage.elementsWorking = Math.min(elementWorking, results.coverage.elementsDiscovered);
+
+  // Calculate score
+  results.score = calculateScore(results);
+
+  return results;
+}
+
+function makeBaseVars(plan) {
+  const vars = {
+    baseUrl: plan.baseUrl,
+    timestamp: String(Date.now()),
+    $timestamp: String(Date.now()),
+    $uuid: uuid(),
+    $randomEmail: randomEmail(),
+    $isoDate: new Date().toISOString(),
+  };
+
+  if (plan.auth && typeof plan.auth === "string" && plan.auth.includes(":")) {
+    const [email, ...rest] = plan.auth.split(":");
+    vars.email = email;
+    vars.password = rest.join(":");
+  }
+
+  return vars;
+}
+
+// ============================================================================
+// Single Flow Execution
+// ============================================================================
+
+async function runSingleFlow({ flow, plan, page, telemetry, varsBase, results }) {
+  const flowStart = Date.now();
+  const flowVars = { ...varsBase, ...(flow.vars || {}) };
+
+  // Template all vars
+  for (const k of Object.keys(flowVars)) {
+    flowVars[k] = template(flowVars[k], flowVars);
+  }
+
+  const flowOut = {
+    id: flow.id,
+    name: flow.name,
+    source: flow.__source,
+    required: !!flow.required,
+    status: "success",
+    startedAt: new Date(flowStart).toISOString(),
+    durationMs: 0,
+    steps: [],
+    assertions: [],
+    errors: [],
+  };
+
+  // Run steps
+  let stepIndex = 0;
+  for (const step of flow.steps || []) {
+    stepIndex++;
+    const stepId = `${flow.id}#${stepIndex}`;
+    const stepName = step.name || `${step.action || "step"}-${stepIndex}`;
+    const stepStart = Date.now();
+
+    const stepRec = {
+      id: stepId,
+      name: stepName,
+      action: step.action,
+      target: step.target || null,
+      status: "success",
+      error: null,
+      danger: null,
+      artifacts: {},
+      startedAt: new Date(stepStart).toISOString(),
+      durationMs: 0,
+    };
+
+    // Trace marker
+    try {
+      await page.evaluate((label) => console.log(`[reality:trace] ${label}`), `STEP ${stepId}`);
+    } catch {}
+
+    // Before screenshot
+    const beforeShot = path.join(plan.artifacts.screenshotsDir, `${flow.id}__${stepIndex}__before.png`);
+    await screenshot(page, beforeShot);
+    stepRec.artifacts.beforeScreenshot = path.relative(plan.outputDir, beforeShot);
+    stepRec.artifacts.beforeDom = await domSnapshot(page);
+
+    // Execute action
+    try {
+      await executeStep({ step, stepRec, plan, page, flowVars, telemetry });
+    } catch (e) {
+      stepRec.status = "error";
+      stepRec.error = String(e?.message || e).slice(0, 220);
+      flowOut.errors.push({ step: stepIndex, message: stepRec.error });
+    }
+
+    // After screenshot
+    const afterShot = path.join(plan.artifacts.screenshotsDir, `${flow.id}__${stepIndex}__after.png`);
+    await screenshot(page, afterShot);
+    stepRec.artifacts.afterScreenshot = path.relative(plan.outputDir, afterShot);
+    stepRec.artifacts.afterDom = await domSnapshot(page);
+
+    stepRec.durationMs = Date.now() - stepStart;
+
+    // Add to timeline
+    results.timeline.push({
+      flowId: flow.id,
+      step: stepIndex,
+      name: stepRec.name,
+      action: stepRec.action,
+      status: stepRec.status,
+      at: Date.now(),
+      url: page.url(),
+      before: stepRec.artifacts.beforeScreenshot,
+      after: stepRec.artifacts.afterScreenshot,
+    });
+
+    flowOut.steps.push(stepRec);
+  }
+
+  // Run assertions
+  for (const a of flow.assertions || []) {
+    const ar = await runAssertion({ assertion: a, plan, page, telemetry, vars: flowVars });
+    flowOut.assertions.push(ar);
+    if (ar.status === "fail" && a.critical) {
+      flowOut.status = "error";
+    }
+  }
+
+  // Cleanup (best-effort)
+  for (const step of flow.cleanup || []) {
+    try {
+      await executeStep({ step, stepRec: {}, plan, page, flowVars, telemetry });
+    } catch {}
+  }
+
+  flowOut.durationMs = Date.now() - flowStart;
+  if (flowOut.errors.length > 0) flowOut.status = "error";
+
+  return flowOut;
+}
+
+// ============================================================================
+// Step Execution
+// ============================================================================
+
+async function executeStep({ step, stepRec, plan, page, flowVars, telemetry }) {
+  const action = String(step.action || "").toLowerCase();
+
+  if (action === "navigate") {
+    const target = template(step.target || "/", flowVars);
+    const url = target.startsWith("http") ? target : (plan.baseUrl + (target.startsWith("/") ? target : `/${target}`));
+    const res = await safeGoto(page, url, plan.timeout);
+    if (!res.ok) throw new Error(res.error || `Navigation failed: ${url}`);
+  }
+
+  else if (action === "wait") {
+    if (step.for === "selector" && step.target) {
+      const target = template(step.target, flowVars);
+      const state = step.state || "visible";
+      const loc = await findLocator(page, target);
+      await loc.waitFor({ state, timeout: Number(step.timeout || plan.timeout) });
+    } else if (step.for === "navigation" && step.match) {
+      const match = new RegExp(template(step.match, flowVars));
+      const timeout = Number(step.timeout || plan.timeout);
+      const end = Date.now() + timeout;
+      while (Date.now() < end) {
+        if (match.test(page.url())) break;
+        await page.waitForTimeout(200);
+      }
+      if (!match.test(page.url())) throw new Error(`URL did not match ${step.match}`);
+    } else if (step.for === "network" && step.match) {
+      const match = template(step.match, flowVars);
+      const timeout = Number(step.timeout || plan.timeout);
+      const since = Date.now();
+      const end = since + timeout;
+      let found = false;
+      while (Date.now() < end) {
+        const recent = telemetry.responses.filter(r => r.ts >= since);
+        if (recent.some(r => r.url.includes(match))) { found = true; break; }
+        await page.waitForTimeout(200);
+      }
+      if (!found) throw new Error(`No network call matching ${match}`);
+    } else {
+      const ms = Number(step.timeout || step.ms || 1000);
+      await page.waitForTimeout(ms);
+    }
+  }
+
+  else if (action === "fill") {
+    const target = template(step.target, flowVars);
+    const value = template(step.value, flowVars);
+    const loc = await findLocator(page, target);
+    await loc.waitFor({ state: "visible", timeout: plan.timeout }).catch(() => {});
+    if (step.clear !== false) await loc.clear().catch(() => {});
+    await loc.fill(String(value ?? ""), { timeout: plan.timeout });
+  }
+
+  else if (action === "click") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+
+    // Danger detection
+    let meta = {};
+    try {
+      meta = await loc.evaluate((el) => ({
+        text: (el.textContent || "").trim().slice(0, 120),
+        className: el.className || "",
+        ariaLabel: el.getAttribute("aria-label") || "",
+        role: el.getAttribute("role") || "",
+      }));
+    } catch {}
+
+    const danger = classifyDanger({ ...meta, url: page.url() });
+    stepRec.danger = danger;
+
+    const policy = String(step.dangerPolicy || "skip").toLowerCase();
+    if (danger.dangerous && !plan.danger) {
+      if (policy === "block") {
+        stepRec.status = "blocked";
+        stepRec.error = `Blocked destructive action (${danger.reason}). Use --danger to allow.`;
+        return;
+      }
+      stepRec.status = "skipped";
+      stepRec.error = `Skipped destructive action (${danger.reason}). Use --danger to allow.`;
+      return;
+    }
+
+    await loc.waitFor({ state: "visible", timeout: plan.timeout }).catch(() => {});
+    try {
+      await loc.click({ timeout: plan.timeout });
+    } catch {
+      await loc.click({ timeout: plan.timeout, force: true });
+    }
+    await page.waitForTimeout(300);
+  }
+
+  else if (action === "check") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+    await loc.check({ timeout: plan.timeout });
+  }
+
+  else if (action === "uncheck") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+    await loc.uncheck({ timeout: plan.timeout });
+  }
+
+  else if (action === "select") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+    if (step.value) {
+      await loc.selectOption({ value: template(step.value, flowVars) });
+    } else if (step.label) {
+      await loc.selectOption({ label: template(step.label, flowVars) });
+    } else if (step.index != null) {
+      await loc.selectOption({ index: Number(step.index) });
+    }
+  }
+
+  else if (action === "hover") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+    await loc.hover({ timeout: plan.timeout });
+  }
+
+  else if (action === "press") {
+    const key = template(step.key, flowVars);
+    await page.keyboard.press(key);
+  }
+
+  else if (action === "screenshot") {
+    const name = template(step.name || `manual-${Date.now()}`, flowVars);
+    const outPath = path.join(plan.artifacts.screenshotsDir, `${name}.png`);
+    await screenshot(page, outPath);
+    stepRec.artifacts.manualScreenshot = path.relative(plan.outputDir, outPath);
+  }
+
+  else if (action === "scroll") {
+    if (step.to === "bottom") {
+      await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+    } else if (step.to === "top") {
+      await page.evaluate(() => window.scrollTo(0, 0));
+    } else if (step.target) {
+      const target = template(step.target, flowVars);
+      const loc = await findLocator(page, target);
+      await loc.scrollIntoViewIfNeeded();
+    }
+  }
+
+  else if (action === "execute") {
+    if (step.script) {
+      await page.evaluate(step.script);
+    } else if (step.scriptFile) {
+      const scriptPath = path.resolve(step.scriptFile);
+      const script = fs.readFileSync(scriptPath, "utf8");
+      await page.evaluate(script);
+    }
+  }
+
+  else {
+    stepRec.status = "unknown";
+    stepRec.error = `Unknown action: ${step.action}`;
+  }
+}
+
+// ============================================================================
+// Assertions
+// ============================================================================
+
+async function runAssertion({ assertion, plan, page, telemetry, vars }) {
+  const type = String(assertion.type || "").toLowerCase().replace(/-/g, "");
+  const critical = !!assertion.critical;
+
+  const out = {
+    type: assertion.type,
+    critical,
+    status: "pass",
+    message: "",
+  };
+
+  try {
+    if (type === "urlcontains") {
+      const v = template(assertion.value, vars);
+      if (!page.url().toLowerCase().includes(v.toLowerCase())) {
+        throw new Error(`URL does not contain: ${v} (got ${page.url()})`);
+      }
+    }
+
+    else if (type === "urlmatches") {
+      const v = template(assertion.pattern || assertion.value, vars);
+      const re = new RegExp(v);
+      if (!re.test(page.url())) throw new Error(`URL does not match: ${v}`);
+    }
+
+    else if (type === "urlnotcontains") {
+      const v = template(assertion.value, vars);
+      if (page.url().toLowerCase().includes(v.toLowerCase())) {
+        throw new Error(`URL should not contain: ${v}`);
+      }
+    }
+
+    else if (type === "routechanged") {
+      const within = Number(assertion.within || 3000);
+      const match = assertion.match ? new RegExp(template(assertion.match, vars)) : null;
+      const before = page.url();
+      await page.waitForTimeout(Math.min(within, 500));
+      const after = page.url();
+      if (after === before) throw new Error(`Route did not change`);
+      if (match && !match.test(after)) throw new Error(`Route changed but does not match: ${assertion.match}`);
+    }
+
+    else if (type === "elementvisible") {
+      const target = template(assertion.target, vars);
+      const loc = await findLocator(page, target);
+      await loc.waitFor({ state: "visible", timeout: Number(assertion.within || plan.timeout) });
+    }
+
+    else if (type === "elementhidden") {
+      const target = template(assertion.target, vars);
+      const loc = await findLocator(page, target);
+      await loc.waitFor({ state: "hidden", timeout: Number(assertion.within || plan.timeout) });
+    }
+
+    else if (type === "elementtext") {
+      const target = template(assertion.target, vars);
+      const loc = await findLocator(page, target);
+      const text = await loc.textContent({ timeout: plan.timeout });
+      if (assertion.contains) {
+        const expected = template(assertion.contains, vars);
+        if (!String(text || "").includes(expected)) {
+          throw new Error(`Element text does not contain "${expected}"`);
+        }
+      }
+      if (assertion.matches) {
+        const re = new RegExp(template(assertion.matches, vars));
+        if (!re.test(text || "")) {
+          throw new Error(`Element text does not match ${assertion.matches}`);
+        }
+      }
+    }
+
+    else if (type === "elementcount") {
+      const target = template(assertion.target, vars);
+      const count = await page.locator(target).count();
+      if (assertion.min != null && count < assertion.min) {
+        throw new Error(`Element count ${count} < min ${assertion.min}`);
+      }
+      if (assertion.max != null && count > assertion.max) {
+        throw new Error(`Element count ${count} > max ${assertion.max}`);
+      }
+      if (assertion.equals != null && count !== assertion.equals) {
+        throw new Error(`Element count ${count} !== ${assertion.equals}`);
+      }
+    }
+
+    else if (type === "toastcontains" || type === "notificationvisible") {
+      const v = template(assertion.text || assertion.contains || assertion.value, vars);
+      const within = Number(assertion.within || 5000);
+      const toastSel = assertion.target || '[role="status"], [role="alert"], .toast, .sonner-toast, [data-sonner-toast], .notification';
+      const loc = page.locator(toastSel).filter({ hasText: new RegExp(v, "i") }).first();
+      await loc.waitFor({ state: "visible", timeout: within });
+    }
+
+    else if (type === "toastnotcontains") {
+      const v = template(assertion.text || assertion.value, vars);
+      const within = Number(assertion.within || 3000);
+      const toastSel = assertion.target || '[role="status"], [role="alert"], .toast, .sonner-toast, [data-sonner-toast], .notification';
+      await page.waitForTimeout(Math.min(within, 1500));
+      const count = await page.locator(toastSel).filter({ hasText: new RegExp(v, "i") }).count();
+      if (count > 0) throw new Error(`Toast contains forbidden text: ${v}`);
+    }
+
+    else if (type === "networkcalled") {
+      const v = template(assertion.match || assertion.value, vars);
+      const within = Number(assertion.within || 10000);
+      const minTimes = assertion.times ?? assertion.minTimes ?? 1;
+      const since = Date.now() - within;
+      const matches = telemetry.responses.filter(r => r.ts >= since && r.url.includes(v));
+      if (matches.length < minTimes) {
+        throw new Error(`Expected ${minTimes} calls matching ${v}, got ${matches.length}`);
+      }
+    }
+
+    else if (type === "networkstatus") {
+      const v = template(assertion.match || assertion.value, vars);
+      const expectStatus = Number(assertion.status || 200);
+      const within = Number(assertion.within || 10000);
+      const since = Date.now() - within;
+      const match = telemetry.responses.find(r => r.ts >= since && r.url.includes(v));
+      if (!match) throw new Error(`No response matching: ${v}`);
+      if (match.status !== expectStatus) {
+        throw new Error(`Expected ${expectStatus}, got ${match.status} for ${match.url}`);
+      }
+    }
+
+    else if (type === "networktiming") {
+      const v = template(assertion.match || assertion.value, vars);
+      const maxDuration = Number(assertion.maxDuration || 5000);
+      // Check request/response pairs - simplified version
+      const match = telemetry.responses.find(r => r.url.includes(v));
+      if (!match) throw new Error(`No response matching: ${v}`);
+      // We don't have timing data in this simplified version
+      out.message = `Network timing check (simplified): ${v}`;
+    }
+
+    else if (type === "noconsoleerrors") {
+      const severity = String(assertion.severity || "error").toLowerCase();
+      const windowMs = Number(assertion.within || 60000);
+      const since = Date.now() - windowMs;
+
+      const ignorePatterns = (assertion.ignore || []).map(p => new RegExp(p));
+      
+      const bad = telemetry.console
+        .filter(m => m.ts >= since)
+        .filter(m => {
+          if (severity === "error") return m.type === "error";
+          if (severity === "warning" || severity === "warn") return m.type === "error" || m.type === "warning";
+          return m.type === "error";
+        })
+        .filter(m => !ignorePatterns.some(re => re.test(m.text)));
+
+      if (bad.length > 0) {
+        throw new Error(`Console ${bad[0].type}: ${String(bad[0].text || "").slice(0, 140)}`);
+      }
+    }
+
+    else if (type === "consolecontains") {
+      const match = template(assertion.match || assertion.value, vars);
+      const severity = String(assertion.severity || "log").toLowerCase();
+      const found = telemetry.console.some(m => {
+        if (severity !== "all" && m.type !== severity) return false;
+        return m.text.includes(match);
+      });
+      if (!found) throw new Error(`Console does not contain: ${match}`);
+    }
+
+    else if (type === "localstorage") {
+      const key = template(assertion.key, vars);
+      const value = await page.evaluate((k) => localStorage.getItem(k), key);
+      if (assertion.exists === true && value === null) {
+        throw new Error(`localStorage key "${key}" does not exist`);
+      }
+      if (assertion.exists === false && value !== null) {
+        throw new Error(`localStorage key "${key}" should not exist`);
+      }
+      if (assertion.equals != null && value !== assertion.equals) {
+        throw new Error(`localStorage "${key}" !== "${assertion.equals}"`);
+      }
+      if (assertion.matches) {
+        const re = new RegExp(assertion.matches);
+        if (!re.test(value || "")) throw new Error(`localStorage "${key}" does not match ${assertion.matches}`);
+      }
+    }
+
+    else if (type === "sessionstorage") {
+      const key = template(assertion.key, vars);
+      const value = await page.evaluate((k) => sessionStorage.getItem(k), key);
+      if (assertion.exists === true && value === null) {
+        throw new Error(`sessionStorage key "${key}" does not exist`);
+      }
+      if (assertion.matches) {
+        const re = new RegExp(assertion.matches);
+        if (!re.test(value || "")) throw new Error(`sessionStorage "${key}" does not match ${assertion.matches}`);
+      }
+    }
+
+    else {
+      out.status = "skip";
+      out.message = `Assertion type not implemented: ${assertion.type}`;
+    }
+  } catch (e) {
+    out.status = "fail";
+    out.message = String(e?.message || e).slice(0, 220);
+  }
+
+  return out;
+}
+
+// ============================================================================
+// Score Calculation
+// ============================================================================
+
+function calculateScore(results) {
+  const routesDiscovered = results.coverage?.routesDiscovered || 0;
+  const routesWorking = results.coverage?.routesWorking || 0;
+  const routePct = routesDiscovered ? (routesWorking / routesDiscovered) : 1;
+
+  const flows = results.flows || [];
+  const flowTotal = flows.length || 1;
+  const flowOk = flows.filter(f => f.status === "success").length;
+
+  let assertsTotal = 0;
+  let assertsPass = 0;
+  for (const f of flows) {
+    for (const a of (f.assertions || [])) {
+      if (a.status === "skip") continue;
+      assertsTotal++;
+      if (a.status === "pass") assertsPass++;
+    }
+  }
+  const assertPct = assertsTotal ? (assertsPass / assertsTotal) : 1;
+
+  const errors = results.errors?.length || 0;
+  const penalty = Math.min(errors * 3, 20);
+
+  const score = (routePct * 30) + ((flowOk / flowTotal) * 40) + (assertPct * 30) - penalty;
+
+  return Math.max(0, Math.min(100, Math.round(score)));
+}
+
+module.exports = { runFlowPlan, classifyDanger, discoverSurface };