@veraxhq/verax 0.2.0 → 0.3.0

package/src/cli/commands/default.js

@@ -3,7 +3,8 @@ 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 { assertExecutionBootstrapAllowed } from '../util/bootstrap-guard.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 +19,8 @@ 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';
+import { assertHasLocalSource } from '../util/source-requirement.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -28,7 +31,7 @@ function getVersion() {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
     return pkg.version;
   } catch {
-    return '0.2.0';
+    return '0.3.0';
   }
 }
 
@@ -43,6 +46,8 @@ export async function defaultCommand(options = {}) {
     url = null,
     json = false,
     verbose = false,
+    determinism = false,
+    determinismRuns = 2,
   } = options;
   
   const projectRoot = resolve(process.cwd());
@@ -52,6 +57,9 @@ export async function defaultCommand(options = {}) {
   if (!existsSync(srcPath)) {
     throw new DataError(`Source directory not found: ${srcPath}`);
   }
+
+  // Enforce local source availability (no URL-only scans)
+  assertHasLocalSource(srcPath);
   
   // Create event emitter
   const events = new RunEventEmitter();
@@ -72,6 +80,83 @@ 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, {
+          contractVersion: 1,
+          artifactVersions: paths.artifactVersions,
+          status: 'FAILED',
+          runId,
+          startedAt,
+          failedAt,
+          error: reason,
+        });
+        
+        atomicWriteJson(paths.runMetaJson, {
+          contractVersion: 1,
+          artifactVersions: paths.artifactVersions,
+          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',
@@ -155,6 +240,9 @@ export async function defaultCommand(options = {}) {
         console.log(''); // blank line
       }
       
+      // PHASE 21.6.1: Runtime guard - crash if called during inspection
+      assertExecutionBootstrapAllowed('inquirer.prompt');
+      
       const answer = await inquirer.prompt([
         {
           type: 'input',
@@ -201,12 +289,16 @@ export async function defaultCommand(options = {}) {
     let startedAt = now.toISOString();
     
     atomicWriteJson(paths.runStatusJson, {
+      contractVersion: 1,
+      artifactVersions: paths.artifactVersions,
       status: 'RUNNING',
       runId,
       startedAt,
     });
     
     atomicWriteJson(paths.runMetaJson, {
+      contractVersion: 1,
+      artifactVersions: paths.artifactVersions,
       veraxVersion: getVersion(),
       nodeVersion: process.version,
       platform: process.platform,
@@ -231,8 +323,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 +357,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 +467,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,35 +539,25 @@ 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...',
     });
     
-    const completedAt = new Date().toISOString();
-    
-    atomicWriteJson(paths.runStatusJson, {
-      status: 'COMPLETE',
-      runId,
-      startedAt,
-      completedAt,
-    });
+    events.stopHeartbeat();
     
-    atomicWriteJson(paths.runMetaJson, {
-      veraxVersion: getVersion(),
-      nodeVersion: process.version,
-      platform: process.platform,
-      cwd: projectRoot,
-      command: 'default',
-      args: { url: resolvedUrl, src },
-      url: resolvedUrl,
-      src: srcPath,
-      startedAt,
-      completedAt,
-      error: null,
-    });
+    const completedAt = new Date().toISOString();
     
+    // Write detect results (or empty if detection failed)
+    const findingsResult = writeFindingsJson(paths.baseDir, detectData);
+
     // Write summary with stable digest
     writeSummaryJson(paths.summaryJson, {
       runId,
@@ -408,33 +577,11 @@ export async function defaultCommand(options = {}) {
       informational: detectData.stats?.informational || 0,
     });
     
-    // 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
@@ -445,6 +592,53 @@ export async function defaultCommand(options = {}) {
     
     // Write observe results
     writeObserveJson(paths.baseDir, observeData);
+
+    // PHASE 6: Verify artifacts after all writers finish
+    const { verifyRun } = await import('../../verax/core/artifacts/verifier.js');
+    const verification = verifyRun(paths.baseDir, paths.artifactVersions);
+    
+    // Determine final status based on verification
+    let finalStatus = 'COMPLETE';
+    if (!verification.ok) {
+      finalStatus = 'INVALID';
+    } else if (verification.warnings.length > 0) {
+      finalStatus = 'VALID_WITH_WARNINGS';
+    }
+    
+    // Write completed status with contract + enforcement snapshot + verification
+    atomicWriteJson(paths.runStatusJson, {
+      contractVersion: 1,
+      artifactVersions: paths.artifactVersions,
+      status: finalStatus,
+      runId,
+      startedAt,
+      completedAt,
+      enforcement: findingsResult?.payload?.enforcement || null,
+      verification: {
+        ok: verification.ok,
+        status: finalStatus,
+        errorsCount: verification.errors.length,
+        warningsCount: verification.warnings.length,
+        verifiedAt: verification.verifiedAt
+      }
+    });
+    
+    // Update metadata with completion time
+    atomicWriteJson(paths.runMetaJson, {
+      contractVersion: 1,
+      artifactVersions: paths.artifactVersions,
+      veraxVersion: getVersion(),
+      nodeVersion: process.version,
+      platform: process.platform,
+      cwd: projectRoot,
+      command: 'default',
+      args: { url: resolvedUrl, src },
+      url: resolvedUrl,
+      src: srcPath,
+      startedAt,
+      completedAt,
+      error: null,
+    });
     
     events.emit('phase:completed', {
       phase: 'Finalize Artifacts',
@@ -456,15 +650,31 @@ export async function defaultCommand(options = {}) {
       console.log('\nRun complete.');
       console.log(`Run ID: ${runId}`);
       console.log(`Artifacts: ${paths.baseDir}`);
+      
+      // PHASE 6: Display verification results
+      const { formatVerificationOutput } = await import('../../verax/core/artifacts/verifier.js');
+      const verificationOutput = formatVerificationOutput(verification, verbose);
+      console.log('');
+      console.log(verificationOutput);
     }
     
     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, {
+          contractVersion: 1,
+          artifactVersions: paths.artifactVersions,
           status: 'FAILED',
           runId,
           startedAt,
@@ -474,6 +684,8 @@ export async function defaultCommand(options = {}) {
         
         // Update metadata
         atomicWriteJson(paths.runMetaJson, {
+          contractVersion: 1,
+          artifactVersions: paths.artifactVersions,
           veraxVersion: getVersion(),
           nodeVersion: process.version,
           platform: process.platform,

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(