@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/guardian/reporter.js

@@ -25,39 +25,26 @@ class GuardianReporter {
 
   createReport(crawlResult, baseUrl) {
     const { visited, totalDiscovered, totalVisited } = crawlResult;
-    
-    const coverage = totalDiscovered > 0 
+
+    const coverage = totalDiscovered > 0
       ? parseFloat(((totalVisited / totalDiscovered) * 100).toFixed(2))
       : 0;
-    
-    // Calculate confidence
-    let confidenceLevel = 'LOW';
-    if (coverage >= 85) {
-      confidenceLevel = 'HIGH';
-    } else if (coverage >= 60) {
-      confidenceLevel = 'MEDIUM';
-    }
-    
-    // Calculate decision
-    let decision = 'READY';
-    if (coverage < 30) {
-      decision = 'DO_NOT_LAUNCH';
-    } else if (coverage < 60) {
-      decision = 'INSUFFICIENT_CONFIDENCE';
-    }
-    
-    // Check for critical errors (server errors only, not 404s)
+
     const failedPages = visited.filter(p => p.status && p.status >= 500);
+    const observedPages = visited.filter(p => p.status && p.status < 500);
+
+    const reasons = [];
+    reasons.push(`Observed page reachability only: visited ${totalVisited} page(s), discovered ${totalDiscovered}, coverage ${coverage}%.`);
     if (failedPages.length > 0) {
-      decision = 'DO_NOT_LAUNCH';
+      reasons.push(`${failedPages.length} page(s) returned server errors or navigation failures.`);
     }
-    
-    const reasons = [];
-    if (coverage < 30) reasons.push(`Low coverage (${coverage}%)`);
-    if (failedPages.length > 0) reasons.push(`${failedPages.length} pages failed to load`);
-    if (coverage >= 60) reasons.push(`Coverage is ${coverage}%`);
-    if (failedPages.length === 0 && coverage >= 60) reasons.push('All visited pages loaded successfully');
-    
+    if (observedPages.length > 0) {
+      reasons.push(`HTTP responses observed for ${observedPages.length} page(s); no user flows or form submissions were executed.`);
+    }
+    reasons.push('No end-to-end user flows were validated; results are limited to link discovery and HTTP status observations.');
+
+    const decision = 'INSUFFICIENT_DATA';
+
     return {
       version: 'mvp-0.1',
       timestamp: new Date().toISOString(),
@@ -69,12 +56,12 @@ class GuardianReporter {
         failedPages: failedPages.length
       },
       confidence: {
-        level: confidenceLevel,
-        reasoning: `Coverage is ${coverage}% with ${failedPages.length} failed pages`
+        level: 'LOW',
+        reasoning: 'Only page reachability was observed; no user flows were confirmed.'
       },
       finalJudgment: {
         decision: decision,
-        reasons: reasons.length > 0 ? reasons : ['All checks passed']
+        reasons: reasons
       },
       pages: visited.map((p, i) => ({
         index: i + 1,
@@ -100,17 +87,16 @@ class GuardianReporter {
       ? parseFloat(((stepsExecuted / stepsTotal) * 100).toFixed(2))
       : 0;
     
-    // For flows: success = READY, failure = DO_NOT_LAUNCH
-    const decision = success ? 'READY' : 'DO_NOT_LAUNCH';
-    const confidenceLevel = success ? 'HIGH' : 'LOW';
-    
+    const decision = success ? 'OBSERVED' : 'PARTIAL';
+    const confidenceLevel = success ? 'MEDIUM' : 'LOW';
+
     const reasons = [];
     if (success) {
-      reasons.push(`Flow "${flowName}" completed successfully`);
-      reasons.push(`All ${stepsTotal} steps executed`);
+      reasons.push(`Observed flow "${flowName}" end-to-end; ${stepsExecuted}/${stepsTotal} steps completed.`);
+      reasons.push('No critical failures detected in this flow.');
     } else {
-      reasons.push(`Flow "${flowName}" failed at step ${failedStep}`);
-      reasons.push(`Error: ${error}`);
+      reasons.push(`Flow "${flowName}" did not complete; stopped at step ${failedStep || 'unknown'} with error: ${error || 'unspecified failure'}.`);
+      reasons.push('This run observed only the partial flow execution above; other flows were not validated.');
     }
     
     return {
@@ -135,8 +121,8 @@ class GuardianReporter {
       confidence: {
         level: confidenceLevel,
         reasoning: success 
-          ? `Flow completed successfully (${stepsExecuted}/${stepsTotal} steps)` 
-          : `Flow failed at step ${failedStep}: ${error}`
+          ? `Observed single flow execution; steps completed ${stepsExecuted}/${stepsTotal}.` 
+          : `Flow incomplete; failed at step ${failedStep || 'unknown'} with error: ${error || 'unspecified failure'}.`
       },
       finalJudgment: {
         decision: decision,

package/src/guardian/run-artifacts.js

@@ -0,0 +1,212 @@
+/**
+ * Run Artifacts Naming & Metadata
+ * Deterministic naming and META.json generation for Guardian runs
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Generate site slug from URL
+ * 
+ * Rules:
+ * - Lowercase
+ * - Remove protocol (http/https)
+ * - Remove trailing slash
+ * - Replace non-alphanumeric with "-"
+ * - Collapse multiple "-" to one
+ * - Trim leading/trailing "-"
+ * 
+ * @param {string} url - Original URL
+ * @returns {string} slug
+ */
+function makeSiteSlug(url) {
+  if (!url) return 'unknown';
+  
+  // Parse URL to get host + path
+  let normalized = url.toLowerCase();
+  
+  // Remove protocol
+  normalized = normalized.replace(/^https?:\/\//i, '');
+  
+  // Remove trailing slash
+  normalized = normalized.replace(/\/$/, '');
+  
+  // Replace any non-alphanumeric character (including colon, slash, dot) with hyphen
+  normalized = normalized.replace(/[^a-z0-9\-]/g, '-');
+  
+  // Collapse multiple hyphens
+  normalized = normalized.replace(/-+/g, '-');
+  
+  // Trim leading/trailing hyphens
+  normalized = normalized.replace(/^-+|-+$/g, '');
+  
+  return normalized || 'unknown';
+}
+
+/**
+ * Generate human-readable run directory name
+ * 
+ * Format: YYYY-MM-DD_HH-MM-SS_<siteSlug>_<policy>_<RESULT>
+ * Example: 2025-12-24_01-31-11_localhost-8001_startup_FAILED
+ * 
+ * @param {Object} opts
+ * @param {Date|string} opts.timestamp - Execution time
+ * @param {string} opts.url - Site URL
+ * @param {string} opts.policy - Policy/profile name (or 'default')
+ * @param {string} opts.result - Result: PASSED, FAILED, or WARN
+ * @returns {string} directory name
+ */
+function makeRunDirName(opts) {
+  const { timestamp, url, policy, result } = opts;
+  
+  // Parse timestamp
+  let time = timestamp instanceof Date ? timestamp : new Date(timestamp);
+  
+  // Format: YYYY-MM-DD_HH-MM-SS
+  const year = time.getFullYear();
+  const month = String(time.getMonth() + 1).padStart(2, '0');
+  const day = String(time.getDate()).padStart(2, '0');
+  const hours = String(time.getHours()).padStart(2, '0');
+  const minutes = String(time.getMinutes()).padStart(2, '0');
+  const seconds = String(time.getSeconds()).padStart(2, '0');
+  
+  const timeStr = `${year}-${month}-${day}_${hours}-${minutes}-${seconds}`;
+  
+  // Generate slug
+  const slug = makeSiteSlug(url);
+  
+  // Normalize policy (extract preset name if needed)
+  let policyName = policy || 'default';
+  if (policyName.startsWith('preset:')) {
+    policyName = policyName.replace('preset:', '');
+  }
+  
+  // Normalize result
+  const normalizedResult = (result || 'UNKNOWN').toUpperCase();
+  
+  return `${timeStr}_${slug}_${policyName}_${normalizedResult}`;
+}
+
+/**
+ * Write META.json for a completed run
+ * 
+ * @param {Object} opts
+ * @param {string} opts.runDir - Run directory path
+ * @param {string} opts.url - Original site URL
+ * @param {string} opts.siteSlug - Generated slug
+ * @param {string} opts.policy - Policy used
+ * @param {string} opts.result - PASSED|FAILED|WARN
+ * @param {number} opts.durationMs - Wall-clock duration
+ * @param {string} opts.profile - Detected site profile (ecommerce|saas|content|unknown)
+ * @param {Object} opts.attempts - Attempt statistics
+ * @param {number} opts.attempts.total
+ * @param {number} opts.attempts.executed
+ * @param {number} opts.attempts.successful
+ * @param {number} opts.attempts.failed
+ * @param {number} opts.attempts.skipped
+ * @param {Array} opts.attempts.skippedDetails - Array of {attempt, reason}
+ * @param {number} [opts.attempts.nearSuccess] - Count of near-success signals
+ * @param {Array} [opts.attempts.nearSuccessDetails] - Array of { attempt, reason }
+ * @throws {Error} if write fails
+ */
+function writeMetaJson(opts) {
+  const {
+    runDir,
+    url,
+    siteSlug,
+    policy,
+    result,
+    durationMs,
+    profile,
+    attempts,
+    verdict
+  } = opts;
+  
+  const meta = {
+    version: 1,
+    timestamp: new Date().toISOString(),
+    url,
+    siteSlug,
+    policy: policy || 'default',
+    result: (result || 'UNKNOWN').toUpperCase(),
+    durationMs: Math.round(durationMs || 0),
+    profile: profile || 'unknown',
+    attempts: {
+      total: attempts?.total || 0,
+      executed: attempts?.executed || 0,
+      successful: attempts?.successful || 0,
+      failed: attempts?.failed || 0,
+      skipped: attempts?.skipped || 0,
+      skippedDetails: attempts?.skippedDetails || [],
+      nearSuccess: attempts?.nearSuccess || 0,
+      nearSuccessDetails: attempts?.nearSuccessDetails || []
+    }
+  };
+  if (verdict) {
+    meta.verdict = {
+      verdict: verdict.verdict,
+      confidence: verdict.confidence,
+      why: verdict.why || ''
+    };
+  }
+  
+  const metaPath = path.join(runDir, 'META.json');
+  fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+  
+  return metaPath;
+}
+
+/**
+ * Read META.json from a run directory
+ * 
+ * @param {string} runDir - Run directory path
+ * @returns {Object|null} parsed META.json or null if missing/invalid
+ */
+function readMetaJson(runDir) {
+  const metaPath = path.join(runDir, 'META.json');
+  
+  if (!fs.existsSync(metaPath)) {
+    return null;
+  }
+  
+  try {
+    const content = fs.readFileSync(metaPath, 'utf8');
+    return JSON.parse(content);
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Format duration for human-readable output
+ * 
+ * @param {number} ms - Milliseconds
+ * @returns {string} formatted duration
+ */
+function formatDuration(ms) {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  
+  const totalSecs = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSecs / 3600);
+  const minutes = Math.floor((totalSecs % 3600) / 60);
+  const seconds = totalSecs % 60;
+  
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`;
+  } else if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  } else {
+    return `${seconds}s`;
+  }
+}
+
+module.exports = {
+  makeSiteSlug,
+  makeRunDirName,
+  writeMetaJson,
+  readMetaJson,
+  formatDuration
+};

package/src/guardian/run-cleanup.js

@@ -0,0 +1,207 @@
+/**
+ * Run Cleanup & Management
+ * Delete old, excessive, or failed runs based on specified criteria
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readMetaJson } = require('./run-artifacts');
+
+/**
+ * Parse duration string (e.g. "7d", "24h", "30m")
+ * 
+ * @param {string} durationStr - Duration like "7d", "24h", "30m"
+ * @returns {number} milliseconds
+ */
+function parseDuration(durationStr) {
+  const match = durationStr.match(/^(\d+)([dhm])$/);
+  if (!match) {
+    throw new Error(`Invalid duration format: ${durationStr}. Use Nd, Nh, or Nm (e.g., "7d", "24h", "30m")`);
+  }
+  
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  
+  switch (unit) {
+    case 'd':
+      return value * 24 * 60 * 60 * 1000;
+    case 'h':
+      return value * 60 * 60 * 1000;
+    case 'm':
+      return value * 60 * 1000;
+    default:
+      throw new Error(`Unknown time unit: ${unit}`);
+  }
+}
+
+/**
+ * Find all run directories
+ * 
+ * @param {string} artifactsDir - Path to artifacts directory
+ * @returns {Array} array of { dirPath, dirName, meta }
+ */
+function loadAllRuns(artifactsDir) {
+  if (!fs.existsSync(artifactsDir)) {
+    return [];
+  }
+  
+  try {
+    const entries = fs.readdirSync(artifactsDir, { withFileTypes: true });
+    const runs = [];
+    
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      
+      const dirPath = path.join(artifactsDir, entry.name);
+      const meta = readMetaJson(dirPath);
+      
+      // Skip runs without META.json
+      if (!meta) continue;
+      
+      runs.push({
+        dirPath,
+        dirName: entry.name,
+        meta
+      });
+    }
+    
+    return runs;
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * Group runs by siteSlug
+ * 
+ * @param {Array} runs - Array of run objects
+ * @returns {Object} map of siteSlug → array of runs
+ */
+function groupBySite(runs) {
+  const grouped = {};
+  for (const run of runs) {
+    const slug = run.meta.siteSlug || 'unknown';
+    if (!grouped[slug]) {
+      grouped[slug] = [];
+    }
+    grouped[slug].push(run);
+  }
+  return grouped;
+}
+
+/**
+ * Sort runs by timestamp (newest first)
+ * 
+ * @param {Array} runs - Array of run objects
+ * @returns {Array} sorted runs
+ */
+function sortByTimestamp(runs) {
+  return runs.sort((a, b) => {
+    const timeA = new Date(a.meta.timestamp).getTime();
+    const timeB = new Date(b.meta.timestamp).getTime();
+    return timeB - timeA;
+  });
+}
+
+/**
+ * Apply cleanup filters
+ * 
+ * @param {Array} runs - Array of run objects
+ * @param {Object} opts - Options
+ * @param {string} opts.olderThan - Duration string (e.g., "7d")
+ * @param {number} opts.keepLatest - Number of latest runs to keep per site
+ * @param {boolean} opts.failedOnly - Only delete FAILED runs
+ * @returns {Array} runs to delete
+ */
+function selectRunsForDeletion(runs, opts = {}) {
+  let toDelete = [...runs];
+  const now = Date.now();
+  
+  // Filter by age
+  if (opts.olderThan) {
+    const ageMs = parseDuration(opts.olderThan);
+    const cutoffTime = now - ageMs;
+    toDelete = toDelete.filter(run => {
+      const runTime = new Date(run.meta.timestamp).getTime();
+      return runTime < cutoffTime;
+    });
+  }
+  
+  // Filter by status
+  if (opts.failedOnly) {
+    toDelete = toDelete.filter(run => run.meta.result === 'FAILED');
+  }
+  
+  // Apply keep-latest per site (only if we're not already filtering by age/status heavily)
+  if (opts.keepLatest && opts.keepLatest > 0) {
+    const grouped = groupBySite(toDelete);
+    const toKeepPaths = new Set();
+    
+    for (const siteSlug in grouped) {
+      const siteRuns = sortByTimestamp(grouped[siteSlug]);
+      // Keep the latest N
+      for (let i = 0; i < Math.min(opts.keepLatest, siteRuns.length); i++) {
+        toKeepPaths.add(siteRuns[i].dirPath);
+      }
+    }
+    
+    toDelete = toDelete.filter(run => !toKeepPaths.has(run.dirPath));
+  }
+  
+  return toDelete;
+}
+
+/**
+ * Execute cleanup
+ * 
+ * @param {string} artifactsDir - Path to artifacts directory
+ * @param {Object} opts - Options
+ * @returns {Object} cleanup result
+ */
+function cleanup(artifactsDir = './artifacts', opts = {}) {
+  const allRuns = loadAllRuns(artifactsDir);
+  
+  if (allRuns.length === 0) {
+    return {
+      deleted: 0,
+      kept: 0,
+      errors: []
+    };
+  }
+  
+  // Determine which runs to delete
+  const toDelete = selectRunsForDeletion(allRuns, opts);
+  const deletePaths = new Set(toDelete.map(r => r.dirPath));
+  
+  const errors = [];
+  
+  // Delete run directories
+  for (const run of toDelete) {
+    try {
+      fs.rmSync(run.dirPath, { recursive: true, force: true });
+    } catch (e) {
+      errors.push(`Failed to delete ${run.dirName}: ${e.message}`);
+    }
+  }
+  
+  return {
+    deleted: toDelete.length,
+    kept: allRuns.length - toDelete.length,
+    errors,
+    deletedRuns: toDelete.map(r => ({
+      dirName: r.dirName,
+      site: r.meta.siteSlug,
+      result: r.meta.result,
+      timestamp: r.meta.timestamp
+    }))
+  };
+}
+
+module.exports = {
+  cleanup,
+  parseDuration,
+  loadAllRuns,
+  groupBySite,
+  sortByTimestamp,
+  selectRunsForDeletion
+};

package/src/guardian/run-latest.js

@@ -0,0 +1,90 @@
+/**
+ * Latest Run Pointers
+ * Maintains LATEST.json and site-specific latest pointers for quick access
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Create a pointer file pointing to the latest run
+ * 
+ * @param {string} pointerPath - Path where pointer file should be saved
+ * @param {Object} meta - META.json content from the run
+ * @param {string} runDirName - Name of the run directory
+ */
+function writePointer(pointerPath, meta, runDirName) {
+  const pointer = {
+    version: 1,
+    timestamp: new Date().toISOString(),
+    pointedRun: runDirName,
+    pointedRunMeta: {
+      timestamp: meta.timestamp,
+      url: meta.url,
+      siteSlug: meta.siteSlug,
+      policy: meta.policy,
+      result: meta.result,
+      durationMs: meta.durationMs
+    }
+  };
+  
+  // Create directory if needed
+  const dir = path.dirname(pointerPath);
+  fs.mkdirSync(dir, { recursive: true });
+  
+  // Atomic write
+  fs.writeFileSync(pointerPath, JSON.stringify(pointer, null, 2));
+}
+
+/**
+ * Update LATEST.json (global latest run)
+ * 
+ * @param {string} runDir - Full path to the run directory
+ * @param {string} runDirName - Name of the run directory
+ * @param {Object} meta - META.json content
+ * @param {string} artifactsDir - Artifacts directory path (for pointer location)
+ */
+function updateLatestGlobal(runDir, runDirName, meta, artifactsDir = './artifacts') {
+  const pointerPath = path.join(artifactsDir, 'LATEST.json');
+  writePointer(pointerPath, meta, runDirName);
+}
+
+/**
+ * Update site-specific latest pointer
+ * 
+ * @param {string} runDir - Full path to the run directory
+ * @param {string} runDirName - Name of the run directory
+ * @param {Object} meta - META.json content
+ * @param {string} artifactsDir - Artifacts directory path (for pointer location)
+ */
+function updateLatestBySite(runDir, runDirName, meta, artifactsDir = './artifacts') {
+  const siteSlug = meta.siteSlug || 'unknown';
+  const pointerPath = path.join(artifactsDir, 'latest', `${siteSlug}.json`);
+  writePointer(pointerPath, meta, runDirName);
+}
+
+/**
+ * Read a pointer file
+ * 
+ * @param {string} pointerPath - Path to pointer file
+ * @returns {Object|null} pointer content or null if missing
+ */
+function readPointer(pointerPath) {
+  if (!fs.existsSync(pointerPath)) {
+    return null;
+  }
+  
+  try {
+    const content = fs.readFileSync(pointerPath, 'utf8');
+    return JSON.parse(content);
+  } catch (e) {
+    return null;
+  }
+}
+
+module.exports = {
+  updateLatestGlobal,
+  updateLatestBySite,
+  readPointer,
+  writePointer
+};