@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/guardian/journey-definitions.js

@@ -0,0 +1,132 @@
+/**
+ * Journey Definitions - Preset journeys for different product types
+ * Each journey is a deterministic sequence of steps
+ */
+
+function getJourneyDefinition(preset = 'saas') {
+  switch (preset) {
+    case 'saas':
+      return getSaasjJourney();
+    case 'shop':
+    case 'ecommerce':
+      return getShopJourney();
+    case 'landing':
+      return getLandingJourney();
+    default:
+      return getSaasjJourney();
+  }
+}
+
+/**
+ * SAAS Journey: Homepage → Find CTA → Signup flow
+ */
+function getSaasjJourney() {
+  return {
+    name: 'SAAS Signup Flow',
+    description: 'Test critical path: homepage → locate signup CTA → click → verify signup page',
+    preset: 'saas',
+    steps: [
+      {
+        id: 'step-1-homepage',
+        name: 'Load homepage',
+        action: 'navigate',
+        target: '/',
+        description: 'User arrives at the homepage'
+      },
+      {
+        id: 'step-2-find-cta',
+        name: 'Find signup CTA',
+        action: 'find_cta',
+        target: null,
+        description: 'Locate primary signup/CTA button (sign up, get started, start, register, pricing, etc)',
+        expectedIndicator: {
+          textMatch: ['sign up', 'signup', 'get started', 'start', 'register', 'pricing'],
+          tagNames: ['A', 'BUTTON']
+        }
+      },
+      {
+        id: 'step-3-verify-homepage',
+        name: 'Verify homepage loaded',
+        action: 'navigate',
+        target: '/pricing',
+        description: 'If CTA not found, try /pricing as fallback'
+      }
+    ]
+  };
+}
+
+/**
+ * Shop Journey: Homepage → Find product CTA → Checkout
+ */
+function getShopJourney() {
+  return {
+    name: 'Shop Checkout Flow',
+    description: 'Test critical path: homepage → find product/checkout CTA → click → verify flow',
+    preset: 'shop',
+    steps: [
+      {
+        id: 'step-1-homepage',
+        name: 'Load homepage',
+        action: 'navigate',
+        target: '/',
+        description: 'User arrives at the homepage'
+      },
+      {
+        id: 'step-2-find-product',
+        name: 'Find product CTA',
+        action: 'find_cta',
+        target: null,
+        description: 'Locate primary product/buy/checkout button',
+        expectedIndicator: {
+          textMatch: ['buy', 'shop', 'add to cart', 'checkout', 'order', 'purchase'],
+          tagNames: ['A', 'BUTTON']
+        }
+      },
+      {
+        id: 'step-3-navigate-shop',
+        name: 'Navigate to shop',
+        action: 'navigate',
+        target: '/shop',
+        description: 'If CTA not found, try /shop as fallback'
+      }
+    ]
+  };
+}
+
+/**
+ * Landing Page Journey: Simple homepage test
+ */
+function getLandingJourney() {
+  return {
+    name: 'Landing Page Journey',
+    description: 'Test: homepage → find contact/CTA → verify page load',
+    preset: 'landing',
+    steps: [
+      {
+        id: 'step-1-homepage',
+        name: 'Load homepage',
+        action: 'navigate',
+        target: '/',
+        description: 'User arrives at the homepage'
+      },
+      {
+        id: 'step-2-find-cta',
+        name: 'Find primary CTA',
+        action: 'find_cta',
+        target: null,
+        description: 'Locate primary call-to-action element',
+        expectedIndicator: {
+          textMatch: ['contact', 'get started', 'sign up', 'learn more', 'demo'],
+          tagNames: ['A', 'BUTTON']
+        }
+      }
+    ]
+  };
+}
+
+module.exports = {
+  getJourneyDefinition,
+  getSaasjJourney,
+  getShopJourney,
+  getLandingJourney
+};

package/src/guardian/journey-scan-cli.js

@@ -0,0 +1,145 @@
+/**
+ * Journey Scan CLI Command
+ * Entry point for running human journey scans from command line
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { JourneyScanner } = require('./journey-scanner');
+const { getJourneyDefinition } = require('./journey-definitions');
+const { HumanReporter } = require('./human-reporter');
+
+async function runJourneyScanCLI(config) {
+  const {
+    baseUrl,
+    preset = 'saas',
+    artifactsDir = './.odavlguardian',
+    headless = true,
+    timeout = 20000,
+    presetProvided = false
+  } = config;
+
+  // Set a process timeout to ensure we don't hang forever
+  const processTimeout = setTimeout(() => {
+    console.error('\n❌ Scan timeout: Process took too long (>120s)');
+    process.exit(2);
+  }, 120000); // 120 second hard limit
+
+  // Validate URL
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch (err) {
+    console.error(`❌ Invalid URL: ${baseUrl}`);
+    clearTimeout(processTimeout);
+    process.exit(2);
+  }
+
+  console.log(`\n🛡️  ODAVL Guardian — Human Journey Scanner`);
+  console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+  console.log(`📍 Target URL:  ${baseUrl}`);
+  console.log(`🎯 Preset:      ${presetProvided ? preset : '(auto)'}`);
+  console.log(`📁 Output:      ${artifactsDir}\n`);
+  process.stdout.write('');  // Flush stdout
+
+  // Create output directory
+  try {
+    if (!fs.existsSync(artifactsDir)) {
+      fs.mkdirSync(artifactsDir, { recursive: true });
+    }
+
+    const screenshotDir = path.join(artifactsDir, 'screenshots');
+    if (!fs.existsSync(screenshotDir)) {
+      fs.mkdirSync(screenshotDir, { recursive: true });
+    }
+
+    // Detect site intent if preset not provided
+    let finalPreset = preset;
+    let intentDetection = null;
+    if (!presetProvided) {
+      const { detectIntent } = require('./intent-detector');
+      console.log('🔎 Detecting site intent...');
+      intentDetection = await detectIntent(baseUrl, { timeout, headless });
+      console.log(`   Detected: ${intentDetection.intent.toUpperCase()} (confidence ${intentDetection.confidence}%)`);
+      if (intentDetection.intent === 'saas') finalPreset = 'saas';
+      else if (intentDetection.intent === 'shop') finalPreset = 'shop';
+      else if (intentDetection.intent === 'landing') finalPreset = 'landing';
+      else finalPreset = 'landing'; // default for unknown
+    }
+
+    // Get journey definition
+    const journey = getJourneyDefinition(finalPreset);
+    console.log(`🚀 Starting journey: ${journey.name}`);
+    console.log(`   ${journey.description}\n`);
+    process.stdout.write('');  // Flush stdout
+
+    // Run scanner
+    const scanner = new JourneyScanner({
+      timeout,
+      headless,
+      screenshotDir
+    });
+
+    console.log('⏳ Executing journey steps...\n');
+    process.stdout.write('');  // Flush stdout
+    
+    const result = await scanner.scan(baseUrl, journey);
+    if (intentDetection) {
+      result.intentDetection = intentDetection;
+    }
+
+    // Generate reports
+    const reporter = new HumanReporter();
+    const humanReport = reporter.generateSummary(result, artifactsDir);
+    const jsonReport = reporter.generateJSON(result, artifactsDir);
+
+    // Print summary to console
+    console.log('\n' + humanReport.content);
+    process.stdout.write('');  // Flush stdout
+
+    // Determine canonical verdict and exit code
+    const { toCanonicalJourneyVerdict, mapExitCodeFromCanonical } = require('./verdicts');
+    const canonical = toCanonicalJourneyVerdict(result.finalDecision);
+    const exitCode = mapExitCodeFromCanonical(canonical);
+
+    // Save results metadata
+    const metadata = {
+      timestamp: new Date().toISOString(),
+      url: baseUrl,
+      preset: finalPreset,
+      decision: result.finalDecision,
+      decisionCanonical: canonical,
+      executedSteps: result.executedSteps.length,
+      failedSteps: result.failedSteps.length
+    };
+
+    fs.writeFileSync(
+      path.join(artifactsDir, 'metadata.json'),
+      JSON.stringify(metadata, null, 2),
+      'utf8'
+    );
+
+    // Exit with canonical-mapped code
+
+    console.log(`📁 Reports saved to: ${artifactsDir}`);
+    console.log(`   - summary.txt (human readable)`);
+    console.log(`   - summary.md (markdown)`);
+    console.log(`   - report.json (full results)`);
+    console.log(`   - screenshots/ (evidence images)`);
+    process.stdout.write('');  // Flush stdout
+
+    clearTimeout(processTimeout);
+    process.exit(exitCode);
+  } catch (err) {
+    console.error(`\n❌ Scan failed: ${err.message}`);
+    if (process.env.DEBUG) {
+      console.error(err.stack);
+    }
+    clearTimeout(processTimeout);
+    process.exit(2);
+  }
+}
+
+module.exports = { runJourneyScanCLI };
+
+module.exports = { runJourneyScanCLI };