@odavl/guardian 0.2.0 → 1.0.0

package/src/guardian/verdict.js

@@ -0,0 +1,320 @@
+/**
+ * Unified Verdict Builder
+ * Deterministic, explainable verdict and confidence scoring
+ */
+
+function clamp01(x) { return Math.max(0, Math.min(1, x)); }
+
+const isExecutedAttempt = (attempt) => attempt && attempt.outcome !== 'SKIPPED';
+
+function mapRunResultToVerdict(runResult) {
+  const r = (runResult || '').toUpperCase();
+  if (r === 'PASSED') return 'READY';
+  if (r === 'FAILED') return 'DO_NOT_LAUNCH';
+  if (r === 'INSUFFICIENT_EVIDENCE') return 'INSUFFICIENT_EVIDENCE';
+  return 'FRICTION'; // WARN or anything else
+}
+
+function computeCoverageScore(snapshot) {
+  const disc = snapshot.discovery || {};
+  if (disc.interactionsDiscovered && disc.interactionsDiscovered > 0) {
+    return clamp01((disc.interactionsExecuted || 0) / (disc.interactionsDiscovered || 1));
+  }
+  const attempts = snapshot.attempts || [];
+  const executedAttempts = attempts.filter(isExecutedAttempt);
+  const executed = executedAttempts.length;
+  return executed > 0 ? 1 : 0; // if we have executed attempts, consider coverage adequate
+}
+
+function computeEvidenceScore(snapshot) {
+  const e = snapshot.evidence || {};
+  const features = [
+    !!e.marketReportJson,
+    !!e.marketReportHtml,
+    !!e.traceZip,
+    !!(e.attemptArtifacts && Object.keys(e.attemptArtifacts).length > 0)
+  ];
+  const present = features.filter(Boolean).length;
+  return clamp01(present / features.length);
+}
+
+function computePenalty(snapshot) {
+  const attempts = snapshot.attempts || [];
+  const failures = attempts.filter(a => a.outcome === 'FAILURE').length;
+  const frictions = attempts.filter(a => a.outcome === 'FRICTION').length;
+  const perFailure = 0.15;
+  const perFriction = 0.1;
+  const raw = failures * perFailure + frictions * perFriction;
+  return Math.min(0.5, raw);
+}
+
+function levelFromScore(score) {
+  if (score >= 0.66) return 'high';
+  if (score >= 0.33) return 'medium';
+  return 'low';
+}
+
+function collectKeyFindings(snapshot) {
+  const findings = [];
+  const attempts = snapshot.attempts || [];
+  const executedAttempts = attempts.filter(a => a.outcome !== 'SKIPPED');
+  const skippedAttempts = attempts.filter(a => a.outcome === 'SKIPPED');
+  const successful = executedAttempts.filter(a => a.outcome === 'SUCCESS').length;
+  const failed = executedAttempts.filter(a => a.outcome === 'FAILURE').length;
+  const friction = executedAttempts.filter(a => a.outcome === 'FRICTION').length;
+
+  // Attempt outcomes
+  if (executedAttempts.length > 0) {
+    findings.push(`${successful} of ${executedAttempts.length} executed attempts completed`);
+    if (failed > 0) findings.push(`${failed} attempt did not complete`);
+    if (friction > 0) findings.push(`${friction} attempt showed friction (slower or rougher than baseline)`);
+    if (skippedAttempts.length > 0) {
+      findings.push(`${skippedAttempts.length} attempt was not executed`);
+    }
+  }
+
+  // Market impact
+  const mi = snapshot.marketImpactSummary || {};
+  const counts = mi.countsBySeverity || { CRITICAL: 0, WARNING: 0, INFO: 0 };
+  if (counts.CRITICAL > 0 || counts.WARNING > 0) {
+    findings.push(`${counts.CRITICAL} critical risk and ${counts.WARNING} warning risk identified`);
+  } else {
+    findings.push(`No critical or warning risks identified`);
+  }
+
+  // Discovery coverage
+  const disc = snapshot.discovery || {};
+  if ((disc.interactionsExecuted || 0) > 0) {
+    findings.push(`${disc.interactionsExecuted}/${disc.interactionsDiscovered || 0} discovered interactions executed`);
+  }
+
+  // Evidence
+  const e = snapshot.evidence || {};
+  const hasReports = !!(e.marketReportJson && e.marketReportHtml);
+  const hasTraces = !!e.traceZip;
+  const hasScreenshots = !!(e.attemptArtifacts && Object.keys(e.attemptArtifacts).length > 0);
+  const evidenceCount = [hasReports, hasTraces, hasScreenshots].filter(Boolean).length;
+  if (evidenceCount === 3) {
+    findings.push(`Complete evidence: reports, traces, and screenshots captured`);
+  } else if (evidenceCount > 0) {
+    findings.push(`Partial evidence: ${[hasReports && 'reports', hasTraces && 'traces', hasScreenshots && 'screenshots'].filter(Boolean).join(', ')}`);
+  }
+
+  return findings.slice(0, 7);
+}
+
+function collectEvidenceRefs(snapshot) {
+  const e = snapshot.evidence || {};
+  const reportPaths = [];
+  if (e.marketReportJson) reportPaths.push(e.marketReportJson);
+  if (e.marketReportHtml) reportPaths.push(e.marketReportHtml);
+  const traces = e.traceZip ? [e.traceZip] : [];
+  const screenshots = [];
+  if (e.attemptArtifacts) {
+    Object.values(e.attemptArtifacts).forEach(a => {
+      if (a.screenshotDir) screenshots.push(a.screenshotDir);
+    });
+  }
+  const affectedPages = (snapshot.discovery?.pagesVisited || []).slice(0, 10);
+  return { reportPaths, traces, screenshots, affectedPages };
+}
+
+function defaultLimits() {
+  return [
+    'Live-site variability may affect signals',
+    'Browser/viewport differences can change outcomes',
+    'Coverage limited to configured attempts and discovered interactions'
+  ];
+}
+
+function situationalLimits(snapshot) {
+  const limits = [];
+  const attempts = snapshot.attempts || [];
+  const skippedCount = attempts.filter(a => a.outcome === 'SKIPPED').length;
+  const disc = snapshot.discovery || {};
+
+  // Skipped attempts
+  if (skippedCount > 0) {
+    limits.push(`${skippedCount} additional attempt was not executed; verdict is therefore limited to fewer paths`);
+  }
+
+  // Discovery coverage gaps
+  const discovered = disc.interactionsDiscovered || 0;
+  const executed = disc.interactionsExecuted || 0;
+  if (discovered > 0 && executed < discovered) {
+    limits.push(`${discovered - executed} of ${discovered} discovered interactions were not tested`);
+  }
+
+  // Evidence gaps
+  const e = snapshot.evidence || {};
+  if (!e.traceZip) {
+    limits.push(`Detailed timing traces were not captured; timing-related issues may not be visible`);
+  }
+  if (!e.marketReportJson) {
+    limits.push(`Market risk analysis was not run; business impact is unassessed`);
+  }
+
+  // Environment variability
+  limits.push(`Live site behavior shifts over time; this verdict reflects this moment`);
+
+  // Browser/environment
+  limits.push(`Results are specific to this browser and viewport; other browsers may differ`);
+
+  return limits.slice(0, 6);
+}
+
+/**
+ * Build unified verdict from snapshot
+ */
+function deriveRunResult(snapshot) {
+  const meta = snapshot.meta || {};
+  if (meta.result) return meta.result;
+  const attempts = snapshot.attempts || [];
+  
+  // Count different outcome types
+  const executedAttempts = attempts.filter(a => a.outcome !== 'SKIPPED' && a.outcome !== 'NOT_APPLICABLE');
+  const discoveryFailedAttempts = attempts.filter(a => a.outcome === 'DISCOVERY_FAILED');
+  const notApplicableAttempts = attempts.filter(a => a.outcome === 'NOT_APPLICABLE');
+  const skippedCount = attempts.filter(a => a.outcome === 'SKIPPED').length;
+  
+  const executed = executedAttempts.length;
+  const successful = executedAttempts.filter(a => a.outcome === 'SUCCESS').length;
+  const failed = executedAttempts.filter(a => a.outcome === 'FAILURE').length;
+  
+  // If NOTHING executed (all skipped, not applicable, or discovery failed), it's insufficient
+  if (executed === 0 && (discoveryFailedAttempts.length > 0 || skippedCount > 0)) {
+    return 'INSUFFICIENT_EVIDENCE';
+  }
+  
+  if (executed === 0) return 'WARN';
+  if (failed === 0 && successful === executed) return 'PASSED';
+  if (failed === executed) return 'FAILED';
+  return 'WARN';
+}
+
+function buildVerdictExplanation(snapshot, verdictStr, executedCount, successCount, failureCount, skippedCount, evidenceScore, penaltyApplied) {
+  let why = '';
+  
+  if (verdictStr === 'READY') {
+    why = `All ${executedCount} executed attempts completed successfully without critical issues. `;
+    if (skippedCount > 0) {
+      why += `${skippedCount} additional attempt was not executed. `;
+    }
+    why += `Evidence is ${evidenceScore >= 0.75 ? 'complete' : 'sufficient'}. `;
+    why += `This differs from FRICTION because all attempts succeeded, and from DO_NOT_LAUNCH because no critical issues were found.`;
+  } else if (verdictStr === 'DO_NOT_LAUNCH') {
+    why = `${failureCount} critical issue was found, preventing safe launch. `;
+    why += `This differs from READY because critical issues must be resolved, and from FRICTION because severity exceeds acceptable limits.`;
+  } else if (verdictStr === 'INSUFFICIENT_EVIDENCE') {
+    why = `No meaningful attempts executed on this site. Most attempts were skipped (not applicable to site) or element discovery failed. `;
+    why += `This site may not match the tested user journeys, or it may be uninstrumented (missing expected UI elements/patterns). `;
+    why += `Verdict cannot be determined without successful execution of at least one relevant journey.`;
+  } else {
+    why = `Results show ${successCount} of ${executedCount} attempted success with some roughness. `;
+    if (failureCount > 0) {
+      why += `${failureCount} attempt did not complete. `;
+    }
+    why += `This differs from READY because outcomes were mixed, and from DO_NOT_LAUNCH because no critical failure was found.`;
+  }
+  
+  return why;
+}
+
+function deriveNextRunHint(snapshot, confidenceLevel) {
+  // Non-intrusive guard: suppress when confidence is high and limits are empty
+  const limits = situationalLimits(snapshot) || [];
+  if (confidenceLevel === 'high' && limits.length === 0) {
+    return null;
+  }
+
+  // (a) Evidence completeness
+  const e = snapshot.evidence || {};
+  const hasReports = !!(e.marketReportJson && e.marketReportHtml);
+  const hasTrace = !!e.traceZip;
+  const hasScreenshots = !!(e.attemptArtifacts && Object.keys(e.attemptArtifacts).length > 0);
+  if (!hasTrace || !hasScreenshots) {
+    return 'Capture additional evidence (e.g., traces) to strengthen timing and flow visibility.';
+  }
+
+  // (b) Coverage completeness
+  const disc = snapshot.discovery || {};
+  const discovered = disc.interactionsDiscovered || 0;
+  const executed = disc.interactionsExecuted || 0;
+  if (discovered > 0 && executed < discovered) {
+    return 'Expand coverage to include additional discovered interactions.';
+  }
+
+  // (c) Recurring timeouts/flakiness within this run
+  const attempts = snapshot.attempts || [];
+  const flows = snapshot.flows || [];
+  const timeoutRegex = /(timeout|timed out)/i;
+  const timeoutCount = (
+    attempts.filter(a => typeof a.error === 'string' && timeoutRegex.test(a.error)).length +
+    flows.filter(f => typeof f.error === 'string' && timeoutRegex.test(f.error)).length
+  );
+  const frictionCount = attempts.filter(a => a.friction && a.friction.isFriction).length;
+  if (timeoutCount >= 2 || frictionCount >= 2) {
+    return 'Use a conservative timeout profile to reduce flakiness.';
+  }
+
+  // (d) Otherwise: no hint
+  return null;
+}
+
+function buildVerdict(snapshot) {
+  const runRes = deriveRunResult(snapshot);
+  const verdictStr = mapRunResultToVerdict(runRes || 'WARN');
+
+  const outcomeScore = verdictStr === 'READY' ? 1 : verdictStr === 'DO_NOT_LAUNCH' ? 0.2 : 0.5;
+  const coverageScore = computeCoverageScore(snapshot); // 0..1
+  const evidenceScore = computeEvidenceScore(snapshot); // 0..1
+  const penalty = computePenalty(snapshot); // 0..0.5
+
+  const raw = 0.5 * outcomeScore + 0.2 * coverageScore + 0.3 * evidenceScore - penalty;
+  const score = clamp01(raw);
+  const level = levelFromScore(score);
+
+  // Detailed metrics for explanation
+  const attempts = snapshot.attempts || [];
+  const executedAttempts = attempts.filter(a => a.outcome !== 'SKIPPED');
+  const executedCount = executedAttempts.length;
+  const successCount = executedAttempts.filter(a => a.outcome === 'SUCCESS').length;
+  const failureCount = executedAttempts.filter(a => a.outcome === 'FAILURE').length;
+  const skippedCount = attempts.filter(a => a.outcome === 'SKIPPED').length;
+
+  const reasons = [];
+  if (successCount === executedCount && executedCount > 0) {
+    reasons.push(`All ${executedCount} executed attempts completed`);
+  } else if (successCount > 0) {
+    reasons.push(`${successCount} of ${executedCount} executed attempts completed`);
+  }
+  if (coverageScore > 0.66) reasons.push('Good coverage from discovered interactions');
+  if (evidenceScore >= 0.75) reasons.push('Complete evidence captured (reports, traces, screenshots)');
+  if (penalty > 0) reasons.push(`${failureCount > 0 ? 'Incomplete attempts' : 'Friction signals'} observed (${(penalty * 100).toFixed(0)}% impact)`);
+  // Do not include 'not executed' in drivers; it appears in findings/limits
+
+  const why = buildVerdictExplanation(
+    snapshot,
+    verdictStr,
+    executedCount,
+    successCount,
+    failureCount,
+    skippedCount,
+    evidenceScore,
+    penalty > 0
+  );
+
+  const nextRunHint = deriveNextRunHint(snapshot, level);
+
+  return {
+    verdict: verdictStr,
+    confidence: { level, score, reasons },
+    why,
+    keyFindings: collectKeyFindings(snapshot),
+    evidence: collectEvidenceRefs(snapshot),
+    limits: situationalLimits(snapshot),
+    nextRunHint
+  };
+}
+
+module.exports = { buildVerdict };

package/src/guardian/verdicts.js

@@ -0,0 +1,74 @@
+/**
+ * Verdict mapping utilities
+ * Canonical user-facing verdicts: READY, FRICTION, DO_NOT_LAUNCH
+ * Internal engine verdicts (legacy): OBSERVED, PARTIAL, INSUFFICIENT_DATA
+ */
+
+function toCanonicalVerdict(internalVerdict) {
+  switch (String(internalVerdict || '').toUpperCase()) {
+    // Internal engine verdicts
+    case 'OBSERVED':
+      return 'READY';
+    case 'PARTIAL':
+      return 'FRICTION';
+    case 'INSUFFICIENT_DATA':
+      return 'DO_NOT_LAUNCH';
+    // Synonyms from other components
+    case 'PASS':
+    case 'SUCCESS':
+      return 'READY';
+    case 'WARN':
+    case 'WARNING':
+    case 'FRICTION':
+      return 'FRICTION';
+    case 'FAIL':
+    case 'FAILURE':
+    case 'DO_NOT_LAUNCH':
+      return 'DO_NOT_LAUNCH';
+    default:
+      return 'DO_NOT_LAUNCH';
+  }
+}
+
+function toInternalVerdict(canonicalVerdict) {
+  switch (String(canonicalVerdict || '').toUpperCase()) {
+    case 'READY':
+      return 'OBSERVED';
+    case 'FRICTION':
+      return 'PARTIAL';
+    case 'DO_NOT_LAUNCH':
+      return 'INSUFFICIENT_DATA';
+    default:
+      return 'INSUFFICIENT_DATA';
+  }
+}
+
+function mapExitCodeFromCanonical(canonicalVerdict) {
+  switch (String(canonicalVerdict || '').toUpperCase()) {
+    case 'READY':
+      return 0;
+    case 'FRICTION':
+      return 1;
+    case 'DO_NOT_LAUNCH':
+    default:
+      return 2;
+  }
+}
+
+module.exports = { toCanonicalVerdict, toInternalVerdict, mapExitCodeFromCanonical };
+
+// Journey scan mapping (SAFE/RISK/DO_NOT_LAUNCH → canonical)
+function toCanonicalJourneyVerdict(journeyVerdict) {
+  switch (String(journeyVerdict || '').toUpperCase()) {
+    case 'SAFE':
+      return 'READY';
+    case 'RISK':
+      return 'FRICTION';
+    case 'DO_NOT_LAUNCH':
+      return 'DO_NOT_LAUNCH';
+    default:
+      return 'DO_NOT_LAUNCH';
+  }
+}
+
+module.exports.toCanonicalJourneyVerdict = toCanonicalJourneyVerdict;

package/src/guardian/watch-runner.js

@@ -19,17 +19,13 @@ function isIgnored(filePath, artifactsDir = './artifacts') {
   if (artifactsDir) {
     ignorePrefixes.push(path.normalize(artifactsDir));
   }
-  return parts.some(p => ignorePrefixes.includes(p)) || normalized.includes('market-run');
+  // Ignore any changes within artifacts directory (run outputs)
+  return parts.some(p => ignorePrefixes.includes(p));
 }
 
 function collectWatchPaths(config) {
   const roots = [
-    'guardian.config.json',
-    'guardian.policy.json',
-    'guardian.profile.docs.yaml',
-    'guardian.profile.ecommerce.yaml',
-    'guardian.profile.marketing.yaml',
-    'guardian.profile.saas.yaml',
+    'config',
     'flows',
     'policies',
     'data',

package/src/payments/stripe-checkout.js

@@ -0,0 +1,169 @@
+/**
+ * ODAVL Guardian Stripe Integration
+ * Real Stripe checkout for PRO and BUSINESS plans
+ */
+
+const { PLANS } = require('../plans/plan-definitions');
+const { setCurrentPlan } = require('../plans/plan-manager');
+
+// Stripe configuration
+const STRIPE_PUBLIC_KEY = process.env.STRIPE_PUBLIC_KEY || '';
+const STRIPE_SECRET_KEY = process.env.STRIPE_SECRET_KEY || '';
+const STRIPE_WEBHOOK_SECRET = process.env.STRIPE_WEBHOOK_SECRET || '';
+
+/**
+ * Create Stripe checkout session
+ * This is called from the website when user clicks "Upgrade"
+ */
+async function createCheckoutSession(planId, successUrl, cancelUrl) {
+  if (!STRIPE_SECRET_KEY) {
+    throw new Error('Stripe is not configured. Set STRIPE_SECRET_KEY environment variable.');
+  }
+  
+  const stripe = require('stripe')(STRIPE_SECRET_KEY);
+  const plan = PLANS[planId.toUpperCase()];
+  
+  if (!plan || !plan.stripePriceId) {
+    throw new Error(`Invalid plan: ${planId}`);
+  }
+  
+  const session = await stripe.checkout.sessions.create({
+    mode: 'subscription',
+    payment_method_types: ['card'],
+    line_items: [
+      {
+        price: plan.stripePriceId,
+        quantity: 1,
+      },
+    ],
+    success_url: successUrl,
+    cancel_url: cancelUrl,
+    metadata: {
+      planId: plan.id,
+    },
+  });
+  
+  return {
+    sessionId: session.id,
+    url: session.url,
+  };
+}
+
+/**
+ * Handle Stripe webhook events
+ * Called when payment succeeds or subscription changes
+ */
+async function handleWebhook(requestBody, signature) {
+  if (!STRIPE_SECRET_KEY || !STRIPE_WEBHOOK_SECRET) {
+    throw new Error('Stripe webhooks not configured');
+  }
+  
+  const stripe = require('stripe')(STRIPE_SECRET_KEY);
+  
+  let event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      requestBody,
+      signature,
+      STRIPE_WEBHOOK_SECRET
+    );
+  } catch (err) {
+    throw new Error(`Webhook signature verification failed: ${err.message}`);
+  }
+  
+  // Handle the event
+  switch (event.type) {
+    case 'checkout.session.completed': {
+      const session = event.data.object;
+      const planId = session.metadata.planId;
+      const customerId = session.customer;
+      const subscriptionId = session.subscription;
+      
+      // Activate the plan
+      setCurrentPlan(planId, {
+        customerId,
+        subscriptionId,
+      });
+      
+      return {
+        success: true,
+        planId,
+        customerId,
+      };
+    }
+    
+    case 'customer.subscription.updated':
+    case 'customer.subscription.deleted': {
+      const subscription = event.data.object;
+      const customerId = subscription.customer;
+      
+      if (subscription.status === 'active') {
+        // Keep subscription active
+        return { success: true, status: 'active' };
+      } else if (['canceled', 'unpaid'].includes(subscription.status)) {
+        // Downgrade to FREE
+        setCurrentPlan('free');
+        return { success: true, status: 'downgraded' };
+      }
+      
+      return { success: true, status: subscription.status };
+    }
+    
+    default:
+      console.log(`Unhandled event type: ${event.type}`);
+      return { success: true, ignored: true };
+  }
+}
+
+/**
+ * Get Stripe public key for client-side
+ */
+function getStripePublicKey() {
+  return STRIPE_PUBLIC_KEY;
+}
+
+/**
+ * Create customer portal session
+ * Allows users to manage their subscription
+ */
+async function createPortalSession(customerId, returnUrl) {
+  if (!STRIPE_SECRET_KEY) {
+    throw new Error('Stripe is not configured');
+  }
+  
+  const stripe = require('stripe')(STRIPE_SECRET_KEY);
+  
+  const session = await stripe.billingPortal.sessions.create({
+    customer: customerId,
+    return_url: returnUrl,
+  });
+  
+  return {
+    url: session.url,
+  };
+}
+
+/**
+ * Verify Stripe is configured
+ */
+function isStripeConfigured() {
+  return !!(STRIPE_SECRET_KEY && STRIPE_PUBLIC_KEY);
+}
+
+/**
+ * Get checkout URL for a plan
+ * Helper for CLI
+ */
+function getCheckoutUrl(planId) {
+  const baseUrl = process.env.GUARDIAN_WEBSITE_URL || 'https://guardian.odavl.com';
+  return `${baseUrl}/checkout?plan=${planId}`;
+}
+
+module.exports = {
+  createCheckoutSession,
+  handleWebhook,
+  getStripePublicKey,
+  createPortalSession,
+  isStripeConfigured,
+  getCheckoutUrl,
+};