@odavl/guardian 0.1.0-rc1 → 0.2.0

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,81 @@ 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)}`);
 
     // 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
@@ -193,7 +212,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,18 @@ async function checkBaseline(options) {
     flowOptions
   });
 
+  // If baseline is not available, skip comparison and return early
+  if (!baseline || baselineStatus !== 'LOADED') {
+    return {
+      exitCode: 0,  // Exit code based on flows only, not baseline
+      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,22 +467,30 @@ async function checkBaseline(options) {
       console.log(` - ${label}: ${r.regressionType} (${reasons})`);
     }
   }
-  console.log(`Report: ${htmlPath}`);
-
-  let exitCode = 0;
-  if (overallRegressionVerdict === 'REGRESSION_FAILURE') exitCode = 4;
-  else if (overallRegressionVerdict === 'REGRESSION_FRICTION') exitCode = 3;
-  else exitCode = 0;
+  
+  // 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}`);
+    }
+  }
 
+  // CRITICAL: Exit code is ALWAYS 0 from baseline check
+  // Exit codes come from flow outcomes only (Phase 2.x policy)
   return {
-    exitCode,
+    exitCode: 0,
     runDir: current.runDir,
     reportJsonPath: jsonPath,
     reportHtmlPath: htmlPath,
     junitPath: junit || null,
     overallRegressionVerdict,
     comparisons,
-    flowComparisons: comparisonFlows
+    flowComparisons: comparisonFlows,
+    baselineStatus: 'LOADED'
   };
 }
 

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 };

package/src/guardian/browser.js

@@ -5,8 +5,15 @@ class GuardianBrowser {
     this.browser = null;
     this.context = null;
     this.page = null;
+    this.ownsContext = false; // Track if we own the context for cleanup
   }
 
+  /**
+   * Launch browser with its own context (legacy mode)
+   * @param {number} timeout - Default timeout
+   * @param {Object} options - Launch options
+   * @returns {Promise<boolean>}
+   */
   async launch(timeout = 20000, options = {}) {
     try {
       const launchOptions = { 
@@ -30,12 +37,28 @@ class GuardianBrowser {
       this.context = await this.browser.newContext(contextOptions);
       this.page = await this.context.newPage();
       this.page.setDefaultTimeout(timeout);
+      this.ownsContext = true; // We own browser and context
       return true;
     } catch (err) {
       throw new Error(`Failed to launch browser: ${err.message}`);
     }
   }
 
+  /**
+   * Phase 7.3: Use an existing context from browser pool
+   * @param {BrowserContext} context - Playwright browser context
+   * @param {Page} page - Playwright page
+   * @param {number} timeout - Default timeout
+   */
+  useContext(context, page, timeout = 20000) {
+    this.context = context;
+    this.page = page;
+    this.ownsContext = false; // Pool owns the context
+    if (timeout) {
+      this.page.setDefaultTimeout(timeout);
+    }
+  }
+
   async navigate(url, timeout = 20000) {
     try {
       const response = await this.page.goto(url, {
@@ -82,7 +105,11 @@ class GuardianBrowser {
 
   async close() {
     try {
-      if (this.browser) await this.browser.close();
+      // Phase 7.3: Only close browser if we own it (legacy mode)
+      // If using pool context, pool handles cleanup
+      if (this.ownsContext && this.browser) {
+        await this.browser.close();
+      }
     } catch (err) {
       // Ignore close errors
     }

package/src/guardian/ci-mode.js

@@ -0,0 +1,15 @@
+function isCiMode() {
+  const ci = process.env.CI;
+  const gha = process.env.GITHUB_ACTIONS;
+  const guardianCi = process.env.GUARDIAN_CI;
+
+  const normalize = (value) => String(value || '').toLowerCase();
+  const isTrueish = (value) => {
+    const v = normalize(value);
+    return v === 'true' || v === '1' || v === 'yes' || v === 'on';
+  };
+
+  return isTrueish(ci) || isTrueish(gha) || isTrueish(guardianCi);
+}
+
+module.exports = { isCiMode };

package/src/guardian/ci-output.js

@@ -0,0 +1,37 @@
+const { formatRunSummary, deriveBaselineVerdict } = require('./run-summary');
+const MAX_REASONS_DEFAULT = 3;
+
+function pickReason(flow) {
+  if (Array.isArray(flow.failureReasons) && flow.failureReasons.length > 0) {
+    return flow.failureReasons[0];
+  }
+  if (flow.error) return flow.error;
+  if (flow.successEval && Array.isArray(flow.successEval.reasons) && flow.successEval.reasons.length > 0) {
+    return flow.successEval.reasons[0];
+  }
+  return 'no reason captured';
+}
+
+function formatCiSummary({ flowResults = [], diffResult = null, baselineCreated = false, exitCode = 0, maxReasons = MAX_REASONS_DEFAULT }) {
+  const lines = [];
+  lines.push('CI MODE: ON');
+  lines.push(formatRunSummary({ flowResults, diffResult, baselineCreated, exitCode }, { label: 'Summary' }));
+
+  if (exitCode !== 0) {
+    lines.push('Why CI failed:');
+    const troubled = flowResults.filter(f => f.outcome === 'FAILURE' || f.outcome === 'FRICTION');
+    troubled.slice(0, maxReasons).forEach(flow => {
+      const reason = pickReason(flow);
+      lines.push(` - ${flow.flowName || flow.flowId || 'flow'}: ${flow.outcome} | ${reason}`);
+    });
+    if (troubled.length > maxReasons) {
+      lines.push(` - … ${troubled.length - maxReasons} more issues`);
+    }
+  } else {
+    lines.push('Result: PASS');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { formatCiSummary, deriveBaselineVerdict };