@odavl/guardian 0.2.0 → 1.0.0

package/src/guardian/failure-intelligence.js

@@ -0,0 +1,173 @@
+/**
+ * Phase 12.3: Human Failure Intelligence
+ * Deterministic heuristics to explain failures like a human.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const STORE_DIR = path.join(os.homedir(), '.odavl-guardian', 'failures');
+const SIGNATURE_FILE = path.join(STORE_DIR, 'signatures.json');
+
+function ensureStore() {
+  if (!fs.existsSync(STORE_DIR)) {
+    fs.mkdirSync(STORE_DIR, { recursive: true });
+  }
+}
+
+function loadSignatures() {
+  ensureStore();
+  if (!fs.existsSync(SIGNATURE_FILE)) {
+    return { sites: {} };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(SIGNATURE_FILE, 'utf-8'));
+  } catch {
+    return { sites: {} };
+  }
+}
+
+function saveSignatures(data) {
+  ensureStore();
+  fs.writeFileSync(SIGNATURE_FILE, JSON.stringify(data, null, 2), 'utf-8');
+  return data;
+}
+
+function getDomain(url) {
+  try {
+    const u = new URL(url);
+    return u.hostname;
+  } catch {
+    return url;
+  }
+}
+
+function classifyFailureStage(stepIndex, totalSteps, goalIndex, success) {
+  if (success) return 'AFTER_GOAL';
+  if (typeof goalIndex !== 'number') goalIndex = totalSteps - 1;
+  if (stepIndex < goalIndex) return 'BEFORE_GOAL';
+  if (stepIndex === goalIndex) return 'AT_GOAL';
+  return 'AFTER_GOAL';
+}
+
+function determineCause(step) {
+  // Deterministic priority
+  // 1) CTA_NOT_FOUND
+  // 2) ELEMENT_NOT_FOUND on submit
+  // 3) TIMEOUT near navigation
+  // 4) INTENT_DRIFT
+  const code = step?.errorCode || step?.result?.errorCode || step?.status;
+  const tags = step?.tags || step?.result?.tags || [];
+  const action = (step?.action || step?.name || '').toLowerCase();
+
+  if (code === 'CTA_NOT_FOUND' || tags.includes('cta')) {
+    return { cause: 'Primary action not visible', hint: 'Make the main signup button visible without scrolling.' };
+  }
+
+  if ((code === 'ELEMENT_NOT_FOUND' || code === 'MISSING_ELEMENT') && (tags.includes('submit') || action.includes('submit'))) {
+    return { cause: 'Form submission blocked', hint: 'Ensure the submit button exists and is enabled.' };
+  }
+
+  if (code === 'TIMEOUT' || (tags.includes('nav') && (code === 'SLOW' || code === 'BLOCKED'))) {
+    return { cause: 'Slow or blocked navigation', hint: 'Speed up routing or ensure target page loads reliably.' };
+  }
+
+  if (code === 'INTENT_DRIFT' || tags.includes('drift')) {
+    return { cause: 'Page no longer matches visitor intent', hint: 'Restore intent-aligned content and CTA on the target page.' };
+  }
+
+  return { cause: 'Unknown failure', hint: 'Investigate logs and UI for missing elements or errors.' };
+}
+
+function analyzeFailure(journeyResult) {
+  const totalSteps = (journeyResult.executedSteps?.length || 0) + (journeyResult.failedSteps?.length || 0);
+  const steps = journeyResult.executedSteps || [];
+  const failed = journeyResult.failedSteps || [];
+
+  let failureStepId = null;
+  let failureStepIdx = -1;
+  let failureStep = null;
+
+  if (failed.length > 0) {
+    // failedSteps may be an array of IDs; locate the first failing step
+    const firstFailId = typeof failed[0] === 'string' ? failed[0] : failed[0]?.id || failed[0];
+    failureStepId = firstFailId;
+    failureStepIdx = steps.findIndex(s => s.id === firstFailId);
+    if (failureStepIdx === -1 && typeof firstFailId === 'number') {
+      failureStepIdx = firstFailId;
+    }
+  } else {
+    // Otherwise, look for error status in executed steps
+    failureStepIdx = steps.findIndex(s => s.status === 'error' || s.status === 'timeout' || s.result?.status === 'error');
+    if (failureStepIdx !== -1) failureStepId = steps[failureStepIdx].id;
+  }
+
+  if (failureStepIdx === -1) {
+    // No explicit failure found; classify after goal if success, else before goal as default
+    const stage = classifyFailureStage(totalSteps - 1, totalSteps, totalSteps - 1, journeyResult.goal?.goalReached === true || journeyResult.success === true);
+    const causeInfo = { cause: 'Unknown failure', hint: 'Investigate logs and UI for missing elements or errors.' };
+    return {
+      failureStepId: failureStepId,
+      failureStage: stage,
+      cause: causeInfo.cause,
+      hint: causeInfo.hint,
+    };
+  }
+
+  failureStep = steps[failureStepIdx] || null;
+  const goalReached = journeyResult.goal?.goalReached === true || journeyResult.success === true;
+  let stage = 'AFTER_GOAL';
+  if (!goalReached) {
+    // Default to BEFORE_GOAL when goal not reached unless explicitly marked as goal step
+    const goalStepId = journeyResult.goal?.goalStepId;
+    if (goalStepId && (failureStep?.id === goalStepId || failureStepIdx === goalStepId)) {
+      stage = 'AT_GOAL';
+    } else {
+      stage = 'BEFORE_GOAL';
+    }
+  }
+  const causeInfo = determineCause(failureStep);
+
+  return {
+    failureStepId: failureStep?.id || failureStepIdx,
+    failureStage: stage,
+    cause: causeInfo.cause,
+    hint: causeInfo.hint,
+  };
+}
+
+function buildSignature(info) {
+  return `${info.failureStage}|${info.cause}|${info.failureStepId ?? 'unknown'}`;
+}
+
+function recordSignature(siteUrl, info) {
+  const data = loadSignatures();
+  const domain = getDomain(siteUrl);
+  if (!data.sites[domain]) data.sites[domain] = { signatures: {} };
+  const sig = buildSignature(info);
+  const entry = data.sites[domain].signatures[sig] || { count: 0, lastSeen: null };
+  entry.count += 1;
+  entry.lastSeen = new Date().toISOString();
+  data.sites[domain].signatures[sig] = entry;
+  saveSignatures(data);
+  return { signature: sig, count: entry.count };
+}
+
+function getSignatureCount(siteUrl, info) {
+  const data = loadSignatures();
+  const domain = getDomain(siteUrl);
+  const sig = buildSignature(info);
+  return data.sites[domain]?.signatures?.[sig]?.count || 0;
+}
+
+module.exports = {
+  analyzeFailure,
+  determineCause,
+  classifyFailureStage,
+  recordSignature,
+  getSignatureCount,
+  buildSignature,
+  loadSignatures,
+  saveSignatures,
+};

package/src/guardian/first-run-profile.js

@@ -0,0 +1,89 @@
+/**
+ * First-Run State Tracking
+ * 
+ * Detects if this is the user's first invocation of Guardian
+ * Applies conservative "golden path" profile on first run
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const FIRST_RUN_STATE_DIR = path.join(os.homedir(), '.odavl-guardian');
+const FIRST_RUN_MARKER = path.join(FIRST_RUN_STATE_DIR, 'first-run-complete.json');
+
+/**
+ * Check if this is the user's first run
+ */
+function isFirstRun() {
+  return !fs.existsSync(FIRST_RUN_MARKER);
+}
+
+/**
+ * Mark first run as complete
+ */
+function markFirstRunComplete() {
+  try {
+    if (!fs.existsSync(FIRST_RUN_STATE_DIR)) {
+      fs.mkdirSync(FIRST_RUN_STATE_DIR, { recursive: true });
+    }
+    fs.writeFileSync(FIRST_RUN_MARKER, JSON.stringify({
+      completedAt: new Date().toISOString(),
+      version: require('../../package.json').version
+    }), 'utf8');
+  } catch (e) {
+    // Silent fail if we can't write state
+  }
+}
+
+/**
+ * Get first-run execution profile
+ * Conservative settings for initial scan
+ */
+function getFirstRunProfile() {
+  return {
+    // Timeouts: more generous for first run
+    timeout: 25000, // 25s (vs default 20s)
+    // Disable resource-intensive options
+    parallel: 1, // Single-threaded
+    failFast: false,
+    fast: false, // Don't skip for speed
+    // Minimal discovery
+    enableDiscovery: false,
+    enableCrawl: true, // Light crawl only
+    maxPages: 10, // Fewer pages
+    maxDepth: 2, // Shallower
+    // Evidence capture
+    enableScreenshots: true,
+    enableTrace: false, // Traces can slow things down
+    headful: false, // Headless is faster
+    // Safety
+    includeUniversal: false,
+    // CI mode off for first run (more readable output)
+    ciMode: false
+  };
+}
+
+/**
+ * Apply first-run profile to config
+ * Merges conservative defaults without overwriting user intent on --url
+ */
+function applyFirstRunProfile(userConfig) {
+  if (!isFirstRun()) {
+    return userConfig; // Not first run; use as-is
+  }
+
+  const profile = getFirstRunProfile();
+  return {
+    ...profile,
+    ...userConfig, // User overrides profile
+    baseUrl: userConfig.baseUrl // Preserve required --url
+  };
+}
+
+module.exports = {
+  isFirstRun,
+  markFirstRunComplete,
+  getFirstRunProfile,
+  applyFirstRunProfile
+};

package/src/guardian/first-run.js

@@ -41,9 +41,14 @@ function printWelcome(label = 'ODAVL Guardian') {
   console.log(lines.join('\n'));
 }
 
+function printFirstRunHint() {
+  console.log("\nTip: Try 'guardian smoke <url>' for a fast CI-ready check.\n");
+}
+
 module.exports = {
   isFirstRun,
   hasRunBefore,
   markAsRun,
-  printWelcome
+  printWelcome,
+  printFirstRunHint
 };

package/src/guardian/flag-validator.js

@@ -5,7 +5,9 @@
 
 const VALID_SUBCOMMANDS = [
   'init', 'protect', 'reality', 'attempt', 'baseline',
-  'presets', 'evaluate', 'version', 'flow', 'scan', 'smoke'
+  'presets', 'template', 'list', 'cleanup', 'evaluate', 'version', 'flow', 'scan', 'smoke', 'check',
+  'journey-scan', 'journey', 'live', 'plan', 'upgrade', 'ci', 'feedback',
+  'sites', 'users', 'audit', 'export', 'recipe'
 ];
 
 const VALID_GLOBAL_FLAGS = [
@@ -14,13 +16,25 @@ const VALID_GLOBAL_FLAGS = [
 
 const VALID_SUBCOMMAND_FLAGS = {
   'scan': ['--url', '--preset', '--artifacts', '--policy', '--headful', '--no-trace', '--no-screenshots', '--watch', '-w', '--fast', '--fail-fast', '--timeout-profile', '--attempts', '--parallel', '--help', '-h'],
+  'journey-scan': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--headful', '--help', '-h'],
+  'journey': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--headful', '--help', '-h'],
+  'live': ['--url', '--preset', '--out', '--artifacts', '--timeout', '--interval', '--cooldown', '--headful', '--help', '-h'],
   'protect': ['--url', '--policy', '--webhook', '--watch', '-w', '--fast', '--fail-fast', '--timeout-profile', '--attempts', '--parallel', '--help', '-h'],
-  'reality': ['--url', '--attempts', '--artifacts', '--policy', '--discover', '--universal', '--webhook', '--headful', '--watch', '-w', '--no-trace', '--no-screenshots', '--fast', '--fail-fast', '--timeout-profile', '--parallel', '--help', '-h'],
+  'reality': ['--url', '--attempts', '--artifacts', '--policy', '--preset', '--discover', '--universal', '--webhook', '--headful', '--watch', '-w', '--no-trace', '--no-screenshots', '--fast', '--fail-fast', '--timeout-profile', '--parallel', '--help', '-h', '--max-pages', '--max-depth', '--timeout'],
   'attempt': ['--url', '--attempt', '--artifacts', '--headful', '--no-trace', '--no-screenshots', '--help', '-h'],
   'smoke': ['--url', '--headful', '--budget-ms', '--help', '-h'],
+  'check': ['--url', '--headful', '--budget-ms', '--help', '-h'],
   'baseline': [],
   'init': ['--preset', '--help', '-h'],
-  'presets': ['--help', '-h']
+  'list': ['--artifacts', '--failed', '--site', '--limit', '--help', '-h'],
+  'cleanup': ['--artifacts', '--older-than', '--keep-latest', '--failed-only', '--help', '-h'],
+  'presets': ['--help', '-h'],
+  'template': ['--output', '--help', '-h'],
+  'sites': ['--project', '--help', '-h'],
+  'users': ['--help', '-h'],
+  'audit': ['--limit', '--action', '--user', '--help', '-h'],
+  'export': ['--format', '--output', '--help', '-h'],
+  'recipe': ['--url', '--file', '--out', '--force', '--help', '-h']
 };
 
 function validateFlags(argv) {

package/src/guardian/html-reporter.js

@@ -5,6 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { getFounderBadgeHTML } = require('../founder/founder-tracker');
 
 class GuardianHTMLReporter {
   /**
@@ -207,6 +208,7 @@ class GuardianHTMLReporter {
             <div class="subtitle">Market Reality Testing Report</div>
         </div>
 
+        ${getFounderBadgeHTML()}
         ${this.generateVerdictSection(jsonReport)}
         ${this.generateMetricsSection(jsonReport)}
         ${this.generateReasonsSection(jsonReport)}