@odavl/guardian 0.1.0-rc1

package/src/guardian/screenshot.js

@@ -0,0 +1,152 @@
+/**
+ * Guardian Screenshot Module
+ * Captures and saves screenshots of visited pages
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class GuardianScreenshot {
+  constructor(options = {}) {
+    this.quality = options.quality || 80; // JPEG quality 0-100
+    this.fullPage = options.fullPage !== false; // Capture full page by default
+    this.type = options.type || 'jpeg'; // jpeg or png
+    this.normalizedViewport = options.normalizedViewport || { width: 1280, height: 720 }; // Phase 5: Consistent viewport
+  }
+
+  /**
+   * Normalize browser viewport for consistent screenshots (Phase 5)
+   * @param {Page} page - Playwright page object
+   * @returns {Promise<void>}
+   */
+  async normalizeViewport(page) {
+    try {
+      await page.setViewportSize({
+        width: this.normalizedViewport.width,
+        height: this.normalizedViewport.height
+      });
+      // Wait for layout to settle
+      await page.waitForTimeout(100);
+    } catch (err) {
+      console.warn(`⚠️  Viewport normalization failed: ${err.message}`);
+    }
+  }
+
+  /**
+   * Capture screenshot of current page
+   * @param {Page} page - Playwright page object
+   * @param {string} outputPath - Where to save the screenshot
+   * @param {object} options - Additional screenshot options
+   * @returns {Promise<boolean>} Success status
+   */
+  async capture(page, outputPath, options = {}) {
+    try {
+      // Phase 5: Normalize viewport for consistent visuals
+      if (options.normalize !== false) {
+        await this.normalizeViewport(page);
+      }
+
+      const screenshotOptions = {
+        path: outputPath,
+        type: this.type,
+        fullPage: options.fullPage !== undefined ? options.fullPage : this.fullPage,
+      };
+
+      // Add quality for JPEG
+      if (this.type === 'jpeg') {
+        screenshotOptions.quality = this.quality;
+      }
+
+      await page.screenshot(screenshotOptions);
+      return true;
+    } catch (error) {
+      console.error(`❌ Screenshot failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Generate filename for screenshot based on URL
+   * @param {string} url - Page URL
+   * @param {number} index - Page index
+   * @returns {string} Safe filename
+   */
+  generateFilename(url, index) {
+    try {
+      const urlObj = new URL(url);
+      let pathname = urlObj.pathname;
+      
+      // Root path
+      if (pathname === '/' || pathname === '') {
+        return `page-${index}-home.${this.type}`;
+      }
+
+      // Clean pathname for filename
+      let safeName = pathname
+        .replace(/^\//, '') // Remove leading slash
+        .replace(/\/$/, '') // Remove trailing slash
+        .replace(/\//g, '-') // Replace slashes with dashes
+        .replace(/[^a-zA-Z0-9\-_.]/g, '_') // Replace unsafe chars
+        .substring(0, 100); // Limit length
+
+      return `page-${index}-${safeName}.${this.type}`;
+    } catch (error) {
+      // Fallback for invalid URLs
+      return `page-${index}-unknown.${this.type}`;
+    }
+  }
+
+  /**
+   * Save screenshot during crawl
+   * @param {Page} page - Playwright page
+   * @param {string} url - Current URL
+   * @param {number} index - Page index
+   * @param {string} artifactsDir - Artifacts directory
+   * @returns {Promise<string|null>} Path to saved screenshot or null
+   */
+  async captureForCrawl(page, url, index, artifactsDir) {
+    try {
+      // Create pages subdirectory
+      const pagesDir = path.join(artifactsDir, 'pages');
+      if (!fs.existsSync(pagesDir)) {
+        fs.mkdirSync(pagesDir, { recursive: true });
+      }
+
+      // Generate filename and full path
+      const filename = this.generateFilename(url, index);
+      const outputPath = path.join(pagesDir, filename);
+
+      // Capture screenshot
+      const success = await this.capture(page, outputPath);
+      
+      if (success) {
+        return filename; // Return relative filename
+      }
+      return null;
+    } catch (error) {
+      console.error(`❌ Failed to capture screenshot for ${url}: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Validate that screenshot file exists and has reasonable size
+   * @param {string} filepath - Path to screenshot file
+   * @returns {boolean} True if valid
+   */
+  validateScreenshot(filepath) {
+    try {
+      if (!fs.existsSync(filepath)) {
+        return false;
+      }
+
+      const stats = fs.statSync(filepath);
+      // Screenshot should be at least 1KB
+      return stats.size > 1024;
+    } catch (error) {
+      return false;
+    }
+  }
+}
+
+module.exports = GuardianScreenshot;

package/src/guardian/sitemap.js

@@ -0,0 +1,225 @@
+/**
+ * Guardian Sitemap Discovery Module
+ * Discovers URLs from robots.txt and sitemap.xml
+ */
+
+const https = require('https');
+const http = require('http');
+
+class GuardianSitemap {
+  constructor(options = {}) {
+    this.timeout = options.timeout || 10000; // 10 seconds timeout
+    this.maxUrls = options.maxUrls || 200; // Maximum URLs to extract
+  }
+
+  /**
+   * Fetch content from URL
+   * @param {string} url - URL to fetch
+   * @returns {Promise<string|null>} Content or null if failed
+   */
+  async fetch(url) {
+    return new Promise((resolve) => {
+      try {
+        const urlObj = new URL(url);
+        const client = urlObj.protocol === 'https:' ? https : http;
+        
+        const request = client.get(url, { timeout: this.timeout }, (response) => {
+          // Follow redirects
+          if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+            return this.fetch(response.headers.location).then(resolve);
+          }
+
+          if (response.statusCode !== 200) {
+            return resolve(null);
+          }
+
+          let data = '';
+          response.on('data', (chunk) => { data += chunk; });
+          response.on('end', () => resolve(data));
+        });
+
+        request.on('error', () => resolve(null));
+        request.on('timeout', () => {
+          request.destroy();
+          resolve(null);
+        });
+      } catch (error) {
+        resolve(null);
+      }
+    });
+  }
+
+  /**
+   * Discover sitemap URLs from robots.txt
+   * @param {string} baseUrl - Base URL of the website
+   * @returns {Promise<string[]>} Array of sitemap URLs
+   */
+  async discoverFromRobots(baseUrl) {
+    try {
+      const robotsUrl = new URL('/robots.txt', baseUrl).href;
+      const content = await this.fetch(robotsUrl);
+      
+      if (!content) {
+        return [];
+      }
+
+      const sitemaps = [];
+      const lines = content.split('\n');
+      
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.toLowerCase().startsWith('sitemap:')) {
+          const sitemapUrl = trimmed.substring(8).trim();
+          if (sitemapUrl) {
+            sitemaps.push(sitemapUrl);
+          }
+        }
+      }
+
+      return sitemaps;
+    } catch (error) {
+      console.error(`❌ Failed to fetch robots.txt: ${error.message}`);
+      return [];
+    }
+  }
+
+  /**
+   * Parse sitemap XML and extract URLs
+   * @param {string} xml - Sitemap XML content
+   * @returns {string[]} Array of URLs
+   */
+  parseSitemap(xml) {
+    try {
+      const urls = [];
+      
+      // Simple regex to extract <loc> tags (works for most sitemaps)
+      const locRegex = /<loc>(.*?)<\/loc>/gi;
+      let match;
+      
+      while ((match = locRegex.exec(xml)) !== null && urls.length < this.maxUrls) {
+        const url = match[1].trim();
+        if (url) {
+          urls.push(url);
+        }
+      }
+
+      return urls;
+    } catch (error) {
+      console.error(`❌ Failed to parse sitemap: ${error.message}`);
+      return [];
+    }
+  }
+
+  /**
+   * Check if URL is a sitemap index (contains other sitemaps)
+   * @param {string} xml - XML content
+   * @returns {boolean} True if sitemap index
+   */
+  isSitemapIndex(xml) {
+    return xml.includes('<sitemapindex') || xml.includes('</sitemapindex>');
+  }
+
+  /**
+   * Discover all URLs from base URL (robots.txt + sitemaps)
+   * @param {string} baseUrl - Base URL of the website
+   * @returns {Promise<object>} Object with discovered URLs and stats
+   */
+  async discover(baseUrl) {
+    const result = {
+      urls: [],
+      sitemapsChecked: 0,
+      source: 'none',
+    };
+
+    try {
+      // Step 1: Check robots.txt for sitemap URLs
+      console.log('🗺️  Checking robots.txt for sitemaps...');
+      const sitemapUrls = await this.discoverFromRobots(baseUrl);
+      
+      if (sitemapUrls.length === 0) {
+        // Try default sitemap.xml location
+        console.log('🗺️  Trying default sitemap.xml...');
+        sitemapUrls.push(new URL('/sitemap.xml', baseUrl).href);
+      }
+
+      // Step 2: Fetch and parse each sitemap
+      for (const sitemapUrl of sitemapUrls) {
+        if (result.urls.length >= this.maxUrls) {
+          break;
+        }
+
+        console.log(`🗺️  Fetching sitemap: ${sitemapUrl}`);
+        const xml = await this.fetch(sitemapUrl);
+        
+        if (!xml) {
+          continue;
+        }
+
+        result.sitemapsChecked++;
+
+        // Check if it's a sitemap index
+        if (this.isSitemapIndex(xml)) {
+          const childSitemaps = this.parseSitemap(xml);
+          console.log(`🗺️  Found sitemap index with ${childSitemaps.length} child sitemaps`);
+          
+          // Fetch child sitemaps
+          for (const childUrl of childSitemaps) {
+            if (result.urls.length >= this.maxUrls) {
+              break;
+            }
+
+            const childXml = await this.fetch(childUrl);
+            if (childXml) {
+              const childUrls = this.parseSitemap(childXml);
+              result.urls.push(...childUrls.slice(0, this.maxUrls - result.urls.length));
+              result.sitemapsChecked++;
+            }
+          }
+        } else {
+          // Regular sitemap
+          const urls = this.parseSitemap(xml);
+          result.urls.push(...urls.slice(0, this.maxUrls - result.urls.length));
+        }
+      }
+
+      // Deduplicate URLs
+      result.urls = [...new Set(result.urls)];
+      
+      if (result.urls.length > 0) {
+        result.source = 'sitemap';
+        console.log(`✅ Discovered ${result.urls.length} URLs from ${result.sitemapsChecked} sitemap(s)`);
+      } else {
+        console.log('⚠️  No URLs found in sitemaps');
+      }
+
+      return result;
+    } catch (error) {
+      console.error(`❌ Sitemap discovery failed: ${error.message}`);
+      return result;
+    }
+  }
+
+  /**
+   * Filter URLs to same origin only
+   * @param {string[]} urls - Array of URLs
+   * @param {string} baseUrl - Base URL to compare against
+   * @returns {string[]} Filtered URLs
+   */
+  filterSameOrigin(urls, baseUrl) {
+    try {
+      const baseOrigin = new URL(baseUrl).origin;
+      
+      return urls.filter(url => {
+        try {
+          return new URL(url).origin === baseOrigin;
+        } catch {
+          return false;
+        }
+      });
+    } catch (error) {
+      return [];
+    }
+  }
+}
+
+module.exports = GuardianSitemap;

package/src/guardian/snapshot-schema.js

@@ -0,0 +1,266 @@
+/**
+ * Market Reality Snapshot v1 Schema Definition
+ * 
+ * A snapshot captures a complete market reality test run:
+ * - what was discovered (crawl)
+ * - what was attempted (attempts)
+ * - what was observed (evidence: screenshots, traces, reports)
+ * - what signals were detected (friction, failures, regressions)
+ * - what the baseline was and how current differs
+ */
+
+const SNAPSHOT_SCHEMA_VERSION = 'v1';
+
+/**
+ * @typedef {Object} SnapshotMeta
+ * @property {string} schemaVersion - always 'v1'
+ * @property {string} createdAt - ISO timestamp
+ * @property {string} toolVersion - package.json version
+ * @property {string} url - base URL tested
+ * @property {string} runId - unique run identifier
+ * @property {string} [environment] - optional deployment environment
+ */
+
+/**
+ * @typedef {Object} CrawlResult
+ * @property {string[]} discoveredUrls - all unique URLs found
+ * @property {number} visitedCount - pages successfully loaded
+ * @property {number} failedCount - pages that failed to load
+ * @property {number} safetyBlockedCount - pages blocked by safety rules
+ * @property {Array<{url: string, statusCode: number, error: string}>} [httpFailures] - detailed failures
+ * @property {string} [notes] - human-readable summary
+ */
+
+/**
+ * @typedef {Object} ValidatorResult
+ * @property {string} id - unique validator ID
+ * @property {string} type - validator type (urlIncludes, elementVisible, etc)
+ * @property {string} status - 'PASS', 'FAIL', or 'WARN'
+ * @property {string} message - human readable result
+ * @property {Object} [evidence] - supporting data (selector, url, snippet, etc)
+ */
+
+/**
+ * @typedef {Object} AttemptResult
+ * @property {string} attemptId - unique attempt identifier
+ * @property {string} attemptName - human-readable name
+ * @property {string} goal - what the user tried to achieve
+ * @property {string} outcome - 'SUCCESS', 'FAILURE', or 'FRICTION'
+ * @property {number} totalDurationMs - elapsed time
+ * @property {number} stepCount - how many steps executed
+ * @property {number} failedStepIndex - index of first failed step, or -1 if all succeeded
+ * @property {Object} friction - friction signals for this attempt
+ * @property {ValidatorResult[]} [validators] - soft failure detectors (Phase 2)
+ * @property {number} [softFailureCount] - count of failed validators
+ * @property {string} [riskCategory] - 'LEAD', 'REVENUE', 'TRUST/UX' (Phase 2)
+ */
+
+/**
+ * @typedef {Object} Evidence
+ * @property {string} artifactDir - root directory where all artifacts were saved
+ * @property {string} [marketReportJson] - path to market-report.json
+ * @property {string} [marketReportHtml] - path to market-report.html
+ * @property {string} [traceZip] - path to trace.zip if enabled
+ * @property {Object<string, string>} [attemptArtifacts] - { attemptId => { reportJson, reportHtml, screenshotDir } }
+ */
+
+/**
+ * @typedef {Object} Signal
+ * @property {string} id - unique signal ID
+ * @property {string} severity - 'low', 'medium', 'high', 'critical'
+ * @property {string} type - 'friction', 'failure', 'regression', 'timeout', 'missing_element', 'soft_failure'
+ * @property {string} description - human readable
+ * @property {string} [affectedAttemptId] - if specific to an attempt
+ */
+
+/**
+ * @typedef {Object} BaselineInfo
+ * @property {boolean} baselineFound - whether a baseline was loaded
+ * @property {boolean} baselineCreatedThisRun - true if baseline was auto-created in this run
+ * @property {string} [baselineCreatedAt] - ISO timestamp when baseline was first created
+ * @property {string} [baselinePath] - file system path to baseline
+ * @property {Object} [diff] - comparison result if baseline exists
+ * @property {Object} [diff.regressions] - { attemptId => {before, after, reason} }
+ * @property {Object} [diff.improvements] - { attemptId => {before, after, reason} }
+ * @property {number} [diff.attemptsDriftCount] - how many attempts changed outcome
+ * @property {Array} [diff.validatorsChanged] - validator regression details (Phase 2)
+ */
+
+/**
+ * @typedef {Object} MarketRisk
+ * @property {string} attemptId - which attempt
+ * @property {string} validatorId - which validator or friction signal
+ * @property {string} category - REVENUE|LEAD|TRUST|UX
+ * @property {string} severity - CRITICAL|WARNING|INFO
+ * @property {number} impactScore - 0-100 deterministic score
+ * @property {string} humanReadableReason - explanation
+ */
+
+/**
+ * @typedef {Object} MarketImpactSummary
+ * @property {string} highestSeverity - CRITICAL|WARNING|INFO
+ * @property {number} totalRiskCount - total number of identified risks
+ * @property {Object} countsBySeverity - { CRITICAL: N, WARNING: N, INFO: N }
+ * @property {MarketRisk[]} topRisks - top 10 risks, sorted by impact score
+ */
+
+/**
+ * @typedef {Object} InteractionResult
+ * @property {string} interactionId - unique ID
+ * @property {string} pageUrl - URL where found
+ * @property {string} type - NAVIGATE|CLICK|FORM_FILL
+ * @property {string} selector - CSS selector to find element
+ * @property {string} outcome - SUCCESS|FAILURE|FRICTION
+ * @property {string} [notes] - details (target URL, error, etc)
+ * @property {number} [durationMs] - execution time
+ * @property {string} [errorMessage] - if FAILURE
+ * @property {string} [evidencePath] - path to screenshot
+ */
+
+/**
+ * @typedef {Object} DiscoverySummary
+ * @property {string[]} pagesVisited - URLs crawled
+ * @property {number} pagesVisitedCount - total pages
+ * @property {number} interactionsDiscovered - total candidates found
+ * @property {number} interactionsExecuted - candidates executed
+ * @property {Object} interactionsByType - { NAVIGATE: N, CLICK: N, FORM_FILL: N }
+ * @property {Object} interactionsByRisk - { safe: N, risky: N }
+ * @property {InteractionResult[]} results - execution results (failures + top successes)
+ * @property {string} [summary] - human readable summary
+ */
+
+/**
+ * @typedef {Object} MarketRealitySnapshot
+ * @property {string} schemaVersion - always 'v1'
+ * @property {SnapshotMeta} meta
+ * @property {CrawlResult} [crawl]
+ * @property {AttemptResult[]} attempts
+ * @property {Array} flows
+ * @property {Signal[]} signals
+ * @property {Object} [riskSummary] - market risk analysis (Phase 2)
+ * @property {MarketImpactSummary} [marketImpactSummary] - market criticality (Phase 3)
+ * @property {DiscoverySummary} [discovery] - auto-discovered interactions (Phase 4)
+ * @property {Evidence} evidence
+ * @property {BaselineInfo} baseline
+ */
+
+function createEmptySnapshot(baseUrl, runId, toolVersion) {
+  return {
+    schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+    meta: {
+      schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+      createdAt: new Date().toISOString(),
+      toolVersion,
+      url: baseUrl,
+      runId,
+      environment: process.env.GUARDIAN_ENV || 'production'
+    },
+    crawl: {
+      discoveredUrls: [],
+      visitedCount: 0,
+      failedCount: 0,
+      safetyBlockedCount: 0,
+      httpFailures: [],
+      notes: ''
+    },
+    attempts: [],
+    flows: [],
+    signals: [],
+    riskSummary: {
+      totalSoftFailures: 0,
+      totalFriction: 0,
+      failuresByCategory: {},
+      topRisks: []
+    },
+    marketImpactSummary: {
+      highestSeverity: 'INFO',
+      totalRiskCount: 0,
+      countsBySeverity: {
+        CRITICAL: 0,
+        WARNING: 0,
+        INFO: 0
+      },
+      topRisks: []
+    },
+    discovery: {
+      pagesVisited: [],
+      pagesVisitedCount: 0,
+      interactionsDiscovered: 0,
+      interactionsExecuted: 0,
+      interactionsByType: {
+        NAVIGATE: 0,
+        CLICK: 0,
+        FORM_FILL: 0
+      },
+      interactionsByRisk: {
+        safe: 0,
+        risky: 0
+      },
+      results: [],
+      summary: ''
+    },
+    evidence: {
+      artifactDir: '',
+      attemptArtifacts: {},
+      flowArtifacts: {}
+    },
+    intelligence: {
+      totalFailures: 0,
+      failures: [],
+      byDomain: {},
+      bySeverity: {},
+      escalationSignals: [],
+      summary: ''
+    },
+    baseline: {
+      baselineFound: false,
+      baselineCreatedThisRun: false,
+      baselineCreatedAt: null,
+      baselinePath: null,
+      diff: null
+    }
+  };
+}
+
+function validateSnapshot(snapshot) {
+  const errors = [];
+
+  if (!snapshot.schemaVersion || snapshot.schemaVersion !== SNAPSHOT_SCHEMA_VERSION) {
+    errors.push('Missing or invalid schemaVersion');
+  }
+
+  if (!snapshot.meta || !snapshot.meta.createdAt || !snapshot.meta.url || !snapshot.meta.runId) {
+    errors.push('Missing required meta fields: createdAt, url, runId');
+  }
+
+  if (!Array.isArray(snapshot.attempts)) {
+    errors.push('attempts must be an array');
+  }
+
+  if (!Array.isArray(snapshot.signals)) {
+    errors.push('signals must be an array');
+  }
+
+  if (!Array.isArray(snapshot.flows)) {
+    errors.push('flows must be an array');
+  }
+
+  if (!snapshot.evidence || !snapshot.evidence.artifactDir) {
+    errors.push('Missing evidence.artifactDir');
+  }
+
+  if (!snapshot.baseline) {
+    errors.push('Missing baseline section');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+module.exports = {
+  SNAPSHOT_SCHEMA_VERSION,
+  createEmptySnapshot,
+  validateSnapshot
+};