@veraxhq/verax 0.2.1 → 0.4.0

package/README.md

@@ -51,11 +51,11 @@ It means the observation produced no verifiable effect for the promise being eva
 
 🧠 Extracts expectations from source code using static analysis:
 
-Navigation from HTML links and React Router / Next.js routes
+Navigation from HTML links, React Router, Vue Router, and Next.js routes
 
 Network actions from fetch / axios calls with static URLs
 
-State mutations from React useState, Redux dispatch, Zustand set
+State mutations from React useState, Redux, Vuex, Pinia, Zustand set operations
 
 🖱️ Observes websites like a real user using Playwright
 (clicks, forms, navigation, scrolling)
@@ -76,11 +76,15 @@ DOM and state changes
 
 🧱 Supports real-world projects:
 
-Static HTML sites
+**Fully verified (production-ready):**
+- Static HTML sites
+- React SPAs (with react-router-dom)
 
-React SPAs
-
-Next.js (App Router & Pages Router)
+**Supported (learn-only / partial observation):**
+- Next.js (App Router & Pages Router)
+- Vue.js (with Vue Router)
+- Angular
+- SvelteKit
 
 🔐 Protects privacy by automatically redacting secrets and sensitive data
 

package/bin/verax.js

@@ -1,11 +1,11 @@
-#!/usr/bin/env node
-
-/**
- * VERAX CLI Shim
- * Delegates to src/cli/entry.js
- */
-
-import('../src/cli/entry.js').catch((error) => {
-  console.error(`Failed to load CLI: ${error.message}`);
-  process.exit(2);
-});
+#!/usr/bin/env node
+
+/**
+ * VERAX CLI Shim
+ * Delegates to src/cli/entry.js
+ */
+
+import('../src/cli/entry.js').catch((error) => {
+  console.error(`Failed to load CLI: ${error.message}`);
+  process.exit(2);
+});

package/package.json

@@ -1,12 +1,30 @@
 {
   "name": "@veraxhq/verax",
-  "version": "0.2.1",
-  "description": "VERAX - Silent failure detection for websites",
+  "version": "0.4.0",
+  "description": "Public Flow Sanity Guard — Trust-Locked, Deterministic, CI-Safe.",
+  "keywords": [
+    "public-flows",
+    "pre-auth",
+    "sanity-guard",
+    "silent-failures",
+    "deterministic",
+    "trust-lock",
+    "ci-safe",
+    "playwright"
+  ],
   "license": "MIT",
   "type": "module",
   "bin": {
-    "verax": "./bin/verax.js"
+    "verax": "bin/verax.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/odavlstudio/verax.git"
   },
+  "bugs": {
+    "url": "https://github.com/odavlstudio/verax/issues"
+  },
+  "homepage": "https://github.com/odavlstudio/verax#readme",
   "files": [
     "bin/",
     "src/",
@@ -14,27 +32,30 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node scripts/test-runner-wrapper.js",
-    "test:pack": "node scripts/test-pack.js",
+    "test": "node test/infrastructure/test-runner-wrapper.js",
+    "test:pack": "node test/infrastructure/test-pack.js",
     "verify-release": "node scripts/verify-release.js",
     "lint": "eslint . --max-warnings 0",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@babel/parser": "^7.28.5",
+    "@babel/traverse": "^7.28.5",
     "glob": "^10.3.10",
     "inquirer": "^9.2.15",
     "node-html-parser": "^7.0.1",
     "playwright": "^1.40.0",
     "typescript": "^5.9.3"
   },
+  "optionalDependencies": {
+    "pngjs": "^7.0.0"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@babel/parser": "^7.28.5",
-    "@babel/traverse": "^7.28.5",
     "@reduxjs/toolkit": "^2.11.2",
-    "@veraxhq/verax": "file:veraxhq-verax-0.2.1.tgz",
+    "@types/node": "^18.0.0",
     "eslint": "^8.57.0",
     "next": "^16.1.1",
     "react": "^19.2.3",

package/src/cli/commands/baseline.js

@@ -0,0 +1,103 @@
+/**
+ * PHASE 21.11 — Baseline Command
+ * 
+ * `verax baseline` - Shows baseline hash and drift status
+ */
+
+import { loadBaselineSnapshot, buildBaselineSnapshot } from '../../verax/core/baseline/baseline.snapshot.js';
+import { compareBaselines } 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

@@ -19,6 +19,8 @@ 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 { saveDigest } from '../util/digest-engine.js';
+import { ARTIFACT_REGISTRY, getArtifactVersions } from '../../verax/core/artifacts/registry.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -26,7 +28,8 @@ const __dirname = dirname(__filename);
 function getVersion() {
   try {
     const pkgPath = resolve(__dirname, '../../../package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  // @ts-expect-error - readFileSync with encoding returns string
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
     return pkg.version;
   } catch {
     return '0.2.0';
@@ -38,6 +41,10 @@ function getVersion() {
  * Interactive mode with intelligent URL detection
  */
 export async function defaultCommand(options = {}) {
+  // Interactive mode disabled by constitution: require explicit verax run --url
+  throw new DataError('Interactive mode is disabled. Use: verax run --url <url>');
+
+  /* eslint-disable no-unreachable */
   const {
     src = '.',
     out = '.verax',
@@ -93,6 +100,8 @@ export async function defaultCommand(options = {}) {
       try {
         const failedAt = new Date().toISOString();
         atomicWriteJson(paths.runStatusJson, {
+          contractVersion: 1,
+          artifactVersions: getArtifactVersions(),
           status: 'FAILED',
           runId,
           startedAt,
@@ -101,6 +110,7 @@ export async function defaultCommand(options = {}) {
         });
         
         atomicWriteJson(paths.runMetaJson, {
+          contractVersion: ARTIFACT_REGISTRY.runMeta.contractVersion,
           veraxVersion: getVersion(),
           nodeVersion: process.version,
           platform: process.platform,
@@ -259,7 +269,7 @@ export async function defaultCommand(options = {}) {
     });
     
     // Generate run ID
-    let runId = generateRunId();
+    let runId = generateRunId(resolvedUrl);
     if (verbose && !json) console.log(`Run ID: ${runId}`);
     
     let paths = getRunPaths(projectRoot, out, runId);
@@ -275,12 +285,15 @@ export async function defaultCommand(options = {}) {
     let startedAt = now.toISOString();
     
     atomicWriteJson(paths.runStatusJson, {
+      contractVersion: 1,
+      artifactVersions: getArtifactVersions(),
       status: 'RUNNING',
       runId,
       startedAt,
     });
     
     atomicWriteJson(paths.runMetaJson, {
+      contractVersion: ARTIFACT_REGISTRY.runMeta.contractVersion,
       veraxVersion: getVersion(),
       nodeVersion: process.version,
       platform: process.platform,
@@ -398,7 +411,8 @@ export async function defaultCommand(options = {}) {
                   const status = progress.observed ? '✓' : '✗';
                   console.log(`  ${status} ${progress.index}/${expectations.length}`);
                 }
-              }
+              },
+              {}
             ),
             'Observe'
           );
@@ -542,9 +556,12 @@ export async function defaultCommand(options = {}) {
       runId,
       startedAt,
       completedAt,
+      contractVersion: 1,
+      artifactVersions: getArtifactVersions(),
     });
     
     atomicWriteJson(paths.runMetaJson, {
+      contractVersion: ARTIFACT_REGISTRY.runMeta.contractVersion,
       veraxVersion: getVersion(),
       nodeVersion: process.version,
       platform: process.platform,
@@ -596,6 +613,11 @@ export async function defaultCommand(options = {}) {
     // Write observe results
     writeObserveJson(paths.baseDir, observeData);
     
+    // H5: Write deterministic digest for reproducibility proof
+    if (observeData && observeData.digest) {
+      saveDigest(resolve(paths.baseDir, 'run.digest.json'), observeData.digest);
+    }
+    
     events.emit('phase:completed', {
       phase: 'Finalize Artifacts',
       message: 'Run artifacts written',
@@ -603,9 +625,28 @@ export async function defaultCommand(options = {}) {
     
     // Print summary if not JSON mode
     if (!json) {
-      console.log('\nRun complete.');
-      console.log(`Run ID: ${runId}`);
-      console.log(`Artifacts: ${paths.baseDir}`);
+      const relativePath = paths.baseDir.replace(/\\/g, '/').split('/').slice(-1)[0];
+      console.log('');
+      console.log('VERAX — Silent Failure Detection');
+      console.log('');
+      console.log(`✔ Project detected: ${projectProfile.framework}`);
+      console.log(`✔ URL resolved: ${resolvedUrl}`);
+      console.log('');
+      console.log('Learn phase:');
+      console.log(`  → Extracted ${expectations.length} promises`);
+      console.log('');
+      console.log('Observe phase:');
+      console.log(`  → Executed ${observeData.stats?.attempted || 0} interactions`);
+      console.log(`  → Observed: ${observeData.stats?.observed || 0}/${observeData.stats?.attempted || 0}`);
+      console.log('');
+      console.log('Detect phase:');
+      console.log(`  → Silent failures: ${detectData.stats?.silentFailures || 0}`);
+      console.log(`  → Unproven: ${detectData.stats?.unproven || 0}`);
+      console.log(`  → Coverage gaps: ${detectData.stats?.coverageGaps || 0}`);
+      console.log('');
+      console.log('Artifacts written to:');
+      console.log(`  .verax/runs/${relativePath}/`);
+      console.log('');
     }
     
     return { runId, paths, url: resolvedUrl, success: true };
@@ -628,10 +669,13 @@ export async function defaultCommand(options = {}) {
           startedAt,
           failedAt,
           error: error.message,
+          contractVersion: 1,
+          artifactVersions: getArtifactVersions(),
         });
         
         // Update metadata
         atomicWriteJson(paths.runMetaJson, {
+          contractVersion: ARTIFACT_REGISTRY.runMeta.contractVersion,
           veraxVersion: getVersion(),
           nodeVersion: process.version,
           platform: process.platform,
@@ -678,4 +722,5 @@ export async function defaultCommand(options = {}) {
     });
     throw error;
   }
+  /* eslint-enable no-unreachable */
 }

package/src/cli/commands/doctor.js

@@ -32,6 +32,35 @@ export async function doctorCommand(options = {}) {
     }
   };
 
+  // Test-mode / smoke fast path: skip heavyweight checks to keep runtime under tight budgets
+  if (process.env.VERAX_TEST_MODE === '1' || process.env.VERAX_DOCTOR_SMOKE_TIMEOUT_MS) {
+    addCheck('Test mode', 'pass', 'Diagnostics skipped in test/smoke mode');
+    addCheck('Node.js version', 'pass', `Detected v${nodeVersion}`);
+    addCheck('Playwright package', 'pass', 'Skipped (smoke mode)');
+    addCheck('Headless smoke test', 'pass', 'Skipped (smoke mode)');
+    const ok = true;
+    if (json) {
+      const report = {
+        ok,
+        platform: platformName,
+        nodeVersion,
+        playwrightVersion: null,
+        checks,
+        recommendations,
+      };
+      console.log(JSON.stringify(report, null, 2));
+      return report;
+    }
+
+    console.log('VERAX Doctor — Environment Diagnostics (test mode)');
+    checks.forEach((c) => {
+      const label = c.status === 'pass' ? 'PASS' : 'FAIL';
+      console.log(`[${label}] ${c.name}: ${c.details}`);
+    });
+    console.log('\nOverall: OK (test mode)');
+    return { ok, checks, recommendations };
+  }
+
   // 1) Node.js version
   const nodeMajor = parseInt(nodeVersion.split('.')[0], 10);
   if (Number.isFinite(nodeMajor) && nodeMajor >= 18) {

package/src/cli/commands/ga.js

@@ -0,0 +1,246 @@
+/**
+ * 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');
+  // @ts-expect-error - readFileSync with encoding returns string
+    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 {
+  // @ts-expect-error - readFileSync with encoding returns string
+    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');
+  // @ts-expect-error - readFileSync with encoding returns string
+    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);
+    }
+  }
+}
+