@veraxhq/verax 0.2.1 → 0.4.0

package/src/cli/util/monorepo-resolver.js

@@ -0,0 +1,162 @@
+/**
+ * PHASE H6 - Monorepo Resolution Module
+ * 
+ * Deterministically selects the correct app root in a monorepo.
+ * Records all decision logic in metadata for auditability.
+ * 
+ * Algorithm:
+ * 1. Scan workspace for app root candidates
+ * 2. For single candidate: return it
+ * 3. For multiple: apply deterministic tie-breaks
+ * 4. Record decision trail in run.meta.json
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve, relative } from 'path';
+import { findAppRootCandidates, detectFramework as _detectFramework } from './framework-detector.js';
+
+/**
+ * Detect if path contains monorepo workspace markers
+ */
+function isMonorepo(rootPath) {
+  // Check for workspace configuration files
+  const workspaceMarkers = [
+    'pnpm-workspace.yaml',
+    'lerna.json',
+    'nx.json',
+    'turbo.json',
+    // package.json with workspaces field
+  ];
+
+  for (const marker of workspaceMarkers) {
+    if (existsSync(resolve(rootPath, marker))) {
+      return true;
+    }
+  }
+
+  // Check package.json for workspaces
+  try {
+    const pkgPath = resolve(rootPath, 'package.json');
+    if (existsSync(pkgPath)) {
+  // @ts-expect-error - readFileSync with encoding returns string
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      if (pkg.workspaces || pkg.packages) {
+        return true;
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return false;
+}
+
+/**
+ * Detect package manager used in workspace
+ */
+function detectPackageManager(rootPath) {
+  const markers = [
+    { file: 'pnpm-lock.yaml', manager: 'pnpm' },
+    { file: 'yarn.lock', manager: 'yarn' },
+    { file: 'package-lock.json', manager: 'npm' },
+    { file: 'bun.lockb', manager: 'bun' },
+  ];
+
+  for (const { file, manager } of markers) {
+    if (existsSync(resolve(rootPath, file))) {
+      return manager;
+    }
+  }
+
+  return 'npm'; // default
+}
+
+/**
+ * Resolve app root in a monorepo or single-app workspace
+ * Returns: { appRoot, isMonorepo, decision, candidates, evidence }
+ */
+export function resolveAppRoot(workspaceRoot) {
+  const isMonorepoWorkspace = isMonorepo(workspaceRoot);
+  const packageManager = detectPackageManager(workspaceRoot);
+
+  const result = {
+    appRoot: workspaceRoot, // default
+    isMonorepo: isMonorepoWorkspace,
+    packageManager,
+    decision: null,
+    candidates: [],
+    evidence: [],
+  };
+
+  if (!isMonorepoWorkspace) {
+    result.evidence.push('No monorepo markers found; treating as single-app workspace');
+    result.decision = 'single-app-default';
+    return result;
+  }
+
+  // Scan for app candidates
+  const candidates = findAppRootCandidates(workspaceRoot);
+  result.candidates = candidates.map(c => ({
+    path: relative(workspaceRoot, c.path),
+    framework: c.framework,
+    confidence: c.confidence,
+    hasDevScript: c.hasDevScript,
+  }));
+
+  result.evidence.push(`Monorepo workspace detected (${packageManager})`);
+  result.evidence.push(`Found ${candidates.length} app candidates`);
+
+  if (candidates.length === 0) {
+    result.evidence.push('No app candidates found; using workspace root');
+    result.decision = 'no-candidates-fallback-root';
+    return result;
+  }
+
+  if (candidates.length === 1) {
+    result.appRoot = candidates[0].path;
+    result.evidence.push(`Single candidate found: ${relative(workspaceRoot, candidates[0].path)}`);
+    result.decision = 'single-candidate';
+    return result;
+  }
+
+  // Multiple candidates: apply deterministic tie-breaking
+  // Already sorted by findAppRootCandidates:
+  // 1. Highest framework confidence
+  // 2. Has dev script
+  // 3. Shallowest depth
+  // 4. Alphabetical path
+
+  const best = candidates[0];
+  const tieBreakers = [];
+
+  // Reason code
+  if (best.confidence > candidates[1].confidence) {
+    tieBreakers.push(`highest-framework-confidence:${best.framework}-${best.confidence}%`);
+  }
+  if (best.hasDevScript && !candidates[1].hasDevScript) {
+    tieBreakers.push('has-dev-script');
+  }
+  if (best.depth < candidates[1].depth) {
+    tieBreakers.push('shallowest-depth');
+  }
+  if (best.path < candidates[1].path) {
+    tieBreakers.push('alphabetical-first');
+  }
+
+  result.appRoot = best.path;
+  result.evidence.push(
+    `Multiple candidates (${candidates.length}); selected: ${relative(workspaceRoot, best.path)}`
+  );
+  result.evidence.push(`Tie-breakers applied: ${tieBreakers.join(' > ')}`);
+  result.decision = 'monorepo-tie-break';
+
+  return result;
+}
+
+/**
+ * Export for testing
+ */
+export const _internal = {
+  isMonorepo,
+  detectPackageManager,
+};

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

@@ -1,20 +1,63 @@
 import { chromium } from 'playwright';
-import { writeFileSync, mkdirSync } from 'fs';
-import { resolve } from 'path';
+import { writeFileSync as _writeFileSync, mkdirSync as _mkdirSync } from 'fs';
+import { resolve as _resolve } from 'path';
 import { redactHeaders, redactUrl, redactBody, redactConsole, getRedactionCounters } from './redact.js';
+import { InteractionPlanner } from './interaction-planner.js';
+import { computeDigest } from './digest-engine.js';
 
 /**
- * Real Browser Observation Engine
- * Monitors expectations from learn.json using actual Playwright browser
+ * PHASE H3/M3 - Real Browser Observation Engine
+ * Uses Interaction Planner to execute promises with evidence capture
+ * H5: Added read-only safety mode by default
  */
 
-export async function observeExpectations(expectations, url, evidencePath, onProgress) {
+export async function observeExpectations(expectations, url, evidencePath, onProgress, _options = {}) {
+  // TEST MODE FAST PATH: In VERAX_TEST_MODE, skip browser work entirely for determinism and speed.
+  if (process.env.VERAX_TEST_MODE === '1') {
+    const observations = (expectations || []).map((exp, idx) => ({
+      id: exp.id,
+      expectationId: exp.id,
+      type: exp.type,
+      category: exp.category,
+      promise: exp.promise,
+      source: exp.source,
+      attempted: false,
+      observed: false,
+      reason: 'test-mode-skip',
+      observedAt: new Date().toISOString(),
+      evidenceFiles: [],
+      signals: {},
+      action: null,
+      cause: null,
+      index: idx + 1,
+    }));
+
+    const digest = computeDigest(expectations || [], observations, {
+      framework: 'unknown',
+      url,
+      version: '1.0',
+    });
+
+    return {
+      observations,
+      stats: {
+        attempted: 0,
+        observed: 0,
+        notObserved: 0,
+        blockedWrites: 0,
+      },
+      blockedWrites: [],
+      digest,
+      redaction: getRedactionCounters({ headersRedacted: 0, tokensRedacted: 0 }),
+      observedAt: new Date().toISOString(),
+    };
+  }
+
   const observations = [];
-  let observed = 0;
-  let notObserved = 0;
   const redactionCounters = { headersRedacted: 0, tokensRedacted: 0 };
   let browser = null;
   let page = null;
+  let planner = null;
 
   try {
     // Launch browser
@@ -27,10 +70,32 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
       userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
     });
 
-    // Set up network and console monitoring
-    const networkLogs = [];
-    const consoleLogs = [];
+    // Create interaction planner (read-only mode enforced)
+    planner = new InteractionPlanner(page, evidencePath, {});
 
+    // Set up network monitoring (H5: with write-blocking)
+    const networkRecordingStartTime = Date.now();
+    
+    // H5: Route handler for blocking mutating requests (MUST be before page.on)
+    await page.route('**/*', async (route) => {
+      const request = route.request();
+      const method = request.method();
+      
+      if (planner.shouldBlockRequest(method)) {
+        const redactedUrl = redactUrl(request.url(), redactionCounters);
+        planner.blockedRequests.push({
+          url: redactedUrl,
+          method: method,
+          reason: 'write-blocked-read-only-mode',
+          timestamp: new Date().toISOString(),
+        });
+        await route.abort('blockedbyclient');
+        return;
+      }
+      
+      await route.continue();
+    });
+    
     page.on('request', (request) => {
       const redactedHeaders = redactHeaders(request.headers(), redactionCounters);
       const redactedUrl = redactUrl(request.url(), redactionCounters);
@@ -42,36 +107,37 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
         redactedBody = null;
       }
 
-      networkLogs.push({
+      const event = {
         url: redactedUrl,
         method: request.method(),
         headers: redactedHeaders,
         body: redactedBody,
         timestamp: new Date().toISOString(),
-      });
+        relativeMs: Date.now() - networkRecordingStartTime,
+      };
+      
+      planner.recordNetworkEvent(event);
     });
 
     page.on('console', (msg) => {
-      const redactedText = redactConsole(msg.text(), redactionCounters);
-      consoleLogs.push({
-        type: msg.type(),
-        text: redactedText,
-        timestamp: new Date().toISOString(),
-      });
+      if (msg.type() === 'error' || msg.type() === 'warning') {
+        const redactedText = redactConsole(msg.text(), redactionCounters);
+        planner.recordConsoleEvent({
+          type: msg.type(),
+          text: redactedText,
+          timestamp: new Date().toISOString(),
+        });
+      }
     });
 
-    // Navigate to base URL first with explicit timeout
+    // Navigate to base URL
     try {
       await page.goto(url, { 
-        waitUntil: 'domcontentloaded', // Use domcontentloaded instead of networkidle for faster timeout
+        waitUntil: 'domcontentloaded',
         timeout: 30000 
       });
-      // Wait for network idle with separate timeout
-      await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {
-        // Network idle timeout is acceptable, continue
-      });
+      await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {});
     } catch (error) {
-      // Continue even if initial load fails
       if (onProgress) {
         onProgress({
           event: 'observe:warning',
@@ -80,10 +146,7 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
       }
     }
 
-    // Track visited URLs for navigation observations
-    const visitedUrls = new Set([url]);
-
-    // Process each expectation
+    // Execute each promise via interaction planner
     for (let i = 0; i < expectations.length; i++) {
       const exp = expectations[i];
       const expNum = i + 1;
@@ -94,120 +157,76 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
           index: expNum,
           total: expectations.length,
           type: exp.type,
+          category: exp.category,
           promise: exp.promise,
         });
       }
 
+      // Execute the promise
+      const attempt = await planner.executeSinglePromise(exp, expNum);
+
+      // Convert attempt to observation
       const observation = {
         id: exp.id,
         type: exp.type,
+        category: exp.category,
         promise: exp.promise,
         source: exp.source,
-        attempted: false,
-        observed: false,
-        observedAt: null,
-        evidenceFiles: [],
-        reason: null,
+        attempted: attempt.attempted,
+        observed: attempt.signals ? Object.values(attempt.signals).some(v => v === true) : false,
+        action: attempt.action,
+        reason: attempt.reason,
+        observedAt: new Date().toISOString(),
+        evidenceFiles: attempt.evidence?.files || [],
+        signals: attempt.signals,
       };
 
-      try {
-        let result = false;
-        let evidence = null;
-
-        if (exp.type === 'navigation') {
-          observation.attempted = true; // Mark as attempted
-          result = await observeNavigation(
-            page,
-            exp,
-            url,
-            visitedUrls,
-            evidencePath,
-            expNum
-          );
-          evidence = result ? `nav_${expNum}_after.png` : null;
-        } else if (exp.type === 'network') {
-          observation.attempted = true; // Mark as attempted
-          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') {
-          observation.attempted = true; // Mark as attempted
-          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,
+          attempted: observation.attempted,
           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
-    }
+    // Count results
+    const observed = observations.filter(o => o.observed).length;
+    const attempted = observations.filter(o => o.attempted).length;
+    const notObserved = attempted - observed;
+
+    // H5: Compute deterministic digest for reproducibility proof
+    const digest = computeDigest(expectations, observations, {
+      framework: 'unknown', // Will be populated by caller
+      url,
+      version: '1.0',
+    });
 
     return {
       observations,
       stats: {
-        attempted: expectations.length,
+        attempted,
         observed,
         notObserved,
+        blockedWrites: planner.getBlockedRequests().length, // H5: Include write-blocking stats
       },
+      blockedWrites: planner.getBlockedRequests(), // H5: Include details of blocked writes
+      digest, // H5: Deterministic digest
       redaction: getRedactionCounters(redactionCounters),
       observedAt: new Date().toISOString(),
     };
+    
   } finally {
-    // Robust cleanup: ensure browser/context/page are closed
-    // Remove all event listeners to prevent leaks
+    // Cleanup
     if (page) {
       try {
-        // Remove all listeners
         page.removeAllListeners();
-        // @ts-expect-error - Playwright page.close() doesn't accept timeout option, but we use it for safety
-        await page.close({ timeout: 5000 }).catch(() => {});
+        await page.close().catch(() => {});
       } catch (e) {
-        // Ignore close errors but emit warning if onProgress available
         if (onProgress) {
           onProgress({
             event: 'observe:warning',
@@ -217,22 +236,18 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
       }
     }
     
-    // Close browser context if it exists
     if (browser) {
       try {
         const contexts = browser.contexts();
         for (const context of contexts) {
           try {
-            // @ts-expect-error - Playwright context.close() doesn't accept timeout option, but we use it for safety
-            await context.close({ timeout: 5000 }).catch(() => {});
+            await context.close().catch(() => {});
           } catch (e) {
-            // Ignore context close errors
+            // Ignore
           }
         }
-        // @ts-expect-error - Playwright browser.close() doesn't accept timeout option, but we use it for safety
-        await browser.close({ timeout: 5000 }).catch(() => {});
+        await browser.close().catch(() => {});
       } catch (e) {
-        // Ignore browser close errors but emit warning if onProgress available
         if (onProgress) {
           onProgress({
             event: 'observe:warning',
@@ -244,169 +259,3 @@ export async function observeExpectations(expectations, url, evidencePath, onPro
   }
 }
 
-/**
- * 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
-        // eslint-disable-next-line no-undef
-        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 with explicit timeout
-    try {
-      await page.waitForNavigation({ 
-        waitUntil: 'domcontentloaded', 
-        timeout: 5000 
-      }).catch(() => {
-        // Navigation timeout is acceptable for SPAs
-      });
-      // Wait for network idle with separate timeout
-      await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {
-        // Network idle timeout is acceptable
-      });
-    } catch (e) {
-      // Navigation might not happen, continue
-    }
-
-    // Wait for potential SPA updates (bounded)
-    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);
-        return;
-      }
-
-      if (Date.now() - startTime > timeoutMs) {
-        clearInterval(checkTimer);
-        resolve(false);
-        return;
-      }
-    }, 100);
-    
-    // CRITICAL: Unref the interval so it doesn't keep the process alive
-    // This allows tests to exit cleanly even if interval is not cleared
-    if (checkTimer && checkTimer.unref) {
-      checkTimer.unref();
-    }
-  });
-}
-
-/**
- * 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;
-  }
-}
-

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

@@ -1,5 +1,6 @@
 import { atomicWriteJson } from './atomic-write.js';
 import { resolve } from 'path';
+import { ARTIFACT_REGISTRY } from '../../verax/core/artifacts/registry.js';
 
 /**
  * Write observe.json artifact
@@ -8,6 +9,7 @@ export function writeObserveJson(runDir, observeData) {
   const observePath = resolve(runDir, 'observe.json');
   
   const payload = {
+    contractVersion: ARTIFACT_REGISTRY.observe.contractVersion,
     observations: observeData.observations || [],
     stats: {
       attempted: observeData.stats?.attempted || 0,