@veraxhq/verax 0.1.0 → 0.2.0

package/src/cli/util/project-writer.js

@@ -0,0 +1,26 @@
+import { atomicWriteJson } from './atomic-write.js';
+import { resolve } from 'path';
+
+/**
+ * Write project profile artifact
+ */
+export function writeProjectJson(runPaths, projectProfile) {
+  const projectJsonPath = resolve(runPaths.baseDir, 'project.json');
+  
+  const projectJson = {
+    framework: projectProfile.framework,
+    router: projectProfile.router,
+    sourceRoot: projectProfile.sourceRoot,
+    packageManager: projectProfile.packageManager,
+    scripts: {
+      dev: projectProfile.scripts.dev,
+      build: projectProfile.scripts.build,
+      start: projectProfile.scripts.start,
+    },
+    detectedAt: projectProfile.detectedAt,
+  };
+  
+  atomicWriteJson(projectJsonPath, projectJson);
+  
+  return projectJsonPath;
+}

package/src/cli/util/redact.js

@@ -0,0 +1,128 @@
+/**
+ * Redaction utilities (Phase 8.2)
+ * Deterministic redaction for headers, URLs, bodies, console messages.
+ */
+
+const REDACTED = '***REDACTED***';
+const SENSITIVE_HEADERS = [
+  'authorization',
+  'cookie',
+  'set-cookie',
+  'x-api-key',
+  'proxy-authorization',
+];
+
+function ensureCounters(counters) {
+  if (!counters) return { headersRedacted: 0, tokensRedacted: 0 };
+  if (typeof counters.headersRedacted !== 'number') counters.headersRedacted = 0;
+  if (typeof counters.tokensRedacted !== 'number') counters.tokensRedacted = 0;
+  return counters;
+}
+
+export function redactHeaders(headers = {}, counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  const c = ensureCounters(counters);
+  const sanitized = {};
+  Object.entries(headers || {}).forEach(([key, value]) => {
+    const lower = key.toLowerCase();
+    if (SENSITIVE_HEADERS.includes(lower)) {
+      sanitized[key] = REDACTED;
+      c.headersRedacted += 1;
+    } else {
+      sanitized[key] = value;
+    }
+  });
+  return sanitized;
+}
+
+export function redactUrl(url, counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  if (url == null) return '';
+  return redactTokensInText(url, counters);
+}
+
+export function redactBody(body, counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  if (body == null) return body;
+  
+  const c = ensureCounters(counters);
+  
+  if (typeof body === 'string') {
+    return redactTokensInText(body, counters);
+  }
+  
+  if (typeof body === 'object' && !Array.isArray(body)) {
+    // Handle plain objects by redacting sensitive property names
+    const redacted = {};
+    Object.entries(body).forEach(([key, value]) => {
+      const keyLower = key.toLowerCase();
+      if (keyLower === 'token' || keyLower === 'api_key' || keyLower === 'access_token' || 
+          keyLower === 'password' || keyLower === 'secret') {
+        // Redact sensitive property values
+        c.tokensRedacted += 1;
+        redacted[key] = REDACTED;
+      } else if (typeof value === 'string') {
+        // Redact token patterns within string values
+        redacted[key] = redactTokensInText(value, counters);
+      } else if (typeof value === 'object' && value !== null) {
+        // Recursively redact nested objects/arrays
+        redacted[key] = redactBody(value, counters);
+      } else {
+        redacted[key] = value;
+      }
+    });
+    return redacted;
+  }
+  
+  if (Array.isArray(body)) {
+    return body.map(item => redactBody(item, counters));
+  }
+  
+  try {
+    const str = JSON.stringify(body);
+    const redacted = redactTokensInText(str, counters);
+    return JSON.parse(redacted);
+  } catch {
+    return REDACTED;
+  }
+}
+
+export function redactConsole(text = '', counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  return redactTokensInText(text, counters);
+}
+
+export function redactTokensInText(text, counters = { headersRedacted: 0, tokensRedacted: 0 }) {
+  const c = ensureCounters(counters);
+  if (text == null) return '';
+  if (typeof text !== 'string') return String(text);
+  
+  let output = text;
+
+  // Query/string parameters FIRST (most specific - only api_key, access_token)
+  // Use word boundary \b to avoid matching within words like "token" inside "example.com"
+  output = output.replace(/\b(api_key|access_token)=([^&\s]+)/gi, (match, key, value) => {
+    // Skip if value is itself just REDACTED (avoid double-redacting)
+    if (value === REDACTED) return match;
+    c.tokensRedacted += 1;
+    return `${key}=${REDACTED}`;
+  });
+
+  // Bearer tokens
+  output = output.replace(/Bearer\s+([A-Za-z0-9._-]+)/gi, (match, token) => {
+    c.tokensRedacted += 1;
+    return `Bearer ${REDACTED}`;
+  });
+
+  // JWT-like strings (three base64url-ish segments)
+  // More specific: require uppercase or numbers, not just domain patterns like "api.example.com"
+  output = output.replace(/[A-Z0-9][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, (match) => {
+    c.tokensRedacted += 1;
+    return REDACTED;
+  });
+
+  return output;
+}
+
+export function getRedactionCounters(counters) {
+  const c = ensureCounters(counters);
+  return { headersRedacted: c.headersRedacted, tokensRedacted: c.tokensRedacted };
+}
+
+export const REDACTION_PLACEHOLDER = REDACTED;

package/src/cli/util/run-id.js

@@ -0,0 +1,30 @@
+import crypto from 'crypto';
+
+/**
+ * Generate a run ID in format: <ISO_TIMESTAMP_UTC>_<6-8 char short hash>
+ * Example: 2026-01-11T00-59-12Z_4f2a9c
+ */
+export function generateRunId() {
+  // Create ISO timestamp with colons replaced by dashes for filesystem compatibility
+  const now = new Date();
+  const isoString = now.toISOString();
+  // Format: 2026-01-11T00:59:12.123Z -> 2026-01-11T00-59-12Z
+  const timestamp = isoString.replace(/:/g, '-').replace(/\.\d+Z/, 'Z');
+  
+  // Generate a short hash (6-8 chars)
+  const hash = crypto
+    .randomBytes(4)
+    .toString('hex')
+    .substring(0, 6);
+  
+  return `${timestamp}_${hash}`;
+}
+
+/**
+ * Validate a run ID format
+ */
+export function isValidRunId(runId) {
+  // Pattern: YYYY-MM-DDTHH-MM-SSZ_hexchars
+  const pattern = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z_[a-f0-9]{6,8}$/;
+  return pattern.test(runId);
+}

package/src/cli/util/summary-writer.js

@@ -0,0 +1,32 @@
+import { atomicWriteJson } from './atomic-write.js';
+import { resolve } from 'path';
+
+/**
+ * Write summary.json with deterministic digest
+ * The digest provides stable counts that should be identical across runs
+ * on the same input (assuming site behavior is stable)
+ */
+export function writeSummaryJson(summaryPath, summaryData, stats = {}) {
+  const payload = {
+    runId: summaryData.runId,
+    status: summaryData.status,
+    startedAt: summaryData.startedAt,
+    completedAt: summaryData.completedAt,
+    command: summaryData.command,
+    url: summaryData.url,
+    notes: summaryData.notes,
+    
+    // Stable digest that should be identical across repeated runs on same input
+    digest: {
+      expectationsTotal: stats.expectationsTotal || 0,
+      attempted: stats.attempted || 0,
+      observed: stats.observed || 0,
+      silentFailures: stats.silentFailures || 0,
+      coverageGaps: stats.coverageGaps || 0,
+      unproven: stats.unproven || 0,
+      informational: stats.informational || 0,
+    },
+  };
+  
+  atomicWriteJson(summaryPath, payload);
+}

package/src/verax/cli/ci-summary.js

@@ -0,0 +1,35 @@
+/**
+ * CI One-Line Summary
+ * 
+ * Prints a deterministic one-line summary for CI logs.
+ * OBSERVATIONAL ONLY - no verdicts, no trust badges, no judgments.
+ */
+
+/**
+ * Generate CI one-line summary
+ * @param {Object} context - Summary context
+ * @returns {string} One-line summary
+ */
+export function generateCISummary(context = {}) {
+  const {
+    expectations = 0,
+    interactions = 0,
+    findings = 0,
+    gaps = 0,
+    silences = 0,
+    runId = 'unknown'
+  } = context;
+  
+  // Format: VERAX | expectations=... | interactions=... | findings=... | gaps=... | silences=... | run=...
+  return `VERAX | expectations=${expectations} | interactions=${interactions} | findings=${findings} | gaps=${gaps} | silences=${silences} | run=${runId}`;
+}
+
+/**
+ * Print CI one-line summary
+ * @param {Object} context - Summary context
+ */
+export function printCISummary(context) {
+  const summary = generateCISummary(context);
+  console.error(summary);
+}
+

package/src/verax/cli/context-explanation.js

@@ -0,0 +1,89 @@
+/**
+ * Wave 4.1 — Context Validation Explanation
+ * 
+ * Provides detailed explanations when context validation fails or matches.
+ */
+
+/**
+ * Generate context validation explanation
+ * @param {Object} contextCheck - Context check result
+ * @param {Array} projectRoutes - Routes extracted from project
+ * @returns {Array<string>} Explanation lines
+ */
+export function explainContextValidation(contextCheck, projectRoutes = []) {
+  const lines = [];
+  
+  if (!contextCheck.ran) {
+    if (contextCheck.reason === 'no_routes_extracted') {
+      lines.push('Context validation skipped: No routes extracted from project.');
+    } else if (contextCheck.reason === 'invalid_url') {
+      lines.push('Context validation skipped: Invalid URL format.');
+    } else {
+      lines.push('Context validation skipped.');
+    }
+    return lines;
+  }
+  
+  if (contextCheck.verdict === 'VALID_CONTEXT') {
+    lines.push(`✓ Context validated: URL matches project`);
+    lines.push(`  ${contextCheck.matchedRoutesCount} of ${contextCheck.totalRoutesChecked || projectRoutes.length} routes matched`);
+    if (contextCheck.sampleMatched && contextCheck.sampleMatched.length > 0) {
+      lines.push(`  Sample matched routes: ${contextCheck.sampleMatched.slice(0, 3).join(', ')}`);
+    }
+    return lines;
+  }
+  
+  // INVALID_CONTEXT or INVALID_CONTEXT_FORCED
+  lines.push(`⚠ Context mismatch: URL does not match project`);
+  lines.push(`  Project routes found: ${projectRoutes.length}`);
+  lines.push(`  Routes matched: ${contextCheck.matchedRoutesCount} of ${contextCheck.totalRoutesChecked || projectRoutes.length}`);
+  
+  if (projectRoutes.length > 0 && contextCheck.matchedRoutesCount === 0) {
+    lines.push('');
+    lines.push('  Project routes (sample):');
+    const sampleRoutes = projectRoutes.slice(0, 5);
+    for (const route of sampleRoutes) {
+      lines.push(`    - ${route}`);
+    }
+    
+    if (contextCheck.internalLinksFound !== undefined) {
+      lines.push(`  Live site internal links found: ${contextCheck.internalLinksFound}`);
+    }
+    
+    lines.push('');
+    lines.push('  Possible reasons:');
+    lines.push('    • Route paths don\'t match (e.g., /about vs /about.html)');
+    lines.push('    • Project routes not linked on homepage');
+    lines.push('    • SPA routes not accessible at expected paths');
+    
+    if (contextCheck.verdict === 'INVALID_CONTEXT') {
+      lines.push('');
+      lines.push('  Next steps:');
+      lines.push('    • Use --force to scan anyway');
+      lines.push('    • Verify URL matches project deployment');
+      lines.push('    • Check that routes exist on the live site');
+    } else {
+      lines.push('');
+      lines.push('  Scan continued with --force flag despite mismatch.');
+    }
+  }
+  
+  return lines;
+}
+
+/**
+ * Print context validation explanation
+ * @param {Object} contextCheck - Context check result
+ * @param {Array} projectRoutes - Routes extracted from project
+ */
+export function printContextExplanation(contextCheck, projectRoutes = []) {
+  const lines = explainContextValidation(contextCheck, projectRoutes);
+  if (lines.length > 0) {
+    console.error('');
+    console.error('Context Validation:');
+    lines.forEach(line => {
+      console.error(line);
+    });
+  }
+}
+

package/src/verax/cli/doctor.js

@@ -0,0 +1,277 @@
+/**
+ * Wave 7 — VERAX Doctor
+ * 
+ * Checks environment, dependencies, and project setup.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { chromium } from 'playwright';
+import { get } from 'http';
+import { get as httpsGet } from 'https';
+import { learn } from '../index.js';
+
+/**
+ * Check Node version
+ * @returns {Object} { status: 'ok'|'warn'|'fail', message: string }
+ */
+function checkNodeVersion() {
+  const requiredMajor = 18;
+  const nodeVersion = process.version;
+  const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  
+  if (majorVersion >= requiredMajor) {
+    return { status: 'ok', message: `Node.js ${nodeVersion} (required: >=${requiredMajor}.0.0)` };
+  } else {
+    return { 
+      status: 'fail', 
+      message: `Node.js ${nodeVersion} is too old (required: >=${requiredMajor}.0.0)`,
+      fix: `Upgrade Node.js: nvm install ${requiredMajor} or visit nodejs.org`
+    };
+  }
+}
+
+/**
+ * Check write permissions to output directory
+ * @param {string} projectRoot - Project root
+ * @returns {Object} { status: 'ok'|'fail', message: string }
+ */
+function checkWritePermissions(projectRoot) {
+  try {
+    const veraxDir = resolve(projectRoot, '.verax');
+    mkdirSync(veraxDir, { recursive: true });
+    
+    const testFile = resolve(veraxDir, '.write-test');
+    writeFileSync(testFile, 'test');
+    unlinkSync(testFile);
+    
+    return { status: 'ok', message: 'Can write to .verax directory' };
+  } catch (error) {
+    return {
+      status: 'fail',
+      message: `Cannot write to .verax directory: ${error.message}`,
+      fix: 'Check file permissions or run with appropriate access'
+    };
+  }
+}
+
+/**
+ * Check Playwright availability
+ * @returns {Promise<Object>} { status: 'ok'|'fail', message: string }
+ */
+async function checkPlaywright() {
+  try {
+    const browser = await chromium.launch({ headless: true });
+    await browser.close();
+    return { status: 'ok', message: 'Playwright browser is available' };
+  } catch (error) {
+    // Detect common error messages and provide specific fixes
+    const errorMsg = error.message.toLowerCase();
+    let fix = 'Run: npx playwright install';
+    
+    if (errorMsg.includes('chromium') || errorMsg.includes('executable')) {
+      fix = 'Run: npx playwright install chromium';
+    } else if (errorMsg.includes('missing') || errorMsg.includes('not found')) {
+      fix = 'Run: npx playwright install --with-deps chromium';
+    }
+    
+    return {
+      status: 'fail',
+      message: `Playwright browser not available: ${error.message}`,
+      fix: fix
+    };
+  }
+}
+
+/**
+ * Check project detection and expectations
+ * @param {string} projectRoot - Project root
+ * @returns {Promise<Object>} { status: 'ok'|'warn', message: string, details: Object }
+ */
+async function checkProjectExpectations(projectRoot) {
+  try {
+    const manifest = await learn(projectRoot);
+    const projectType = manifest.projectType || 'unknown';
+    const expectationsCount = manifest.learnTruth?.expectationsDiscovered || 0;
+    
+    if (expectationsCount > 0) {
+      return {
+        status: 'ok',
+        message: `Project type: ${projectType}, ${expectationsCount} expectations found`,
+        details: {
+          projectType,
+          expectationsCount,
+          routesCount: manifest.publicRoutes?.length || 0
+        }
+      };
+    } else {
+      return {
+        status: 'warn',
+        message: `Project type: ${projectType}, but 0 expectations found`,
+        details: {
+          projectType,
+          expectationsCount: 0
+        },
+        fix: 'Add static patterns (HTML links, static fetch calls, or state mutations)'
+      };
+    }
+  } catch (error) {
+    return {
+      status: 'fail',
+      message: `Failed to analyze project: ${error.message}`,
+      fix: 'Check that projectRoot is correct and project is readable'
+    };
+  }
+}
+
+/**
+ * Check URL reachability
+ * @param {string} url - URL to check
+ * @returns {Promise<Object>} { status: 'ok'|'fail', message: string }
+ */
+async function checkUrlReachability(url) {
+  return new Promise((resolve) => {
+    try {
+      const urlObj = new URL(url);
+      const clientGet = urlObj.protocol === 'https:' ? httpsGet : get;
+
+      const request = clientGet(url, { timeout: 5000 }, (response) => {
+        request.destroy();
+        if (response.statusCode >= 200 && response.statusCode < 400) {
+          resolve({ status: 'ok', message: `URL ${url} is reachable (${response.statusCode})` });
+        } else {
+          resolve({ 
+            status: 'warn', 
+            message: `URL ${url} returned ${response.statusCode}`,
+            fix: 'Verify URL is correct and server is running'
+          });
+        }
+      });
+      
+      request.on('error', (error) => {
+        resolve({
+          status: 'fail',
+          message: `Cannot reach ${url}: ${error.message}`,
+          fix: 'Ensure server is running and URL is correct'
+        });
+      });
+      
+      request.on('timeout', () => {
+        request.destroy();
+        resolve({
+          status: 'warn',
+          message: `URL ${url} did not respond within 5 seconds`,
+          fix: 'Check if server is running and accessible'
+        });
+      });
+      
+      request.setTimeout(5000);
+    } catch (error) {
+      resolve({
+        status: 'fail',
+        message: `Invalid URL: ${error.message}`,
+        fix: 'Provide a valid URL (e.g., http://localhost:3000)'
+      });
+    }
+  });
+}
+
+/**
+ * Run doctor checks
+ * @param {Object} options - { projectRoot, url, json }
+ * @returns {Promise<Object>} Doctor results
+ */
+export async function runDoctor(options = {}) {
+  const { projectRoot = process.cwd(), url = null, json = false } = options;
+  
+  const checks = [];
+  let overallStatus = 'ok';
+  
+  // Check 1: Node version
+  const nodeCheck = checkNodeVersion();
+  checks.push({ name: 'Node.js Version', ...nodeCheck });
+  if (nodeCheck.status === 'fail') overallStatus = 'fail';
+  
+  // Check 2: Write permissions
+  const writeCheck = checkWritePermissions(projectRoot);
+  checks.push({ name: 'Write Permissions', ...writeCheck });
+  if (writeCheck.status === 'fail') overallStatus = 'fail';
+  
+  // Check 3: Playwright
+  const playwrightCheck = await checkPlaywright();
+  checks.push({ name: 'Playwright Browser', ...playwrightCheck });
+  if (playwrightCheck.status === 'fail') overallStatus = 'fail';
+  
+  // Check 4: Project expectations
+  const projectCheck = await checkProjectExpectations(projectRoot);
+  checks.push({ name: 'Project Analysis', ...projectCheck });
+  if (projectCheck.status === 'fail') overallStatus = 'fail';
+  else if (projectCheck.status === 'warn' && overallStatus === 'ok') overallStatus = 'warn';
+  
+  // Check 5: URL reachability (if provided)
+  if (url) {
+    const urlCheck = await checkUrlReachability(url);
+    checks.push({ name: 'URL Reachability', ...urlCheck });
+    if (urlCheck.status === 'fail') overallStatus = 'fail';
+    else if (urlCheck.status === 'warn' && overallStatus === 'ok') overallStatus = 'warn';
+  }
+  
+  // Collect fixes
+  const fixes = checks.filter(c => c.fix).map(c => c.fix);
+  
+  return {
+    status: overallStatus,
+    checks,
+    fixes
+  };
+}
+
+/**
+ * Print doctor results
+ * @param {Object} results - Doctor results
+ * @param {boolean} json - Whether to output JSON
+ */
+export function printDoctorResults(results, json = false) {
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  
+  // Human-readable output
+  console.error('\n' + '═'.repeat(60));
+  console.error('VERAX Doctor');
+  console.error('═'.repeat(60));
+  
+  const statusEmoji = {
+    'ok': '✅',
+    'warn': '⚠️',
+    'fail': '❌'
+  };
+  
+  for (const check of results.checks) {
+    const emoji = statusEmoji[check.status] || '❓';
+    console.error(`\n${emoji} ${check.name}`);
+    console.error(`   ${check.message}`);
+    if (check.details) {
+      for (const [key, value] of Object.entries(check.details)) {
+        console.error(`   ${key}: ${value}`);
+      }
+    }
+    if (check.fix) {
+      console.error(`   Fix: ${check.fix}`);
+    }
+  }
+  
+  console.error('\n' + '─'.repeat(60));
+  console.error(`Overall Status: ${results.status.toUpperCase()}`);
+  
+  if (results.fixes.length > 0) {
+    console.error('\nRecommended Fixes:');
+    results.fixes.forEach((fix, index) => {
+      console.error(`  ${index + 1}. ${fix}`);
+    });
+  }
+  
+  console.error('═'.repeat(60) + '\n');
+}
+