@odavl/guardian 0.1.0-rc1

package/src/guardian/attempt.js

@@ -0,0 +1,227 @@
+/**
+ * Guardian Attempt Mode
+ * Single user attempt execution orchestration
+ * Phase 2: Soft failure detection via validators
+ */
+
+const { GuardianBrowser } = require('./browser');
+const { AttemptEngine } = require('./attempt-engine');
+const { AttemptReporter } = require('./attempt-reporter');
+const { getAttemptDefinition } = require('./attempt-registry');
+const GuardianNetworkTrace = require('./network-trace');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Programmatic API for executing attempts
+ * Returns result object instead of calling process.exit
+ * @param {Object} config - Configuration
+ * @returns {Promise<Object>} Result with outcome, exitCode, paths, etc.
+ */
+async function executeAttempt(config) {
+  const {
+    baseUrl,
+    attemptId = 'contact_form',
+    artifactsDir = './artifacts',
+    enableTrace = true,
+    enableScreenshots = true,
+    headful = false
+  } = config;
+
+  // Validate baseUrl
+  try {
+    new URL(baseUrl);
+  } catch (e) {
+    throw new Error(`Invalid URL: ${baseUrl}`);
+  }
+
+  const browser = new GuardianBrowser();
+  let attemptResult = null;
+  let runDir = null;
+
+  try {
+    // Prepare artifacts directory
+    const now = new Date();
+    const dateStr = now.toISOString()
+      .replace(/[:\-]/g, '')
+      .substring(0, 15)
+      .replace('T', '-');
+    const runId = `attempt-${dateStr}`;
+    runDir = path.join(artifactsDir, runId);
+
+    if (!fs.existsSync(runDir)) {
+      fs.mkdirSync(runDir, { recursive: true });
+    }
+
+    console.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`);
+
+    // Start trace if enabled
+    let tracePath = null;
+    if (enableTrace && browser.context) {
+      const networkTrace = new GuardianNetworkTrace({ enableTrace: true });
+      tracePath = await networkTrace.startTrace(browser.context, runDir);
+      if (tracePath) {
+        console.log(`📹 Trace recording started`);
+      }
+    }
+
+    // Execute attempt
+    console.log(`\n🎬 Executing attempt...`);
+    const engine = new AttemptEngine({
+      attemptId,
+      timeout: config.timeout || 30000,
+      frictionThresholds: config.frictionThresholds || {
+        totalDurationMs: 2500,
+        stepDurationMs: 1500,
+        retryCount: 1
+      }
+    });
+
+    // Get validators from attempt definition (Phase 2)
+    const attemptDef = getAttemptDefinition(attemptId);
+    const validators = attemptDef?.validators || [];
+
+    attemptResult = await engine.executeAttempt(browser.page, attemptId, baseUrl, runDir, validators);
+
+    console.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`);
+    }
+
+    // Generate reports
+    console.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)}`);
+
+    // Save HTML report
+    const htmlContent = reporter.generateHtmlReport(report);
+    const htmlPath = reporter.saveHtmlReport(htmlContent, runDir);
+    console.log(`✅ HTML report: ${path.basename(htmlPath)}`);
+
+    // Display summary
+    console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+
+    const outcomeEmoji = attemptResult.outcome === 'SUCCESS' ? '🟢' : 
+                          attemptResult.outcome === 'FRICTION' ? '🟡' : '🔴';
+
+    console.log(`\n${outcomeEmoji} ${attemptResult.outcome}`);
+
+    if (attemptResult.outcome === 'SUCCESS') {
+      console.log(`\n✅ User successfully completed the attempt!`);
+      console.log(`   ${attemptResult.successReason}`);
+    } else if (attemptResult.outcome === 'FRICTION') {
+      console.log(`\n⚠️  Attempt succeeded but with friction:`);
+      attemptResult.friction.reasons.forEach(reason => {
+        console.log(`   • ${reason}`);
+      });
+    } else {
+      console.log(`\n❌ Attempt failed:`);
+      console.log(`   ${attemptResult.error}`);
+    }
+
+    console.log(`\n⏱️  Duration: ${attemptResult.totalDurationMs}ms`);
+    console.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}`);
+        failedSteps.forEach(step => {
+          console.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}`);
+        retriedSteps.forEach(step => {
+          console.log(`   • ${step.id}: ${step.retries} retries`);
+        });
+      }
+    }
+
+    console.log(`\n💾 Full report: ${runDir}`);
+    console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+
+    // Close browser before returning
+    try {
+      await browser.close();
+    } catch (closeErr) {
+      // Ignore browser close errors
+    }
+
+    // Determine exit code
+    let exitCode = 0;
+    if (attemptResult.outcome === 'SUCCESS') {
+      exitCode = 0;
+    } else if (attemptResult.outcome === 'FRICTION') {
+      exitCode = 2;
+    } else {
+      exitCode = 1;
+    }
+
+    // Return structured result
+    return {
+      outcome: attemptResult.outcome,
+      exitCode,
+      attemptResult,
+      artifactsDir: runDir,
+      reportJsonPath: path.join(runDir, 'attempt-report.json'),
+      reportHtmlPath: path.join(runDir, 'attempt-report.html'),
+      tracePath: enableTrace ? path.join(runDir, 'trace.zip') : null,
+      steps: attemptResult.steps,
+      friction: attemptResult.friction,
+      error: attemptResult.error,
+      successReason: attemptResult.successReason
+    };
+
+  } catch (err) {
+    await browser.close().catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * CLI wrapper for executeAttempt that prints output and calls process.exit
+ */
+async function runAttemptCLI(config) {
+  const {
+    baseUrl,
+    attemptId = 'contact_form',
+    headful = false
+  } = config;
+
+  console.log(`\n🛡️  ODAVL Guardian — Single User Attempt (Phase 1)`);
+  console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+  console.log(`📍 Target: ${baseUrl}`);
+  console.log(`🎯 Attempt: ${attemptId}`);
+  console.log(`⚙️  Mode: ${headful ? 'headed' : 'headless'}`);
+
+  try {
+    const result = await executeAttempt(config);
+    process.exit(result.exitCode);
+  } catch (err) {
+    console.error(`\n❌ Error: ${err.message}`);
+    if (err.stack) console.error(err.stack);
+    process.exit(1);
+  }
+}
+
+module.exports = { executeAttempt, runAttemptCLI };

package/src/guardian/auto-attempt-builder.js

@@ -0,0 +1,283 @@
+/**
+ * Auto-Attempt Builder (Phase 2)
+ * 
+ * Converts discovered interactions into safe, executable attempt definitions.
+ * - Filters by safety/confidence
+ * - Generates deterministic steps (navigate → interact → validate)
+ * - Deduplicates attempts
+ * - Applies minimal validators
+ * 
+ * NO AI. Pure deterministic logic.
+ */
+
+const crypto = require('crypto');
+
+/**
+ * @typedef {Object} AutoAttemptDefinition
+ * @property {string} attemptId - unique ID (e.g., "auto-navigate-about")
+ * @property {string} name - human-readable name
+ * @property {string} goal - what the attempt is testing
+ * @property {Array<Object>} steps - execution steps
+ * @property {Array<Object>} validators - success validators
+ * @property {string} riskCategory - TRUST, REVENUE, LEAD, UNKNOWN
+ * @property {string} source - 'auto-generated'
+ * @property {Object} metadata - discovery metadata (interaction, confidence, etc.)
+ */
+
+/**
+ * Generate stable hash for deduplication
+ */
+function generateAttemptHash(interaction) {
+  const key = `${interaction.pageUrl}|${interaction.type}|${interaction.selector}|${interaction.text || ''}`;
+  return crypto.createHash('md5').update(key).digest('hex').substring(0, 8);
+}
+
+/**
+ * Generate attemptId from interaction
+ */
+function generateAttemptId(interaction, hash) {
+  const prefix = 'auto';
+  const interactionClass = (interaction.interactionClass || 'action').toLowerCase();
+  const sanitizedText = (interaction.text || interaction.ariaLabel || 'unknown')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .substring(0, 20);
+  
+  return `${prefix}-${interactionClass}-${sanitizedText}-${hash}`;
+}
+
+/**
+ * Generate human-readable name
+ */
+function generateAttemptName(interaction) {
+  const className = interaction.interactionClass || 'Interaction';
+  const text = interaction.text || interaction.ariaLabel || interaction.selector;
+  return `Auto ${className}: ${text.substring(0, 50)}`;
+}
+
+/**
+ * Generate goal statement
+ */
+function generateGoal(interaction) {
+  const action = interaction.type === 'NAVIGATE' ? 'Navigate to' :
+                 interaction.type === 'CLICK' ? 'Click' :
+                 interaction.type === 'FORM_FILL' ? 'Fill form' : 'Interact with';
+  const target = interaction.text || interaction.ariaLabel || interaction.selector;
+  return `${action} "${target}" and verify page remains responsive`;
+}
+
+/**
+ * Generate execution steps for an interaction
+ */
+function generateSteps(interaction) {
+  const steps = [];
+
+  // Step 1: Navigate to page where interaction was found
+  steps.push({
+    id: 'navigate_to_page',
+    type: 'navigate',
+    target: interaction.pageUrl,
+    description: `Navigate to ${interaction.pageUrl}`
+  });
+
+  // Step 2: Wait for element to be visible
+  steps.push({
+    id: 'wait_for_element',
+    type: 'waitFor',
+    target: interaction.selector,
+    timeout: 10000,
+    description: `Wait for element: ${interaction.selector}`
+  });
+
+  // Step 3: Execute interaction
+  if (interaction.type === 'NAVIGATE') {
+    steps.push({
+      id: 'click_link',
+      type: 'click',
+      target: interaction.selector,
+      description: `Click link: ${interaction.text || interaction.selector}`
+    });
+  } else if (interaction.type === 'CLICK') {
+    steps.push({
+      id: 'click_button',
+      type: 'click',
+      target: interaction.selector,
+      description: `Click button: ${interaction.text || interaction.selector}`
+    });
+  } else if (interaction.type === 'FORM_FILL') {
+    // Fill form fields with safe test data
+    steps.push({
+      id: 'fill_form',
+      type: 'fillForm',
+      target: interaction.selector,
+      formData: generateFormData(interaction.formFields || []),
+      description: `Fill form: ${interaction.formId || interaction.selector}`
+    });
+  }
+
+  // Step 4: Wait briefly for DOM updates
+  steps.push({
+    id: 'wait_for_update',
+    type: 'wait',
+    duration: 500,
+    description: 'Wait for DOM update'
+  });
+
+  return steps;
+}
+
+/**
+ * Generate safe form data
+ */
+function generateFormData(fieldTypes) {
+  const data = {};
+  fieldTypes.forEach((type, idx) => {
+    if (type === 'email') {
+      data[`email_${idx}`] = `autotest${idx}@example.com`;
+    } else if (type === 'text') {
+      data[`text_${idx}`] = `Auto test ${idx}`;
+    } else if (type === 'password') {
+      data[`password_${idx}`] = 'AutoTest123!';
+    } else if (type === 'tel') {
+      data[`tel_${idx}`] = '5551234567';
+    } else if (type === 'url') {
+      data[`url_${idx}`] = 'https://example.com';
+    }
+  });
+  return data;
+}
+
+/**
+ * Generate minimal validators for auto-attempts
+ * Focus on: page responsive, no critical errors, state changed
+ */
+function generateValidators(interaction) {
+  const validators = [];
+
+  // Validator 1: Page is still responsive (no crash)
+  validators.push({
+    type: 'elementVisible',
+    selector: 'body'
+  });
+
+  // Validator 2: No console errors above 'error' level
+  validators.push({
+    type: 'noConsoleErrorsAbove',
+    minSeverity: 'error'
+  });
+
+  return validators;
+}
+
+/**
+ * Determine risk category for auto-attempt
+ * Auto-attempts are lower priority than manual intent flows
+ */
+function determineRiskCategory(interaction) {
+  const { interactionClass, text = '', ariaLabel = '' } = interaction;
+  const combinedText = `${text} ${ariaLabel}`.toLowerCase();
+
+  // Navigation to key pages: TRUST
+  if (interactionClass === 'NAVIGATION') {
+    if (combinedText.includes('about') || combinedText.includes('contact') ||
+        combinedText.includes('help') || combinedText.includes('support')) {
+      return 'TRUST';
+    }
+  }
+
+  // Forms: LEAD
+  if (interactionClass === 'SUBMISSION') {
+    return 'LEAD';
+  }
+
+  // Default: lower priority
+  return 'DISCOVERY';
+}
+
+/**
+ * Build auto-attempt from discovered interaction
+ */
+function buildAutoAttempt(interaction) {
+  const hash = generateAttemptHash(interaction);
+  const attemptId = generateAttemptId(interaction, hash);
+  const name = generateAttemptName(interaction);
+  const goal = generateGoal(interaction);
+  const steps = generateSteps(interaction);
+  const validators = generateValidators(interaction);
+  const riskCategory = determineRiskCategory(interaction);
+
+  return {
+    id: attemptId,          // Registry expects 'id'
+    attemptId,              // Keep for backwards compatibility
+    name,
+    goal,
+    baseSteps: steps,       // Engine expects 'baseSteps'
+    successConditions: [
+      { type: 'selector', target: 'body', description: 'Page loaded and responsive' }
+    ],
+    validators,
+    riskCategory,
+    source: 'auto-generated',
+    metadata: {
+      discoveryInteractionId: interaction.interactionId,
+      discoveredUrl: interaction.pageUrl,
+      interactionType: interaction.type,
+      interactionClass: interaction.interactionClass,
+      confidenceScore: interaction.confidenceScore,
+      selector: interaction.selector,
+      text: interaction.text,
+      ariaLabel: interaction.ariaLabel
+    }
+  };
+}
+
+/**
+ * Main function: Convert discovered interactions to auto-attempts
+ * @param {Array<Object>} interactions - discovered interactions from DiscoveryEngine
+ * @param {Object} options - filtering options
+ * @returns {Array<AutoAttemptDefinition>} auto-attempt definitions
+ */
+function buildAutoAttempts(interactions, options = {}) {
+  const {
+    minConfidence = 60,
+    maxAttempts = 10,
+    excludeRisky = true,
+    includeClasses = ['NAVIGATION', 'ACTION', 'SUBMISSION', 'TOGGLE']
+  } = options;
+
+  // Filter safe, high-confidence interactions
+  let filtered = interactions.filter(interaction => {
+    if (excludeRisky && interaction.isRisky) return false;
+    if (interaction.confidenceScore < minConfidence) return false;
+    if (!includeClasses.includes(interaction.interactionClass)) return false;
+    return true;
+  });
+
+  // Sort by confidence (highest first)
+  filtered.sort((a, b) => b.confidenceScore - a.confidenceScore);
+
+  // Deduplicate by hash
+  const seen = new Set();
+  const unique = [];
+  for (const interaction of filtered) {
+    const hash = generateAttemptHash(interaction);
+    if (!seen.has(hash)) {
+      seen.add(hash);
+      unique.push(interaction);
+    }
+  }
+
+  // Limit to maxAttempts
+  const limited = unique.slice(0, maxAttempts);
+
+  // Build attempts
+  return limited.map(interaction => buildAutoAttempt(interaction));
+}
+
+module.exports = {
+  buildAutoAttempts,
+  buildAutoAttempt,
+  generateAttemptId,
+  generateSteps,
+  generateValidators
+};

package/src/guardian/baseline-reporter.js

@@ -0,0 +1,143 @@
+const fs = require('fs');
+const path = require('path');
+
+class BaselineCheckReporter {
+  saveJsonReport(report, artifactsDir) {
+    const p = path.join(artifactsDir, 'baseline-check-report.json');
+    fs.writeFileSync(p, JSON.stringify(report, null, 2));
+    return p;
+  }
+
+  generateHtmlReport(report) {
+    const verdict = report.overallRegressionVerdict;
+    const color = verdict === 'NO_REGRESSION' ? '#10b981' : verdict === 'REGRESSION_FRICTION' ? '#f59e0b' : '#ef4444';
+    const emoji = verdict === 'NO_REGRESSION' ? '🟢' : verdict === 'REGRESSION_FRICTION' ? '🟡' : '🔴';
+
+    const rows = report.comparisons.map((c, i) => {
+      const badgeColor = c.regressionType === 'NO_REGRESSION' ? '#10b981' : (c.regressionType.startsWith('REGRESSION_FRICTION') ? '#f59e0b' : '#ef4444');
+      const badgeText = c.regressionType.replace(/_/g, ' ');
+      return `
+        <tr>
+          <td>${i + 1}</td>
+          <td>${c.attemptId}</td>
+          <td>${c.baselineOutcome}</td>
+          <td>${c.currentOutcome}</td>
+          <td><span class="badge" style="background:${badgeColor}">${badgeText}</span></td>
+          <td>${(c.keyMetricsDelta.durationPct ?? 0).toFixed(2)}%</td>
+          <td>${c.keyMetricsDelta.retriesDelta ?? 0}</td>
+          <td>
+            ${c.links.reportHtml ? `<a href="${path.basename(c.links.reportHtml)}" target="_blank">Attempt HTML</a>` : ''}
+            ${c.links.reportJson ? ` | <a href="${path.basename(c.links.reportJson)}" target="_blank">Attempt JSON</a>` : ''}
+          </td>
+        </tr>
+        <tr class="details">
+          <td colspan="8">
+            <details>
+              <summary>Details</summary>
+              <div class="detail-content">
+                <p><strong>Regression Reasons:</strong> ${c.regressionReasons.length ? c.regressionReasons.join('; ') : 'None'}</p>
+                <p><strong>Improvements:</strong> ${c.improvements.length ? c.improvements.join('; ') : 'None'}</p>
+                <p><strong>Friction Delta:</strong> added=[${(c.frictionDelta.added||[]).join(', ')}], removed=[${(c.frictionDelta.removed||[]).join(', ')}], changed=[${(c.frictionDelta.changed||[]).map(x=>x.id).join(', ')}]</p>
+              </div>
+            </details>
+          </td>
+        </tr>
+      `;
+    }).join('');
+
+    const flowRows = (report.flowComparisons || []).map((c, i) => {
+      const badgeColor = c.regressionType === 'NO_REGRESSION' ? '#10b981' : '#ef4444';
+      const badgeText = c.regressionType.replace(/_/g, ' ');
+      return `
+        <tr>
+          <td>${i + 1}</td>
+          <td>${c.flowId}</td>
+          <td>${c.baselineOutcome}</td>
+          <td>${c.currentOutcome}</td>
+          <td><span class="badge" style="background:${badgeColor}">${badgeText}</span></td>
+          <td colspan="3">${c.regressionReasons.slice(0,2).join('; ') || '—'}</td>
+        </tr>
+      `;
+    }).join('');
+
+    return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Baseline Check Report</title>
+  <style>
+    body { font-family: -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Arial; background:#f6f7fb; color:#1f2937; padding:20px; }
+    .container { max-width: 1100px; margin: 0 auto; }
+    .header { background: #111827; color:#fff; padding:20px; border-radius:12px; }
+    .badge { color:#fff; padding:6px 10px; border-radius:999px; font-size:0.85em; }
+    .verdict { display:inline-flex; align-items:center; gap:8px; background:${color}; color:#fff; padding:10px 14px; border-radius:999px; font-weight:bold; }
+    table { width:100%; border-collapse:collapse; background:#fff; border-radius:10px; overflow:hidden; margin-top:16px; }
+    th, td { padding:10px 12px; border-bottom:1px solid #e5e7eb; text-align:left; }
+    th { background:#f3f4f6; }
+    tr.details td { background:#fafafa; }
+    details { margin: 6px 0; }
+    .meta { display:flex; gap:16px; color:#e5e7eb; margin-top:8px; font-size:0.95em; }
+  </style>
+  </head>
+<body>
+  <div class="container">
+    <div class="header">
+      <h1>Baseline Check</h1>
+      <div class="verdict">${emoji} ${verdict}</div>
+      <div class="meta">
+        <div><strong>Baseline:</strong> ${report.meta.baselineName}</div>
+        <div><strong>URL:</strong> ${report.meta.baseUrl}</div>
+        <div><strong>Run ID:</strong> ${report.meta.runId}</div>
+        <div><strong>Time:</strong> ${report.meta.timestamp}</div>
+      </div>
+    </div>
+
+    <table>
+      <thead>
+        <tr>
+          <th>#</th>
+          <th>Attempt</th>
+          <th>Baseline</th>
+          <th>Current</th>
+          <th>Regression</th>
+          <th>Δ Duration %</th>
+          <th>Δ Retries</th>
+          <th>Links</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${rows}
+      </tbody>
+    </table>
+
+    ${flowRows ? `
+    <h3 style="margin-top:20px;">Intent Flows</h3>
+    <table>
+      <thead>
+        <tr>
+          <th>#</th>
+          <th>Flow</th>
+          <th>Baseline</th>
+          <th>Current</th>
+          <th>Regression</th>
+          <th colspan="3">Notes</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${flowRows}
+      </tbody>
+    </table>` : ''}
+  </div>
+  </body>
+</html>`;
+  }
+
+  saveHtmlReport(html, artifactsDir) {
+    const p = path.join(artifactsDir, 'baseline-check-report.html');
+    fs.writeFileSync(p, html, 'utf8');
+    return p;
+  }
+}
+
+module.exports = { BaselineCheckReporter };