@veraxhq/verax 0.1.0 → 0.2.0

package/src/cli/commands/inspect.js

@@ -0,0 +1,109 @@
+import { resolve } from 'path';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { DataError } from '../util/errors.js';
+
+/**
+ * `verax inspect` command
+ * Read an existing run folder and display summary
+ */
+export async function inspectCommand(runPath, options = {}) {
+  const { json = false } = options;
+  
+  const fullPath = resolve(runPath);
+  
+  // Validate run directory exists
+  if (!existsSync(fullPath)) {
+    throw new DataError(`Run directory not found: ${fullPath}`);
+  }
+  
+  // Check for required files
+  const requiredFiles = ['summary.json', 'findings.json'];
+  const missingFiles = [];
+  
+  for (const file of requiredFiles) {
+    const filePath = `${fullPath}/${file}`;
+    if (!existsSync(filePath)) {
+      missingFiles.push(file);
+    }
+  }
+  
+  if (missingFiles.length > 0) {
+    throw new DataError(
+      `Invalid run directory. Missing files: ${missingFiles.join(', ')}`
+    );
+  }
+  
+  // Read summary and findings
+  let summary, findings;
+  
+  try {
+    summary = JSON.parse(readFileSync(`${fullPath}/summary.json`, 'utf8'));
+  } catch (error) {
+    throw new DataError(`Failed to parse summary.json: ${error.message}`);
+  }
+  
+  try {
+    findings = JSON.parse(readFileSync(`${fullPath}/findings.json`, 'utf8'));
+  } catch (error) {
+    throw new DataError(`Failed to parse findings.json: ${error.message}`);
+  }
+  
+  // Check for evidence directory
+  const evidenceDir = `${fullPath}/evidence`;
+  const hasEvidence = existsSync(evidenceDir);
+  let evidenceCount = 0;
+  
+  if (hasEvidence) {
+    try {
+      evidenceCount = readdirSync(evidenceDir).length;
+    } catch (error) {
+      evidenceCount = 0;
+    }
+  }
+  
+  // Build output
+  const output = {
+    runId: summary.runId || 'unknown',
+    status: summary.status || 'unknown',
+    startedAt: summary.startedAt || null,
+    completedAt: summary.completedAt || null,
+    url: summary.url || null,
+    findingsCount: Array.isArray(findings) ? findings.length : 0,
+    evidenceDir: hasEvidence ? evidenceDir : null,
+    evidenceFileCount: evidenceCount,
+  };
+  
+  if (json) {
+    // Output as single JSON object
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    // Output as human-readable summary
+    console.log('\n=== Run Summary ===\n');
+    console.log(`Run ID: ${output.runId}`);
+    console.log(`Status: ${output.status}`);
+    
+    if (output.startedAt) {
+      console.log(`Started: ${output.startedAt}`);
+    }
+    
+    if (output.completedAt) {
+      console.log(`Completed: ${output.completedAt}`);
+    }
+    
+    if (output.url) {
+      console.log(`URL: ${output.url}`);
+    }
+    
+    console.log(`\nFindings: ${output.findingsCount}`);
+    
+    if (output.evidenceDir) {
+      console.log(`Evidence: ${output.evidenceDir} (${output.evidenceFileCount} files)`);
+    } else {
+      console.log(`Evidence: not found`);
+    }
+    
+    console.log('');
+  }
+  
+  return output;
+}

package/src/cli/commands/run.js

@@ -0,0 +1,402 @@
+import { resolve, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { UsageError, DataError, CrashError } 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';
+import { RunEventEmitter } from '../util/events.js';
+import { discoverProject } from '../util/project-discovery.js';
+import { writeProjectJson } from '../util/project-writer.js';
+import { extractExpectations } from '../util/expectation-extractor.js';
+import { writeLearnJson } from '../util/learn-writer.js';
+import { observeExpectations } from '../util/observation-engine.js';
+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';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function getVersion() {
+  try {
+    const pkgPath = resolve(__dirname, '../../../package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version;
+  } catch {
+    return '0.2.0';
+  }
+}
+
+/**
+ * `verax run` command
+ * Strict, non-interactive CLI mode with explicit flags
+ */
+export async function runCommand(options) {
+  const {
+    url,
+    src = '.',
+    out = '.verax',
+    json = false,
+    verbose = false,
+  } = options;
+  
+  // Validate required arguments
+  if (!url) {
+    throw new UsageError('Missing required argument: --url <url>');
+  }
+  
+  const projectRoot = resolve(process.cwd());
+  const srcPath = resolve(projectRoot, src);
+  
+  // Validate src directory exists
+  if (!existsSync(srcPath)) {
+    throw new DataError(`Source directory not found: ${srcPath}`);
+  }
+  
+  // Create event emitter
+  const events = new RunEventEmitter();
+  
+  // Setup event handlers
+  if (json) {
+    events.on('*', (event) => {
+      console.log(JSON.stringify(event));
+    });
+  } else {
+    events.on('*', (event) => {
+      if (verbose) {
+        console.log(`[${event.type}] ${event.message || ''}`);
+      }
+    });
+  }
+  
+  let runId = null;
+  let paths = null;
+  let startedAt = null;
+  
+  try {
+    // Generate run ID
+    runId = generateRunId();
+    if (verbose && !json) console.log(`Run ID: ${runId}`);
+    
+    paths = getRunPaths(projectRoot, out, runId);
+    ensureRunDirectories(paths);
+    
+    // Discover project configuration
+    let projectProfile;
+    try {
+      projectProfile = await discoverProject(srcPath);
+    } catch (error) {
+      projectProfile = {
+        framework: 'unknown',
+        router: null,
+        sourceRoot: srcPath,
+        packageManager: 'unknown',
+        scripts: { dev: null, build: null, start: null },
+        detectedAt: new Date().toISOString(),
+      };
+    }
+    
+    // Emit project detection events
+    events.emit('project:detected', {
+      framework: projectProfile.framework,
+      router: projectProfile.router,
+      sourceRoot: projectProfile.sourceRoot,
+      packageManager: projectProfile.packageManager,
+    });
+    
+    // Emit phase events
+    events.emit('phase:started', {
+      phase: 'Detect Project',
+      message: 'Detecting project structure...',
+    });
+    
+    events.emit('phase:started', {
+      phase: 'Resolve URL',
+      message: `Using URL: ${url}`,
+    });
+    
+    events.emit('phase:started', {
+      phase: 'Initialize Run',
+      message: 'Initializing run artifacts...',
+    });
+    
+    // Write initial status
+    const now = new Date();
+    startedAt = now.toISOString();
+    
+    atomicWriteJson(paths.runStatusJson, {
+      status: 'RUNNING',
+      runId,
+      startedAt,
+    });
+    
+    // Write metadata
+    atomicWriteJson(paths.runMetaJson, {
+      veraxVersion: getVersion(),
+      nodeVersion: process.version,
+      platform: process.platform,
+      cwd: projectRoot,
+      command: 'run',
+      args: { url, src, out },
+      url,
+      src: srcPath,
+      startedAt,
+      completedAt: null,
+      error: null,
+    });
+    
+    // Simulate learning phase (placeholder)
+    events.emit('phase:started', {
+      phase: 'Learn',
+      message: 'Analyzing project structure...',
+    });
+    
+    // Extract expectations
+    const { expectations, skipped } = await extractExpectations(projectProfile, projectProfile.sourceRoot);
+    
+    // For now, emit a placeholder trace event
+    events.emit('phase:completed', {
+      phase: 'Learn',
+      message: 'Project analysis complete',
+    });
+    
+    // Observe phase
+    events.emit('phase:started', {
+      phase: 'Observe',
+      message: 'Launching browser and observing expectations...',
+    });
+    
+    let observeData = null;
+    if (expectations.length > 0) {
+      try {
+        observeData = await observeExpectations(
+          expectations,
+          url,
+          paths.evidenceDir,
+          (progress) => {
+            events.emit(progress.event, progress);
+          }
+        );
+      } catch (error) {
+        events.emit('observe:error', {
+          message: error.message,
+        });
+        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(),
+      };
+    }
+    
+    events.emit('phase:completed', {
+      phase: 'Observe',
+      message: 'Browser observation complete',
+    });
+    
+      // Detect phase
+      events.emit('phase:started', {
+        phase: 'Detect',
+        message: 'Analyzing findings and detecting silent failures...',
+      });
+    
+      let detectData = null;
+      try {
+        // Use already-extracted expectations
+        const learnData = {
+          expectations,
+          skipped,
+        };
+      
+        detectData = await detectFindings(learnData, observeData, projectRoot, (progress) => {
+          events.emit(progress.event, progress);
+        });
+      } catch (error) {
+        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(),
+        };
+      }
+    
+      events.emit('phase:completed', {
+        phase: 'Detect',
+        message: 'Silent failure detection complete',
+      });
+    
+    // Emit finalize phase
+    events.emit('phase:started', {
+      phase: 'Finalize Artifacts',
+      message: 'Writing run results...',
+    });
+    
+    const completedAt = new Date().toISOString();
+    
+    // Write completed status
+    atomicWriteJson(paths.runStatusJson, {
+      status: 'COMPLETE',
+      runId,
+      startedAt,
+      completedAt,
+    });
+    
+    // Update metadata with completion time
+    atomicWriteJson(paths.runMetaJson, {
+      veraxVersion: getVersion(),
+      nodeVersion: process.version,
+      platform: process.platform,
+      cwd: projectRoot,
+      command: 'run',
+      args: { url, src, out },
+      url,
+      src: srcPath,
+      startedAt,
+      completedAt,
+      error: null,
+    });
+    
+    // Write summary with stable digest
+    writeSummaryJson(paths.summaryJson, {
+      runId,
+      status: 'COMPLETE',
+      startedAt,
+      completedAt,
+      command: 'run',
+      url,
+      notes: 'Run completed successfully',
+    }, {
+      expectationsTotal: expectations.length,
+      attempted: observeData.stats?.attempted || 0,
+      observed: observeData.stats?.observed || 0,
+      silentFailures: detectData.stats?.silentFailures || 0,
+      coverageGaps: detectData.stats?.coverageGaps || 0,
+      unproven: detectData.stats?.unproven || 0,
+      informational: detectData.stats?.informational || 0,
+    });
+    
+    // Write detect results (or empty if detection failed)
+    writeFindingsJson(paths.baseDir, detectData);
+    
+    // Write traces (at least phase events)
+    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';
+    atomicWriteText(paths.tracesJsonl, tracesContent);
+    
+    // Write project profile
+    writeProjectJson(paths, projectProfile);
+    
+    // Write learn results
+    writeLearnJson(paths, expectations, skipped);
+    
+    // Write observe results
+    writeObserveJson(paths.baseDir, observeData);
+    
+    events.emit('phase:completed', {
+      phase: 'Finalize Artifacts',
+      message: 'Run artifacts written',
+    });
+    
+    // Print summary if not JSON mode
+    if (!json) {
+      console.log('\nRun complete.');
+      console.log(`Run ID: ${runId}`);
+      console.log(`Artifacts: ${paths.baseDir}`);
+    }
+    
+    return { runId, paths, success: true };
+  } catch (error) {
+    // Mark run as FAILED if we have paths
+    if (paths && runId && startedAt) {
+      try {
+        const failedAt = new Date().toISOString();
+        atomicWriteJson(paths.runStatusJson, {
+          status: 'FAILED',
+          runId,
+          startedAt,
+          failedAt,
+          error: error.message,
+        });
+        
+        // Update metadata
+        atomicWriteJson(paths.runMetaJson, {
+          veraxVersion: getVersion(),
+          nodeVersion: process.version,
+          platform: process.platform,
+          cwd: projectRoot,
+          command: 'run',
+          args: { url, src, out },
+          url,
+          src: srcPath,
+          startedAt,
+          completedAt: failedAt,
+          error: error.message,
+        });
+        
+        // Write summary with digest even on failure
+        try {
+          writeSummaryJson(paths.summaryJson, {
+            runId,
+            status: 'FAILED',
+            startedAt,
+            completedAt: failedAt,
+            command: 'run',
+            url,
+            notes: `Run failed: ${error.message}`,
+          }, {
+            expectationsTotal: 0,
+            attempted: 0,
+            observed: 0,
+            silentFailures: 0,
+            coverageGaps: 0,
+            unproven: 0,
+            informational: 0,
+          });
+        } catch (summaryError) {
+          // Ignore summary write errors during failure handling
+        }
+      } catch (statusError) {
+        // Ignore errors when writing failure status
+      }
+    }
+    
+    events.emit('error', {
+      message: error.message,
+      stack: error.stack,
+    });
+    throw error;
+  }
+}

package/src/cli/entry.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+/**
+ * VERAX CLI Entry Point
+ * 
+ * Commands:
+ * - verax                    (smart default with URL detection/prompting)
+ * - verax run --url <url>    (strict, non-interactive)
+ * - verax inspect <runPath>  (read and display run summary)
+ * 
+ * Exit codes:
+ * - 0:  success
+ * - 2:  internal crash
+ * - 64: invalid CLI usage
+ * - 65: invalid input data
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { readFileSync } from 'fs';
+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 { getExitCode, UsageError, DataError, CrashError } from './util/errors.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read package.json for version
+function getVersion() {
+  try {
+    const pkgPath = resolve(__dirname, '../../package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  try {
+    // Handle --version
+    if (args.includes('--version') || args.includes('-v')) {
+      console.log(`verax ${getVersion()}`);
+      process.exit(0);
+    }
+    
+    // Handle explicit --help
+    if (args.includes('--help') || args.includes('-h')) {
+      showHelp();
+      process.exit(0);
+    }
+    
+    // If no args, run default command
+    if (args.length === 0) {
+      await defaultCommand({});
+      process.exit(0);
+    }
+    
+    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');
+      }
+      
+      const result = await runCommand({ url, src, out, json, verbose });
+      process.exit(0);
+    }
+    
+    // Handle 'inspect' command
+    if (command === 'inspect') {
+      if (args.length < 2) {
+        throw new UsageError('inspect command requires a run path argument');
+      }
+      
+      const runPath = args[1];
+      const json = args.includes('--json');
+      
+      const result = 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');
+      const result = await doctorCommand({ json, extraFlags });
+      process.exit(0);
+    }
+    
+    // Handle 'help' command
+    if (command === 'help' || command === '--help' || command === '-h') {
+      showHelp();
+      process.exit(0);
+    }
+    
+    // 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');
+    
+    const result = await defaultCommand({ url, src, out, json, verbose });
+    process.exit(0);
+  } catch (error) {
+    // Print error message
+    if (error.message) {
+      console.error(`Error: ${error.message}`);
+    }
+    
+    // Get exit code
+    const exitCode = getExitCode(error);
+    process.exit(exitCode);
+  }
+}
+
+function showHelp() {
+  const version = getVersion();
+  console.log(`
+verax ${version}
+VERAX — Silent failure detection for websites
+
+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 doctor [--json]                       Diagnose local environment
+  verax --version                              Show version
+  verax --help                                 Show this help
+
+OPTIONS:
+  --url <url>        Target URL to scan
+  --src <path>       Source directory (default: .)
+  --out <path>       Output directory for artifacts (default: .verax)
+  --json             Output as JSON lines (progress events)
+  --verbose          Verbose output
+  --help             Show this help
+  --version          Show version
+
+EXAMPLES:
+  # Smart mode (interactive if needed)
+  verax
+
+  # Smart mode with explicit URL
+  verax --url https://example.com
+
+  # Strict mode (CI-friendly, non-interactive)
+  verax run --url https://example.com --src . --out .verax
+
+  # Inspect previous run
+  verax inspect .verax/runs/2026-01-11T00-59-12Z_4f2a9c
+
+EXIT CODES:
+  0   Success (tool executed)
+  2   Internal crash
+  64  Invalid CLI usage (missing args, invalid flags)
+  65  Invalid input data (bad JSON, unreadable folder, etc.)
+
+ARTIFACTS:
+  Artifacts are written to: <out>/runs/<runId>/
+  Required files:
+    - run.status.json     Run status lifecycle
+    - run.meta.json       Metadata about the run
+    - summary.json        Summary of results
+    - findings.json       Array of findings
+    - traces.jsonl        JSONL traces of execution
+    - evidence/           Directory for evidence files
+`);
+}
+
+function parseArg(args, name) {
+  const index = args.indexOf(name);
+  if (index !== -1 && index + 1 < args.length) {
+    return args[index + 1];
+  }
+  return null;
+}
+
+main().catch((error) => {
+  console.error(`Fatal error: ${error.message}`);
+  process.exit(2);
+});