@odavl/guardian 0.2.0 → 1.0.0

package/src/guardian/config-loader.js

@@ -0,0 +1,162 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = {
+  crawl: {
+    maxPages: 25,
+    maxDepth: 3,
+  },
+  timeouts: {
+    navigationMs: 20000,
+  },
+  output: {
+    dir: './.odavlguardian',
+  }
+};
+
+function findConfigFile(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(current, 'guardian.config.json');
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+function validatePositiveInt(value, name, allowZero = false) {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    throw new Error(`${name} must be a number`);
+  }
+  if (!Number.isInteger(value)) {
+    throw new Error(`${name} must be an integer`);
+  }
+  if (allowZero) {
+    if (value < 0) throw new Error(`${name} must be >= 0`);
+  } else {
+    if (value <= 0) throw new Error(`${name} must be > 0`);
+  }
+}
+
+function validateConfigShape(raw, filePath) {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`Invalid config in ${filePath}: expected an object`);
+  }
+
+  const effective = {
+    crawl: {
+      maxPages: DEFAULTS.crawl.maxPages,
+      maxDepth: DEFAULTS.crawl.maxDepth
+    },
+    timeouts: {
+      navigationMs: DEFAULTS.timeouts.navigationMs
+    },
+    output: {
+      dir: DEFAULTS.output.dir
+    }
+  };
+
+  if (raw.crawl) {
+    if (raw.crawl.maxPages !== undefined) {
+      validatePositiveInt(raw.crawl.maxPages, 'crawl.maxPages');
+      effective.crawl.maxPages = raw.crawl.maxPages;
+    }
+    if (raw.crawl.maxDepth !== undefined) {
+      validatePositiveInt(raw.crawl.maxDepth, 'crawl.maxDepth', true);
+      effective.crawl.maxDepth = raw.crawl.maxDepth;
+    }
+  }
+
+  if (raw.timeouts) {
+    if (raw.timeouts.navigationMs !== undefined) {
+      validatePositiveInt(raw.timeouts.navigationMs, 'timeouts.navigationMs');
+      effective.timeouts.navigationMs = raw.timeouts.navigationMs;
+    }
+  }
+
+  if (raw.output) {
+    if (raw.output.dir !== undefined) {
+      if (typeof raw.output.dir !== 'string' || raw.output.dir.trim() === '') {
+        throw new Error('output.dir must be a non-empty string');
+      }
+      effective.output.dir = raw.output.dir;
+    }
+  }
+
+  return effective;
+}
+
+function applyLocalConfig(inputConfig) {
+  const cliSource = inputConfig._cliSource || {};
+  const discoveredPath = findConfigFile();
+  let fileConfig = null;
+  let fileEffective = null;
+
+  if (discoveredPath) {
+    try {
+      fileConfig = JSON.parse(fs.readFileSync(discoveredPath, 'utf8'));
+      fileEffective = validateConfigShape(fileConfig, discoveredPath);
+    } catch (err) {
+      throw new Error(`Invalid guardian.config.json at ${discoveredPath}: ${err.message}`);
+    }
+  }
+
+  const effective = {
+    crawl: { ...DEFAULTS.crawl },
+    timeouts: { ...DEFAULTS.timeouts },
+    output: { ...DEFAULTS.output }
+  };
+
+  if (fileEffective) {
+    effective.crawl = { ...effective.crawl, ...fileEffective.crawl };
+    effective.timeouts = { ...effective.timeouts, ...fileEffective.timeouts };
+    effective.output = { ...effective.output, ...fileEffective.output };
+  }
+
+  // CLI overrides
+  if (inputConfig.maxPages !== undefined) {
+    validatePositiveInt(inputConfig.maxPages, 'crawl.maxPages');
+    effective.crawl.maxPages = inputConfig.maxPages;
+  }
+  if (inputConfig.maxDepth !== undefined) {
+    validatePositiveInt(inputConfig.maxDepth, 'crawl.maxDepth', true);
+    effective.crawl.maxDepth = inputConfig.maxDepth;
+  }
+  if (inputConfig.timeout !== undefined) {
+    validatePositiveInt(inputConfig.timeout, 'timeouts.navigationMs');
+    effective.timeouts.navigationMs = inputConfig.timeout;
+  }
+  if (inputConfig.artifactsDir !== undefined) {
+    if (typeof inputConfig.artifactsDir !== 'string' || inputConfig.artifactsDir.trim() === '') {
+      throw new Error('output.dir must be a non-empty string');
+    }
+    effective.output.dir = inputConfig.artifactsDir;
+  }
+
+  // Determine source label
+  let source = 'defaults';
+  if (fileEffective) source = 'guardian.config.json';
+  const cliOverride = cliSource.maxPages || cliSource.maxDepth || cliSource.timeout || cliSource.artifactsDir;
+  if (cliOverride) source = 'cli';
+
+  const finalConfig = { ...inputConfig };
+  finalConfig.maxPages = effective.crawl.maxPages;
+  finalConfig.maxDepth = effective.crawl.maxDepth;
+  finalConfig.timeout = effective.timeouts.navigationMs;
+  finalConfig.artifactsDir = effective.output.dir;
+
+  return {
+    config: finalConfig,
+    report: {
+      source,
+      path: fileEffective ? path.resolve(discoveredPath) : null,
+      effective
+    }
+  };
+}
+
+module.exports = { applyLocalConfig, DEFAULTS };

package/src/guardian/drift-detector.js

@@ -0,0 +1,100 @@
+/**
+ * Drift Detection Engine for Journey Results
+ * Deterministic comparison against stored baseline snapshot.
+ */
+
+function buildBaselineFromJourneyResult(result) {
+  const keySteps = (result.executedSteps || []).map(s => ({ id: s.id, success: !!s.success }));
+  const baseline = {
+    decision: result.finalDecision,
+    intent: (result.intentDetection && result.intentDetection.intent) || 'unknown',
+    goalReached: !!(result.goal && result.goal.goalReached),
+    keySteps,
+    timestamp: new Date().toISOString()
+  };
+  return baseline;
+}
+
+function compareAgainstBaseline(baseline, current) {
+  const reasons = [];
+  const currentSteps = {};
+  (current.executedSteps || []).forEach(s => { currentSteps[s.id] = !!s.success; });
+
+  // Decision drift
+  const before = baseline.decision;
+  const after = current.finalDecision;
+  if (before === 'SAFE' && (after === 'RISK' || after === 'DO_NOT_LAUNCH')) {
+    reasons.push(`Decision regressed: ${before} → ${after}`);
+  }
+
+  // Goal drift
+  const baselineGoal = !!baseline.goalReached;
+  const currentGoal = !!(current.goal && current.goal.goalReached);
+  if (baselineGoal && !currentGoal) {
+    reasons.push('Visitors can no longer reach goal');
+  }
+
+  // Intent drift
+  const baselineIntent = (baseline.intent || 'unknown').toLowerCase();
+  const currentIntent = ((current.intentDetection && current.intentDetection.intent) || 'unknown').toLowerCase();
+  if (baselineIntent !== 'unknown' && currentIntent !== 'unknown' && baselineIntent !== currentIntent) {
+    reasons.push(`Site intent changed from ${baselineIntent.toUpperCase()} to ${currentIntent.toUpperCase()}`);
+  }
+
+  // Critical step regression: any step that succeeded before now fails
+  for (const ks of baseline.keySteps || []) {
+    if (ks.success === true) {
+      const now = currentSteps[ks.id];
+      if (now === false || now === undefined) {
+        reasons.push(`Critical step failed: ${ks.id}`);
+      }
+    }
+  }
+
+  return {
+    hasDrift: reasons.length > 0,
+    reasons: reasons
+  };
+}
+
+function classifySeverity(driftInfo, currentResult) {
+  if (!driftInfo || !driftInfo.hasDrift) return 'NONE';
+  
+  const reasons = driftInfo.reasons || [];
+  
+  // CRITICAL conditions:
+  // 1. Decision drifted to DO_NOT_LAUNCH
+  if (currentResult.decision === 'DO_NOT_LAUNCH') {
+    // Exception: if run stability is very low (<50), downgrade to WARN
+    // unless site is unreachable
+    if (!reasons.some(r => r.includes('SITE_UNREACHABLE'))) {
+      const stabilityScore = currentResult.stability?.runStabilityScore || 100;
+      if (stabilityScore < 50) {
+        return 'WARN'; // Downgrade: unstable run, re-check recommended
+      }
+    }
+    return 'CRITICAL';
+  }
+  
+  // 2. Site unreachable - always CRITICAL (do not downgrade)
+  if (reasons.some(r => r.includes('SITE_UNREACHABLE'))) return 'CRITICAL';
+  
+  // 3. Goal drift (visitors can no longer reach goal)
+  if (reasons.some(r => r.includes('goal drift: true → false'))) {
+    // Check stability before deciding
+    const stabilityScore = currentResult.stability?.runStabilityScore || 100;
+    if (stabilityScore < 50) {
+      return 'WARN'; // Downgrade: unstable, suspicious drift
+    }
+    return 'CRITICAL';
+  }
+  
+  // Default: WARN for all other drift
+  return 'WARN';
+}
+
+module.exports = {
+  buildBaselineFromJourneyResult,
+  compareAgainstBaseline,
+  classifySeverity
+};

package/src/guardian/enhanced-html-reporter.js

@@ -12,11 +12,38 @@
 
 const fs = require('fs');
 const path = require('path');
+const { analyzePatterns, loadRecentRunsForSite } = require('./pattern-analyzer');
+const {
+  formatVerdictStatus,
+  formatConfidence,
+  formatVerdictWhy,
+  formatKeyFindings,
+  formatLimits,
+  formatConfidenceMicroLine,
+  formatFirstRunNote,
+  formatJourneyMessage,
+  formatNextRunHint,
+  formatPatternSummary,
+  formatPatternWhy,
+  formatPatternFocus,
+  formatPatternLimits,
+  formatConfidenceDrivers,
+  formatFocusSummary,
+  formatDeltaInsight,
+  // Stage V / Step 5.2: Silence Discipline helpers
+  shouldRenderFocusSummary,
+  shouldRenderDeltaInsight,
+  shouldRenderPatterns,
+  shouldRenderConfidenceDrivers,
+  shouldRenderJourneyMessage,
+  shouldRenderNextRunHint,
+  shouldRenderFirstRunNote
+} = require('./text-formatters');
 
 /**
  * Generate enhanced HTML report
  */
-function generateEnhancedHtml(snapshot, outputDir) {
+function generateEnhancedHtml(snapshot, outputDir, options = {}) {
   if (!snapshot) {
     return '<html><body><h1>No snapshot data</h1></body></html>';
   }
@@ -51,12 +78,24 @@ function generateEnhancedHtml(snapshot, outputDir) {
     .meta { color: #7f8c8d; margin-bottom: 30px; }
     .meta span { display: inline-block; margin-right: 20px; }
     .summary { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 20px; margin-bottom: 30px; }
+      .verdict-card { background: #ffffff; border: 2px solid #3498db; padding: 16px; border-radius: 8px; margin: 20px 0; }
+      .verdict-title { font-weight: 600; font-size: 18px; color: #2c3e50; margin-bottom: 8px; }
+      .verdict-item { margin: 4px 0; }
+      .bullets { margin-top: 8px; padding-left: 18px; }
     .stat-card { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 20px; border-radius: 8px; text-align: center; }
     .stat-card.critical { background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%); }
     .stat-card.warning { background: linear-gradient(135deg, #fad961 0%, #f76b1c 100%); }
     .stat-card.info { background: linear-gradient(135deg, #a8edea 0%, #fed6e3 100%); color: #333; }
     .stat-number { font-size: 48px; font-weight: bold; margin-bottom: 10px; }
     .stat-label { font-size: 14px; text-transform: uppercase; letter-spacing: 1px; opacity: 0.9; }
+    .pattern-item { background: #f9f9f9; border-left: 4px solid #9b59b6; padding: 15px; margin-bottom: 15px; border-radius: 4px; }
+    .pattern-item.high { border-left-color: #e74c3c; }
+    .pattern-item.medium { border-left-color: #f39c12; }
+    .pattern-item.low { border-left-color: #95a5a6; }
+    .pattern-summary { font-weight: 600; margin-bottom: 8px; }
+    .pattern-why { color: #7f8c8d; font-size: 14px; margin-bottom: 8px; }
+    .pattern-limits { color: #95a5a6; font-size: 13px; font-style: italic; }
+    .pattern-focus { color: #2c3e50; font-size: 14px; margin-bottom: 6px; }
     .risk-item { background: #fff; border-left: 4px solid #e74c3c; padding: 15px; margin-bottom: 15px; border-radius: 4px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
     .risk-item.warning { border-left-color: #f39c12; }
     .risk-item.info { border-left-color: #3498db; }
@@ -99,6 +138,179 @@ function generateEnhancedHtml(snapshot, outputDir) {
       <span><strong>Date:</strong> ${meta.createdAt || 'Unknown'}</span>
     </div>
 
+    <!-- Verdict & Confidence -->
+    <div class="verdict-card">
+      <div class="verdict-title">Verdict & Confidence</div>
+      ${(() => {
+        const v = snapshot.verdict || meta.verdict || null;
+        if (!v) return '<div class="verdict-item">No verdict available</div>';
+        // First-run context detection
+        let firstRunLine = '';
+        var journeyLineHtml = '';
+        let priorRuns = 0; // Declare in outer scope for use in drivers logic
+        try {
+          const artifactsDir = options.artifactsDir;
+          const siteSlug = options.siteSlug || (meta.siteSlug);
+          if (artifactsDir && siteSlug) {
+            const runs = loadRecentRunsForSite(artifactsDir, siteSlug, 10);
+            priorRuns = runs.length;
+          }
+          const runIndex = priorRuns;
+          if (shouldRenderFirstRunNote(runIndex)) {
+            firstRunLine = `<div class=\"verdict-item\"><em>${formatFirstRunNote()}</em></div>`;
+          }
+          // Confidence interpretation micro-line (Stage IV)
+          const cfLevel = (v.confidence || {}).level;
+          const showMicro = ((cfLevel && cfLevel !== 'high') || runIndex < 2);
+          var confidenceLineHtml = showMicro ? `<div class=\"verdict-item\">${formatConfidenceMicroLine()}</div>` : '';
+
+          // Three-Runs Journey Messaging (Stage IV)
+          try {
+            if (artifactsDir && siteSlug) {
+              const patterns = analyzePatterns(artifactsDir, siteSlug, 10) || [];
+              const patternsPresent = patterns.length > 0;
+              if (!patternsPresent) {
+                if (shouldRenderJourneyMessage(runIndex)) {
+                  const journeyMsg = formatJourneyMessage(runIndex);
+                  if (journeyMsg) {
+                    journeyLineHtml = `<div class=\"verdict-item\">${journeyMsg}</div>`;
+                  }
+                }
+              }
+            }
+          } catch (_) {}
+        } catch (_) {}
+        const vStatus = formatVerdictStatus(v);
+        const vConf = formatConfidence(v);
+        const vWhy = formatVerdictWhy(v);
+        const vFindings = formatKeyFindings(v);
+        const vLimits = formatLimits(v);
+        const vNextHint = formatNextRunHint(v);
+
+        // Confidence Drivers Card (Layer 4 / Step 4.2)
+        // Stage V / Step 5.2: Use centralized suppression helper
+        let vDrivers = [];
+        if (shouldRenderConfidenceDrivers(v, priorRuns)) {
+          vDrivers = formatConfidenceDrivers(v);
+        }
+
+        // Focus Summary (Layer 5 - Advisor Mode)
+        // Stage V / Step 5.2: Use centralized suppression helper
+        let vFocus = [];
+        try {
+          const patterns = options.artifactsDir && options.siteSlug 
+            ? analyzePatterns(options.artifactsDir, options.siteSlug, 10) 
+            : [];
+          if (shouldRenderFocusSummary(v, patterns)) {
+            vFocus = formatFocusSummary(v, patterns);
+          }
+        } catch (_) {}
+
+        // Delta Insight (Stage V / Step 5.1)
+        let deltaImproved = [];
+        let deltaRegressed = [];
+        try {
+          if (options.artifactsDir && options.siteSlug) {
+            const runs = loadRecentRunsForSite(options.artifactsDir, options.siteSlug, 10);
+            if (runs.length >= 2) {
+              const previousRun = runs[1];
+              let previousVerdict = null;
+              let previousPatterns = [];
+              
+              if (previousRun.snapshotPath) {
+                try {
+                  const prevSnap = JSON.parse(fs.readFileSync(previousRun.snapshotPath, 'utf8'));
+                  previousVerdict = prevSnap.verdict || prevSnap.meta?.verdict || null;
+                } catch (_) {}
+              }
+              
+              try {
+                previousPatterns = analyzePatterns(options.artifactsDir, options.siteSlug, 10, previousRun.runId) || [];
+              } catch (_) {}
+              
+              const detectedPatterns = options.artifactsDir && options.siteSlug 
+                ? analyzePatterns(options.artifactsDir, options.siteSlug, 10) 
+                : [];
+              
+              const delta = formatDeltaInsight(v, previousVerdict, detectedPatterns, previousPatterns);
+              
+              // Stage V / Step 5.2: Use centralized suppression helper
+              if (shouldRenderDeltaInsight(delta)) {
+                deltaImproved = delta.improved || [];
+                deltaRegressed = delta.regressed || [];
+              }
+            }
+          }
+        } catch (_) {}
+
+        return `
+          <div class="verdict-item"><strong>Verdict:</strong> ${vStatus}</div>
+          <div class="verdict-item"><strong>Confidence:</strong> ${vConf}</div>
+          ${confidenceLineHtml || ''}
+          ${vWhy ? `<div class="verdict-item"><strong>Why:</strong> ${vWhy}</div>` : ''}
+          ${vDrivers.length ? `<div class="verdict-item"><strong>Confidence Drivers:</strong>
+            <ul class="bullets">${vDrivers.map(d => `<li>${d}</li>`).join('')}</ul>
+          </div>` : ''}
+          ${vFocus.length ? `<div class="verdict-item"><strong>Focus Summary:</strong>
+            <ul class="bullets">${vFocus.map(f => `<li>${f}</li>`).join('')}</ul>
+          </div>` : ''}
+          ${(deltaImproved.length || deltaRegressed.length) ? `<div class="verdict-item"><strong>Delta Insight:</strong>
+            <ul class="bullets">
+              ${deltaImproved.map(line => `<li>✅ ${line}</li>`).join('')}
+              ${deltaRegressed.map(line => `<li>⚠️ ${line}</li>`).join('')}
+            </ul>
+          </div>` : ''}
+          ${firstRunLine}
+          ${journeyLineHtml}
+          ${vFindings.length ? `<div class="verdict-item"><strong>Key Findings:</strong>
+            <ul class="bullets">${vFindings.map(f => `<li>${f}</li>`).join('')}</ul>
+          </div>` : ''}
+          ${vLimits.length ? `<div class="verdict-item"><strong>Limits:</strong>
+            <ul class="bullets">${vLimits.map(l => `<li>${l}</li>`).join('')}</ul>
+          </div>` : ''}
+          ${(() => {
+            if (shouldRenderNextRunHint(v)) {
+              const hint = formatNextRunHint(v);
+              return hint ? `<div class="verdict-item"><strong>Next Run Hint:</strong> ${hint}</div>` : '';
+            }
+            return '';
+          })()}
+        `;
+      })()}
+    </div>
+
+    <!-- Observed Patterns -->
+    ${(() => {
+      if (!options.artifactsDir || !options.siteSlug) return '';
+      try {
+        const patterns = analyzePatterns(options.artifactsDir, options.siteSlug, 10);
+        // Stage V / Step 5.2: Use centralized suppression helper
+        if (!shouldRenderPatterns(patterns)) return '';
+        return `
+    <div style="margin-top: 30px;">
+      <h2>🔍 Observed Patterns (Cross-Run Analysis)</h2>
+      ${patterns.slice(0, 5).map((pattern, idx) => {
+        const summary = formatPatternSummary(pattern);
+        const why = formatPatternWhy(pattern);
+        const focus = formatPatternFocus(pattern);
+        const limits = formatPatternLimits(pattern);
+        return `
+      <div class="pattern-item ${pattern.confidence}">
+        <div class="pattern-summary">${idx + 1}. ${summary}</div>
+        <div class="pattern-why">${why}</div>
+        ${focus ? `<div class="pattern-focus">${focus}</div>` : ''}
+        ${limits ? `<div class="pattern-limits">Limits: ${limits}</div>` : ''}
+      </div>
+      `;
+      }).join('')}
+      ${patterns.length > 5 ? `<p style="color: #7f8c8d; margin-top: 10px;">... ${patterns.length - 5} more pattern(s) detected.</p>` : ''}
+    </div>
+        `;
+      } catch (err) {
+        return '';
+      }
+    })()}
+
     <!-- Summary Cards -->
     <div class="summary">
       <div class="stat-card critical">
@@ -155,12 +367,17 @@ function generateEnhancedHtml(snapshot, outputDir) {
 `;
     attempts.forEach(attempt => {
       const outcomeClass = attempt.outcome === 'SUCCESS' ? 'success' : 'failure';
+      const outcomeLabel = attempt.outcome === 'SKIPPED' ? 'Not Executed' : (attempt.outcome || 'UNKNOWN');
+      const reasonLine = attempt.outcome === 'SKIPPED' && attempt.skipReason ? `<div class="risk-details" style="font-size:12px;color:#7f8c8d;">Reason: ${attempt.skipReason}</div>` : '';
       html += `
       <li class="attempt-item">
         <span class="attempt-name">${attempt.attemptName || attempt.attemptId}</span>
-        <span class="attempt-outcome ${outcomeClass}">${attempt.outcome || 'UNKNOWN'}</span>
+        <span class="attempt-outcome ${outcomeClass}">${outcomeLabel}</span>
       </li>
 `;
+      if (reasonLine) {
+        html += reasonLine;
+      }
     });
     html += `
     </ul>
@@ -286,8 +503,8 @@ function generateEnhancedHtml(snapshot, outputDir) {
 /**
  * Write enhanced HTML report to file
  */
-function writeEnhancedHtml(snapshot, outputDir) {
-  const html = generateEnhancedHtml(snapshot, outputDir);
+function writeEnhancedHtml(snapshot, outputDir, options = {}) {
+  const html = generateEnhancedHtml(snapshot, outputDir, options);
   const reportPath = path.join(outputDir, 'report.html');
   
   const dir = path.dirname(reportPath);

package/src/guardian/env-guard.js

@@ -0,0 +1,127 @@
+/**
+ * Environment Readiness Guard
+ * 
+ * Detects missing critical dependencies and fails early with actionable errors.
+ * NO stack traces. NO noise. Just the fix.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Check if Playwright browsers are installed
+ */
+function checkPlaywrightBrowsers() {
+  try {
+    // Playwright caches browsers under ~/.cache/ms-playwright or similar
+    // Quick check: can we require the Playwright package?
+    require('playwright');
+    // If that works, browsers should be available
+    return { ok: true };
+  } catch (e) {
+    return {
+      ok: false,
+      error: 'Playwright not properly installed or browsers missing',
+      fix: 'npx playwright install'
+    };
+  }
+}
+
+/**
+ * Check Node version compatibility
+ */
+function checkNodeVersion() {
+  const version = process.version; // e.g., "v18.0.0"
+  const major = parseInt(version.slice(1).split('.')[0], 10);
+  if (major < 18) {
+    return {
+      ok: false,
+      error: `Node.js ${version} is too old (minimum: 18.0.0)`,
+      fix: 'Upgrade Node.js to version 18 or later'
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Check disk space (rough heuristic)
+ */
+function checkDiskSpace() {
+  try {
+    // Try to write a small temp file
+    const tempFile = path.join(require('os').tmpdir(), `.guardian-space-check-${Date.now()}`);
+    fs.writeFileSync(tempFile, 'test', 'utf8');
+    fs.unlinkSync(tempFile);
+    return { ok: true };
+  } catch (e) {
+    return {
+      ok: false,
+      error: 'Insufficient disk space or write permission denied',
+      fix: 'Ensure /tmp (or temp directory) has at least 100MB free'
+    };
+  }
+}
+
+/**
+ * Run all environment checks
+ * @returns {object} - { allOk: boolean, issues: array }
+ */
+function checkEnvironment() {
+  const checks = [
+    { name: 'Node.js version', check: checkNodeVersion },
+    { name: 'Playwright browsers', check: checkPlaywrightBrowsers },
+    { name: 'Disk space', check: checkDiskSpace }
+  ];
+
+  const issues = [];
+
+  for (const { name, check } of checks) {
+    try {
+      const result = check();
+      if (!result.ok) {
+        issues.push({
+          name,
+          error: result.error,
+          fix: result.fix
+        });
+      }
+    } catch (e) {
+      issues.push({
+        name,
+        error: e.message,
+        fix: 'See documentation or contact support'
+      });
+    }
+  }
+
+  return {
+    allOk: issues.length === 0,
+    issues
+  };
+}
+
+/**
+ * Print environment guard error and exit
+ */
+function failWithEnvironmentError(issues) {
+  console.error('\n❌ Environment Check Failed\n');
+  console.error('Guardian cannot run due to missing or incompatible dependencies:\n');
+
+  issues.forEach((issue, idx) => {
+    console.error(`${idx + 1}. ${issue.name}`);
+    console.error(`   Error:  ${issue.error}`);
+    console.error(`   Fix:    ${issue.fix}`);
+    console.error('');
+  });
+
+  console.error('After fixing the above, run Guardian again:\n');
+  console.error('  guardian reality --url <your-site-url>\n');
+
+  process.exit(1);
+}
+
+module.exports = {
+  checkEnvironment,
+  failWithEnvironmentError
+};