@odavl/guardian 0.2.0 → 1.0.0

package/src/guardian/live-cli.js

@@ -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

@@ -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

@@ -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,
+};