@veraxhq/verax 0.1.0 → 0.2.0

package/src/cli/util/observation-engine.js

@@ -0,0 +1,366 @@
+import { chromium } from 'playwright';
+import { writeFileSync, mkdirSync } from 'fs';
+import { resolve, join } from 'path';
+import { redactHeaders, redactUrl, redactBody, redactConsole, getRedactionCounters } from './redact.js';
+
+/**
+ * Real Browser Observation Engine
+ * Monitors expectations from learn.json using actual Playwright browser
+ */
+
+export async function observeExpectations(expectations, url, evidencePath, onProgress) {
+  const observations = [];
+  let observed = 0;
+  let notObserved = 0;
+  const redactionCounters = { headersRedacted: 0, tokensRedacted: 0 };
+  let browser = null;
+  let page = null;
+
+  try {
+    // Launch browser
+    browser = await chromium.launch({
+      headless: true,
+    });
+
+    page = await browser.newPage({
+      viewport: { width: 1280, height: 800 },
+      userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+    });
+
+    // Set up network and console monitoring
+    const networkLogs = [];
+    const consoleLogs = [];
+
+    page.on('request', (request) => {
+      const redactedHeaders = redactHeaders(request.headers(), redactionCounters);
+      const redactedUrl = redactUrl(request.url(), redactionCounters);
+      let redactedBody = null;
+      try {
+        const body = request.postData();
+        redactedBody = body ? redactBody(body, redactionCounters) : null;
+      } catch {
+        redactedBody = null;
+      }
+
+      networkLogs.push({
+        url: redactedUrl,
+        method: request.method(),
+        headers: redactedHeaders,
+        body: redactedBody,
+        timestamp: new Date().toISOString(),
+      });
+    });
+
+    page.on('console', (msg) => {
+      const redactedText = redactConsole(msg.text(), redactionCounters);
+      consoleLogs.push({
+        type: msg.type(),
+        text: redactedText,
+        timestamp: new Date().toISOString(),
+      });
+    });
+
+    // Navigate to base URL first
+    try {
+      await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
+    } catch (error) {
+      // Continue even if initial load fails
+      if (onProgress) {
+        onProgress({
+          event: 'observe:warning',
+          message: `Failed to load base URL: ${error.message}`,
+        });
+      }
+    }
+
+    // Track visited URLs for navigation observations
+    const visitedUrls = new Set([url]);
+
+    // Process each expectation
+    for (let i = 0; i < expectations.length; i++) {
+      const exp = expectations[i];
+      const expNum = i + 1;
+
+      if (onProgress) {
+        onProgress({
+          event: 'observe:attempt',
+          index: expNum,
+          total: expectations.length,
+          type: exp.type,
+          promise: exp.promise,
+        });
+      }
+
+      const observation = {
+        id: exp.id,
+        type: exp.type,
+        promise: exp.promise,
+        source: exp.source,
+        observed: false,
+        observedAt: null,
+        evidenceFiles: [],
+        reason: null,
+      };
+
+      try {
+        let result = false;
+        let evidence = null;
+
+        if (exp.type === 'navigation') {
+          result = await observeNavigation(
+            page,
+            exp,
+            url,
+            visitedUrls,
+            evidencePath,
+            expNum
+          );
+          evidence = result ? `nav_${expNum}_after.png` : null;
+        } else if (exp.type === 'network') {
+          result = await observeNetwork(page, exp, networkLogs, 5000);
+          if (result) {
+            const evidenceFile = `network_${expNum}.json`;
+            try {
+              mkdirSync(evidencePath, { recursive: true });
+              const targetUrl = exp.promise.value;
+              const relevant = networkLogs.filter((log) =>
+                log.url === targetUrl || log.url.includes(targetUrl) || targetUrl.includes(log.url)
+              );
+              writeFileSync(resolve(evidencePath, evidenceFile), JSON.stringify(relevant, null, 2), 'utf-8');
+            } catch {
+              // best effort
+            }
+            evidence = evidenceFile;
+          } else {
+            evidence = null;
+          }
+        } else if (exp.type === 'state') {
+          result = await observeState(page, exp, evidencePath, expNum);
+          evidence = result ? `state_${expNum}_after.png` : null;
+        }
+
+        if (result) {
+          observation.observed = true;
+          observation.observedAt = new Date().toISOString();
+          if (evidence) observation.evidenceFiles.push(evidence);
+          observed++;
+        } else {
+          observation.reason = 'No matching event observed';
+          notObserved++;
+        }
+      } catch (error) {
+        observation.reason = `Error: ${error.message}`;
+        notObserved++;
+      }
+
+      observations.push(observation);
+
+      if (onProgress) {
+        onProgress({
+          event: 'observe:result',
+          index: expNum,
+          observed: observation.observed,
+          reason: observation.reason,
+        });
+      }
+    }
+
+    // Persist shared evidence
+    try {
+      mkdirSync(evidencePath, { recursive: true });
+      const networkPath = resolve(evidencePath, 'network_logs.json');
+      writeFileSync(networkPath, JSON.stringify(networkLogs, null, 2), 'utf-8');
+      const consolePath = resolve(evidencePath, 'console_logs.json');
+      writeFileSync(consolePath, JSON.stringify(consoleLogs, null, 2), 'utf-8');
+    } catch {
+      // Best effort; do not throw
+    }
+
+    return {
+      observations,
+      stats: {
+        attempted: expectations.length,
+        observed,
+        notObserved,
+      },
+      redaction: getRedactionCounters(redactionCounters),
+      observedAt: new Date().toISOString(),
+    };
+  } finally {
+    // Clean up
+    if (page) {
+      try {
+        await page.close();
+      } catch (e) {
+        // Ignore close errors
+      }
+    }
+    if (browser) {
+      try {
+        await browser.close();
+      } catch (e) {
+        // Ignore close errors
+      }
+    }
+  }
+}
+
+/**
+ * Observe navigation expectation
+ * Attempts to find and click element, observes URL/SPA changes
+ */
+async function observeNavigation(page, expectation, baseUrl, visitedUrls, evidencePath, expNum) {
+  const targetPath = expectation.promise.value;
+
+  try {
+    // Screenshot before interaction
+    const beforePath = resolve(evidencePath, `nav_${expNum}_before.png`);
+    await page.screenshot({ path: beforePath }).catch(() => {});
+
+    // Find element by searching all anchor tags
+    const element = await page.evaluate((path) => {
+      const anchors = Array.from(document.querySelectorAll('a'));
+      const found = anchors.find(a => {
+        const href = a.getAttribute('href');
+        return href === path || href.includes(path);
+      });
+      return found ? { tag: 'a', href: found.getAttribute('href') } : null;
+    }, targetPath);
+
+    if (!element) {
+      return false;
+    }
+
+    const urlBefore = page.url();
+    const contentBefore = await page.content();
+
+    // Click the element - try multiple approaches
+    try {
+      await page.locator(`a[href="${element.href}"]`).click({ timeout: 3000 });
+    } catch (e) {
+      try {
+        await page.click(`a[href="${element.href}"]`);
+      } catch (e2) {
+        // Try clicking by text content
+        const text = await page.evaluate((href) => {
+          const anchors = Array.from(document.querySelectorAll('a'));
+          const found = anchors.find(a => a.getAttribute('href') === href);
+          return found ? found.textContent : null;
+        }, element.href);
+        
+        if (text) {
+          await page.click(`a:has-text("${text}")`).catch(() => {});
+        }
+      }
+    }
+
+    // Wait for navigation or SPA update
+    try {
+      await page.waitForNavigation({ waitUntil: 'networkidle', timeout: 2000 }).catch(() => {});
+    } catch (e) {
+      // Navigation might not happen
+    }
+
+    // Wait for potential SPA updates
+    await page.waitForTimeout(300);
+
+    // Screenshot after interaction
+    const afterPath = resolve(evidencePath, `nav_${expNum}_after.png`);
+    await page.screenshot({ path: afterPath }).catch(() => {});
+
+    const urlAfter = page.url();
+    const contentAfter = await page.content();
+
+    // Check if URL changed or content changed
+    if (urlBefore !== urlAfter || contentBefore !== contentAfter) {
+      visitedUrls.add(urlAfter);
+      return true;
+    }
+
+    return false;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Observe network expectation
+ * Checks if matching request was made
+ */
+async function observeNetwork(page, expectation, networkLogs, timeoutMs) {
+  const targetUrl = expectation.promise.value;
+  const startTime = Date.now();
+
+  return new Promise((resolve) => {
+    const checkTimer = setInterval(() => {
+      const found = networkLogs.some((log) => {
+        return (
+          log.url === targetUrl ||
+          log.url.includes(targetUrl) ||
+          targetUrl.includes(log.url)
+        );
+      });
+
+      if (found) {
+        clearInterval(checkTimer);
+        resolve(true);
+      }
+
+      if (Date.now() - startTime > timeoutMs) {
+        clearInterval(checkTimer);
+        resolve(false);
+      }
+    }, 100);
+  });
+}
+
+/**
+ * Observe state expectation
+ * Detects DOM changes or loading indicators
+ */
+async function observeState(page, expectation, evidencePath, expNum) {
+  try {
+    // Screenshot before
+    const beforePath = resolve(evidencePath, `state_${expNum}_before.png`);
+    await page.screenshot({ path: beforePath });
+
+    const htmlBefore = await page.content();
+
+    // Wait briefly for potential state changes
+    await page.waitForTimeout(2000);
+
+    const htmlAfter = await page.content();
+
+    // Screenshot after
+    const afterPath = resolve(evidencePath, `state_${expNum}_after.png`);
+    await page.screenshot({ path: afterPath });
+
+    // Check if DOM changed
+    if (htmlBefore !== htmlAfter) {
+      return true;
+    }
+
+    // Check for common state indicators (loading, error, success messages)
+    const hasStateIndicators =
+      (await page.$('.loading')) ||
+      (await page.$('[role="status"]')) ||
+      (await page.$('.toast')) ||
+      (await page.$('[aria-live]'));
+
+    return !!hasStateIndicators;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Check if page content changed (for SPA detection)
+ */
+async function checkPageContentChanged(page) {
+  try {
+    const bodyText = await page.locator('body').textContent();
+    return bodyText && bodyText.length > 0;
+  } catch (error) {
+    return false;
+  }
+}

package/src/cli/util/observe-writer.js

@@ -0,0 +1,25 @@
+import { atomicWriteJson } from './atomic-write.js';
+import { resolve } from 'path';
+
+/**
+ * Write observe.json artifact
+ */
+export function writeObserveJson(runDir, observeData) {
+  const observePath = resolve(runDir, 'observe.json');
+  
+  const payload = {
+    observations: observeData.observations || [],
+    stats: {
+      attempted: observeData.stats?.attempted || 0,
+      observed: observeData.stats?.observed || 0,
+      notObserved: observeData.stats?.notObserved || 0,
+    },
+    redaction: {
+      headersRedacted: observeData.redaction?.headersRedacted || 0,
+      tokensRedacted: observeData.redaction?.tokensRedacted || 0,
+    },
+    observedAt: observeData.observedAt || new Date().toISOString(),
+  };
+  
+  atomicWriteJson(observePath, payload);
+}

package/src/cli/util/paths.js

@@ -0,0 +1,29 @@
+import { join } from 'path';
+import { mkdirSync } from 'fs';
+
+/**
+ * Build run artifact paths
+ */
+export function getRunPaths(projectRoot, outDir, runId) {
+  const baseDir = join(projectRoot, outDir, 'runs', runId);
+  
+  return {
+    baseDir,
+    runStatusJson: join(baseDir, 'run.status.json'),
+    runMetaJson: join(baseDir, 'run.meta.json'),
+    summaryJson: join(baseDir, 'summary.json'),
+    findingsJson: join(baseDir, 'findings.json'),
+    tracesJsonl: join(baseDir, 'traces.jsonl'),
+    evidenceDir: join(baseDir, 'evidence'),
+    learnJson: join(baseDir, 'learn.json'),
+    observeJson: join(baseDir, 'observe.json'),
+  };
+}
+
+/**
+ * Ensure all required directories exist
+ */
+export function ensureRunDirectories(paths) {
+  mkdirSync(paths.baseDir, { recursive: true });
+  mkdirSync(paths.evidenceDir, { recursive: true });
+}

package/src/cli/util/project-discovery.js

@@ -0,0 +1,277 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+
+/**
+ * Project Discovery Module
+ * Detects framework, router, source root, and dev server configuration
+ */
+
+export async function discoverProject(srcPath) {
+  const projectRoot = resolve(srcPath);
+  
+  // Find the nearest package.json
+  const packageJsonPath = findPackageJson(projectRoot);
+  
+  // If there's a package.json, use its directory
+  // Otherwise, use the srcPath (even if it's a static HTML project)
+  const projectDir = packageJsonPath ? dirname(packageJsonPath) : projectRoot;
+  
+  let packageJson = null;
+  if (packageJsonPath && existsSync(packageJsonPath)) {
+    try {
+      packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    } catch (error) {
+      packageJson = null;
+    }
+  }
+  
+  // Detect framework
+  const framework = detectFramework(projectDir, packageJson);
+  const router = detectRouter(framework, projectDir);
+  
+  // Determine package manager
+  const packageManager = detectPackageManager(projectDir);
+  
+  // Extract scripts
+  const scripts = {
+    dev: packageJson?.scripts?.dev || null,
+    build: packageJson?.scripts?.build || null,
+    start: packageJson?.scripts?.start || null,
+  };
+  
+  return {
+    framework,
+    router,
+    sourceRoot: projectDir,
+    packageManager,
+    scripts,
+    detectedAt: new Date().toISOString(),
+    packageJsonPath,
+  };
+}
+
+/**
+ * Find the nearest package.json by walking up directories
+ */
+function findPackageJson(startPath) {
+  let currentPath = resolve(startPath);
+  
+  // First check if package.json exists in startPath itself
+  const immediatePackage = resolve(currentPath, 'package.json');
+  if (existsSync(immediatePackage)) {
+    return immediatePackage;
+  }
+  
+  // Then walk up (limit to 5 levels for monorepos, not 10)
+  for (let i = 0; i < 5; i++) {
+    const parentPath = dirname(currentPath);
+    if (parentPath === currentPath) {
+      // Reached filesystem root
+      break;
+    }
+    
+    currentPath = parentPath;
+    const packageJsonPath = resolve(currentPath, 'package.json');
+    if (existsSync(packageJsonPath)) {
+      return packageJsonPath;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Detect the framework type
+ */
+function detectFramework(projectDir, packageJson) {
+  // Check for Next.js
+  if (hasNextJs(projectDir, packageJson)) {
+    return 'nextjs';
+  }
+  
+  // Check for Vite + React
+  if (hasViteReact(projectDir, packageJson)) {
+    return 'react-vite';
+  }
+  
+  // Check for Create React App
+  if (hasCreateReactApp(packageJson)) {
+    return 'react-cra';
+  }
+  
+  // Check for static HTML
+  if (hasStaticHtml(projectDir)) {
+    return 'static-html';
+  }
+  
+  // Unknown framework
+  return 'unknown';
+}
+
+/**
+ * Detect Next.js
+ */
+function hasNextJs(projectDir, packageJson) {
+  // Check for next.config.js or next.config.mjs
+  const hasNextConfig = existsSync(resolve(projectDir, 'next.config.js')) ||
+    existsSync(resolve(projectDir, 'next.config.mjs')) ||
+    existsSync(resolve(projectDir, 'next.config.ts'));
+  
+  if (hasNextConfig) {
+    return true;
+  }
+  
+  // Check for 'next' dependency
+  if (packageJson?.dependencies?.next || packageJson?.devDependencies?.next) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Detect router type for Next.js
+ */
+function detectRouter(framework, projectDir) {
+  if (framework !== 'nextjs') {
+    return null;
+  }
+  
+  // Check for /app directory (app router) - must contain actual files
+  const appPath = resolve(projectDir, 'app');
+  if (existsSync(appPath) && hasRouteFiles(appPath)) {
+    return 'app';
+  }
+  
+  // Check for /pages directory (pages router)
+  if (existsSync(resolve(projectDir, 'pages'))) {
+    return 'pages';
+  }
+  
+  return null;
+}
+
+/**
+ * Check if a directory contains route files (not just an empty scaffold)
+ */
+function hasRouteFiles(dirPath) {
+  try {
+    const entries = readdirSync(dirPath);
+    return entries.some(entry => {
+      // Look for .js, .ts, .jsx, .tsx files (not just directories)
+      return /\.(js|ts|jsx|tsx)$/.test(entry);
+    });
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Detect Vite + React
+ */
+function hasViteReact(projectDir, packageJson) {
+  const hasViteConfig = existsSync(resolve(projectDir, 'vite.config.js')) ||
+    existsSync(resolve(projectDir, 'vite.config.ts')) ||
+    existsSync(resolve(projectDir, 'vite.config.mjs'));
+  
+  if (!hasViteConfig) {
+    return false;
+  }
+  
+  // Check for react dependency
+  if (packageJson?.dependencies?.react || packageJson?.devDependencies?.react) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Detect Create React App
+ */
+function hasCreateReactApp(packageJson) {
+  return !!(packageJson?.dependencies?.['react-scripts'] || 
+    packageJson?.devDependencies?.['react-scripts']);
+}
+
+/**
+ * Detect static HTML (no framework)
+ */
+function hasStaticHtml(projectDir) {
+  return existsSync(resolve(projectDir, 'index.html'));
+}
+
+/**
+ * Detect package manager
+ */
+function detectPackageManager(projectDir) {
+  // Check for pnpm-lock.yaml
+  if (existsSync(resolve(projectDir, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+  
+  // Check for yarn.lock
+  if (existsSync(resolve(projectDir, 'yarn.lock'))) {
+    return 'yarn';
+  }
+  
+  // Check for package-lock.json (npm)
+  if (existsSync(resolve(projectDir, 'package-lock.json'))) {
+    return 'npm';
+  }
+  
+  // Default to npm if none found but package.json exists
+  if (existsSync(resolve(projectDir, 'package.json'))) {
+    return 'npm';
+  }
+  
+  return 'unknown';
+}
+
+/**
+ * Get human-readable framework name
+ */
+export function getFrameworkDisplayName(framework, router) {
+  if (framework === 'nextjs') {
+    const routerType = router === 'app' ? 'app router' : router === 'pages' ? 'pages router' : 'unknown router';
+    return `Next.js (${routerType})`;
+  }
+  
+  if (framework === 'react-vite') {
+    return 'Vite + React';
+  }
+  
+  if (framework === 'react-cra') {
+    return 'Create React App';
+  }
+  
+  if (framework === 'static-html') {
+    return 'Static HTML';
+  }
+  
+  return 'Unknown';
+}
+
+/**
+ * Extract probable port from dev script
+ */
+export function extractPortFromScript(script) {
+  if (!script) return null;
+  
+  // Common patterns:
+  // - --port 3000
+  // - -p 3000
+  // - PORT=3000
+  
+  const portMatch = script.match(/(?:--port|-p)\s+(\d+)/);
+  if (portMatch) {
+    return parseInt(portMatch[1], 10);
+  }
+  
+  const portEnvMatch = script.match(/PORT=(\d+)/);
+  if (portEnvMatch) {
+    return parseInt(portEnvMatch[1], 10);
+  }
+  
+  return null;
+}