@veraxhq/verax 0.1.0 → 0.2.0

package/src/cli/commands/default.js

@@ -0,0 +1,523 @@
+import { resolve } from 'path';
+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 { 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 { tryResolveUrlFromEnv } from '../util/env-url.js';
+import { discoverProject, getFrameworkDisplayName, extractPortFromScript } 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` smart default command
+ * Interactive mode with intelligent URL detection
+ */
+export async function defaultCommand(options = {}) {
+  const {
+    src = '.',
+    out = '.verax',
+    url = null,
+    json = false,
+    verbose = false,
+  } = options;
+  
+  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));
+    });
+  }
+  
+  // Show progress if not JSON
+  if (!json && !verbose) {
+    events.on('phase:started', (event) => {
+      if (!json) {
+        console.log(`${event.phase}...`);
+      }
+    });
+  }
+  
+  try {
+    events.emit('phase:started', {
+      phase: 'Detect Project',
+      message: 'Detecting project type...',
+    });
+    
+    // Discover project configuration
+    let projectProfile;
+    try {
+      projectProfile = await discoverProject(srcPath);
+    } catch (error) {
+      // If discovery fails, create a minimal profile
+      projectProfile = {
+        framework: 'unknown',
+        router: null,
+        sourceRoot: srcPath,
+        packageManager: 'unknown',
+        scripts: { dev: null, build: null, start: null },
+        detectedAt: new Date().toISOString(),
+      };
+    }
+    
+    const frameworkName = getFrameworkDisplayName(projectProfile.framework, projectProfile.router);
+    
+    if (!json) {
+      console.log(`Detected framework: ${frameworkName}`);
+      console.log(`Resolved source root: ${projectProfile.sourceRoot}`);
+    }
+    
+    events.emit('project:detected', {
+      framework: projectProfile.framework,
+      router: projectProfile.router,
+      frameworkName,
+      sourceRoot: projectProfile.sourceRoot,
+    });
+    
+    events.emit('phase:completed', {
+      phase: 'Detect Project',
+      message: `Detected framework: ${frameworkName}`,
+    });
+    
+    // Phase: Resolve URL
+    let resolvedUrl = url;
+    
+    if (!resolvedUrl) {
+      events.emit('phase:started', {
+        phase: 'Resolve URL',
+        message: 'Attempting to resolve URL from environment...',
+      });
+      
+      resolvedUrl = tryResolveUrlFromEnv();
+      
+      // Try to extract URL from dev script if available
+      if (!resolvedUrl && projectProfile.scripts.dev) {
+        const port = extractPortFromScript(projectProfile.scripts.dev);
+        if (port) {
+          resolvedUrl = `http://localhost:${port}`;
+          if (!json) {
+            console.log(`Detected dev script: ${projectProfile.scripts.dev}`);
+          }
+          events.emit('dev:script:detected', {
+            script: projectProfile.scripts.dev,
+            port,
+          });
+        }
+      }
+      
+      if (resolvedUrl && !json) {
+        console.log(`Detected URL: ${resolvedUrl}`);
+      }
+    }
+    
+    // If still no URL, prompt interactively
+    if (!resolvedUrl) {
+      events.emit('phase:started', {
+        phase: 'Resolve URL',
+        message: 'Prompting for URL...',
+      });
+      
+      if (!json) {
+        console.log(''); // blank line
+      }
+      
+      const answer = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'url',
+          message: 'Enter the URL to scan',
+          validate: (input) => {
+            if (!input.trim()) {
+              return 'URL is required';
+            }
+            if (!input.startsWith('http://') && !input.startsWith('https://')) {
+              return 'URL must start with http:// or https://';
+            }
+            return true;
+          },
+        },
+      ]);
+      
+      resolvedUrl = answer.url;
+    }
+    
+    if (!json) {
+      console.log(`Using URL: ${resolvedUrl}`);
+    }
+    
+    events.emit('phase:completed', {
+      phase: 'Resolve URL',
+      message: `URL resolved: ${resolvedUrl}`,
+    });
+    
+    // Generate run ID
+    let runId = generateRunId();
+    if (verbose && !json) console.log(`Run ID: ${runId}`);
+    
+    let paths = getRunPaths(projectRoot, out, runId);
+    ensureRunDirectories(paths);
+    
+    // Initialize Run
+    events.emit('phase:started', {
+      phase: 'Initialize Run',
+      message: 'Initializing run artifacts...',
+    });
+    
+    const now = new Date();
+    let startedAt = now.toISOString();
+    
+    atomicWriteJson(paths.runStatusJson, {
+      status: 'RUNNING',
+      runId,
+      startedAt,
+    });
+    
+    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: null,
+      error: null,
+    });
+    
+    events.emit('phase:completed', {
+      phase: 'Initialize Run',
+      message: 'Run initialized',
+    });
+    
+    // Learning phase (placeholder)
+    events.emit('phase:started', {
+      phase: 'Learn',
+      message: 'Analyzing project structure...',
+    });
+    
+    // Extract expectations
+    const { expectations, skipped } = await extractExpectations(projectProfile, projectProfile.sourceRoot);
+    
+    if (!json) {
+      console.log(`Found ${expectations.length} expectations`);
+      if (Object.values(skipped).reduce((a, b) => a + b, 0) > 0) {
+        console.log(`Skipped: ${Object.values(skipped).reduce((a, b) => a + b, 0)} (dynamic/computed)`);
+      }
+    }
+    
+    // Emit expectations found events
+    expectations.slice(0, 5).forEach(exp => {
+      events.emit('expectation:found', {
+        type: exp.type,
+        promise: exp.promise,
+        file: exp.source.file,
+      });
+    });
+    
+    if (expectations.length > 5) {
+      events.emit('expectation:found', {
+        message: `... and ${expectations.length - 5} more expectations`,
+      });
+    }
+    
+    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,
+          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}`);
+            }
+          }
+        );
+        
+        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,
+        });
+        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...',
+      });
+    
+      // 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}`);
+          }
+        });
+      
+        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(),
+        };
+      }
+    
+      events.emit('phase:completed', {
+        phase: 'Detect',
+        message: 'Silent failure detection complete',
+      });
+    
+    // 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,
+    });
+    
+    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 summary with stable digest
+    writeSummaryJson(paths.summaryJson, {
+      runId,
+      status: 'COMPLETE',
+      startedAt,
+      completedAt,
+      command: 'default',
+      url: resolvedUrl,
+      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);
+    
+    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, url: resolvedUrl, 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: 'default',
+          args: { url: url || null, src },
+          url: url || null,
+          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: 'default',
+            url: url || null,
+            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/commands/doctor.js

@@ -0,0 +1,165 @@
+/**
+ * VERAX Doctor (Phase 8.1)
+ * Environment diagnostics for enterprise hardening.
+ * Never throws on check failures; only invalid usage should bubble out.
+ */
+
+import { existsSync } from 'fs';
+import { platform } from 'os';
+import { createRequire } from 'module';
+import { UsageError } from '../util/errors.js';
+
+export async function doctorCommand(options = {}) {
+  const { json = false, extraFlags = [] } = options;
+
+  if (extraFlags.length > 0) {
+    throw new UsageError(`Unknown flag(s): ${extraFlags.join(', ')}`);
+  }
+
+  const checks = [];
+  const recommendations = [];
+  const platformName = platform();
+  const nodeVersion = process.versions.node;
+  let playwrightVersion = null;
+  let playwright = null;
+  let chromiumPath = null;
+  const require = createRequire(import.meta.url);
+
+  const addCheck = (name, status, details, recommendation) => {
+    checks.push({ name, status, details });
+    if (recommendation) {
+      recommendations.push(recommendation);
+    }
+  };
+
+  // 1) Node.js version
+  const nodeMajor = parseInt(nodeVersion.split('.')[0], 10);
+  if (Number.isFinite(nodeMajor) && nodeMajor >= 18) {
+    addCheck('Node.js version', 'pass', `Detected v${nodeVersion} (>=18 required)`);
+  } else {
+    addCheck('Node.js version', 'fail', `Detected v${nodeVersion} (<18)`, 'Upgrade Node.js to v18+');
+  }
+
+  // 2) Playwright package presence + version
+  try {
+    playwright = await import('playwright');
+    try {
+      const pkg = require('playwright/package.json');
+      playwrightVersion = pkg?.version || null;
+    } catch {
+      playwrightVersion = null;
+    }
+    addCheck('Playwright package', 'pass', `Installed${playwrightVersion ? ` v${playwrightVersion}` : ''}`);
+  } catch (error) {
+    addCheck(
+      'Playwright package',
+      'fail',
+      'Not installed or not resolvable',
+      'npm install -D playwright'
+    );
+  }
+
+  // 3) Playwright Chromium binaries
+  if (playwright && playwright.chromium) {
+    try {
+      chromiumPath = playwright.chromium.executablePath();
+      if (chromiumPath && existsSync(chromiumPath)) {
+        addCheck('Playwright Chromium', 'pass', `Executable found at ${chromiumPath}`);
+      } else {
+        addCheck(
+          'Playwright Chromium',
+          'fail',
+          'Chromium binary not found',
+          'npx playwright install --with-deps chromium'
+        );
+      }
+    } catch (error) {
+      addCheck(
+        'Playwright Chromium',
+        'fail',
+        `Unable to resolve Chromium executable (${error.message})`,
+        'npx playwright install --with-deps chromium'
+      );
+    }
+  } else {
+    addCheck(
+      'Playwright Chromium',
+      'fail',
+      'Skipped because Playwright is missing',
+      'npm install -D playwright && npx playwright install --with-deps chromium'
+    );
+  }
+
+  // 4) Headless launch smoke test
+  if (playwright && playwright.chromium && chromiumPath && existsSync(chromiumPath)) {
+    try {
+      const browser = await playwright.chromium.launch({ headless: true });
+      const page = await browser.newPage();
+      await page.goto('about:blank');
+      await browser.close();
+      addCheck('Headless smoke test', 'pass', 'Chromium launched headless and closed successfully');
+    } catch (error) {
+      addCheck(
+        'Headless smoke test',
+        'fail',
+        `Headless launch failed: ${error.message}`,
+        platformName === 'linux'
+          ? 'Try: npx playwright install --with-deps chromium && launch with --no-sandbox in constrained environments'
+          : 'Reinstall playwright: npx playwright install --with-deps chromium'
+      );
+    }
+  } else {
+    addCheck(
+      'Headless smoke test',
+      'fail',
+      'Skipped because Chromium executable is unavailable',
+      'npx playwright install --with-deps chromium'
+    );
+  }
+
+  // 5) Linux sandbox guidance
+  if (platformName === 'linux') {
+    const ciHints = detectCIHints();
+    const detailParts = ['Sandbox guidance: if launch fails, use --no-sandbox or ensure libnss3/libatk are installed'];
+    if (ciHints) detailParts.push(`Detected CI: ${ciHints}`);
+    addCheck('Linux sandbox guidance', 'pass', detailParts.join(' | '));
+  }
+
+  const ok = checks.every((c) => c.status === 'pass');
+
+  if (json) {
+    const report = {
+      ok,
+      platform: platformName,
+      nodeVersion,
+      playwrightVersion,
+      checks,
+      recommendations,
+    };
+    console.log(JSON.stringify(report, null, 2));
+    return report;
+  }
+
+  // Human-readable output
+  console.log('VERAX Doctor — Environment Diagnostics');
+  checks.forEach((c) => {
+    const label = c.status === 'pass' ? 'PASS' : 'FAIL';
+    console.log(`[${label}] ${c.name}: ${c.details}`);
+  });
+  console.log(`
+Overall: ${ok ? 'OK' : 'Issues found'} (${checks.filter(c => c.status === 'fail').length} failing checks)`);
+  if (recommendations.length > 0) {
+    console.log('\nRecommended actions:');
+    recommendations.forEach((r) => console.log(`- ${r}`));
+  }
+
+  return { ok, checks, recommendations };
+}
+
+function detectCIHints() {
+  if (process.env.GITHUB_ACTIONS === 'true') return 'GITHUB_ACTIONS';
+  if (process.env.CI === 'true') return 'CI';
+  if (process.env.BITBUCKET_BUILD_NUMBER) return 'BITBUCKET';
+  if (process.env.GITLAB_CI) return 'GITLAB_CI';
+  return '';
+}