@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/guardian/attempt-registry.js

@@ -3,7 +3,17 @@
  * Phase 3: supports multiple curated attempts
  */
 
-const DEFAULT_ATTEMPTS = ['contact_form', 'language_switch', 'newsletter_signup', 'signup', 'login', 'checkout'];
+const DEFAULT_ATTEMPTS = [
+  'site_smoke',
+  'primary_ctas',
+  'contact_discovery_v2',
+  'contact_form',
+  'language_switch',
+  'newsletter_signup',
+  'signup',
+  'login',
+  'checkout'
+];
 
 const attemptDefinitions = {
   contact_form: {
@@ -158,6 +168,37 @@ const attemptDefinitions = {
     ]
   },
 
+  // Universal Attempts (no instrumentation required)
+  site_smoke: {
+    id: 'site_smoke',
+    name: 'Site Smoke Navigation',
+    goal: 'Probe homepage stability and internal navigation',
+    riskCategory: 'TRUST/UX',
+    source: 'universal',
+    baseSteps: [],
+    successConditions: []
+  },
+
+  primary_ctas: {
+    id: 'primary_ctas',
+    name: 'Primary CTA Coverage',
+    goal: 'Verify primary CTAs navigate correctly',
+    riskCategory: 'LEAD',
+    source: 'universal',
+    baseSteps: [],
+    successConditions: []
+  },
+
+  contact_discovery_v2: {
+    id: 'contact_discovery_v2',
+    name: 'Contact Discovery v2',
+    goal: 'Find contact surfaces (mailto or contact route)',
+    riskCategory: 'TRUST/UX',
+    source: 'universal',
+    baseSteps: [],
+    successConditions: []
+  },
+
   // Universal Reality Pack: deterministic, zero-config safety checks
   universal_reality: {
     id: 'universal_reality',

package/src/guardian/attempt-relevance.js

@@ -0,0 +1,106 @@
+/**
+ * Attempt Relevance Decision Engine
+ * Determines which attempts should run based on site introspection.
+ */
+
+/**
+ * Relevance rules mapping attempt IDs to required introspection flags
+ */
+const RELEVANCE_RULES = {
+  'contact_form': { requires: 'hasContactForm', reason: 'No contact form detected' },
+  'language_switch': { requires: 'hasLanguageSwitch', reason: 'No language switch detected' },
+  'signup': { requires: 'hasSignup', reason: 'No signup elements detected' },
+  'login': { requires: 'hasLogin', reason: 'No login elements detected' },
+  'checkout': { requires: 'hasCheckout', reason: 'No checkout elements detected' },
+  'newsletter_signup': { requires: 'hasNewsletter', reason: 'No newsletter signup detected' }
+};
+
+/**
+ * Filter attempts based on site introspection
+ * 
+ * @param {Array} attempts - Array of attempt objects with {id, ...}
+ * @param {Object} introspection - Result from inspectSite()
+ * @returns {Object} { toRun: Array, toSkip: Array }
+ */
+function filterAttempts(attempts, introspection) {
+  const toRun = [];
+  const toSkip = [];
+
+  for (const attempt of attempts) {
+    const rule = RELEVANCE_RULES[attempt.id];
+
+    if (!rule) {
+      // No rule defined: always run (universal attempts)
+      toRun.push(attempt);
+      continue;
+    }
+
+    // Check if introspection flag is true
+    const flagValue = introspection[rule.requires];
+    
+    if (flagValue === true) {
+      toRun.push(attempt);
+    } else {
+      toSkip.push({
+        attempt: attempt.id,
+        reason: rule.reason
+      });
+    }
+  }
+
+  return { toRun, toSkip };
+}
+
+/**
+ * Check if an attempt should be skipped
+ * 
+ * @param {string} attemptId - The attempt ID
+ * @param {Object} introspection - Result from inspectSite()
+ * @returns {Object|null} Skip info {reason} or null if should run
+ */
+function shouldSkipAttempt(attemptId, introspection) {
+  const rule = RELEVANCE_RULES[attemptId];
+
+  if (!rule) {
+    // No rule: never skip
+    return null;
+  }
+
+  const flagValue = introspection[rule.requires];
+  
+  if (flagValue === true) {
+    return null; // Should run
+  } else {
+    return { reason: rule.reason };
+  }
+}
+
+/**
+ * Get human-readable summary of introspection results
+ * 
+ * @param {Object} introspection - Result from inspectSite()
+ * @returns {string} Summary text
+ */
+function summarizeIntrospection(introspection) {
+  const detected = [];
+  
+  if (introspection.hasLogin) detected.push('login');
+  if (introspection.hasSignup) detected.push('signup');
+  if (introspection.hasCheckout) detected.push('checkout');
+  if (introspection.hasNewsletter) detected.push('newsletter');
+  if (introspection.hasContactForm) detected.push('contact form');
+  if (introspection.hasLanguageSwitch) detected.push('language switch');
+
+  if (detected.length === 0) {
+    return 'No specific capabilities detected';
+  }
+
+  return `Detected: ${detected.join(', ')}`;
+}
+
+module.exports = {
+  RELEVANCE_RULES,
+  filterAttempts,
+  shouldSkipAttempt,
+  summarizeIntrospection
+};

package/src/guardian/attempt.js

@@ -25,9 +25,17 @@ async function executeAttempt(config) {
     artifactsDir = './artifacts',
     enableTrace = true,
     enableScreenshots = true,
-    headful = false
+    headful = false,
+    quiet = false,
+    // Phase 7.3: Accept browser context from pool
+    browserContext = null,
+    browserPage = null
   } = config;
 
+  const log = (...args) => {
+    if (!quiet) console.log(...args);
+  };
+
   // Validate baseUrl
   try {
     new URL(baseUrl);
@@ -38,6 +46,7 @@ async function executeAttempt(config) {
   const browser = new GuardianBrowser();
   let attemptResult = null;
   let runDir = null;
+  const usingPoolContext = browserContext && browserPage;
 
   try {
     // Prepare artifacts directory
@@ -53,16 +62,24 @@ async function executeAttempt(config) {
       fs.mkdirSync(runDir, { recursive: true });
     }
 
-    console.log(`\n📁 Artifacts: ${runDir}`);
+    log(`\n📁 Artifacts: ${runDir}`);
 
-    // Launch browser
-    console.log(`\n🚀 Launching browser...`);
-    const browserOptions = { 
-      headless: !headful,
-      args: !headful ? ['--no-sandbox', '--disable-setuid-sandbox'] : []
-    };
-    await browser.launch(30000, browserOptions);
-    console.log(`✅ Browser launched`);
+    // Phase 7.3: Use pool context or launch own browser
+    if (usingPoolContext) {
+      browser.useContext(browserContext, browserPage, config.timeout || 30000);
+      if (!quiet) {
+        // Silent - don't log for each attempt in pool mode
+      }
+    } else {
+      // Legacy mode: launch own browser
+      log(`\n🚀 Launching browser...`);
+      const browserOptions = { 
+        headless: !headful,
+        args: !headful ? ['--no-sandbox', '--disable-setuid-sandbox'] : []
+      };
+      await browser.launch(30000, browserOptions);
+      log(`✅ Browser launched`);
+    }
 
     // Start trace if enabled
     let tracePath = null;
@@ -70,12 +87,12 @@ async function executeAttempt(config) {
       const networkTrace = new GuardianNetworkTrace({ enableTrace: true });
       tracePath = await networkTrace.startTrace(browser.context, runDir);
       if (tracePath) {
-        console.log(`📹 Trace recording started`);
+        log(`📹 Trace recording started`);
       }
     }
 
     // Execute attempt
-    console.log(`\n🎬 Executing attempt...`);
+    log(`\n🎬 Executing attempt...`);
     const engine = new AttemptEngine({
       attemptId,
       timeout: config.timeout || 30000,
@@ -92,79 +109,103 @@ async function executeAttempt(config) {
 
     attemptResult = await engine.executeAttempt(browser.page, attemptId, baseUrl, runDir, validators);
 
-    console.log(`\n✅ Attempt completed: ${attemptResult.outcome}`);
+    log(`\n✅ Attempt completed: ${attemptResult.outcome}`);
 
     // Stop trace if enabled
     if (enableTrace && browser.context && tracePath) {
       const networkTrace = new GuardianNetworkTrace({ enableTrace: true });
       await networkTrace.stopTrace(browser.context, tracePath);
-      console.log(`✅ Trace saved: trace.zip`);
+      log(`✅ Trace saved: trace.zip`);
     }
 
     // Generate reports
-    console.log(`\n📊 Generating reports...`);
+    log(`\n📊 Generating reports...`);
     const reporter = new AttemptReporter();
     const report = reporter.createReport(attemptResult, baseUrl, attemptId);
 
     // Save JSON report
     const jsonPath = reporter.saveJsonReport(report, runDir);
-    console.log(`✅ JSON report: ${path.basename(jsonPath)}`);
+    log(`✅ JSON report: ${path.basename(jsonPath)}`);
 
     // Save HTML report
     const htmlContent = reporter.generateHtmlReport(report);
     const htmlPath = reporter.saveHtmlReport(htmlContent, runDir);
-    console.log(`✅ HTML report: ${path.basename(htmlPath)}`);
+    log(`✅ HTML report: ${path.basename(htmlPath)}`);
+
+    // Persist deterministic attempt evidence (attempt.json + steps log)
+    const attemptJsonPath = path.join(runDir, 'attempt.json');
+    const attemptSnapshot = {
+      attemptId,
+      baseUrl,
+      outcome: attemptResult.outcome,
+      startedAt: attemptResult.startedAt,
+      endedAt: attemptResult.endedAt,
+      totalDurationMs: attemptResult.totalDurationMs,
+      friction: attemptResult.friction,
+      validators: attemptResult.validators,
+      softFailures: attemptResult.softFailures,
+      successReason: attemptResult.successReason,
+      error: attemptResult.error,
+      steps: attemptResult.steps
+    };
+    fs.writeFileSync(attemptJsonPath, JSON.stringify(attemptSnapshot, null, 2));
+
+    const stepsLogPath = path.join(runDir, 'steps.jsonl');
+    const stepsLog = (attemptResult.steps || []).map(s => JSON.stringify(s)).join('\n');
+    fs.writeFileSync(stepsLogPath, stepsLog + (stepsLog ? '\n' : ''));
 
     // Display summary
-    console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+    log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
 
     const outcomeEmoji = attemptResult.outcome === 'SUCCESS' ? '🟢' : 
                           attemptResult.outcome === 'FRICTION' ? '🟡' : '🔴';
 
-    console.log(`\n${outcomeEmoji} ${attemptResult.outcome}`);
+    log(`\n${outcomeEmoji} ${attemptResult.outcome}`);
 
     if (attemptResult.outcome === 'SUCCESS') {
-      console.log(`\n✅ User successfully completed the attempt!`);
-      console.log(`   ${attemptResult.successReason}`);
+      log(`\n✅ User successfully completed the attempt!`);
+      log(`   ${attemptResult.successReason}`);
     } else if (attemptResult.outcome === 'FRICTION') {
-      console.log(`\n⚠️  Attempt succeeded but with friction:`);
+      log(`\n⚠️  Attempt succeeded but with friction:`);
       attemptResult.friction.reasons.forEach(reason => {
-        console.log(`   • ${reason}`);
+        log(`   • ${reason}`);
       });
     } else {
-      console.log(`\n❌ Attempt failed:`);
-      console.log(`   ${attemptResult.error}`);
+      log(`\n❌ Attempt failed:`);
+      log(`   ${attemptResult.error}`);
     }
 
-    console.log(`\n⏱️  Duration: ${attemptResult.totalDurationMs}ms`);
-    console.log(`📋 Steps: ${attemptResult.steps.length}`);
+    log(`\n⏱️  Duration: ${attemptResult.totalDurationMs}ms`);
+    log(`📋 Steps: ${attemptResult.steps.length}`);
 
     if (attemptResult.steps.length > 0) {
       const failedSteps = attemptResult.steps.filter(s => s.status === 'failed');
       if (failedSteps.length > 0) {
-        console.log(`❌ Failed steps: ${failedSteps.length}`);
+        log(`❌ Failed steps: ${failedSteps.length}`);
         failedSteps.forEach(step => {
-          console.log(`   • ${step.id}: ${step.error}`);
+          log(`   • ${step.id}: ${step.error}`);
         });
       }
 
       const retriedSteps = attemptResult.steps.filter(s => s.retries > 0);
       if (retriedSteps.length > 0) {
-        console.log(`🔄 Steps with retries: ${retriedSteps.length}`);
+        log(`🔄 Steps with retries: ${retriedSteps.length}`);
         retriedSteps.forEach(step => {
-          console.log(`   • ${step.id}: ${step.retries} retries`);
+          log(`   • ${step.id}: ${step.retries} retries`);
         });
       }
     }
 
-    console.log(`\n💾 Full report: ${runDir}`);
-    console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+    log(`\n💾 Full report: ${runDir}`);
+    log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
 
-    // Close browser before returning
-    try {
-      await browser.close();
-    } catch (closeErr) {
-      // Ignore browser close errors
+    // Phase 7.3: Close browser only if we own it (not using pool)
+    if (!usingPoolContext) {
+      try {
+        await browser.close();
+      } catch (closeErr) {
+        // Ignore browser close errors
+      }
     }
 
     // Determine exit code
@@ -185,6 +226,8 @@ async function executeAttempt(config) {
       artifactsDir: runDir,
       reportJsonPath: path.join(runDir, 'attempt-report.json'),
       reportHtmlPath: path.join(runDir, 'attempt-report.html'),
+      attemptJsonPath,
+      stepsLogPath,
       tracePath: enableTrace ? path.join(runDir, 'trace.zip') : null,
       steps: attemptResult.steps,
       friction: attemptResult.friction,
@@ -193,7 +236,10 @@ async function executeAttempt(config) {
     };
 
   } catch (err) {
-    await browser.close().catch(() => {});
+    // Phase 7.3: Only close if we own the browser
+    if (!usingPoolContext) {
+      await browser.close().catch(() => {});
+    }
     throw err;
   }
 }

package/src/guardian/attempts-filter.js

@@ -0,0 +1,63 @@
+/**
+ * Guardian Attempts Filter
+ * Validates and filters attempts/flows based on user input
+ */
+
+const { getDefaultAttemptIds, getAttemptDefinition } = require('./attempt-registry');
+const { getDefaultFlowIds, getFlowDefinition } = require('./flow-registry');
+
+function validateAttemptFilter(filterString) {
+  if (!filterString || !filterString.trim()) {
+    return { valid: true, ids: [] };
+  }
+
+  const ids = filterString.split(',').map(s => s.trim()).filter(Boolean);
+  
+  if (ids.length === 0) {
+    return { valid: true, ids: [] };
+  }
+
+  // Validate each ID exists
+  const invalid = [];
+  for (const id of ids) {
+    const attemptDef = getAttemptDefinition(id);
+    const flowDef = getFlowDefinition(id);
+    if (!attemptDef && !flowDef) {
+      invalid.push(id);
+    }
+  }
+
+  if (invalid.length > 0) {
+    return {
+      valid: false,
+      error: `Unknown attempt/flow: ${invalid[0]}`,
+      hint: `Run 'guardian presets' to see available attempts/flows`
+    };
+  }
+
+  return { valid: true, ids };
+}
+
+function filterAttempts(attempts, filterIds) {
+  if (!filterIds || filterIds.length === 0) {
+    return attempts;
+  }
+
+  const filterSet = new Set(filterIds);
+  return attempts.filter(id => filterSet.has(id));
+}
+
+function filterFlows(flows, filterIds) {
+  if (!filterIds || filterIds.length === 0) {
+    return flows;
+  }
+
+  const filterSet = new Set(filterIds);
+  return flows.filter(id => filterSet.has(id));
+}
+
+module.exports = {
+  validateAttemptFilter,
+  filterAttempts,
+  filterFlows
+};

package/src/guardian/baseline.js

@@ -316,11 +316,25 @@ async function checkBaseline(options) {
 
   const baselinePath = path.join(baselineDir ? baselineDir : path.join(artifactsDir, 'baselines'), `${name}.json`);
   let baseline;
+  let baselineStatus = 'LOADED';
   try {
     baseline = loadBaselineOrThrow(baselinePath);
   } catch (err) {
-    console.error(`\n❌ Baseline error: ${err.message}`);
-    return { exitCode: 1, error: err.message };
+    // Handle missing baseline gracefully
+    if (err.code === 'BASELINE_MISSING') {
+      console.log(`Baseline: not found (no comparison)`);
+      baselineStatus = 'NO_BASELINE';
+      baseline = null;
+    } else if (err.code === 'SCHEMA_MISMATCH') {
+      console.warn(`⚠️  Baseline schema mismatch - skipping comparison`);
+      baselineStatus = 'BASELINE_UNUSABLE';
+      baseline = null;
+    } else {
+      // Assume JSON parse error or other corruption
+      console.warn(`⚠️  Baseline corrupt or unreadable - skipping comparison`);
+      baselineStatus = 'BASELINE_UNUSABLE';
+      baseline = null;
+    }
   }
 
   const current = await executeReality({ 
@@ -338,6 +352,19 @@ async function checkBaseline(options) {
     flowOptions
   });
 
+  // If baseline is not available, skip comparison and return early
+  if (!baseline || baselineStatus !== 'LOADED') {
+    const currentExitCode = typeof current.exitCode === 'number' ? current.exitCode : 0;
+    return {
+      exitCode: currentExitCode,
+      runDir: current.runDir,
+      overallRegressionVerdict: baselineStatus === 'NO_BASELINE' ? 'NO_BASELINE' : 'BASELINE_UNUSABLE',
+      comparisons: [],
+      flowComparisons: [],
+      baselineStatus
+    };
+  }
+
   // Use baseline attempts (includes auto-generated) for comparison
   const comparisonAttempts = baseline.attempts || attempts;
 
@@ -441,12 +468,26 @@ async function checkBaseline(options) {
       console.log(` - ${label}: ${r.regressionType} (${reasons})`);
     }
   }
-  console.log(`Report: ${htmlPath}`);
+  
+  // Show improvements
+  const improvementList = comparisons.filter(c => c.improvements && c.improvements.length > 0);
+  if (improvementList.length > 0) {
+    console.log('\n✅ Improvements detected:');
+    for (const i of improvementList.slice(0, 5)) {
+      const label = i.attemptId || 'unknown';
+      const improvementText = i.improvements.slice(0, 2).join('; ');
+      console.log(` + ${label}: ${improvementText}`);
+    }
+  }
 
-  let exitCode = 0;
-  if (overallRegressionVerdict === 'REGRESSION_FAILURE') exitCode = 4;
-  else if (overallRegressionVerdict === 'REGRESSION_FRICTION') exitCode = 3;
-  else exitCode = 0;
+  // Exit code reflects regression severity while preserving underlying run exit codes
+  const currentExitCode = typeof current.exitCode === 'number' ? current.exitCode : 0;
+  let exitCode = currentExitCode;
+  if (overallRegressionVerdict === 'REGRESSION_FAILURE') {
+    exitCode = Math.max(exitCode, 4);
+  } else if (overallRegressionVerdict === 'REGRESSION_FRICTION') {
+    exitCode = Math.max(exitCode, 3);
+  }
 
   return {
     exitCode,
@@ -456,7 +497,8 @@ async function checkBaseline(options) {
     junitPath: junit || null,
     overallRegressionVerdict,
     comparisons,
-    flowComparisons: comparisonFlows
+    flowComparisons: comparisonFlows,
+    baselineStatus: 'LOADED'
   };
 }
 

package/src/guardian/breakage-intelligence.js

@@ -34,6 +34,7 @@ function analyzeFailure(item, isFlow = false) {
     id: isFlow ? item.flowId : item.attemptId,
     name: isFlow ? item.flowName : item.attemptName,
     outcome: item.outcome,
+    source: isFlow ? 'flow' : 'attempt',
     breakType,
     domain,
     severity,

package/src/guardian/browser-pool.js

@@ -0,0 +1,131 @@
+/**
+ * Browser Pool - Phase 7.3
+ * 
+ * Manages a single browser instance per run with context-based isolation.
+ * - One browser launched per run
+ * - Each attempt gets a fresh context (isolated cookies, storage, viewport)
+ * - Deterministic cleanup of contexts and browser
+ * - Compatible with parallel execution
+ */
+
+const { chromium } = require('playwright');
+
+class BrowserPool {
+  constructor() {
+    this.browser = null;
+    this.contexts = new Set();
+    this.launched = false;
+  }
+
+  /**
+   * Launch the shared browser instance
+   * @param {Object} options - Launch options (headless, args, timeout)
+   * @returns {Promise<void>}
+   */
+  async launch(options = {}) {
+    if (this.launched) {
+      return; // Already launched
+    }
+
+    const launchOptions = {
+      headless: options.headless !== undefined ? options.headless : true,
+      args: options.args || []
+    };
+
+    try {
+      this.browser = await chromium.launch(launchOptions);
+      this.launched = true;
+    } catch (err) {
+      throw new Error(`Failed to launch browser: ${err.message}`);
+    }
+  }
+
+  /**
+   * Create a new isolated context for an attempt
+   * @param {Object} contextOptions - Context options (viewport, recordHar, etc.)
+   * @returns {Promise<Object>} { context, page }
+   */
+  async createContext(contextOptions = {}) {
+    if (!this.browser) {
+      throw new Error('Browser not launched. Call launch() first.');
+    }
+
+    try {
+      const options = { ...contextOptions };
+      
+      // Enable HAR recording if requested
+      if (contextOptions.recordHar && contextOptions.harPath) {
+        options.recordHar = { path: contextOptions.harPath };
+      }
+
+      const context = await this.browser.newContext(options);
+      this.contexts.add(context);
+
+      const page = await context.newPage();
+      if (contextOptions.timeout) {
+        page.setDefaultTimeout(contextOptions.timeout);
+      }
+
+      return { context, page };
+    } catch (err) {
+      throw new Error(`Failed to create context: ${err.message}`);
+    }
+  }
+
+  /**
+   * Close a specific context (deterministic cleanup)
+   * @param {BrowserContext} context - The context to close
+   * @returns {Promise<void>}
+   */
+  async closeContext(context) {
+    if (!context) return;
+
+    try {
+      this.contexts.delete(context);
+      await context.close();
+    } catch (err) {
+      // Ignore close errors (may already be closed)
+    }
+  }
+
+  /**
+   * Close all contexts and the browser (end of run)
+   * @returns {Promise<void>}
+   */
+  async close() {
+    // Close all remaining contexts first
+    const contextArray = Array.from(this.contexts);
+    for (const context of contextArray) {
+      await this.closeContext(context);
+    }
+
+    // Close browser
+    if (this.browser) {
+      try {
+        await this.browser.close();
+      } catch (err) {
+        // Ignore close errors
+      }
+      this.browser = null;
+      this.launched = false;
+    }
+  }
+
+  /**
+   * Check if browser is launched
+   * @returns {boolean}
+   */
+  isLaunched() {
+    return this.launched && this.browser !== null;
+  }
+
+  /**
+   * Get count of active contexts (for testing/debugging)
+   * @returns {number}
+   */
+  getActiveContextCount() {
+    return this.contexts.size;
+  }
+}
+
+module.exports = { BrowserPool };