@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/guardian/human-reporter.js

@@ -0,0 +1,431 @@
+/**
+ * Human Report Generator
+ * Transforms journey results into human-readable summaries
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { analyzeFailure, recordSignature, getSignatureCount } = require('./failure-intelligence');
+
+class HumanReporter {
+  constructor(options = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Generate a complete human summary and save to file
+   */
+  generateSummary(journeyResult, outputDir) {
+    const summary = this._buildSummary(journeyResult);
+    
+    // Save as both .txt and .md
+    const txtPath = path.join(outputDir, 'summary.txt');
+    const mdPath = path.join(outputDir, 'summary.md');
+
+    fs.writeFileSync(txtPath, summary.text, 'utf8');
+    fs.writeFileSync(mdPath, summary.markdown, 'utf8');
+
+    return {
+      text: txtPath,
+      markdown: mdPath,
+      content: summary.text
+    };
+  }
+
+  /**
+   * Generate JSON report for programmatic access
+   */
+  generateJSON(journeyResult, outputDir) {
+    const { toCanonicalJourneyVerdict } = require('./verdicts');
+    const decisionCanonical = toCanonicalJourneyVerdict(journeyResult.finalDecision);
+    const report = {
+      metadata: {
+        timestamp: new Date().toISOString(),
+        version: '1.0',
+        journey: journeyResult.journey
+      },
+      target: {
+        url: journeyResult.url,
+        reachable: journeyResult.executedSteps.length > 0
+      },
+      intentDetection: journeyResult.intentDetection || { intent: 'unknown', confidence: 0, signals: [] },
+      goal: journeyResult.goal || { goalReached: false, goalDescription: '' },
+      baseline: journeyResult.baseline || null,
+      drift: journeyResult.drift || { driftDetected: false, driftReasons: [] },
+      execution: {
+        totalSteps: journeyResult.executedSteps.length + journeyResult.failedSteps.length,
+        succeededSteps: journeyResult.executedSteps.length,
+        failedSteps: journeyResult.failedSteps.length,
+        successRate: journeyResult.executedSteps.length > 0 
+          ? Math.round((journeyResult.executedSteps.length / 
+              (journeyResult.executedSteps.length + journeyResult.failedSteps.length)) * 100)
+          : 0
+      },
+      classification: journeyResult.errorClassification || { type: 'UNKNOWN' },
+      decision: journeyResult.finalDecision,
+      decisionCanonical,
+      reasoning: this._buildReasoning(journeyResult),
+      impact: this._assessUserImpact(journeyResult),
+      timing: {
+        started: journeyResult.startedAt,
+        ended: journeyResult.endedAt
+      },
+      details: {
+        steps: journeyResult.executedSteps,
+        failures: journeyResult.failedSteps,
+        evidence: journeyResult.evidence
+      }
+    };
+
+    // Failure intelligence section
+    const info = analyzeFailure(journeyResult);
+    const rec = recordSignature(journeyResult.url, info);
+    report.failureInsights = {
+      failureStage: info.failureStage,
+      failureStepId: info.failureStepId,
+      cause: info.cause,
+      hint: info.hint,
+      signature: rec.signature,
+      occurrences: rec.count,
+    };
+
+    const reportPath = path.join(outputDir, 'report.json');
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf8');
+
+    return report;
+  }
+
+  /**
+   * Build human text summary
+   */
+  _buildSummary(journeyResult) {
+    const decision = journeyResult.finalDecision || 'UNKNOWN';
+    const classification = journeyResult.errorClassification || {};
+    
+    const text = this._formatText(journeyResult);
+    const markdown = this._formatMarkdown(journeyResult);
+
+    return { text, markdown };
+  }
+
+  _formatText(journeyResult) {
+    const { toCanonicalJourneyVerdict } = require('./verdicts');
+    const canonical = toCanonicalJourneyVerdict(journeyResult.finalDecision);
+        // Baseline compare
+        if (journeyResult.baseline) {
+          lines.push('BASELINE');
+          lines.push('─────────────────────────────────────────────────────────────────');
+          const b = journeyResult.baseline;
+          lines.push(`Saved decision: ${b.decision}`);
+          lines.push(`Saved intent:   ${String(b.intent || 'unknown').toUpperCase()}`);
+          lines.push(`Saved goal:     ${b.goalReached ? 'Reached' : 'Not reached'}\n`);
+
+          lines.push('CURRENT VS BASELINE');
+          lines.push('─────────────────────────────────────────────────────────────────');
+          const d = journeyResult.drift || { driftDetected: false, driftReasons: [] };
+          if (d.driftDetected) {
+            lines.push('Regression detected:');
+            for (const r of d.driftReasons) lines.push(`– ${r}`);
+          } else {
+            lines.push('No regression detected');
+          }
+          lines.push();
+        }
+    const lines = [];
+    const decision = canonical || 'DO_NOT_LAUNCH';
+
+    lines.push('═══════════════════════════════════════════════════════════════');
+    lines.push('                    ODAVL GUARDIAN — JOURNEY REPORT');
+    lines.push('═══════════════════════════════════════════════════════════════\n');
+
+    lines.push(`DECISION: ${this._decisionEmoji(decision)} ${decision}`);
+    lines.push(`Journey: ${journeyResult.journey || 'Unknown'}`);
+    lines.push(`Target:  ${journeyResult.url}\n`);
+
+    // Intent detection
+    if (journeyResult.intentDetection) {
+      const id = journeyResult.intentDetection;
+      lines.push('SITE TYPE');
+      lines.push('─────────────────────────────────────────────────────────────────');
+      lines.push(`Detected: ${String(id.intent || 'unknown').toUpperCase()} (confidence ${id.confidence || 0}%)`);
+      lines.push(`Visitor Goal: ${this._intentToHumanGoal(id.intent)}`);
+      const goal = journeyResult.goal || { goalReached: false, goalDescription: '' };
+      lines.push(`Goal Reached: ${goal.goalReached ? 'Yes' : 'No'} — ${goal.goalDescription}\n`);
+    }
+
+    lines.push('EXECUTION SUMMARY');
+    lines.push('─────────────────────────────────────────────────────────────────');
+    lines.push(`Steps Executed:  ${journeyResult.executedSteps.length}`);
+    lines.push(`Steps Failed:    ${journeyResult.failedSteps.length}`);
+    lines.push(`Total Steps:     ${journeyResult.executedSteps.length + journeyResult.failedSteps.length}`);
+    
+    if (journeyResult.executedSteps.length > 0) {
+      const rate = Math.round((journeyResult.executedSteps.length / 
+        (journeyResult.executedSteps.length + journeyResult.failedSteps.length)) * 100);
+      lines.push(`Success Rate:    ${rate}%\n`);
+    }
+
+    lines.push('WHAT GUARDIAN TESTED');
+    lines.push('─────────────────────────────────────────────────────────────────');
+    const steps = journeyResult.executedSteps || [];
+    for (let i = 0; i < steps.length; i++) {
+      lines.push(`${i + 1}. ${steps[i].name || `Step ${i + 1}`}`);
+    }
+    lines.push();
+
+    if (journeyResult.failedSteps && journeyResult.failedSteps.length > 0) {
+      lines.push('WHAT FAILED');
+      lines.push('─────────────────────────────────────────────────────────────────');
+      for (const failure of journeyResult.failedSteps) {
+        const step = journeyResult.executedSteps.find(s => s.id === failure);
+        if (step) {
+          lines.push(`✗ ${step.name || failure}: ${step.error || 'Unknown failure'}`);
+        }
+      }
+      lines.push();
+    }
+
+    if (journeyResult.errorClassification) {
+      lines.push('ERROR CLASSIFICATION');
+      lines.push('─────────────────────────────────────────────────────────────────');
+      lines.push(`Type:   ${journeyResult.errorClassification.type || 'UNKNOWN'}`);
+      lines.push(`Reason: ${journeyResult.errorClassification.reason || 'N/A'}\n`);
+    }
+
+    lines.push('DECISION REASONING');
+    lines.push('─────────────────────────────────────────────────────────────────');
+    lines.push(this._buildReasoning(journeyResult));
+    lines.push();
+
+    // Failure intelligence
+    const fi = analyzeFailure(journeyResult);
+    const occurrences = getSignatureCount(journeyResult.url, fi);
+    lines.push('WHERE USERS STOP');
+    lines.push('─────────────────────────────────────────────────────────────────');
+    lines.push(`Stage: ${fi.failureStage}`);
+    lines.push(`Step:  ${fi.failureStepId ?? 'unknown'}`);
+    lines.push();
+
+    lines.push('WHY IT LIKELY HAPPENS');
+    lines.push('─────────────────────────────────────────────────────────────────');
+    lines.push(fi.cause);
+    lines.push();
+
+    lines.push('FIRST FIX TO TRY');
+    lines.push('─────────────────────────────────────────────────────────────────');
+    lines.push(fi.hint);
+    lines.push(`\nThis failure pattern occurred ${occurrences} time(s).`);
+    lines.push();
+
+    lines.push('USER IMPACT');
+    lines.push('─────────────────────────────────────────────────────────────────');
+    lines.push(this._assessUserImpact(journeyResult));
+    lines.push();
+
+    lines.push('═══════════════════════════════════════════════════════════════');
+    lines.push('RECOMMENDATION');
+    lines.push('═══════════════════════════════════════════════════════════════');
+    lines.push(this._getRecommendation(journeyResult));
+    lines.push();
+
+    return lines.join('\n');
+  }
+
+  _formatMarkdown(journeyResult) {
+    const { toCanonicalJourneyVerdict } = require('./verdicts');
+    const canonical = toCanonicalJourneyVerdict(journeyResult.finalDecision);
+        if (journeyResult.baseline) {
+          const b = journeyResult.baseline;
+          const d = journeyResult.drift || { driftDetected: false, driftReasons: [] };
+          lines.push(`## Baseline`);
+          lines.push(`- Decision: ${b.decision}`);
+          lines.push(`- Intent: ${String(b.intent || 'unknown').toUpperCase()}`);
+          lines.push(`- Goal: ${b.goalReached ? 'Reached' : 'Not reached'}`);
+          lines.push();
+          lines.push(`## Current vs Baseline`);
+          if (d.driftDetected) {
+            lines.push('Regression detected:');
+            for (const r of d.driftReasons) lines.push(`- ${r}`);
+          } else {
+            lines.push('No regression detected');
+          }
+          lines.push();
+        }
+    const lines = [];
+    const decision = canonical || 'DO_NOT_LAUNCH';
+
+    lines.push(`# ODAVL Guardian — Journey Report\n`);
+    
+    lines.push(`## Decision: ${this._decisionEmoji(decision)} **${decision}**\n`);
+    lines.push(`- **Journey:** ${journeyResult.journey || 'Unknown'}`);
+    lines.push(`- **Target:** ${journeyResult.url}`);
+    lines.push(`- **Time:** ${journeyResult.startedAt}\n`);
+
+    if (journeyResult.intentDetection) {
+      const id = journeyResult.intentDetection;
+      lines.push(`## Site Type`);
+      lines.push(`- **Detected:** ${String(id.intent || 'unknown').toUpperCase()} (confidence ${id.confidence || 0}%)`);
+      lines.push(`- **Visitor Goal:** ${this._intentToHumanGoal(id.intent)}`);
+      const goal = journeyResult.goal || { goalReached: false, goalDescription: '' };
+      lines.push(`- **Goal Reached:** ${goal.goalReached ? 'Yes' : 'No'} — ${goal.goalDescription}\n`);
+    }
+
+    lines.push(`## Execution Summary\n`);
+    lines.push(`| Metric | Value |`);
+    lines.push(`|--------|-------|`);
+    lines.push(`| Steps Executed | ${journeyResult.executedSteps.length} |`);
+    lines.push(`| Steps Failed | ${journeyResult.failedSteps.length} |`);
+    const rate = journeyResult.executedSteps.length > 0
+      ? Math.round((journeyResult.executedSteps.length / 
+          (journeyResult.executedSteps.length + journeyResult.failedSteps.length)) * 100)
+      : 0;
+    lines.push(`| Success Rate | ${rate}% |\n`);
+
+    lines.push(`## What Guardian Tested\n`);
+    const steps = journeyResult.executedSteps || [];
+    for (let i = 0; i < steps.length; i++) {
+      lines.push(`${i + 1}. ${steps[i].name || `Step ${i + 1}`}`);
+    }
+    lines.push();
+
+    if (journeyResult.failedSteps?.length > 0) {
+      lines.push(`## Failures\n`);
+      for (const failure of journeyResult.failedSteps) {
+        const step = journeyResult.executedSteps.find(s => s.id === failure);
+        if (step) {
+          lines.push(`- ✗ **${step.name || failure}**: ${step.error || 'Unknown failure'}`);
+        }
+      }
+      lines.push();
+    }
+
+    if (journeyResult.errorClassification) {
+      lines.push(`## Error Classification\n`);
+      lines.push(`- **Type:** ${journeyResult.errorClassification.type || 'UNKNOWN'}`);
+      lines.push(`- **Reason:** ${journeyResult.errorClassification.reason || 'N/A'}\n`);
+    }
+
+    lines.push(`## Reasoning\n`);
+    lines.push(this._buildReasoning(journeyResult));
+    lines.push();
+
+    lines.push(`## User Impact\n`);
+    lines.push(this._assessUserImpact(journeyResult));
+    lines.push();
+
+    const fi = analyzeFailure(journeyResult);
+    const occurrences = getSignatureCount(journeyResult.url, fi);
+    lines.push(`## Where Users Stop`);
+    lines.push(`- **Stage:** ${fi.failureStage}`);
+    lines.push(`- **Step:** ${fi.failureStepId ?? 'unknown'}`);
+    lines.push();
+    lines.push(`## Why It Likely Happens`);
+    lines.push(`- ${fi.cause}`);
+    lines.push();
+    lines.push(`## First Fix To Try`);
+    lines.push(`- ${fi.hint}`);
+    lines.push();
+    lines.push(`> This failure pattern occurred ${occurrences} time(s).`);
+    lines.push();
+
+    lines.push(`## Recommendation\n`);
+    lines.push(this._getRecommendation(journeyResult));
+    lines.push();
+
+    return lines.join('\n');
+  }
+
+  _decisionEmoji(decision) {
+    const map = {
+      'READY': '✅',
+      'FRICTION': '⚠️ ',
+      'DO_NOT_LAUNCH': '🚫'
+    };
+    return map[decision] || '❓';
+  }
+
+  _buildReasoning(journeyResult) {
+    const decision = journeyResult.finalDecision;
+    const executed = journeyResult.executedSteps?.length || 0;
+    const failed = journeyResult.failedSteps?.length || 0;
+    const goalReached = journeyResult.goal?.goalReached === true;
+
+    if (decision === 'SAFE') {
+      return `All ${executed} steps completed, and the visitor goal was reached. Journey is fully functional.`;
+    }
+
+    if (decision === 'RISK') {
+      if (failed === 0 && !goalReached) {
+        return `Journey steps succeeded, but the visitor goal was not reached. Conversion risk exists.`;
+      }
+      return `${executed} of ${executed + failed} steps succeeded (${Math.round((executed / (executed + failed)) * 100)}%). Some parts of the critical journey work, but risks exist.`;
+    }
+
+    if (decision === 'DO_NOT_LAUNCH') {
+      if (journeyResult.fatalError) {
+        return `Site is unreachable or blocked. Cannot complete user journey at all. Error: ${journeyResult.fatalError}`;
+      }
+      return `Journey failed completely (0/${executed + failed} steps succeeded). Site or critical elements are broken. Do not launch.`;
+    }
+
+    return 'Unable to determine outcome from results.';
+  }
+
+  _assessUserImpact(journeyResult) {
+    const classification = journeyResult.errorClassification?.type;
+
+    if (journeyResult.finalDecision === 'SAFE') {
+      return 'Visitors will successfully complete the critical user journey. No blockers detected.';
+    }
+
+    if (classification === 'CTA_NOT_FOUND') {
+      return 'Visitors cannot find the key conversion element. Sign-up/checkout CTA is missing or inaccessible.';
+    }
+
+    if (classification === 'NAVIGATION_BLOCKED') {
+      return 'Visitors cannot navigate to critical pages. Internal navigation is broken.';
+    }
+
+    if (classification === 'SITE_UNREACHABLE') {
+      return 'Site is entirely unreachable. Visitors cannot access the website at all.';
+    }
+
+    if (journeyResult.finalDecision === 'RISK') {
+      return 'Some steps work but the journey is incomplete. Visitors may struggle to convert.';
+    }
+
+    return 'Site has critical failures that impact user conversion.';
+  }
+
+  _getRecommendation(journeyResult) {
+    const decision = journeyResult.finalDecision;
+
+    if (decision === 'SAFE') {
+      return '✅ **READY TO LAUNCH** — Critical journey is fully functional. Monitor for regressions.';
+    }
+
+    if (decision === 'RISK') {
+      if (journeyResult.goal?.goalReached === false && journeyResult.failedSteps?.length === 0) {
+        return '⚠️  **LAUNCH WITH CAUTION** — Help visitors reach the goal (signup, checkout, contact) before launch.';
+      }
+      return '⚠️  **LAUNCH WITH CAUTION** — Fix identified failures before launch. Test thoroughly.';
+    }
+
+    if (decision === 'DO_NOT_LAUNCH') {
+      return '🚫 **DO NOT LAUNCH** — Critical failures detected. Fix issues before attempting deployment.';
+    }
+
+    return 'Unable to make recommendation.';
+  }
+
+  _intentToHumanGoal(intent) {
+    switch (intent) {
+      case 'saas': return 'Sign up or view pricing';
+      case 'shop': return 'Add to cart or begin checkout';
+      case 'landing': return 'Send a message or reach contact section';
+      default: return 'Find a clear action and proceed';
+    }
+  }
+}
+
+module.exports = { HumanReporter };

package/src/guardian/index.js

@@ -176,35 +176,38 @@ async function runGuardian(config) {
       }
     }
 
-    // Display verdict
+    // Display verdict with evidence-first messaging
     console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-    
-    const { decision } = report.finalJudgment;
+
+    const { decision, reasons } = report.finalJudgment;
     const coverageStr = `${report.summary.coverage}%`;
-    
-    if (decision === 'READY') {
-      console.log(`\n🟢 READY — Safe to launch`);
-    } else if (decision === 'DO_NOT_LAUNCH') {
-      console.log(`\n🔴 DO_NOT_LAUNCH — Issues found`);
-    } else {
-      console.log(`\n🟡 INSUFFICIENT_CONFIDENCE — Needs more data`);
-    }
-    
-    console.log(`\n📈 Coverage: ${coverageStr}`);
+
+    // Map internal to canonical verdict labels for CLI output
+    const { toCanonicalVerdict } = require('./verdicts');
+    const canonical = toCanonicalVerdict(decision);
+    const verdictLabel = canonical === 'READY'
+      ? 'READY — flows seen end-to-end'
+      : canonical === 'FRICTION'
+        ? 'FRICTION — some flows failed or could not be confirmed'
+        : 'DO_NOT_LAUNCH — only limited observations or critical failures'
+
+    console.log(`\n🔎 Verdict: ${verdictLabel}`);
+    console.log(`\n📈 Coverage (link discovery only): ${coverageStr}`);
     console.log(`📄 Pages visited: ${report.summary.visitedPages}`);
-    console.log(`❌ Failed pages: ${report.summary.failedPages}`);
+    console.log(`❌ Failed pages (server/nav errors): ${report.summary.failedPages}`);
     console.log(`💬 Confidence: ${report.confidence.level}`);
-    
-    console.log(`\n📋 Reasons:`);
-    report.finalJudgment.reasons.forEach(reason => {
+
+    console.log(`\nEvidence and limitations:`);
+    reasons.forEach(reason => {
       console.log(`   • ${reason}`);
     });
 
     console.log(`\n💾 Full report: ${savedReport.reportPath}`);
     console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
 
-    // Exit with appropriate code
-    const exitCode = (decision === 'READY') ? 0 : 1;
+    // Exit with deterministic codes: OBSERVED=0, PARTIAL=1, INSUFFICIENT_DATA=2
+    const { mapExitCodeFromCanonical } = require('./verdicts');
+    const exitCode = mapExitCodeFromCanonical(canonical);
     process.exit(exitCode);
 
   } catch (err) {

package/src/guardian/init-command.js

@@ -27,10 +27,14 @@ function initGuardian(options = {}) {
 
   // 1. Create policy file
   try {
-    const policyPath = path.join(cwd, 'guardian.policy.json');
+    const configDir = path.join(cwd, 'config');
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    const policyPath = path.join(configDir, 'guardian.policy.json');
     
     if (fs.existsSync(policyPath)) {
-      console.log('⚠️  guardian.policy.json already exists. Skipping.');
+      console.log('⚠️  config/guardian.policy.json already exists. Skipping.');
     } else {
       // Load preset
       const presetsDir = path.join(__dirname, '../../policies');
@@ -56,8 +60,8 @@ function initGuardian(options = {}) {
       }
 
       fs.writeFileSync(policyPath, policyContent, 'utf-8');
-      result.created.push('guardian.policy.json');
-      console.log('✅ Created guardian.policy.json');
+      result.created.push('config/guardian.policy.json');
+      console.log('✅ Created config/guardian.policy.json');
     }
   } catch (error) {
     result.errors.push(`Failed to create policy: ${error.message}`);
@@ -105,7 +109,7 @@ function initGuardian(options = {}) {
   console.log('  3. Review the generated report:');
   console.log('     Check artifacts/ directory\n');
   console.log('  4. Customize policy:');
-  console.log('     Edit guardian.policy.json\n');
+    console.log('     Edit config/guardian.policy.json\n');
   console.log('  5. Integrate with CI/CD:');
   console.log('     Use .github/workflows/guardian.yml as template\n');
   console.log('━'.repeat(60) + '\n');

package/src/guardian/intent-detector.js

@@ -0,0 +1,146 @@
+/**
+ * Intent Detection Engine
+ * Inspects the homepage and classifies site intent.
+ * Returns { intent: 'saas'|'shop'|'landing'|'unknown', confidence: 0-100, signals: string[] }
+ */
+
+const { GuardianBrowser } = require('./browser');
+
+async function detectIntent(url, options = {}) {
+  const browser = new GuardianBrowser();
+  const timeout = options.timeout || 20000;
+  const headless = options.headless !== false;
+  const result = { intent: 'unknown', confidence: 0, signals: [] };
+
+  try {
+    await browser.launch(timeout, { headless });
+    await browser.page.goto(url, { waitUntil: 'load', timeout });
+    // Ensure content is rendered before signal extraction
+    await browser.page.waitForLoadState('domcontentloaded');
+    await browser.page.waitForTimeout(100);
+    const signals = await _extractSignals(browser.page);
+    const { intent, confidence } = _classifyFromSignals(signals);
+    result.intent = intent;
+    result.confidence = confidence;
+    result.signals = signals;
+    return result;
+  } catch (err) {
+    return { intent: 'unknown', confidence: 0, signals: [`error:${err.message}`] };
+  } finally {
+    try {
+      if (browser?.context) await browser.context.close();
+      if (browser?.browser) await browser.browser.close();
+    } catch {}
+  }
+}
+
+async function _extractSignals(page) {
+  try {
+    return await page.evaluate(() => {
+      const signals = [];
+
+      function textIncludes(el, kws) {
+        const t = (el.innerText || '').toLowerCase();
+        return kws.some(k => t.includes(k));
+      }
+
+      const anchors = Array.from(document.querySelectorAll('a'));
+      const buttons = Array.from(document.querySelectorAll('button'));
+      const forms = Array.from(document.querySelectorAll('form'));
+
+      // URL patterns in anchors
+      const urlKWs = ['/pricing', '/signup', '/account/signup', '/shop', '/cart', '/checkout', '/contact'];
+      for (const a of anchors) {
+        const href = (a.getAttribute('href') || '').toLowerCase();
+        urlKWs.forEach(k => { if (href.includes(k)) signals.push(`url:${k}`); });
+      }
+
+      // Keywords: signup/subscribe/pricing
+      const saasKWs = ['sign up', 'signup', 'subscribe', 'get started', 'pricing', 'plan'];
+      [...anchors, ...buttons].forEach(el => {
+        if (textIncludes(el, saasKWs)) signals.push('kw:saas');
+      });
+
+      // Shop keywords: buy/cart/checkout/add to cart/order/purchase
+      const shopKWs = ['buy', 'cart', 'checkout', 'add to cart', 'order', 'purchase'];
+      [...anchors, ...buttons].forEach(el => {
+        if (textIncludes(el, shopKWs)) signals.push('kw:shop');
+      });
+
+      // Landing/contact keywords
+      const landingKWs = ['contact', 'get in touch'];
+      [...anchors, ...buttons].forEach(el => {
+        if (textIncludes(el, landingKWs)) signals.push('kw:landing');
+      });
+
+      // Forms vs payment buttons
+      const hasEmailInput = !!document.querySelector('input[type="email"], input[name*="email" i]');
+      const hasContactForm = forms.some(f => {
+        const txts = f.querySelectorAll('textarea');
+        const names = f.querySelectorAll('input[name*="name" i]');
+        const emails = f.querySelectorAll('input[type="email"], input[name*="email" i]');
+        return emails.length > 0 || (names.length > 0 && txts.length > 0);
+      });
+      if (hasEmailInput) signals.push('form:email');
+      if (hasContactForm) signals.push('form:contact');
+
+      const hasPaymentBtn = [...buttons, ...anchors].some(el => textIncludes(el, ['buy', 'checkout', 'add to cart', 'purchase']));
+      if (hasPaymentBtn) signals.push('btn:payment');
+
+      // Price indications (numbers with per month/year)
+      const bodyText = (document.body.innerText || '').toLowerCase();
+      if (/\$\s*\d+/.test(bodyText) || /€\s*\d+/.test(bodyText)) {
+        if (bodyText.includes('per month') || bodyText.includes('/month') || bodyText.includes('monthly')) {
+          signals.push('price:monthly');
+        }
+        if (bodyText.includes('per year') || bodyText.includes('/year') || bodyText.includes('annually')) {
+          signals.push('price:annual');
+        }
+      }
+
+      // Fallback: scan body text for keywords
+      if (saasKWs.some(k => bodyText.includes(k))) signals.push('kw:saas');
+      if (shopKWs.some(k => bodyText.includes(k))) signals.push('kw:shop');
+      if (landingKWs.some(k => bodyText.includes(k))) signals.push('kw:landing');
+
+      return signals;
+    });
+  } catch (e) {
+    return [`error:${e.message}`];
+  }
+}
+
+function _classifyFromSignals(signals) {
+  let saas = 0, shop = 0, landing = 0;
+
+  for (const s of signals) {
+    if (s.startsWith('kw:saas')) saas += 2;
+    if (s.startsWith('url:/pricing')) saas += 3;
+    if (s.startsWith('url:/signup')) saas += 3;
+    if (s.startsWith('form:email')) saas += 2;
+    if (s.startsWith('price:')) saas += 1;
+
+    if (s.startsWith('kw:shop')) shop += 2;
+    if (s.startsWith('btn:payment')) shop += 3;
+    if (s.startsWith('url:/shop')) shop += 2;
+    if (s.startsWith('url:/cart')) shop += 3;
+    if (s.startsWith('url:/checkout')) shop += 3;
+
+    if (s.startsWith('kw:landing')) landing += 2;
+    if (s.startsWith('form:contact')) landing += 3;
+    if (s.startsWith('url:/contact')) landing += 2;
+  }
+
+  const scores = { saas, shop, landing };
+  const top = Object.entries(scores).sort((a, b) => b[1] - a[1])[0];
+  const maxScore = top ? top[1] : 0;
+  const intent = maxScore >= 2 ? top[0] : 'unknown';
+  const confidence = Math.min(100, Math.round((maxScore / 10) * 100));
+  return { intent, confidence };
+}
+
+module.exports = {
+  detectIntent,
+  _extractSignals,
+  _classifyFromSignals
+};