@odavl/guardian 0.1.0-rc1 → 1.0.0

package/src/founder/founder-tracker.js

@@ -0,0 +1,213 @@
+/**
+ * Phase 10: Founder Tracker
+ * Detects and tracks first 100 users (Founding Users)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const FOUNDER_DIR = path.join(os.homedir(), '.odavl-guardian', 'founder');
+const FOUNDER_FILE = path.join(FOUNDER_DIR, 'status.json');
+const GLOBAL_COUNTER_FILE = path.join(FOUNDER_DIR, 'global-counter.json');
+const FOUNDER_LIMIT = 100;
+
+/**
+ * Ensure founder directory exists
+ */
+function ensureFounderDir() {
+  if (!fs.existsSync(FOUNDER_DIR)) {
+    fs.mkdirSync(FOUNDER_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Generate unique machine ID (stable across runs)
+ */
+function getMachineId() {
+  const machineFile = path.join(FOUNDER_DIR, 'machine-id.txt');
+  ensureFounderDir();
+  
+  if (fs.existsSync(machineFile)) {
+    return fs.readFileSync(machineFile, 'utf-8').trim();
+  }
+  
+  // Generate new machine ID
+  const id = crypto.randomBytes(16).toString('hex');
+  fs.writeFileSync(machineFile, id, 'utf-8');
+  return id;
+}
+
+/**
+ * Get global founder counter
+ */
+function getGlobalCounter() {
+  ensureFounderDir();
+  
+  if (!fs.existsSync(GLOBAL_COUNTER_FILE)) {
+    return { count: 0, users: [] };
+  }
+  
+  try {
+    return JSON.parse(fs.readFileSync(GLOBAL_COUNTER_FILE, 'utf-8'));
+  } catch (error) {
+    return { count: 0, users: [] };
+  }
+}
+
+/**
+ * Save global founder counter
+ */
+function saveGlobalCounter(counter) {
+  ensureFounderDir();
+  fs.writeFileSync(GLOBAL_COUNTER_FILE, JSON.stringify(counter, null, 2), 'utf-8');
+}
+
+/**
+ * Get founder status for current user
+ */
+function getFounderStatus() {
+  ensureFounderDir();
+  
+  if (!fs.existsSync(FOUNDER_FILE)) {
+    return null;
+  }
+  
+  try {
+    return JSON.parse(fs.readFileSync(FOUNDER_FILE, 'utf-8'));
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Save founder status for current user
+ */
+function saveFounderStatus(status) {
+  ensureFounderDir();
+  fs.writeFileSync(FOUNDER_FILE, JSON.stringify(status, null, 2), 'utf-8');
+}
+
+/**
+ * Check if user is a founding user
+ */
+function isFoundingUser() {
+  const status = getFounderStatus();
+  return status && status.isFounder === true;
+}
+
+/**
+ * Register current user (call on first scan)
+ */
+function registerUser() {
+  // Check if already registered
+  const existingStatus = getFounderStatus();
+  if (existingStatus) {
+    return existingStatus;
+  }
+  
+  const machineId = getMachineId();
+  const counter = getGlobalCounter();
+  
+  // Check if machine ID already registered
+  const alreadyRegistered = counter.users.includes(machineId);
+  
+  if (alreadyRegistered) {
+    // Find their position
+    const position = counter.users.indexOf(machineId) + 1;
+    const status = {
+      isFounder: position <= FOUNDER_LIMIT,
+      registeredAt: new Date().toISOString(),
+      founderNumber: position <= FOUNDER_LIMIT ? position : null,
+      machineId,
+    };
+    saveFounderStatus(status);
+    return status;
+  }
+  
+  // New user - add to global counter
+  counter.count += 1;
+  counter.users.push(machineId);
+  saveGlobalCounter(counter);
+  
+  const isFounder = counter.count <= FOUNDER_LIMIT;
+  const status = {
+    isFounder,
+    registeredAt: new Date().toISOString(),
+    founderNumber: isFounder ? counter.count : null,
+    machineId,
+  };
+  
+  saveFounderStatus(status);
+  return status;
+}
+
+/**
+ * Get founder message for display
+ */
+function getFounderMessage() {
+  const status = getFounderStatus();
+  
+  if (!status) {
+    return null;
+  }
+  
+  if (status.isFounder) {
+    return `🌟 You're Founding User #${status.founderNumber} — thank you for helping shape Guardian.`;
+  }
+  
+  return null;
+}
+
+/**
+ * Get founder badge for reports (HTML)
+ */
+function getFounderBadgeHTML() {
+  const status = getFounderStatus();
+  
+  if (!status || !status.isFounder) {
+    return '';
+  }
+  
+  return `
+    <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 12px 20px; border-radius: 8px; margin: 16px 0; text-align: center; font-weight: 600; box-shadow: 0 4px 12px rgba(102, 126, 234, 0.3);">
+      🌟 Founding User #${status.founderNumber}
+      <div style="font-size: 0.85em; opacity: 0.9; margin-top: 4px;">Thank you for being an early supporter</div>
+    </div>
+  `;
+}
+
+/**
+ * Get total registered users count
+ */
+function getTotalUsers() {
+  const counter = getGlobalCounter();
+  return counter.count;
+}
+
+/**
+ * Reset founder data (for testing only)
+ */
+function resetFounderData() {
+  if (fs.existsSync(FOUNDER_FILE)) {
+    fs.unlinkSync(FOUNDER_FILE);
+  }
+  if (fs.existsSync(GLOBAL_COUNTER_FILE)) {
+    fs.unlinkSync(GLOBAL_COUNTER_FILE);
+  }
+  const machineFile = path.join(FOUNDER_DIR, 'machine-id.txt');
+  if (fs.existsSync(machineFile)) {
+    fs.unlinkSync(machineFile);
+  }
+}
+
+module.exports = {
+  registerUser,
+  isFoundingUser,
+  getFounderStatus,
+  getFounderMessage,
+  getFounderBadgeHTML,
+  getTotalUsers,
+  resetFounderData,
+};

package/src/founder/usage-signals.js

@@ -0,0 +1,141 @@
+/**
+ * Phase 10: Usage Signals Tracker
+ * Minimal local tracking of key milestones
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SIGNALS_DIR = path.join(os.homedir(), '.odavl-guardian');
+const SIGNALS_FILE = path.join(SIGNALS_DIR, 'signals.json');
+
+/**
+ * Ensure signals directory exists
+ */
+function ensureSignalsDir() {
+  if (!fs.existsSync(SIGNALS_DIR)) {
+    fs.mkdirSync(SIGNALS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get current signals
+ */
+function getSignals() {
+  ensureSignalsDir();
+  
+  if (!fs.existsSync(SIGNALS_FILE)) {
+    return {
+      firstScanAt: null,
+      firstLiveAt: null,
+      firstUpgradeAt: null,
+      totalScans: 0,
+      totalLiveSessions: 0,
+    };
+  }
+  
+  try {
+    return JSON.parse(fs.readFileSync(SIGNALS_FILE, 'utf-8'));
+  } catch (error) {
+    return {
+      firstScanAt: null,
+      firstLiveAt: null,
+      firstUpgradeAt: null,
+      totalScans: 0,
+      totalLiveSessions: 0,
+    };
+  }
+}
+
+/**
+ * Save signals
+ */
+function saveSignals(signals) {
+  ensureSignalsDir();
+  fs.writeFileSync(SIGNALS_FILE, JSON.stringify(signals, null, 2), 'utf-8');
+}
+
+/**
+ * Record first scan
+ */
+function recordFirstScan() {
+  const signals = getSignals();
+  
+  if (!signals.firstScanAt) {
+    signals.firstScanAt = new Date().toISOString();
+  }
+  
+  signals.totalScans += 1;
+  saveSignals(signals);
+  
+  return signals;
+}
+
+/**
+ * Record first live guardian session
+ */
+function recordFirstLive() {
+  const signals = getSignals();
+  
+  if (!signals.firstLiveAt) {
+    signals.firstLiveAt = new Date().toISOString();
+  }
+  
+  signals.totalLiveSessions += 1;
+  saveSignals(signals);
+  
+  return signals;
+}
+
+/**
+ * Record first upgrade
+ */
+function recordFirstUpgrade(planId) {
+  const signals = getSignals();
+  
+  if (!signals.firstUpgradeAt) {
+    signals.firstUpgradeAt = new Date().toISOString();
+    signals.firstUpgradePlan = planId;
+  }
+  
+  saveSignals(signals);
+  
+  return signals;
+}
+
+/**
+ * Get usage summary
+ */
+function getUsageSummary() {
+  const signals = getSignals();
+  
+  return {
+    hasScanned: signals.firstScanAt !== null,
+    hasUsedLive: signals.firstLiveAt !== null,
+    hasUpgraded: signals.firstUpgradeAt !== null,
+    totalScans: signals.totalScans,
+    totalLiveSessions: signals.totalLiveSessions,
+    daysSinceFirstScan: signals.firstScanAt 
+      ? Math.floor((Date.now() - new Date(signals.firstScanAt).getTime()) / (1000 * 60 * 60 * 24))
+      : 0,
+  };
+}
+
+/**
+ * Reset signals (for testing)
+ */
+function resetSignals() {
+  if (fs.existsSync(SIGNALS_FILE)) {
+    fs.unlinkSync(SIGNALS_FILE);
+  }
+}
+
+module.exports = {
+  recordFirstScan,
+  recordFirstLive,
+  recordFirstUpgrade,
+  getSignals,
+  getUsageSummary,
+  resetSignals,
+};

package/src/guardian/alert-ledger.js

@@ -0,0 +1,121 @@
+/**
+ * Alert Ledger - Deduplication and Cooldown
+ * Tracks emitted alerts to prevent spam
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+/**
+ * Compute deterministic signature from drift reasons
+ * @param {string[]} reasons - Array of drift reasons
+ * @returns {string} - SHA256 hash (hex)
+ */
+function computeAlertSignature(reasons) {
+  if (!Array.isArray(reasons) || reasons.length === 0) return null;
+  
+  // Normalize: sort and stringify
+  const normalized = reasons.slice().sort();
+  const str = JSON.stringify(normalized);
+  return crypto.createHash('sha256').update(str).digest('hex');
+}
+
+function getLedgerPath(outDir) {
+  const alertDir = path.join(outDir, 'alerts');
+  if (!fs.existsSync(alertDir)) fs.mkdirSync(alertDir, { recursive: true });
+  return path.join(alertDir, 'ledger.json');
+}
+
+function loadLedger(outDir) {
+  const ledgerPath = getLedgerPath(outDir);
+  if (!fs.existsSync(ledgerPath)) return { alerts: [] };
+  try {
+    return JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
+  } catch {
+    return { alerts: [] };
+  }
+}
+
+function saveLedger(outDir, ledger) {
+  const ledgerPath = getLedgerPath(outDir);
+  fs.writeFileSync(ledgerPath, JSON.stringify(ledger, null, 2), 'utf8');
+}
+
+/**
+ * Determine if alert should be emitted based on deduplication and cooldown
+ * @param {string[]} reasons - Drift reasons
+ * @param {string} severity - 'CRITICAL' or 'WARN'
+ * @param {string} outDir - Artifacts directory
+ * @param {number} cooldownMinutes - Cooldown period (default 60)
+ * @returns {object} - {emit: boolean, reason: string, signature: string, severity: string}
+ */
+function shouldEmitAlert(reasons, severity, outDir, cooldownMinutes = 60) {
+  const signature = computeAlertSignature(reasons);
+  if (!signature) return { emit: false, reason: 'no drift reasons', signature: null, severity };
+
+  const ledger = loadLedger(outDir);
+  
+  // First alert ever
+  if (ledger.alerts.length === 0) {
+    return { emit: true, reason: 'first alert (no ledger)', signature, severity };
+  }
+
+  // Find existing alert with same signature
+  const existingAlert = ledger.alerts.find(a => a.signature === signature);
+  
+  if (!existingAlert) {
+    // New drift pattern
+    return { emit: true, reason: 'new drift pattern', signature, severity };
+  }
+
+  // Duplicate signature - check cooldown
+  const lastTime = new Date(existingAlert.timestamp).getTime();
+  const now = Date.now();
+  const elapsedMinutes = (now - lastTime) / (60 * 1000);
+
+  if (elapsedMinutes < cooldownMinutes) {
+    // Check severity escalation
+    if (existingAlert.severity === 'WARN' && severity === 'CRITICAL') {
+      return { emit: true, reason: 'severity escalated from WARN to CRITICAL', signature, severity };
+    }
+    // Suppressed by cooldown
+    return { emit: false, reason: `duplicate alert (cooldown active: ${Math.round(elapsedMinutes)}/${cooldownMinutes}min)`, signature, severity };
+  }
+
+  // Cooldown expired
+  return { emit: true, reason: `cooldown expired (${Math.round(elapsedMinutes)}min)`, signature, severity };
+}
+
+/**
+ * Record emitted alert to ledger
+ * @param {string} signature - Alert signature
+ * @param {string} severity - 'CRITICAL' or 'WARN'
+ * @param {string} outDir - Artifacts directory
+ */
+function recordAlert(signature, severity, outDir) {
+  const ledger = loadLedger(outDir);
+  
+  const alert = {
+    signature,
+    severity,
+    timestamp: new Date().toISOString()
+  };
+  
+  // Update or add alert
+  const existingIndex = ledger.alerts.findIndex(a => a.signature === signature);
+  if (existingIndex >= 0) {
+    ledger.alerts[existingIndex] = alert;
+  } else {
+    ledger.alerts.push(alert);
+  }
+  
+  saveLedger(outDir, ledger);
+}
+
+module.exports = {
+  computeAlertSignature,
+  shouldEmitAlert,
+  recordAlert,
+  loadLedger
+};