@veraxhq/verax 0.2.1 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # 🛡️ VERAX
 
+> **SOURCE CODE REQUIRED** — VERAX requires local access to source code. It is not a public website scanner. See [docs/README.md](docs/README.md) for the canonical product contract.
+
 A forensic observation engine for real user outcomes
 
 VERAX observes and reports gaps between what your code explicitly promises and what users can actually observe.
@@ -229,27 +231,21 @@ MEDIUM (60–79) — likely discrepancy with some ambiguity
 
 LOW (<60) — weak or partial evidence; interpret cautiously
 
-🧭 When VERAX is a good fit
-
-SaaS signup and pricing flows
-
-React and Next.js projects
-
-CI pipelines that need UX reality checks
-
-Teams that value evidence over assumptions
-
-🚫 When VERAX is NOT a good fit
-
-Internal admin dashboards
-
-Authentication-heavy systems
+🧭 Supported use cases
 
-Apps built around highly dynamic routing
+- React, Next.js, or static HTML projects where you can provide local source code
+- CI pipelines that can mount the repository so VERAX can analyze it
+- Developer workstations that need evidence-backed silent failure detection
+- Teams that value deterministic evidence over heuristics or AI guesses
+- Demo projects in this repo (see [demos/](demos/))
 
-Unsupported frameworks
+🚫 Not supported
 
-Teams expecting a full QA replacement
+- URL-only scans without source code (fails fast with guidance)
+- Production monitoring or hosted/public scanning
+- Highly dynamic routing without static promises to analyze
+- Closed-source third-party targets where code is unavailable
+- Using VERAX as a drop-in QA replacement
 
 🧪 Project status
 

package/bin/verax.js

@@ -2,10 +2,17 @@
 
 /**
  * VERAX CLI Shim
+ * PHASE 21.6.1: Verified entry point
  * Delegates to src/cli/entry.js
+ * 
+ * This file MUST be the only entry point for the verax CLI.
+ * package.json "bin" field points to this file.
  */
 
 import('../src/cli/entry.js').catch((error) => {
   console.error(`Failed to load CLI: ${error.message}`);
+  if (error.stack) {
+    console.error(error.stack);
+  }
   process.exit(2);
 });

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@veraxhq/verax",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "VERAX - Silent failure detection for websites",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "verax": "./bin/verax.js"
+    "verax": "bin/verax.js"
   },
   "files": [
     "bin/",
@@ -34,7 +34,7 @@
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
     "@reduxjs/toolkit": "^2.11.2",
-    "@veraxhq/verax": "file:veraxhq-verax-0.2.1.tgz",
+    "@veraxhq/verax": "file:veraxhq-verax-0.3.0.tgz",
     "eslint": "^8.57.0",
     "next": "^16.1.1",
     "react": "^19.2.3",

package/src/cli/commands/baseline.js

@@ -0,0 +1,104 @@
+/**
+ * PHASE 21.11 — Baseline Command
+ * 
+ * `verax baseline` - Shows baseline hash and drift status
+ */
+
+import { resolve } from 'path';
+import { loadBaselineSnapshot, buildBaselineSnapshot } from '../../verax/core/baseline/baseline.snapshot.js';
+import { compareBaselines, isBaselineFrozen } from '../../verax/core/baseline/baseline.enforcer.js';
+
+/**
+ * Baseline command
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {Object} options - Command options
+ */
+export async function baselineCommand(projectDir, options = {}) {
+  const { json = false } = options;
+  
+  const frozen = loadBaselineSnapshot(projectDir);
+  const current = buildBaselineSnapshot(projectDir);
+  
+  if (!frozen) {
+    if (json) {
+      console.log(JSON.stringify({
+        status: 'NO_BASELINE',
+        message: 'No baseline snapshot found (pre-GA)',
+        current: {
+          hash: current.baselineHash,
+          version: current.veraxVersion,
+          commit: current.gitCommit
+        }
+      }, null, 2));
+    } else {
+      console.log('\n=== Baseline Status ===\n');
+      console.log('Status: NO_BASELINE (pre-GA)');
+      console.log(`Current baseline hash: ${current.baselineHash}`);
+      console.log(`Version: ${current.veraxVersion}`);
+      console.log(`Commit: ${current.gitCommit}`);
+      console.log(`Dirty: ${current.gitDirty ? 'YES' : 'NO'}`);
+      console.log('\nNote: Baseline will be frozen when GA-READY is achieved.\n');
+    }
+    return;
+  }
+  
+  const comparison = compareBaselines(current, frozen);
+  const frozenStatus = frozen.frozen ? 'FROZEN' : 'NOT_FROZEN';
+  
+  if (json) {
+    console.log(JSON.stringify({
+      status: frozenStatus,
+      frozen: frozen.frozen,
+      drifted: comparison.drifted,
+      message: comparison.message,
+      frozenBaseline: {
+        hash: frozen.baselineHash,
+        version: frozen.veraxVersion,
+        commit: frozen.gitCommit,
+        timestamp: frozen.timestamp
+      },
+      currentBaseline: {
+        hash: current.baselineHash,
+        version: current.veraxVersion,
+        commit: current.gitCommit
+      },
+      differences: comparison.differences
+    }, null, 2));
+  } else {
+    console.log('\n=== Baseline Status ===\n');
+    console.log(`Status: ${frozenStatus}`);
+    console.log(`Frozen: ${frozen.frozen ? 'YES' : 'NO'}`);
+    console.log(`Drifted: ${comparison.drifted ? 'YES' : 'NO'}`);
+    console.log(`\nMessage: ${comparison.message}`);
+    
+    console.log('\nFrozen Baseline:');
+    console.log(`  Hash: ${frozen.baselineHash}`);
+    console.log(`  Version: ${frozen.veraxVersion}`);
+    console.log(`  Commit: ${frozen.gitCommit}`);
+    console.log(`  Timestamp: ${frozen.timestamp}`);
+    
+    console.log('\nCurrent Baseline:');
+    console.log(`  Hash: ${current.baselineHash}`);
+    console.log(`  Version: ${current.veraxVersion}`);
+    console.log(`  Commit: ${current.gitCommit}`);
+    console.log(`  Dirty: ${current.gitDirty ? 'YES' : 'NO'}`);
+    
+    if (comparison.drifted) {
+      console.log('\n⚠️  BASELINE DRIFT DETECTED:');
+      for (const diff of comparison.differences) {
+        console.log(`  - ${diff.message}`);
+        if (diff.component) {
+          console.log(`    Component: ${diff.component}`);
+        }
+      }
+      console.log('\n⚠️  Changes to core contracts/policies after GA require:');
+      console.log('    1. MAJOR version bump');
+      console.log('    2. Baseline regeneration');
+      console.log('    3. GA re-evaluation\n');
+    } else {
+      console.log('\n✓ Baseline integrity maintained\n');
+    }
+  }
+}
+

package/src/cli/commands/default.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import inquirer from 'inquirer';
+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';
@@ -19,6 +20,7 @@ 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);
@@ -29,7 +31,7 @@ function getVersion() {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
     return pkg.version;
   } catch {
-    return '0.2.0';
+    return '0.3.0';
   }
 }
 
@@ -44,6 +46,8 @@ export async function defaultCommand(options = {}) {
     url = null,
     json = false,
     verbose = false,
+    determinism = false,
+    determinismRuns = 2,
   } = options;
   
   const projectRoot = resolve(process.cwd());
@@ -53,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();
@@ -93,6 +100,8 @@ export async function defaultCommand(options = {}) {
       try {
         const failedAt = new Date().toISOString();
         atomicWriteJson(paths.runStatusJson, {
+          contractVersion: 1,
+          artifactVersions: paths.artifactVersions,
           status: 'FAILED',
           runId,
           startedAt,
@@ -101,6 +110,8 @@ export async function defaultCommand(options = {}) {
         });
         
         atomicWriteJson(paths.runMetaJson, {
+          contractVersion: 1,
+          artifactVersions: paths.artifactVersions,
           veraxVersion: getVersion(),
           nodeVersion: process.version,
           platform: process.platform,
@@ -229,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',
@@ -275,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,
@@ -537,27 +555,9 @@ export async function defaultCommand(options = {}) {
     
     const completedAt = new Date().toISOString();
     
-    atomicWriteJson(paths.runStatusJson, {
-      status: 'COMPLETE',
-      runId,
-      startedAt,
-      completedAt,
-    });
-    
-    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,
-    });
-    
+    // Write detect results (or empty if detection failed)
+    const findingsResult = writeFindingsJson(paths.baseDir, detectData);
+
     // Write summary with stable digest
     writeSummaryJson(paths.summaryJson, {
       runId,
@@ -577,9 +577,6 @@ export async function defaultCommand(options = {}) {
       informational: detectData.stats?.informational || 0,
     });
     
-    // Write detect results (or empty if detection failed)
-    writeFindingsJson(paths.baseDir, detectData);
-    
     // Write traces (include all events including heartbeats)
     const allEvents = events.getEvents();
     const tracesContent = allEvents
@@ -595,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',
@@ -606,6 +650,12 @@ 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 };
@@ -623,6 +673,8 @@ export async function defaultCommand(options = {}) {
       try {
         const failedAt = new Date().toISOString();
         atomicWriteJson(paths.runStatusJson, {
+          contractVersion: 1,
+          artifactVersions: paths.artifactVersions,
           status: 'FAILED',
           runId,
           startedAt,
@@ -632,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/ga.js

@@ -0,0 +1,243 @@
+/**
+ * PHASE 21.6 — GA Readiness CLI Command
+ * 
+ * Pure inspection command. Evaluates GA readiness using existing artifacts only.
+ * No URL, no browser, no project execution.
+ */
+
+import { evaluateGAReadiness } from '../../verax/core/ga/ga.contract.js';
+import { writeGAStatus } from '../../verax/core/ga/ga.artifact.js';
+import { writeGAReport } from '../../verax/core/ga/ga-report-writer.js';
+import { GA_BLOCKER_CODE } from '../../verax/core/ga/ga.contract.js';
+import { resolve } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { findLatestRunId, validateRunId } from '../util/run-resolver.js';
+import { UsageError } from '../util/errors.js';
+
+/**
+ * Load failure ledger summary
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Object|null} Failure ledger summary or null
+ */
+function loadFailureLedger(projectDir, runId) {
+  const ledgerPath = resolve(projectDir, '.verax', 'runs', runId, 'failure.ledger.json');
+  if (!existsSync(ledgerPath)) {
+    return null;
+  }
+  
+  try {
+    const content = readFileSync(ledgerPath, 'utf-8');
+    const ledger = JSON.parse(content);
+    return ledger.summary || null;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Load determinism verdict
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {Promise<string|null>} Determinism verdict or null
+ */
+async function loadDeterminismVerdict(projectDir, runId) {
+  const decisionsPath = resolve(projectDir, '.verax', 'runs', runId, 'decisions.json');
+  if (!existsSync(decisionsPath)) {
+    return null;
+  }
+  
+  try {
+    const decisions = JSON.parse(readFileSync(decisionsPath, 'utf-8'));
+    const { DecisionRecorder } = await import('../../verax/core/determinism-model.js');
+    const recorder = DecisionRecorder.fromExport(decisions);
+    const { computeDeterminismVerdict } = await import('../../verax/core/determinism/contract.js');
+    const verdict = computeDeterminismVerdict(recorder);
+    return verdict.verdict;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Check for Evidence Law violations
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {string} runId - Run ID
+ * @returns {boolean} Whether Evidence Law was violated
+ */
+function checkEvidenceLawViolations(projectDir, runId) {
+  const findingsPath = resolve(projectDir, '.verax', 'runs', runId, 'findings.json');
+  if (!existsSync(findingsPath)) {
+    return false;
+  }
+  
+  try {
+    const content = readFileSync(findingsPath, 'utf-8');
+    const findings = JSON.parse(content);
+    
+    if (!Array.isArray(findings.findings)) {
+      return false;
+    }
+    
+    // Check for CONFIRMED findings with incomplete evidence
+    for (const finding of findings.findings) {
+      if ((finding.severity === 'CONFIRMED' || finding.status === 'CONFIRMED') &&
+          finding.evidencePackage && !finding.evidencePackage.isComplete) {
+        return true;
+      }
+    }
+    
+    return false;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * PHASE 21.6.1: `verax ga` command
+ * 
+ * Pure inspection command. No URL, no browser, no execution.
+ * 
+ * @param {Object} options - Options
+ * @param {string} [options.runId] - Run ID (defaults to latest)
+ * @param {boolean} [options.json] - Output as JSON
+ */
+export async function gaCommand(options = {}) {
+  const { runId: providedRunId = null, json = false } = options;
+  
+  const projectDir = resolve(process.cwd());
+  
+  // Resolve run ID: use provided or find latest
+  let runId = providedRunId;
+  
+  if (!runId) {
+    // Find latest run
+    runId = findLatestRunId(projectDir);
+    
+    if (!runId) {
+      // No runs found - GA is BLOCKED
+      const gaResult = {
+        pass: false,
+        blockers: [{
+          code: GA_BLOCKER_CODE.NO_RUNS_FOUND || 'GA_NO_RUNS_FOUND',
+          message: 'No runs found in .verax/runs/. Run a scan first.',
+          context: {}
+        }],
+        warnings: [],
+        summary: {
+          pass: false,
+          blockersCount: 1,
+          warningsCount: 0,
+          checkedAt: new Date().toISOString()
+        },
+        inputs: {
+          gates: null,
+          determinism: null,
+          evidenceLaw: null,
+          failureLedger: null
+        }
+      };
+      
+      if (json) {
+        console.log(JSON.stringify({
+          gaReady: false,
+          blockers: gaResult.blockers,
+          warnings: [],
+          summary: gaResult.summary
+        }, null, 2));
+      } else {
+        console.log('\n' + '='.repeat(80));
+        console.log('GA READINESS EVALUATION');
+        console.log('='.repeat(80));
+        console.log('\nGA STATUS: ❌ BLOCKED');
+        console.log('\nBlockers:');
+        console.log('- No runs found in .verax/runs/. Run a scan first.');
+        console.log('='.repeat(80) + '\n');
+      }
+      
+      process.exit(4);
+      return;
+    }
+  } else {
+    // Validate provided run ID
+    if (!validateRunId(projectDir, runId)) {
+      const error = new UsageError(`Run ID not found: ${runId}`);
+      // UsageError already has exit code 64
+      throw error;
+    }
+  }
+  
+  // Load context from artifacts (pure filesystem reads)
+  const failureLedger = loadFailureLedger(projectDir, runId);
+  const determinismVerdict = await loadDeterminismVerdict(projectDir, runId);
+  const evidenceLawViolated = checkEvidenceLawViolations(projectDir, runId);
+  
+  // Evaluate GA readiness
+  const gaResult = await evaluateGAReadiness({
+    projectDir,
+    runId,
+    determinismVerdict,
+    evidenceLawViolated,
+    failureLedger
+  });
+  
+  // Write status artifact
+  const artifactPath = writeGAStatus(projectDir, runId, gaResult);
+  
+  // Write GA report
+  const reportPath = writeGAReport(projectDir, runId, gaResult);
+  
+  // Output
+  if (json) {
+    console.log(JSON.stringify({
+      gaReady: gaResult.pass,
+      blockers: gaResult.blockers,
+      warnings: gaResult.warnings,
+      summary: gaResult.summary,
+      artifactPath,
+      reportPath
+    }, null, 2));
+  } else {
+    console.log('\n' + '='.repeat(80));
+    console.log('GA READINESS EVALUATION');
+    console.log('='.repeat(80));
+    console.log(`\nGA STATUS: ${gaResult.pass ? '✅ READY' : '❌ BLOCKED'}`);
+    
+    if (gaResult.blockers.length > 0) {
+      console.log('\nBlockers:');
+      for (const blocker of gaResult.blockers) {
+        console.log(`- ${blocker.message}`);
+      }
+    }
+    
+    if (gaResult.warnings.length > 0) {
+      console.log('\nWarnings:');
+      for (const warning of gaResult.warnings) {
+        console.log(`- ${warning.message}`);
+      }
+    }
+    
+    console.log(`\nSee: ${artifactPath}`);
+    console.log(`Report: ${reportPath}`);
+    console.log('='.repeat(80) + '\n');
+  }
+  
+  // Exit codes: 0 = GA-READY, 2 = GA-BLOCKED, 70 = Internal corruption
+  if (!gaResult.pass) {
+    // Check if it's an internal corruption issue
+    const hasInternalBlocker = gaResult.blockers.some(b => 
+      b.code === 'GA_INTERNAL_FAILURES' || 
+      b.code === 'GA_CONTRACT_FAILURES'
+    );
+    
+    if (hasInternalBlocker) {
+      process.exit(70);
+    } else {
+      process.exit(2);
+    }
+  }
+}
+