@veraxhq/verax 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veraxhq/verax",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "VERAX - Silent failure detection for websites",
   "license": "MIT",
   "type": "module",
@@ -14,8 +14,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test",
-    "test:pack": "node scripts/test-pack.js"
+    "test": "node scripts/test-runner-wrapper.js",
+    "test:pack": "node scripts/test-pack.js",
+    "verify-release": "node scripts/verify-release.js",
+    "lint": "eslint . --max-warnings 0",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "glob": "^10.3.10",
@@ -30,6 +33,13 @@
   "devDependencies": {
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
-    "@veraxhq/verax": "file:veraxhq-verax-0.2.0.tgz"
+    "@reduxjs/toolkit": "^2.11.2",
+    "@veraxhq/verax": "file:veraxhq-verax-0.2.1.tgz",
+    "eslint": "^8.57.0",
+    "next": "^16.1.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "react-redux": "^9.2.0",
+    "react-router-dom": "^7.12.0"
   }
 }

package/src/cli/commands/default.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import inquirer from 'inquirer';
-import { UsageError, DataError, CrashError } from '../util/errors.js';
+import { DataError } from '../util/errors.js';
 import { generateRunId } from '../util/run-id.js';
 import { getRunPaths, ensureRunDirectories } from '../util/paths.js';
 import { atomicWriteJson, atomicWriteText } from '../util/atomic-write.js';
@@ -18,6 +18,7 @@ import { writeObserveJson } from '../util/observe-writer.js';
 import { detectFindings } from '../util/detection-engine.js';
 import { writeFindingsJson } from '../util/findings-writer.js';
 import { writeSummaryJson } from '../util/summary-writer.js';
+import { computeRuntimeBudget, withTimeout } from '../util/runtime-budget.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -72,6 +73,79 @@ export async function defaultCommand(options = {}) {
     });
   }
   
+  let runId = null;
+    /** @type {ReturnType<typeof getRunPaths> | null} */
+    let paths = null;
+  let startedAt = null;
+  let watchdogTimer = null;
+  let budget = null;
+  let timedOut = false;
+  
+  // Graceful finalization function
+  const finalizeOnTimeout = async (reason) => {
+    if (timedOut) return; // Prevent double finalization
+    timedOut = true;
+    
+    events.stopHeartbeat();
+    
+    // TypeScript narrowing: paths is guaranteed to be non-null here due to control flow
+    if (paths && runId && startedAt) {
+      try {
+        const failedAt = new Date().toISOString();
+        atomicWriteJson(paths.runStatusJson, {
+          status: 'FAILED',
+          runId,
+          startedAt,
+          failedAt,
+          error: reason,
+        });
+        
+        atomicWriteJson(paths.runMetaJson, {
+          veraxVersion: getVersion(),
+          nodeVersion: process.version,
+          platform: process.platform,
+          cwd: projectRoot,
+          command: 'default',
+          args: { url: url || null, src },
+          url: url || null,
+          src: srcPath,
+          startedAt,
+          completedAt: failedAt,
+          error: reason,
+        });
+        
+        try {
+          writeSummaryJson(paths.summaryJson, {
+            runId,
+            status: 'FAILED',
+            startedAt,
+            completedAt: failedAt,
+            command: 'default',
+            url: url || null,
+            notes: `Run timed out: ${reason}`,
+          }, {
+            expectationsTotal: 0,
+            attempted: 0,
+            observed: 0,
+            silentFailures: 0,
+            coverageGaps: 0,
+            unproven: 0,
+            informational: 0,
+          });
+        } catch (summaryError) {
+          // Ignore summary write errors during timeout handling
+        }
+      } catch (statusError) {
+        // Ignore errors when writing failure status
+      }
+    }
+    
+    events.emit('error', {
+      message: reason,
+      type: 'timeout',
+    });
+  };
+  
   try {
     events.emit('phase:started', {
       phase: 'Detect Project',
@@ -231,8 +305,17 @@ export async function defaultCommand(options = {}) {
       message: 'Analyzing project structure...',
     });
     
-    // Extract expectations
-    const { expectations, skipped } = await extractExpectations(projectProfile, projectProfile.sourceRoot);
+    events.startHeartbeat('Learn', json);
+    
+    let expectations, skipped;
+    try {
+      // Extract expectations
+      const result = await extractExpectations(projectProfile, projectProfile.sourceRoot);
+      expectations = result.expectations;
+      skipped = result.skipped;
+    } finally {
+      events.stopHeartbeat();
+    }
     
     if (!json) {
       console.log(`Found ${expectations.length} expectations`);
@@ -256,55 +339,109 @@ export async function defaultCommand(options = {}) {
       });
     }
     
+    // Compute runtime budget based on expectations count
+    budget = computeRuntimeBudget({
+      expectationsCount: expectations.length,
+      mode: 'default',
+      framework: projectProfile.framework,
+      fileCount: projectProfile.fileCount || expectations.length,
+    });
+    
+    // Set up global watchdog timer
+    watchdogTimer = setTimeout(async () => {
+      await finalizeOnTimeout(`Global timeout exceeded: ${budget.totalMaxMs}ms`);
+      // Exit with code 0 (tool executed, just timed out)
+      process.exit(0);
+    }, budget.totalMaxMs);
+    
+    // Wrap Learn phase with timeout
+    try {
+      await withTimeout(
+        budget.learnMaxMs,
+        Promise.resolve(), // Learn phase already completed
+        'Learn'
+      );
+    } catch (error) {
+      if (error.message.includes('timeout')) {
+        await finalizeOnTimeout(`Learn phase timeout: ${budget.learnMaxMs}ms`);
+        process.exit(0);
+      }
+      throw error;
+    }
+    
     events.emit('phase:completed', {
       phase: 'Learn',
       message: 'Project analysis complete',
     });
     
-    // Observe phase
+    // Observe phase with timeout
     events.emit('phase:started', {
       phase: 'Observe',
       message: 'Launching browser and observing expectations...',
     });
     
+    events.startHeartbeat('Observe', json);
+    
     let observeData = null;
-    if (expectations.length > 0) {
-      try {
-        observeData = await observeExpectations(
-          expectations,
-          resolvedUrl,
-          paths.evidenceDir,
-          (progress) => {
-            events.emit(progress.event, progress);
-            if (!json && progress.event === 'observe:result') {
-              const status = progress.observed ? '✓' : '✗';
-              console.log(`  ${status} ${progress.index}/${expectations.length}`);
+    try {
+      if (expectations.length > 0) {
+        try {
+          observeData = await withTimeout(
+            budget.observeMaxMs,
+            observeExpectations(
+              expectations,
+              resolvedUrl,
+              paths.evidenceDir,
+              (progress) => {
+                events.emit(progress.event, progress);
+                if (!json && progress.event === 'observe:result') {
+                  const status = progress.observed ? '✓' : '✗';
+                  console.log(`  ${status} ${progress.index}/${expectations.length}`);
+                }
+              }
+            ),
+            'Observe'
+          );
+          
+          if (!json) {
+            console.log(`Observed: ${observeData.stats.observed}/${expectations.length}`);
+          }
+        } catch (error) {
+          if (error.message.includes('timeout')) {
+            if (!json) {
+              console.error(`Observe error: timeout after ${budget.observeMaxMs}ms`);
+            }
+            events.emit('observe:error', {
+              message: `Observe phase timeout: ${budget.observeMaxMs}ms`,
+            });
+            observeData = {
+              observations: [],
+              stats: { attempted: 0, observed: 0, notObserved: 0 },
+              observedAt: new Date().toISOString(),
+            };
+          } else {
+            if (!json) {
+              console.error(`Observe error: ${error.message}`);
             }
+            events.emit('observe:error', {
+              message: error.message,
+            });
+            observeData = {
+              observations: [],
+              stats: { attempted: 0, observed: 0, notObserved: 0 },
+              observedAt: new Date().toISOString(),
+            };
           }
-        );
-        
-        if (!json) {
-          console.log(`Observed: ${observeData.stats.observed}/${expectations.length}`);
-        }
-      } catch (error) {
-        if (!json) {
-          console.error(`Observe error: ${error.message}`);
         }
-        events.emit('observe:error', {
-          message: error.message,
-        });
+      } else {
         observeData = {
           observations: [],
           stats: { attempted: 0, observed: 0, notObserved: 0 },
           observedAt: new Date().toISOString(),
         };
       }
-    } else {
-      observeData = {
-        observations: [],
-        stats: { attempted: 0, observed: 0, notObserved: 0 },
-        observedAt: new Date().toISOString(),
-      };
+    } finally {
+      events.stopHeartbeat();
     }
     
     events.emit('phase:completed', {
@@ -312,47 +449,71 @@ export async function defaultCommand(options = {}) {
       message: 'Browser observation complete',
     });
     
-      // Detect phase
+      // Detect phase with timeout
       events.emit('phase:started', {
         phase: 'Detect',
         message: 'Analyzing findings and detecting silent failures...',
       });
     
+      events.startHeartbeat('Detect', json);
+    
       // Load learn and observe data for detection
       let learnData = { expectations: [] };
       let detectData = null;
     
       try {
-        learnData = {
-          expectations,
-          skipped,
-        };
-      
-        detectData = await detectFindings(learnData, observeData, projectRoot, (progress) => {
-          events.emit(progress.event, progress);
-          if (!json && progress.event === 'detect:classified') {
-            const symbol = progress.classification === 'silent-failure' ? '✗' :
-                          progress.classification === 'observed' ? '✓' :
-                          progress.classification === 'coverage-gap' ? '⊘' : '⚠';
-            console.log(`  ${symbol} ${progress.index}/${learnData.expectations.length}`);
+        try {
+          learnData = {
+            expectations,
+            skipped,
+          };
+        
+          detectData = await withTimeout(
+            budget.detectMaxMs,
+            detectFindings(learnData, observeData, projectRoot, (progress) => {
+              events.emit(progress.event, progress);
+              if (!json && progress.event === 'detect:classified') {
+                const symbol = progress.classification === 'silent-failure' ? '✗' :
+                              progress.classification === 'observed' ? '✓' :
+                              progress.classification === 'coverage-gap' ? '⊘' : '⚠';
+                console.log(`  ${symbol} ${progress.index}/${learnData.expectations.length}`);
+              }
+            }),
+            'Detect'
+          );
+          
+          if (!json && detectData.stats.silentFailures > 0) {
+            console.log(`Silent failures detected: ${detectData.stats.silentFailures}`);
+          }
+        } catch (error) {
+          if (error.message.includes('timeout')) {
+            if (!json) {
+              console.error(`Detect error: timeout after ${budget.detectMaxMs}ms`);
+            }
+            events.emit('detect:error', {
+              message: `Detect phase timeout: ${budget.detectMaxMs}ms`,
+            });
+            detectData = {
+              findings: [],
+              stats: { total: 0, silentFailures: 0, observed: 0, coverageGaps: 0, unproven: 0, informational: 0 },
+              detectedAt: new Date().toISOString(),
+            };
+          } else {
+            if (!json) {
+              console.error(`Detect error: ${error.message}`);
+            }
+            events.emit('detect:error', {
+              message: error.message,
+            });
+            detectData = {
+              findings: [],
+              stats: { total: 0, silentFailures: 0, observed: 0, coverageGaps: 0, unproven: 0, informational: 0 },
+              detectedAt: new Date().toISOString(),
+            };
           }
-        });
-      
-        if (!json && detectData.stats.silentFailures > 0) {
-          console.log(`Silent failures detected: ${detectData.stats.silentFailures}`);
-        }
-      } catch (error) {
-        if (!json) {
-          console.error(`Detect error: ${error.message}`);
         }
-        events.emit('detect:error', {
-          message: error.message,
-        });
-        detectData = {
-          findings: [],
-          stats: { total: 0, silentFailures: 0, observed: 0, coverageGaps: 0, unproven: 0, informational: 0 },
-          detectedAt: new Date().toISOString(),
-        };
+      } finally {
+        events.stopHeartbeat();
       }
     
       events.emit('phase:completed', {
@@ -360,12 +521,20 @@ export async function defaultCommand(options = {}) {
         message: 'Silent failure detection complete',
       });
     
+    // Clear watchdog timer on successful completion
+    if (watchdogTimer) {
+      clearTimeout(watchdogTimer);
+      watchdogTimer = null;
+    }
+    
     // Finalize Artifacts
     events.emit('phase:started', {
       phase: 'Finalize Artifacts',
       message: 'Writing run results...',
     });
     
+    events.stopHeartbeat();
+    
     const completedAt = new Date().toISOString();
     
     atomicWriteJson(paths.runStatusJson, {
@@ -411,30 +580,11 @@ export async function defaultCommand(options = {}) {
     // Write detect results (or empty if detection failed)
     writeFindingsJson(paths.baseDir, detectData);
     
-    const traces = [
-      {
-        type: 'phase:started',
-        timestamp: startedAt,
-        phase: 'Detect Project',
-      },
-      {
-        type: 'phase:completed',
-        timestamp: new Date().toISOString(),
-        phase: 'Detect Project',
-      },
-      {
-        type: 'phase:started',
-        timestamp: new Date().toISOString(),
-        phase: 'Learn',
-      },
-      {
-        type: 'phase:completed',
-        timestamp: completedAt,
-        phase: 'Learn',
-      },
-    ];
-    
-    const tracesContent = traces.map(t => JSON.stringify(t)).join('\n') + '\n';
+    // Write traces (include all events including heartbeats)
+    const allEvents = events.getEvents();
+    const tracesContent = allEvents
+      .map(e => JSON.stringify(e))
+      .join('\n') + '\n';
     atomicWriteText(paths.tracesJsonl, tracesContent);
     
     // Write project profile
@@ -460,8 +610,16 @@ export async function defaultCommand(options = {}) {
     
     return { runId, paths, url: resolvedUrl, success: true };
   } catch (error) {
+    // Clear watchdog timer on error
+    if (watchdogTimer) {
+      clearTimeout(watchdogTimer);
+      watchdogTimer = null;
+    }
+    
+    events.stopHeartbeat();
+    
     // Mark run as FAILED if we have paths
-    if (paths && runId && startedAt) {
+    if (paths && runId && startedAt && typeof paths === 'object') {
       try {
         const failedAt = new Date().toISOString();
         atomicWriteJson(paths.runStatusJson, {

package/src/cli/commands/doctor.js

@@ -92,11 +92,26 @@ export async function doctorCommand(options = {}) {
 
   // 4) Headless launch smoke test
   if (playwright && playwright.chromium && chromiumPath && existsSync(chromiumPath)) {
+    /** @type {any} */
+    let browser = null;
     try {
-      const browser = await playwright.chromium.launch({ headless: true });
-      const page = await browser.newPage();
-      await page.goto('about:blank');
-      await browser.close();
+      // Configurable timeout via env (default 5000ms, CI can override to 3000ms)
+      const smokeTimeoutMs = parseInt(process.env.VERAX_DOCTOR_SMOKE_TIMEOUT_MS || '5000', 10);
+      
+      // Wrap entire smoke test in hard timeout
+      const smokeTestPromise = (async () => {
+        browser = await playwright.chromium.launch({ headless: true, timeout: smokeTimeoutMs });
+        const page = await browser.newPage();
+        await page.goto('about:blank', { timeout: smokeTimeoutMs });
+        return true;
+      })();
+      
+      // Race against timeout
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Smoke test timed out')), smokeTimeoutMs);
+      });
+      
+      await Promise.race([smokeTestPromise, timeoutPromise]);
       addCheck('Headless smoke test', 'pass', 'Chromium launched headless and closed successfully');
     } catch (error) {
       addCheck(
@@ -107,6 +122,23 @@ export async function doctorCommand(options = {}) {
           ? 'Try: npx playwright install --with-deps chromium && launch with --no-sandbox in constrained environments'
           : 'Reinstall playwright: npx playwright install --with-deps chromium'
       );
+    } finally {
+      // CRITICAL: Always close browser to prevent hanging processes
+      // Bound close operation too (max 2s)
+      if (browser) {
+        try {
+          const closePromise = browser.close();
+          const closeTimeout = new Promise((resolve) => setTimeout(resolve, 2000));
+          await Promise.race([closePromise, closeTimeout]);
+        } catch (closeError) {
+          // Ignore close errors - force kill if needed
+          try {
+            await browser.close();
+          } catch {
+            // Final attempt failed, process will clean up
+          }
+        }
+      }
     }
   } else {
     addCheck(