npm - @odavl/guardian - Versions diffs - 0.1.0-rc1 → 1.0.0 - Mend

@odavl/guardian 0.1.0-rc1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (101) hide show

package/CHANGELOG.md +146 -0
package/README.md +155 -97
package/bin/guardian.js +1544 -55
package/config/README.md +59 -0
package/config/profiles/landing-demo.yaml +16 -0
package/package.json +26 -11
package/policies/landing-demo.json +22 -0
package/src/enterprise/audit-logger.js +166 -0
package/src/enterprise/pdf-exporter.js +267 -0
package/src/enterprise/rbac-gate.js +142 -0
package/src/enterprise/rbac.js +239 -0
package/src/enterprise/site-manager.js +180 -0
package/src/founder/feedback-system.js +156 -0
package/src/founder/founder-tracker.js +213 -0
package/src/founder/usage-signals.js +141 -0
package/src/guardian/alert-ledger.js +121 -0
package/src/guardian/attempt-engine.js +587 -12
package/src/guardian/attempt-registry.js +42 -1
package/src/guardian/attempt-relevance.js +106 -0
package/src/guardian/attempt.js +85 -39
package/src/guardian/attempts-filter.js +63 -0
package/src/guardian/baseline.js +50 -8
package/src/guardian/breakage-intelligence.js +1 -0
package/src/guardian/browser-pool.js +131 -0
package/src/guardian/browser.js +28 -1
package/src/guardian/ci-cli.js +121 -0
package/src/guardian/ci-mode.js +15 -0
package/src/guardian/ci-output.js +38 -0
package/src/guardian/cli-summary.js +167 -67
package/src/guardian/config-loader.js +162 -0
package/src/guardian/data-guardian-detector.js +189 -0
package/src/guardian/detection-layers.js +271 -0
package/src/guardian/drift-detector.js +100 -0
package/src/guardian/enhanced-html-reporter.js +221 -4
package/src/guardian/env-guard.js +127 -0
package/src/guardian/failure-intelligence.js +173 -0
package/src/guardian/first-run-profile.js +89 -0
package/src/guardian/first-run.js +54 -0
package/src/guardian/flag-validator.js +111 -0
package/src/guardian/flow-executor.js +309 -44
package/src/guardian/html-reporter.js +2 -0
package/src/guardian/human-reporter.js +431 -0
package/src/guardian/index.js +22 -19
package/src/guardian/init-command.js +9 -5
package/src/guardian/intent-detector.js +146 -0
package/src/guardian/journey-definitions.js +132 -0
package/src/guardian/journey-scan-cli.js +145 -0
package/src/guardian/journey-scanner.js +583 -0
package/src/guardian/junit-reporter.js +18 -1
package/src/guardian/language-detection.js +99 -0
package/src/guardian/live-cli.js +95 -0
package/src/guardian/live-scheduler-runner.js +137 -0
package/src/guardian/live-scheduler.js +146 -0
package/src/guardian/market-reporter.js +357 -82
package/src/guardian/parallel-executor.js +116 -0
package/src/guardian/pattern-analyzer.js +348 -0
package/src/guardian/policy.js +80 -3
package/src/guardian/prerequisite-checker.js +101 -0
package/src/guardian/preset-loader.js +27 -18
package/src/guardian/profile-loader.js +96 -0
package/src/guardian/reality.js +1612 -115
package/src/guardian/reporter.js +27 -41
package/src/guardian/run-artifacts.js +212 -0
package/src/guardian/run-cleanup.js +207 -0
package/src/guardian/run-latest.js +90 -0
package/src/guardian/run-list.js +211 -0
package/src/guardian/run-summary.js +20 -0
package/src/guardian/scan-presets.js +100 -11
package/src/guardian/selector-fallbacks.js +394 -0
package/src/guardian/semantic-contact-detection.js +255 -0
package/src/guardian/semantic-contact-finder.js +201 -0
package/src/guardian/semantic-targets.js +234 -0
package/src/guardian/site-introspection.js +257 -0
package/src/guardian/smoke.js +258 -0
package/src/guardian/snapshot-schema.js +25 -1
package/src/guardian/snapshot.js +69 -3
package/src/guardian/stability-scorer.js +169 -0
package/src/guardian/success-evaluator.js +214 -0
package/src/guardian/template-command.js +184 -0
package/src/guardian/text-formatters.js +426 -0
package/src/guardian/timeout-profiles.js +57 -0
package/src/guardian/verdict.js +320 -0
package/src/guardian/verdicts.js +74 -0
package/src/guardian/wait-for-outcome.js +120 -0
package/src/guardian/watch-runner.js +181 -0
package/src/payments/stripe-checkout.js +169 -0
package/src/plans/plan-definitions.js +148 -0
package/src/plans/plan-manager.js +211 -0
package/src/plans/usage-tracker.js +210 -0
package/src/recipes/recipe-engine.js +188 -0
package/src/recipes/recipe-failure-analysis.js +159 -0
package/src/recipes/recipe-registry.js +134 -0
package/src/recipes/recipe-runtime.js +507 -0
package/src/recipes/recipe-store.js +410 -0
package/guardian-contract-v1.md +0 -149
/package/{guardian.config.json → config/guardian.config.json} +0 -0
/package/{guardian.policy.json → config/guardian.policy.json} +0 -0
/package/{guardian.profile.docs.yaml → config/profiles/docs.yaml} +0 -0
/package/{guardian.profile.ecommerce.yaml → config/profiles/ecommerce.yaml} +0 -0
/package/{guardian.profile.marketing.yaml → config/profiles/marketing.yaml} +0 -0
/package/{guardian.profile.saas.yaml → config/profiles/saas.yaml} +0 -0

package/src/guardian/language-detection.js ADDED Viewed

@@ -0,0 +1,99 @@
+/**
+ * Language Detection
+ *
+ * Deterministic language detection from HTML attributes.
+ * No guessing, no AI. Only reads explicit language declarations.
+ */
+/**
+ * Detect page language from HTML
+ *
+ * Detection order:
+ * 1. <html lang="..."> attribute
+ * 2. <meta http-equiv="content-language" ...> attribute
+ * 3. fallback: "unknown"
+ *
+ * @param {Page} page - Playwright page object
+ * @returns {Promise<string>} BCP-47 language code or "unknown"
+ */
+async function detectLanguage(page) {
+  try {
+    // Try <html lang="...">
+    const htmlLang = await page.evaluate(() => {
+      const htmlElement = document.documentElement;
+      return htmlElement.getAttribute('lang');
+    });
+    if (htmlLang && htmlLang.trim()) {
+      // Return the language code (e.g., "de", "de-DE", "en", "en-US")
+      return htmlLang.trim().toLowerCase();
+    }
+    // Try <meta http-equiv="content-language" ...>
+    const metaLang = await page.evaluate(() => {
+      const meta = document.querySelector('meta[http-equiv="content-language"]');
+      return meta ? meta.getAttribute('content') : null;
+    });
+    if (metaLang && metaLang.trim()) {
+      return metaLang.trim().toLowerCase();
+    }
+    // Fallback
+    return 'unknown';
+  } catch (error) {
+    // If evaluation fails, return unknown
+    return 'unknown';
+  }
+}
+/**
+ * Parse BCP-47 language code to get primary language
+ * e.g., "de-DE" -> "de", "en-US" -> "en"
+ */
+function getPrimaryLanguage(languageCode) {
+  if (!languageCode || languageCode === 'unknown') {
+    return 'unknown';
+  }
+  // Extract primary language (before first hyphen)
+  const primary = languageCode.split('-')[0].toLowerCase();
+  return primary || 'unknown';
+}
+/**
+ * Get human-readable language name from code
+ */
+const LANGUAGE_NAMES = {
+  'de': 'German',
+  'en': 'English',
+  'es': 'Spanish',
+  'fr': 'French',
+  'pt': 'Portuguese',
+  'it': 'Italian',
+  'nl': 'Dutch',
+  'sv': 'Swedish',
+  'ar': 'Arabic',
+  'zh': 'Chinese',
+  'ja': 'Japanese',
+  'ko': 'Korean',
+  'ru': 'Russian',
+  'pl': 'Polish',
+  'unknown': 'Unknown'
+};
+function getLanguageName(languageCode) {
+  if (!languageCode || languageCode === 'unknown') {
+    return 'Unknown';
+  }
+  const primary = getPrimaryLanguage(languageCode);
+  return LANGUAGE_NAMES[primary] || `Unknown (${primary})`;
+}
+module.exports = {
+  detectLanguage,
+  getPrimaryLanguage,
+  getLanguageName,
+  LANGUAGE_NAMES
+};

package/src/guardian/live-cli.js ADDED Viewed

@@ -0,0 +1,95 @@
+/**
+ * Live Guardian CLI
+ * Periodically run journey scans and compare against baseline.
+ */
+const fs = require('fs');
+const path = require('path');
+const { runJourneyScanCLI } = require('./journey-scan-cli');
+const { getJourneyDefinition } = require('./journey-definitions');
+const { detectIntent } = require('./intent-detector');
+const { JourneyScanner } = require('./journey-scanner');
+const { buildBaselineFromJourneyResult, compareAgainstBaseline, classifySeverity } = require('./drift-detector');
+const { shouldEmitAlert, recordAlert } = require('./alert-ledger');
+async function runLiveCLI(config) {
+  const { baseUrl, artifactsDir = './.odavlguardian', intervalMinutes = null, headless = true, timeout = 20000, preset, presetProvided = false, cooldownMinutes = 60 } = config;
+  // Ensure output directories
+  if (!fs.existsSync(artifactsDir)) fs.mkdirSync(artifactsDir, { recursive: true });
+  const baselinePath = path.join(artifactsDir, 'baseline.json');
+  async function singleRunEvaluate() {
+    // Auto intent + journey selection if preset not provided
+    let finalPreset = preset || 'saas';
+    let intentDetection = null;
+    if (!presetProvided) {
+      intentDetection = await detectIntent(baseUrl, { timeout, headless });
+      if (intentDetection.intent === 'saas') finalPreset = 'saas';
+      else if (intentDetection.intent === 'shop') finalPreset = 'shop';
+      else if (intentDetection.intent === 'landing') finalPreset = 'landing';
+      else finalPreset = 'landing';
+    }
+    const journey = getJourneyDefinition(finalPreset);
+    const scanner = new JourneyScanner({ timeout, headless, screenshotDir: path.join(artifactsDir, 'screenshots') });
+    const result = await scanner.scan(baseUrl, journey);
+    if (intentDetection) result.intentDetection = intentDetection;
+    // Baseline capture on first run
+    if (!fs.existsSync(baselinePath)) {
+      const baseline = buildBaselineFromJourneyResult(result);
+      fs.writeFileSync(baselinePath, JSON.stringify(baseline, null, 2), 'utf8');
+      console.log('📌 Baseline captured.');
+      return { result, baseline, drift: { hasDrift: false, reasons: [] }, exitCode: 0 };
+    }
+    // Load baseline and compare
+    const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+    const drift = compareAgainstBaseline(baseline, result);
+    const severity = classifySeverity(drift, result);
+    // Write report and baseline comparison summary
+    const { HumanReporter } = require('./human-reporter');
+    result.baseline = baseline;
+    result.drift = drift;
+    result.severity = severity;
+    const reporter = new HumanReporter();
+    reporter.generateSummary(result, artifactsDir);
+    reporter.generateJSON(result, artifactsDir);
+    if (drift.hasDrift) {
+      const alertDecision = shouldEmitAlert(drift.reasons, severity, artifactsDir, cooldownMinutes);
+      if (alertDecision.emit) {
+        console.log(`🚨 Guardian detected a behavioral regression (${severity}):`);
+        for (const r of drift.reasons) console.log(`– ${r}`);
+        recordAlert(alertDecision.signature, severity, artifactsDir);
+        return { result, baseline, drift, severity, exitCode: 3 };
+      } else {
+        console.log(`✅ Drift detected but alert suppressed (${alertDecision.reason})`);
+        return { result, baseline, drift, severity, exitCode: 0 };
+      }
+    }
+    console.log('✅ No regression detected.');
+    return { result, baseline, drift, severity, exitCode: 0 };
+  }
+  if (intervalMinutes && intervalMinutes > 0) {
+    let running = true;
+    const handleSigint = () => { running = false; console.log('\n🛑 Live Guardian stopped.'); process.exit(0); };
+    process.on('SIGINT', handleSigint);
+    console.log(`⏱️  Live mode: every ${intervalMinutes} minute(s)`);
+    while (running) {
+      const { exitCode } = await singleRunEvaluate();
+      if (exitCode === 3) process.exit(3);
+      await new Promise(r => setTimeout(r, intervalMinutes * 60 * 1000));
+    }
+  } else {
+    const { exitCode } = await singleRunEvaluate();
+    process.exit(exitCode);
+  }
+}
+module.exports = { runLiveCLI };

package/src/guardian/live-scheduler-runner.js ADDED Viewed

@@ -0,0 +1,137 @@
+/**
+ * Live Scheduler Runner
+ * Detached background process that executes schedules on time.
+ *
+ * Each tick invokes the existing CLI path: "guardian live <url> [--preset ...]"
+ * to reuse baseline/drift/alerts and plan/RBAC enforcement without refactoring.
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+const SCHED_DIR = path.join(os.homedir(), '.odavl-guardian', 'scheduler');
+const STATE_FILE = path.join(SCHED_DIR, 'schedules.json');
+// Active timers per schedule id
+const timers = new Map();
+function loadState() {
+  try {
+    const data = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+    if (!data.schedules) data.schedules = [];
+    return data;
+  } catch {
+    return { schedules: [] };
+  }
+}
+function saveState(state) {
+  const data = {
+    schedules: state.schedules || [],
+    runner: state.runner || null,
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(STATE_FILE, JSON.stringify(data, null, 2), 'utf-8');
+}
+function scheduleRun(entry) {
+  // Clear existing timer
+  const existing = timers.get(entry.id);
+  if (existing) {
+    clearTimeout(existing);
+    timers.delete(entry.id);
+  }
+  if (entry.status !== 'running') {
+    return;
+  }
+  const now = Date.now();
+  const nextTs = entry.nextRunAt ? Date.parse(entry.nextRunAt) : (now + entry.intervalMinutes * 60 * 1000);
+  const delay = Math.max(0, nextTs - now);
+  const t = setTimeout(() => {
+    executeLive(entry).then(() => {
+      // Update times and reschedule
+      const state = loadState();
+      const s = state.schedules.find(x => x.id === entry.id);
+      if (s) {
+        const finished = Date.now();
+        s.lastRunAt = new Date(finished).toISOString();
+        s.nextRunAt = new Date(finished + s.intervalMinutes * 60 * 1000).toISOString();
+        saveState(state);
+        scheduleRun(s);
+      }
+    }).catch(() => {
+      // On failure, still advance nextRunAt
+      const state = loadState();
+      const s = state.schedules.find(x => x.id === entry.id);
+      if (s) {
+        const finished = Date.now();
+        s.lastRunAt = new Date(finished).toISOString();
+        s.nextRunAt = new Date(finished + s.intervalMinutes * 60 * 1000).toISOString();
+        saveState(state);
+        scheduleRun(s);
+      }
+    });
+  }, delay);
+  timers.set(entry.id, t);
+}
+function executeLive(entry) {
+  return new Promise((resolve) => {
+    // Spawn the existing CLI path in a child process.
+    const nodeExec = process.execPath;
+    const binPath = path.join(__dirname, '..', '..', 'bin', 'guardian.js');
+    const args = ['live', '--url', entry.url];
+    if (entry.preset) {
+      args.push('--preset', entry.preset);
+    }
+    const child = spawn(nodeExec, [binPath, ...args], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.on('exit', () => resolve());
+    child.on('error', () => resolve());
+  });
+}
+function reconcile() {
+  const state = loadState();
+  // For every running schedule, ensure a timer exists
+  for (const s of state.schedules) {
+    if (s.status === 'running') {
+      scheduleRun(s);
+    } else {
+      const t = timers.get(s.id);
+      if (t) {
+        clearTimeout(t);
+        timers.delete(s.id);
+      }
+    }
+  }
+}
+function startWatch() {
+  try {
+    fs.watch(STATE_FILE, { persistent: true }, () => {
+      reconcile();
+    });
+  } catch {
+    // Fallback: periodic reconcile
+    setInterval(reconcile, 5000);
+  }
+}
+function main() {
+  // Initial reconcile and watch for changes
+  reconcile();
+  startWatch();
+}
+main();

package/src/guardian/live-scheduler.js ADDED Viewed

@@ -0,0 +1,146 @@
+/**
+ * Live Scheduler (Phase A)
+ * Local-first, time-based scheduler with persisted state.
+ *
+ * Schedules are stored under ~/.odavl-guardian/scheduler/schedules.json
+ * Background runner: live-scheduler-runner.js (detached child process).
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+const SCHED_DIR = path.join(os.homedir(), '.odavl-guardian', 'scheduler');
+const STATE_FILE = path.join(SCHED_DIR, 'schedules.json');
+const RUNNER_FILE = path.join(__dirname, 'live-scheduler-runner.js');
+function ensureSchedDir() {
+  if (!fs.existsSync(SCHED_DIR)) {
+    fs.mkdirSync(SCHED_DIR, { recursive: true });
+  }
+}
+function loadState() {
+  ensureSchedDir();
+  if (!fs.existsSync(STATE_FILE)) {
+    return { schedules: [], runner: null };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+    if (!data.schedules) data.schedules = [];
+    return data;
+  } catch (err) {
+    return { schedules: [], runner: null };
+  }
+}
+function saveState(state) {
+  ensureSchedDir();
+  const data = {
+    schedules: state.schedules || [],
+    runner: state.runner || null,
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(STATE_FILE, JSON.stringify(data, null, 2), 'utf-8');
+  return data;
+}
+function genId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+/**
+ * Create and register a new schedule
+ */
+function createSchedule({ url, preset = 'saas', intervalMinutes }) {
+  if (!url || typeof url !== 'string') throw new Error('url is required');
+  if (!intervalMinutes || intervalMinutes <= 0) throw new Error('intervalMinutes must be > 0');
+  const state = loadState();
+  const id = genId();
+  const now = Date.now();
+  const nextRunAt = new Date(now + intervalMinutes * 60 * 1000).toISOString();
+  const entry = {
+    id,
+    url,
+    preset,
+    intervalMinutes,
+    status: 'running',
+    lastRunAt: null,
+    nextRunAt,
+    createdAt: new Date().toISOString(),
+  };
+  state.schedules.push(entry);
+  saveState(state);
+  return entry;
+}
+/**
+ * Stop a schedule by id
+ */
+function stopSchedule(id) {
+  const state = loadState();
+  const s = state.schedules.find(x => x.id === id);
+  if (!s) throw new Error(`Schedule not found: ${id}`);
+  s.status = 'stopped';
+  saveState(state);
+  return s;
+}
+/**
+ * List schedules
+ */
+function listSchedules() {
+  const state = loadState();
+  return state.schedules;
+}
+/**
+ * Check if runner pid is active
+ */
+function isRunnerActive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+/**
+ * Start background runner (detached)
+ */
+function startBackgroundRunner() {
+  ensureSchedDir();
+  const state = loadState();
+  // Avoid multiple runners
+  if (state.runner && isRunnerActive(state.runner.pid)) {
+    return state.runner;
+  }
+  const nodeExec = process.execPath;
+  const child = spawn(nodeExec, [RUNNER_FILE], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  const runnerInfo = {
+    pid: child.pid,
+    startedAt: new Date().toISOString(),
+  };
+  child.unref();
+  state.runner = runnerInfo;
+  saveState(state);
+  return runnerInfo;
+}
+module.exports = {
+  createSchedule,
+  stopSchedule,
+  listSchedules,
+  startBackgroundRunner,
+  loadState,
+  saveState,
+};