@veraxhq/verax 0.2.1 → 0.3.0

package/src/cli/commands/truth.js

@@ -0,0 +1,114 @@
+/**
+ * PHASE 21.11 — Truth Command
+ * 
+ * `verax truth` - Shows truth certificate summary
+ */
+
+import { resolve } from 'path';
+import { findLatestRunId } from '../util/run-resolver.js';
+import { generateTruthCertificate, loadTruthCertificate } from '../../verax/core/truth/truth.certificate.js';
+
+/**
+ * Truth command
+ * 
+ * @param {string} projectDir - Project directory
+ * @param {Object} options - Command options
+ */
+export async function truthCommand(projectDir, options = {}) {
+  const { json = false, runId: runIdOpt = null } = options;
+  
+  const runId = runIdOpt || findLatestRunId(projectDir);
+  
+  if (!runId) {
+    if (json) {
+      console.log(JSON.stringify({
+        error: 'NO_RUNS_FOUND',
+        message: 'No runs found. Run a scan first.'
+      }, null, 2));
+    } else {
+      console.log('\n=== Truth Certificate ===\n');
+      console.log('Error: No runs found. Run a scan first.\n');
+    }
+    return;
+  }
+  
+  // Try to load existing certificate, otherwise generate
+  let certificate = loadTruthCertificate(projectDir, runId);
+  
+  if (!certificate) {
+    certificate = await generateTruthCertificate(projectDir, runId);
+    if (certificate) {
+      const { writeTruthCertificate } = await import('../../verax/core/truth/truth.certificate.js');
+      writeTruthCertificate(projectDir, runId, certificate);
+    }
+  }
+  
+  if (!certificate) {
+    if (json) {
+      console.log(JSON.stringify({
+        error: 'CERTIFICATE_GENERATION_FAILED',
+        message: 'Failed to generate truth certificate'
+      }, null, 2));
+    } else {
+      console.log('\n=== Truth Certificate ===\n');
+      console.log('Error: Failed to generate truth certificate\n');
+    }
+    return;
+  }
+  
+  if (json) {
+    console.log(JSON.stringify(certificate, null, 2));
+  } else {
+    console.log('\n=== Truth Certificate ===\n');
+    console.log(`Run ID: ${certificate.runId}`);
+    console.log(`URL: ${certificate.url || 'N/A'}`);
+    console.log(`Generated: ${certificate.generatedAt}`);
+    
+    console.log('\nEvidence Law:');
+    console.log(`  Status: ${certificate.evidenceLaw.status}`);
+    console.log(`  Violated: ${certificate.evidenceLaw.violated ? 'YES' : 'NO'}`);
+    
+    console.log('\nDeterminism:');
+    console.log(`  Verdict: ${certificate.determinism.verdict}`);
+    console.log(`  Message: ${certificate.determinism.message}`);
+    
+    console.log('\nFailures:');
+    console.log(`  Total: ${certificate.failures.total}`);
+    console.log(`  Blocking: ${certificate.failures.blocking ? 'YES' : 'NO'}`);
+    console.log(`  Degraded: ${certificate.failures.degraded ? 'YES' : 'NO'}`);
+    console.log(`  By Severity: ${JSON.stringify(certificate.failures.bySeverity)}`);
+    
+    console.log('\nGA:');
+    console.log(`  Verdict: ${certificate.ga.verdict}`);
+    console.log(`  Ready: ${certificate.ga.ready ? 'YES' : 'NO'}`);
+    console.log(`  Blockers: ${certificate.ga.blockers}`);
+    console.log(`  Warnings: ${certificate.ga.warnings}`);
+    
+    console.log('\nSecurity:');
+    console.log(`  Overall: ${certificate.security.overall}`);
+    console.log(`  Secrets: ${certificate.security.secrets}`);
+    console.log(`  Vulnerabilities: ${certificate.security.vulnerabilities}`);
+    
+    console.log('\nPerformance:');
+    console.log(`  Verdict: ${certificate.performance.verdict}`);
+    console.log(`  OK: ${certificate.performance.ok ? 'YES' : 'NO'}`);
+    console.log(`  Violations: ${certificate.performance.violations}`);
+    
+    console.log('\nBaseline:');
+    console.log(`  Hash: ${certificate.baseline.hash || 'N/A'}`);
+    console.log(`  Frozen: ${certificate.baseline.frozen ? 'YES' : 'NO'}`);
+    console.log(`  Version: ${certificate.baseline.version || 'N/A'}`);
+    
+    console.log('\nProvenance:');
+    console.log(`  Hash: ${certificate.provenance.hash || 'N/A'}`);
+    console.log(`  Version: ${certificate.provenance.version || 'N/A'}`);
+    
+    console.log('\nOverall Verdict:');
+    console.log(`  Status: ${certificate.overallVerdict.status}`);
+    if (certificate.overallVerdict.reasons.length > 0) {
+      console.log(`  Reasons: ${certificate.overallVerdict.reasons.join('; ')}`);
+    }
+    console.log('');
+  }
+}
+

package/src/cli/entry.js

@@ -3,6 +3,11 @@
 /**
  * VERAX CLI Entry Point
  * 
+ * PHASE 21.6.1: Two-Phase CLI Bootstrap
+ * 
+ * Phase A: Raw argv parsing with zero side effects
+ * Phase B: Dispatch - inspection commands bypass execution bootstrap
+ * 
  * Commands:
  * - verax                    (smart default with URL detection/prompting)
  * - verax run --url <url>    (strict, non-interactive)
@@ -22,11 +27,47 @@ import { defaultCommand } from './commands/default.js';
 import { runCommand } from './commands/run.js';
 import { inspectCommand } from './commands/inspect.js';
 import { doctorCommand } from './commands/doctor.js';
+import { gatesCommand } from './commands/gates.js';
+import { gaCommand } from './commands/ga.js';
+import { releaseCheckCommand } from './commands/release-check.js';
+import { securityCheckCommand } from './commands/security-check.js';
+import { baselineCommand } from './commands/baseline.js';
+import { truthCommand } from './commands/truth.js';
 import { getExitCode, UsageError } from './util/errors.js';
+import { getSourceCodeRequirementBanner } from '../verax/core/product-definition.js';
+import { enableInspectionMode, disableInspectionMode } from './util/bootstrap-guard.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+/**
+ * PHASE 21.6.1: CLI Self-Identification
+ * Prints diagnostic information to identify which binary is executed
+ */
+function printCLIIdentity(args) {
+  const verbose = args.includes('--verbose');
+  const debugCli = process.env.VERAX_DEBUG_CLI === '1';
+  
+  if (!verbose && !debugCli) {
+    return;
+  }
+  
+  console.error('=== VERAX CLI IDENTITY ===');
+  console.error(`process.argv[1]: ${process.argv[1]}`);
+  console.error(`__filename: ${__filename}`);
+  
+  try {
+    const pkgPath = resolve(__dirname, '../../package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    console.error(`package.json version: ${pkg.version}`);
+    console.error(`package.json location: ${pkgPath}`);
+  } catch (error) {
+    console.error(`Failed to read package.json: ${error.message}`);
+  }
+  
+  console.error('========================');
+}
+
 // Read package.json for version
 function getVersion() {
   try {
@@ -38,84 +79,263 @@ function getVersion() {
   }
 }
 
-async function main() {
-  const args = process.argv.slice(2);
+/**
+ * PHASE A: Raw argv parsing with zero side effects
+ * 
+ * @param {string[]} args - Raw command line arguments
+ * @returns {Object} Parsed command structure
+ */
+function parseCommand(args) {
+  // Handle --version (no side effects)
+  if (args.includes('--version') || args.includes('-v')) {
+    return { type: 'version' };
+  }
   
-  try {
-    // Handle --version
-    if (args.includes('--version') || args.includes('-v')) {
-      console.log(`verax ${getVersion()}`);
-      process.exit(0);
+  // Handle explicit --help (no side effects)
+  if (args.includes('--help') || args.includes('-h')) {
+    return { type: 'help' };
+  }
+  
+  // If no args, default to smart mode
+  if (args.length === 0) {
+    return { type: 'default', options: {} };
+  }
+  
+  const command = args[0];
+  
+  // Inspection commands (must bypass execution bootstrap)
+  if (command === 'inspect') {
+    if (args.length < 2) {
+      throw new UsageError('inspect command requires a run path argument');
     }
-    
-    // Handle explicit --help
-    if (args.includes('--help') || args.includes('-h')) {
-      showHelp();
-      process.exit(0);
+    return {
+      type: 'inspect',
+      runPath: args[1],
+      json: args.includes('--json'),
+      timeline: args.includes('--timeline'),
+      decisions: args.includes('--decisions'),
+      failures: args.includes('--failures'),
+      performance: args.includes('--performance'),
+      evidence: args.includes('--evidence')
+    };
+  }
+  
+  if (command === 'gates') {
+    return {
+      type: 'gates',
+      json: args.includes('--json'),
+      verbose: args.includes('--verbose')
+    };
+  }
+  
+  if (command === 'ga') {
+    return {
+      type: 'ga',
+      runId: parseArg(args, '--run-id'),
+      json: args.includes('--json')
+    };
+  }
+  
+  if (command === 'release:check' || command === 'release-check') {
+    return {
+      type: 'release:check',
+      json: args.includes('--json')
+    };
+  }
+  
+  if (command === 'security:check' || command === 'security-check') {
+    return {
+      type: 'security:check',
+      json: args.includes('--json')
+    };
+  }
+  
+  if (command === 'baseline') {
+    return {
+      type: 'baseline',
+      json: args.includes('--json')
+    };
+  }
+  
+  if (command === 'truth') {
+    return {
+      type: 'truth',
+      runId: parseArg(args, '--run-id'),
+      json: args.includes('--json')
+    };
+  }
+  
+  if (command === 'doctor') {
+    const allowedFlags = new Set(['--json']);
+    const extraFlags = args.slice(1).filter((a) => a.startsWith('-') && !allowedFlags.has(a));
+    return {
+      type: 'doctor',
+      json: args.includes('--json'),
+      extraFlags
+    };
+  }
+  
+  // Execution commands
+  if (command === 'run') {
+    const url = parseArg(args, '--url');
+    const fixture = parseArg(args, '--fixture');
+    if (!url && !fixture) {
+      throw new UsageError('run command requires --url <url> or --fixture <fixture> argument');
     }
-    
-    // If no args, run default command
-    if (args.length === 0) {
-      await defaultCommand({});
-      process.exit(0);
+    return {
+      type: 'run',
+      url,
+      fixture,
+      src: parseArg(args, '--src') || '.',
+      out: parseArg(args, '--out') || '.verax',
+      json: args.includes('--json'),
+      verbose: args.includes('--verbose'),
+      determinism: args.includes('--determinism'),
+      determinismRuns: args.includes('--determinism') ? parseInt(parseArg(args, '--determinism-runs') || '2', 10) : 0
+    };
+  }
+  
+  if (command === 'help' || command === '--help' || command === '-h') {
+    return { type: 'help' };
+  }
+  
+  // Default command: smart scanning mode
+  return {
+    type: 'default',
+    options: {
+      url: parseArg(args, '--url'),
+      src: parseArg(args, '--src') || '.',
+      out: parseArg(args, '--out') || '.verax',
+      json: args.includes('--json'),
+      verbose: args.includes('--verbose')
     }
+  };
+}
+
+/**
+ * PHASE B: Dispatch with isolation enforcement
+ * 
+ * @param {Object} parsed - Parsed command from Phase A
+ */
+async function dispatch(parsed) {
+  try {
+    // Inspection commands: enable guard mode
+    const isInspectionCommand = ['inspect', 'gates', 'ga', 'doctor', 'release:check', 'security:check', 'baseline', 'truth'].includes(parsed.type);
     
-    const command = args[0];
-    
-    // Handle 'run' command
-    if (command === 'run') {
-      const url = parseArg(args, '--url');
-      const src = parseArg(args, '--src') || '.';
-      const out = parseArg(args, '--out') || '.verax';
-      const json = args.includes('--json');
-      const verbose = args.includes('--verbose');
-      
-      if (!url) {
-        throw new UsageError('run command requires --url <url> argument');
-      }
-      
-      await runCommand({ url, src, out, json, verbose });
-      process.exit(0);
+    if (isInspectionCommand) {
+      enableInspectionMode();
     }
     
-    // Handle 'inspect' command
-    if (command === 'inspect') {
-      if (args.length < 2) {
-        throw new UsageError('inspect command requires a run path argument');
+    try {
+      switch (parsed.type) {
+        case 'version':
+          console.log(`verax ${getVersion()}`);
+          process.exit(0);
+          break;
+          
+        case 'help':
+          showHelp();
+          process.exit(0);
+          break;
+          
+        case 'inspect':
+          await inspectCommand(parsed.runPath, { 
+            json: parsed.json,
+            timeline: parsed.timeline,
+            decisions: parsed.decisions,
+            failures: parsed.failures,
+            performance: parsed.performance,
+            evidence: parsed.evidence
+          });
+          process.exit(0);
+          break;
+          
+        case 'gates':
+          await gatesCommand({ json: parsed.json, verbose: parsed.verbose });
+          // gatesCommand handles exit code internally
+          return;
+          
+        case 'ga':
+          await gaCommand({ runId: parsed.runId, json: parsed.json });
+          // gaCommand handles exit code internally
+          return;
+          
+        case 'release:check':
+          await releaseCheckCommand({ json: parsed.json });
+          // releaseCheckCommand handles exit code internally
+          return;
+          
+        case 'security:check':
+          await securityCheckCommand({ json: parsed.json });
+          // securityCheckCommand handles exit code internally
+          return;
+          
+        case 'baseline':
+          await baselineCommand(process.cwd(), { json: parsed.json });
+          process.exit(0);
+          break;
+          
+        case 'truth':
+          await truthCommand(process.cwd(), { json: parsed.json, runId: parsed.runId });
+          process.exit(0);
+          break;
+          
+        case 'doctor':
+          await doctorCommand({ json: parsed.json, extraFlags: parsed.extraFlags });
+          process.exit(0);
+          break;
+          
+        case 'run':
+          await runCommand({
+            url: parsed.url,
+            fixture: parsed.fixture,
+            src: parsed.src,
+            out: parsed.out,
+            json: parsed.json,
+            verbose: parsed.verbose,
+            determinism: parsed.determinism,
+            determinismRuns: parsed.determinismRuns
+          });
+          process.exit(0);
+          break;
+          
+        case 'default':
+          await defaultCommand(parsed.options);
+          process.exit(0);
+          break;
+          
+        default:
+          throw new UsageError(`Unknown command: ${parsed.type}`);
+      }
+    } finally {
+      if (isInspectionCommand) {
+        disableInspectionMode();
       }
-      
-      const runPath = args[1];
-      const json = args.includes('--json');
-      
-      await inspectCommand(runPath, { json });
-      process.exit(0);
-    }
-
-    // Handle 'doctor' command
-    if (command === 'doctor') {
-      const allowedFlags = new Set(['--json']);
-      const extraFlags = args.slice(1).filter((a) => a.startsWith('-') && !allowedFlags.has(a));
-      const json = args.includes('--json');
-      await doctorCommand({ json, extraFlags });
-      process.exit(0);
     }
-    
-    // Handle 'help' command
-    if (command === 'help' || command === '--help' || command === '-h') {
-      showHelp();
-      process.exit(0);
+  } catch (error) {
+    // Print error message
+    if (error.message) {
+      console.error(`Error: ${error.message}`);
     }
     
-    // Default command: smart scanning mode
-    // Options can be passed as flags before/after the default command position
-    const url = parseArg(args, '--url');
-    const src = parseArg(args, '--src') || '.';
-    const out = parseArg(args, '--out') || '.verax';
-    const json = args.includes('--json');
-    const verbose = args.includes('--verbose');
+    // Get exit code
+    const exitCode = getExitCode(error);
+    process.exit(exitCode);
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  // PHASE 21.6.1: Print CLI identity for debugging
+  printCLIIdentity(args);
+  
+  try {
+    // PHASE A: Parse command (zero side effects)
+    const parsed = parseCommand(args);
     
-    await defaultCommand({ url, src, out, json, verbose });
-    process.exit(0);
+    // PHASE B: Dispatch with isolation enforcement
+    await dispatch(parsed);
   } catch (error) {
     // Print error message
     if (error.message) {
@@ -130,24 +350,41 @@ async function main() {
 
 function showHelp() {
   const version = getVersion();
+  const banner = getSourceCodeRequirementBanner();
   console.log(`
 verax ${version}
 VERAX — Silent failure detection for websites
 
+ ${banner}
+ Canonical product contract: docs/README.md
+
 USAGE:
   verax [options]                              Smart mode (detects/prompts for URL)
   verax run --url <url> [options]             Strict mode (non-interactive, CI-friendly)
   verax inspect <runPath> [--json]            Inspect an existing run
+  verax inspect <runPath> --timeline         Show chronological timeline
+  verax inspect <runPath> --decisions         Show decision trace
+  verax inspect <runPath> --failures          Show failure ledger
+  verax inspect <runPath> --performance       Show performance metrics
+  verax inspect <runPath> --evidence          Show evidence cross-index
   verax doctor [--json]                       Diagnose local environment
+  verax gates [--json] [--verbose]            Evaluate capability gates (PHASE 19)
+  verax ga [--run-id <id>] [--json]            Evaluate GA readiness (PHASE 21.6)
+  verax release:check [--json]                Check release readiness (PHASE 21.7)
+  verax security:check [--json]               Check security baseline (PHASE 21.8)
+  verax baseline [--json]                     Show baseline hash and drift status (PHASE 21.11)
+  verax truth [--run-id <id>] [--json]         Show truth certificate (PHASE 21.11)
   verax --version                              Show version
   verax --help                                 Show this help
 
 OPTIONS:
   --url <url>        Target URL to scan
-  --src <path>       Source directory (default: .)
+  --src <path>       Source directory (default: .) — required; URL-only scans are blocked
   --out <path>       Output directory for artifacts (default: .verax)
   --json             Output as JSON lines (progress events)
   --verbose          Verbose output
+  --determinism      Run determinism check (executes scan multiple times and compares results)
+  --determinism-runs <N>  Number of runs for determinism check (default: 2)
   --help             Show this help
   --version          Show version