@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/plans/usage-tracker.js

@@ -0,0 +1,210 @@
+/**
+ * ODAVL Guardian Usage Tracker
+ * Tracks scans per month and enforces plan limits
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const USAGE_DIR = path.join(os.homedir(), '.odavl-guardian', 'usage');
+const USAGE_FILE = path.join(USAGE_DIR, 'usage.json');
+
+/**
+ * Ensure usage directory exists
+ */
+function ensureUsageDir() {
+  if (!fs.existsSync(USAGE_DIR)) {
+    fs.mkdirSync(USAGE_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get current month key (YYYY-MM)
+ */
+function getCurrentMonthKey() {
+  const now = new Date();
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+}
+
+/**
+ * Load usage data
+ */
+function loadUsage() {
+  ensureUsageDir();
+  
+  if (!fs.existsSync(USAGE_FILE)) {
+    return {
+      currentMonth: getCurrentMonthKey(),
+      scansThisMonth: 0,
+      sites: [],
+      totalScans: 0,
+      history: {},
+    };
+  }
+  
+  try {
+    const data = JSON.parse(fs.readFileSync(USAGE_FILE, 'utf-8'));
+    
+    // Reset if new month
+    const currentMonth = getCurrentMonthKey();
+    if (data.currentMonth !== currentMonth) {
+      // Archive old month
+      data.history[data.currentMonth] = {
+        scans: data.scansThisMonth,
+        sites: data.sites.length,
+      };
+      
+      // Reset for new month
+      data.currentMonth = currentMonth;
+      data.scansThisMonth = 0;
+    }
+    
+    return data;
+  } catch (error) {
+    console.error('Error loading usage data:', error.message);
+    return {
+      currentMonth: getCurrentMonthKey(),
+      scansThisMonth: 0,
+      sites: [],
+      totalScans: 0,
+      history: {},
+    };
+  }
+}
+
+/**
+ * Save usage data
+ */
+function saveUsage(usage) {
+  ensureUsageDir();
+  fs.writeFileSync(USAGE_FILE, JSON.stringify(usage, null, 2), 'utf-8');
+}
+
+/**
+ * Record a scan
+ */
+function recordScan(url) {
+  const usage = loadUsage();
+  
+  // Extract domain from URL
+  let domain;
+  try {
+    const urlObj = new URL(url);
+    domain = urlObj.hostname;
+  } catch {
+    domain = url;
+  }
+  
+  // Increment scan count
+  usage.scansThisMonth += 1;
+  usage.totalScans += 1;
+  
+  // Track unique site
+  if (!usage.sites.includes(domain)) {
+    usage.sites.push(domain);
+  }
+  
+  // Record timestamp
+  if (!usage.scanHistory) {
+    usage.scanHistory = [];
+  }
+  usage.scanHistory.push({
+    url,
+    domain,
+    timestamp: new Date().toISOString(),
+  });
+  
+  // Keep only last 100 scans in history
+  if (usage.scanHistory.length > 100) {
+    usage.scanHistory = usage.scanHistory.slice(-100);
+  }
+  
+  saveUsage(usage);
+  return usage;
+}
+
+/**
+ * Get current usage stats
+ */
+function getUsageStats() {
+  return loadUsage();
+}
+
+/**
+ * Get scans remaining for current plan
+ */
+function getScansRemaining(maxScans) {
+  const usage = loadUsage();
+  if (maxScans === -1) return 'Unlimited';
+  return Math.max(0, maxScans - usage.scansThisMonth);
+}
+
+/**
+ * Check if can perform scan
+ */
+function canPerformScan(maxScans) {
+  if (maxScans === -1) return true; // unlimited
+  const usage = loadUsage();
+  return usage.scansThisMonth < maxScans;
+}
+
+/**
+ * Check if can add site
+ */
+function canAddSite(url, maxSites) {
+  if (maxSites === -1) return true; // unlimited
+  
+  const usage = loadUsage();
+  
+  // Extract domain
+  let domain;
+  try {
+    const urlObj = new URL(url);
+    domain = urlObj.hostname;
+  } catch {
+    domain = url;
+  }
+  
+  // If site already tracked, it's OK
+  if (usage.sites.includes(domain)) {
+    return true;
+  }
+  
+  // Check if under limit
+  return usage.sites.length < maxSites;
+}
+
+/**
+ * Reset usage (for testing or manual reset)
+ */
+function resetUsage() {
+  ensureUsageDir();
+  const usage = {
+    currentMonth: getCurrentMonthKey(),
+    scansThisMonth: 0,
+    sites: [],
+    totalScans: 0,
+    history: {},
+    scanHistory: [],
+  };
+  saveUsage(usage);
+  return usage;
+}
+
+/**
+ * Get usage file path (for debugging)
+ */
+function getUsageFilePath() {
+  return USAGE_FILE;
+}
+
+module.exports = {
+  recordScan,
+  getUsageStats,
+  getScansRemaining,
+  canPerformScan,
+  canAddSite,
+  resetUsage,
+  getUsageFilePath,
+};

package/src/recipes/recipe-engine.js

@@ -0,0 +1,188 @@
+/**
+ * Phase 12.1: Recipe Engine
+ * Core recipe execution and validation system
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Validate recipe schema
+ */
+function validateRecipe(recipe) {
+  const errors = [];
+  
+  if (!recipe.id || typeof recipe.id !== 'string') {
+    errors.push('Recipe must have a string id');
+  }
+  
+  if (!recipe.name || typeof recipe.name !== 'string') {
+    errors.push('Recipe must have a string name');
+  }
+  
+  if (!recipe.platform || typeof recipe.platform !== 'string') {
+    errors.push('Recipe must have a platform (shopify|saas|landing)');
+  }
+  
+  if (!['shopify', 'saas', 'landing'].includes(recipe.platform)) {
+    errors.push(`Invalid platform: ${recipe.platform}. Must be shopify, saas, or landing`);
+  }
+  
+  if (!recipe.intent || typeof recipe.intent !== 'string') {
+    errors.push('Recipe must have an intent string');
+  }
+  
+  if (!Array.isArray(recipe.steps) || recipe.steps.length === 0) {
+    errors.push('Recipe must have at least one step');
+  }
+  
+  if (recipe.steps && !recipe.steps.every(s => typeof s === 'string')) {
+    errors.push('All recipe steps must be strings');
+  }
+  
+  if (!recipe.expectedGoal || typeof recipe.expectedGoal !== 'string') {
+    errors.push('Recipe must have an expectedGoal');
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Get recipe complexity score
+ */
+function getComplexityScore(recipe) {
+  const stepCount = recipe.steps.length;
+  
+  if (stepCount <= 3) return 'simple';
+  if (stepCount <= 7) return 'moderate';
+  return 'complex';
+}
+
+/**
+ * Get estimated execution time (seconds)
+ */
+function getEstimatedTime(recipe) {
+  const stepCount = recipe.steps.length;
+  const complexity = getComplexityScore(recipe);
+  
+  // Base time per step
+  let baseTime = 5;
+  
+  if (complexity === 'complex') {
+    baseTime = 8;
+  } else if (complexity === 'moderate') {
+    baseTime = 6;
+  }
+  
+  return stepCount * baseTime;
+}
+
+/**
+ * Create recipe execution context
+ */
+function createExecutionContext(recipe, baseUrl, options = {}) {
+  return {
+    recipe,
+    baseUrl,
+    startedAt: new Date(),
+    steps: [],
+    state: {
+      currentUrl: baseUrl,
+      pageTitle: null,
+      pageUrl: null,
+      lastElement: null,
+      data: options.data || {}
+    },
+    options,
+    success: false,
+    error: null,
+    completedAt: null,
+    duration: 0
+  };
+}
+
+/**
+ * Record step execution
+ */
+function recordStep(context, stepIndex, action, result) {
+  const step = {
+    index: stepIndex,
+    action,
+    result,
+    timestamp: new Date().toISOString(),
+    duration: 0
+  };
+  
+  context.steps.push(step);
+  return step;
+}
+
+/**
+ * Mark execution complete
+ */
+function markComplete(context, success, error = null) {
+  context.success = success;
+  context.error = error;
+  context.completedAt = new Date();
+  context.duration = Math.round(
+    (context.completedAt - context.startedAt) / 1000
+  );
+  return context;
+}
+
+/**
+ * Generate human-readable recipe summary
+ */
+function getRecipeSummary(recipe) {
+  return {
+    id: recipe.id,
+    name: recipe.name,
+    platform: recipe.platform,
+    intent: recipe.intent,
+    stepCount: recipe.steps.length,
+    complexity: getComplexityScore(recipe),
+    estimatedTime: getEstimatedTime(recipe),
+    expectedGoal: recipe.expectedGoal
+  };
+}
+
+/**
+ * Format recipe for display
+ */
+function formatRecipe(recipe) {
+  const summary = getRecipeSummary(recipe);
+  
+  let output = '';
+  output += `📋 ${summary.name}\n`;
+  output += `   Platform: ${summary.platform}\n`;
+  output += `   Intent: ${summary.intent}\n`;
+  output += `   Complexity: ${summary.complexity}\n`;
+  output += `   Steps: ${summary.stepCount}\n`;
+  output += `   Estimated Time: ${summary.estimatedTime}s\n`;
+  output += `   Expected Goal: ${summary.expectedGoal}\n`;
+  
+  if (recipe.notes) {
+    output += `   Notes: ${recipe.notes}\n`;
+  }
+  
+  output += `\n   Steps:\n`;
+  recipe.steps.forEach((step, i) => {
+    output += `     ${i + 1}. ${step}\n`;
+  });
+  
+  return output;
+}
+
+module.exports = {
+  validateRecipe,
+  getComplexityScore,
+  getEstimatedTime,
+  createExecutionContext,
+  recordStep,
+  markComplete,
+  getRecipeSummary,
+  formatRecipe
+};

package/src/recipes/recipe-failure-analysis.js

@@ -0,0 +1,159 @@
+/**
+ * Recipe Failure Analysis & Reporting
+ * 
+ * Integrates recipe failures into the decision engine and breakage intelligence.
+ */
+
+/**
+ * Analyze a recipe execution failure
+ * 
+ * @param {Object} recipeResult - Result from executeRecipeRuntime
+ * @returns {Object} Intelligence object for reporting
+ */
+function analyzeRecipeFailure(recipeResult) {
+  if (recipeResult.success) {
+    return null; // No failure to analyze
+  }
+
+  const { failedStep, failureReason, steps, recipe, recipeName, baseUrl } = recipeResult;
+  
+  // Categorize failure type
+  let failureType = 'EXECUTION';
+  let severity = 'CRITICAL';
+  
+  if (failureReason.includes('not found')) {
+    failureType = 'ELEMENT_NOT_FOUND';
+  } else if (failureReason.includes('not visible')) {
+    failureType = 'ELEMENT_NOT_VISIBLE';
+  } else if (failureReason.includes('Goal not reached')) {
+    failureType = 'GOAL_FAILURE';
+  } else if (failureReason.includes('Runtime error')) {
+    failureType = 'RUNTIME_ERROR';
+    severity = 'CRITICAL';
+  } else if (failureReason.includes('Recipe not found')) {
+    failureType = 'RECIPE_NOT_FOUND';
+    severity = 'INFO';
+  }
+
+  const stepsFailed = steps.filter(s => !s.success).length;
+  const stepsTotal = steps.length;
+
+  return {
+    id: `recipe-${recipe}`,
+    name: `Recipe: ${recipeName}`,
+    outcome: 'FAILURE',
+    failureType,
+    severity,
+    baseUrl,
+    recipeId: recipe,
+    recipeName,
+    failedStepId: failedStep,
+    failedStepNumber: failedStep ? parseInt(failedStep.split('-').pop(), 10) : null,
+    failureReason,
+    stepProgress: {
+      completed: stepsTotal - stepsFailed,
+      total: stepsTotal,
+      percentage: Math.round(((stepsTotal - stepsFailed) / stepsTotal) * 100)
+    },
+    humanReadableError: formatRecipeError(recipeName, failedStep, failureReason, stepsTotal),
+    source: 'recipe-runtime',
+    behavioralSignals: [
+      {
+        signal: 'RECIPE_EXECUTION_FAILED',
+        message: failureReason,
+        severity: severity
+      }
+    ]
+  };
+}
+
+/**
+ * Format recipe error for human readability
+ */
+function formatRecipeError(recipeName, failedStep, failureReason, totalSteps) {
+  const stepNum = failedStep ? parseInt(failedStep.split('-').pop(), 10) + 1 : 0;
+  
+  return `Recipe '${recipeName}' failed at step ${stepNum} of ${totalSteps}: ${failureReason}`;
+}
+
+/**
+ * Convert recipe failure to attempt-like structure for reporting compatibility
+ */
+function recipeFailureToAttempt(recipeResult) {
+  const intelligence = analyzeRecipeFailure(recipeResult);
+  if (!intelligence) return null;
+
+  return {
+    attemptId: intelligence.id,
+    attemptName: intelligence.name,
+    outcome: 'FAILURE',
+    error: intelligence.failureReason,
+    failureType: intelligence.failureType,
+    severity: intelligence.severity,
+    baseUrl: intelligence.baseUrl,
+    riskCategory: 'TRUST', // Recipes are trust/integrity checks
+    source: 'recipe',
+    validators: [
+      {
+        id: 'recipe-step-validation',
+        name: 'Recipe Step Execution',
+        passed: false,
+        evidence: recipeResult.evidence
+      }
+    ],
+    behavioralSignals: intelligence.behavioralSignals
+  };
+}
+
+/**
+ * Integrate recipe failures into market impact analysis
+ */
+function assessRecipeImpact(recipeResult) {
+  if (recipeResult.success) {
+    return {
+      hasRisk: false,
+      riskScore: 0,
+      severity: 'INFO',
+      message: `Recipe '${recipeResult.recipeName}' passed successfully`
+    };
+  }
+
+  const intelligence = analyzeRecipeFailure(recipeResult);
+  
+  // Recipe failures always elevate risk
+  let riskScore = 70; // Base critical risk
+  let severity = 'CRITICAL';
+
+  // Adjust based on step completion
+  const progress = intelligence.stepProgress.percentage;
+  if (progress === 0) {
+    riskScore = 90; // Failed on first step — very bad
+  } else if (progress < 50) {
+    riskScore = 80; // Failed early
+  } else {
+    riskScore = 60; // Failed late but still indicates issue
+  }
+
+  // Type-specific scoring
+  if (intelligence.failureType === 'GOAL_FAILURE') {
+    riskScore = Math.max(riskScore - 10, 50); // Goal failure less severe than execution error
+    severity = 'WARNING';
+  }
+
+  return {
+    hasRisk: true,
+    riskScore,
+    severity,
+    message: intelligence.humanReadableError,
+    recipe: intelligence.recipeId,
+    failureType: intelligence.failureType,
+    stepProgress: intelligence.stepProgress
+  };
+}
+
+module.exports = {
+  analyzeRecipeFailure,
+  formatRecipeError,
+  recipeFailureToAttempt,
+  assessRecipeImpact
+};

package/src/recipes/recipe-registry.js

@@ -0,0 +1,134 @@
+/**
+ * Phase 12.2: Recipe Registry
+ * Local-first registry tracking provenance and integrity of recipes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const RECIPES_DIR = path.join(os.homedir(), '.odavl-guardian', 'recipes');
+const REGISTRY_FILE = path.join(RECIPES_DIR, 'registry.json');
+
+function ensureRecipesDir() {
+  if (!fs.existsSync(RECIPES_DIR)) {
+    fs.mkdirSync(RECIPES_DIR, { recursive: true });
+  }
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(v => stableStringify(v)).join(',') + ']';
+  }
+  const keys = Object.keys(value).sort();
+  const entries = keys.map(k => `${JSON.stringify(k)}:${stableStringify(value[k])}`);
+  return '{' + entries.join(',') + '}';
+}
+
+function computeRecipeChecksum(recipe) {
+  const normalized = stableStringify(recipe);
+  return crypto.createHash('sha256').update(normalized).digest('hex');
+}
+
+function loadRegistry() {
+  ensureRecipesDir();
+  if (!fs.existsSync(REGISTRY_FILE)) {
+    return { entries: [], updatedAt: null };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(REGISTRY_FILE, 'utf-8'));
+  } catch (err) {
+    return { entries: [], updatedAt: null };
+  }
+}
+
+function saveRegistry(registry) {
+  ensureRecipesDir();
+  const data = {
+    entries: registry.entries || [],
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(REGISTRY_FILE, JSON.stringify(data, null, 2), 'utf-8');
+  return data;
+}
+
+function ensureBuiltInRegistry(builtIns) {
+  const registry = loadRegistry();
+  let changed = false;
+  for (const recipe of builtIns) {
+    if (!registry.entries.some(e => e.id === recipe.id)) {
+      registry.entries.push({
+        id: recipe.id,
+        name: recipe.name,
+        platform: recipe.platform,
+        version: recipe.version || '1.0.0',
+        source: 'builtin',
+        checksum: computeRecipeChecksum(recipe),
+        addedAt: new Date().toISOString(),
+      });
+      changed = true;
+    }
+  }
+  if (changed) {
+    saveRegistry(registry);
+  }
+}
+
+function registerRecipe({ id, name, platform, version, source, checksum }) {
+  const registry = loadRegistry();
+  const existing = registry.entries.find(e => e.id === id);
+  if (existing) {
+    Object.assign(existing, { name, platform, version, source, checksum });
+  } else {
+    registry.entries.push({
+      id,
+      name,
+      platform,
+      version: version || '1.0.0',
+      source: source || 'imported',
+      checksum,
+      addedAt: new Date().toISOString(),
+    });
+  }
+  return saveRegistry(registry);
+}
+
+function removeRegistryEntry(id) {
+  const registry = loadRegistry();
+  const next = registry.entries.filter(e => e.id !== id);
+  registry.entries = next;
+  return saveRegistry(registry);
+}
+
+function getRegistryEntry(id) {
+  const registry = loadRegistry();
+  return registry.entries.find(e => e.id === id);
+}
+
+function listRegistryEntries() {
+  const registry = loadRegistry();
+  return registry.entries;
+}
+
+function resetRegistry() {
+  ensureRecipesDir();
+  if (fs.existsSync(REGISTRY_FILE)) {
+    fs.unlinkSync(REGISTRY_FILE);
+  }
+}
+
+module.exports = {
+  computeRecipeChecksum,
+  loadRegistry,
+  saveRegistry,
+  registerRecipe,
+  ensureBuiltInRegistry,
+  getRegistryEntry,
+  listRegistryEntries,
+  removeRegistryEntry,
+  resetRegistry,
+};