cursor-guard 2.1.1 → 4.0.0

package/references/lib/core/anomaly.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { isGitRepo, gitDir: getGitDir } = require('../utils');
+
+// ── Alert file paths ────────────────────────────────────────────
+
+function alertFilePath(projectDir) {
+  if (isGitRepo(projectDir)) {
+    const gDir = getGitDir(projectDir);
+    if (gDir) return path.join(gDir, 'cursor-guard-alert.json');
+  }
+  return path.join(projectDir, '.cursor-guard-backup', 'cursor-guard-alert.json');
+}
+
+// ── In-process change tracker ───────────────────────────────────
+
+/**
+ * Create a change tracker for in-process monitoring (used by auto-backup).
+ *
+ * @param {object} cfg - Loaded config (needs proactive_alert, alert_thresholds)
+ * @returns {{ events: Array, alerts: Array, config: object }}
+ */
+function createChangeTracker(cfg) {
+  return {
+    events: [],
+    alerts: [],
+    config: {
+      enabled: cfg.proactive_alert !== false,
+      filesPerWindow: cfg.alert_thresholds.files_per_window,
+      windowSeconds: cfg.alert_thresholds.window_seconds,
+      cooldownSeconds: cfg.alert_thresholds.cooldown_seconds,
+      maxEvents: 1000,
+      maxAlerts: 100,
+    },
+  };
+}
+
+/**
+ * Record a change event in the tracker.
+ *
+ * @param {object} tracker
+ * @param {number} fileCount - Number of files changed
+ * @param {string[]} [files] - Changed file paths (optional, for diagnostics)
+ */
+function recordChange(tracker, fileCount, files) {
+  if (!tracker.config.enabled) return;
+
+  tracker.events.push({
+    timestamp: Date.now(),
+    fileCount,
+    files: files || [],
+  });
+
+  if (tracker.events.length > tracker.config.maxEvents) {
+    tracker.events = tracker.events.slice(-tracker.config.maxEvents);
+  }
+}
+
+/**
+ * Analyze the tracker for anomalous change velocity.
+ *
+ * @param {object} tracker
+ * @returns {{ anomaly: boolean, alert?: object }}
+ */
+function checkAnomaly(tracker) {
+  if (!tracker.config.enabled || tracker.events.length === 0) {
+    return { anomaly: false };
+  }
+
+  const now = Date.now();
+  const windowMs = tracker.config.windowSeconds * 1000;
+  const recentEvents = tracker.events.filter(e => e.timestamp >= now - windowMs);
+  const totalFiles = recentEvents.reduce((sum, e) => sum + e.fileCount, 0);
+
+  if (totalFiles < tracker.config.filesPerWindow) {
+    return { anomaly: false };
+  }
+
+  const lastAlert = tracker.alerts[tracker.alerts.length - 1];
+  const cooldownMs = tracker.config.cooldownSeconds * 1000;
+  if (lastAlert && now - lastAlert.detectedAt < cooldownMs) {
+    return { anomaly: true, alert: lastAlert, suppressed: true };
+  }
+
+  const alert = {
+    type: 'high_change_velocity',
+    detectedAt: now,
+    timestamp: new Date(now).toISOString(),
+    fileCount: totalFiles,
+    windowSeconds: tracker.config.windowSeconds,
+    threshold: tracker.config.filesPerWindow,
+    expiresAt: new Date(now + 5 * 60 * 1000).toISOString(),
+    recommendation: 'High volume of file changes detected. Consider reviewing recent modifications and creating a manual snapshot.',
+  };
+
+  tracker.alerts.push(alert);
+  if (tracker.alerts.length > tracker.config.maxAlerts) {
+    tracker.alerts = tracker.alerts.slice(-tracker.config.maxAlerts);
+  }
+
+  return { anomaly: true, alert };
+}
+
+/**
+ * Get the current alert status summary from the tracker.
+ *
+ * @param {object} tracker
+ * @returns {{ enabled: boolean, hasActiveAlert: boolean, latestAlert?: object, alertCount: number, recentActivity: object }}
+ */
+function getAlertStatus(tracker) {
+  if (!tracker.config.enabled) {
+    return { enabled: false, hasActiveAlert: false, alertCount: 0, recentActivity: { windowSeconds: 0, fileCount: 0 } };
+  }
+
+  const now = Date.now();
+  const windowMs = tracker.config.windowSeconds * 1000;
+  const recentEvents = tracker.events.filter(e => e.timestamp >= now - windowMs);
+  const fileCount = recentEvents.reduce((sum, e) => sum + e.fileCount, 0);
+
+  const latestAlert = tracker.alerts[tracker.alerts.length - 1];
+  const isActive = latestAlert && now < new Date(latestAlert.expiresAt).getTime();
+
+  return {
+    enabled: true,
+    hasActiveAlert: !!isActive,
+    latestAlert: isActive ? latestAlert : undefined,
+    alertCount: tracker.alerts.length,
+    recentActivity: {
+      windowSeconds: tracker.config.windowSeconds,
+      fileCount,
+    },
+  };
+}
+
+// ── Alert file persistence (bridge between auto-backup and MCP) ─
+
+/**
+ * Save an alert to a file so the MCP server can read it.
+ *
+ * @param {string} projectDir
+ * @param {object} alert
+ */
+function saveAlert(projectDir, alert) {
+  const filePath = alertFilePath(projectDir);
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(alert, null, 2));
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Load and return any active (non-expired) alert from file.
+ * Pure read — does not delete expired files (use clearExpiredAlert for that).
+ *
+ * @param {string} projectDir
+ * @returns {object|null} - Alert object or null
+ */
+function loadActiveAlert(projectDir) {
+  const filePath = alertFilePath(projectDir);
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    if (!data.expiresAt) return null;
+    if (Date.now() >= new Date(data.expiresAt).getTime()) return null;
+    return data;
+  } catch { return null; }
+}
+
+/**
+ * Remove the alert file if it exists and is expired. No-op if still active.
+ * Safe to call periodically from the watcher loop.
+ *
+ * @param {string} projectDir
+ * @returns {boolean} true if an expired file was removed
+ */
+function clearExpiredAlert(projectDir) {
+  const filePath = alertFilePath(projectDir);
+  try {
+    if (!fs.existsSync(filePath)) return false;
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch {
+      try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+      return true;
+    }
+    if (data.expiresAt && Date.now() >= new Date(data.expiresAt).getTime()) {
+      fs.unlinkSync(filePath);
+      return true;
+    }
+    return false;
+  } catch { return false; }
+}
+
+/**
+ * Unconditionally remove the alert file (e.g. user acknowledged the alert).
+ *
+ * @param {string} projectDir
+ */
+function clearAlert(projectDir) {
+  const filePath = alertFilePath(projectDir);
+  try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+}
+
+module.exports = {
+  createChangeTracker,
+  recordChange,
+  checkAnomaly,
+  getAlertStatus,
+  saveAlert,
+  loadActiveAlert,
+  clearExpiredAlert,
+  clearAlert,
+  alertFilePath,
+};

package/references/lib/core/backups.js

@@ -0,0 +1,357 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  git, isGitRepo, gitDir: getGitDir, walkDir, diskFreeGB,
+} = require('../utils');
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function parseShadowTimestamp(name) {
+  const m = name.match(/^(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})(?:_(\d{3}))?$/);
+  if (!m) return null;
+  const ms = m[7] ? `.${m[7]}` : '';
+  return new Date(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}${ms}`);
+}
+
+function parseBeforeExpression(before) {
+  if (!before) return null;
+  const iso = Date.parse(before);
+  if (!isNaN(iso)) return new Date(iso);
+  const agoMatch = before.match(/^(\d+)\s*(second|minute|hour|day|week|month)s?\s*ago$/i);
+  if (agoMatch) {
+    const n = parseInt(agoMatch[1], 10);
+    const unit = agoMatch[2].toLowerCase();
+    const ms = { second: 1000, minute: 60000, hour: 3600000, day: 86400000, week: 604800000, month: 2592000000 }[unit] || 0;
+    return new Date(Date.now() - n * ms);
+  }
+  return null;
+}
+
+function entryToMs(entry) {
+  if (!entry.timestamp) return 0;
+  const iso = Date.parse(entry.timestamp);
+  if (!isNaN(iso)) return iso;
+  const tsName = typeof entry.timestamp === 'string' && entry.timestamp.startsWith('pre-restore-')
+    ? entry.timestamp.slice('pre-restore-'.length)
+    : entry.timestamp;
+  const d = parseShadowTimestamp(tsName);
+  return d ? d.getTime() : 0;
+}
+
+// ── List backups ────────────────────────────────────────────────
+
+/**
+ * List available backup/restore points from all sources.
+ * Returns a globally time-sorted list (newest first), truncated to `limit`.
+ *
+ * @param {string} projectDir
+ * @param {object} [opts]
+ * @param {string} [opts.file] - Filter to commits touching this relative path
+ * @param {string} [opts.before] - Time boundary (e.g. '10 minutes ago', ISO string)
+ * @param {number} [opts.limit=20] - Max total results
+ * @returns {{ sources: Array<{type: string, ref?: string, commitHash?: string, shortHash?: string, timestamp?: string, message?: string, path?: string}> }}
+ */
+function listBackups(projectDir, opts = {}) {
+  const limit = opts.limit || 20;
+  const sources = [];
+
+  if (opts.file) {
+    const normalized = path.normalize(opts.file).replace(/\\/g, '/');
+    if (path.isAbsolute(normalized) || normalized.startsWith('..')) {
+      return { sources: [], error: 'file path must be relative and within project directory' };
+    }
+  }
+
+  const repo = isGitRepo(projectDir);
+  const beforeDate = parseBeforeExpression(opts.before);
+
+  // Git sources
+  if (repo) {
+    // Auto-backup commits (git --before handles native filtering)
+    const autoRef = 'refs/guard/auto-backup';
+    const autoExists = git(['rev-parse', '--verify', autoRef], { cwd: projectDir, allowFail: true });
+    if (autoExists) {
+      const logArgs = ['log', autoRef, `--format=%H %aI %s`, `-${limit}`, '--grep=^guard:'];
+      if (opts.before) logArgs.push(`--before=${opts.before}`);
+      if (opts.file) logArgs.push('--', opts.file);
+      const out = git(logArgs, { cwd: projectDir, allowFail: true });
+      if (out) {
+        for (const line of out.split('\n').filter(Boolean)) {
+          const firstSpace = line.indexOf(' ');
+          const secondSpace = line.indexOf(' ', firstSpace + 1);
+          const hash = line.substring(0, firstSpace);
+          const timestamp = line.substring(firstSpace + 1, secondSpace);
+          const message = line.substring(secondSpace + 1);
+          sources.push({
+            type: 'git-auto-backup',
+            ref: autoRef,
+            commitHash: hash,
+            shortHash: hash.substring(0, 7),
+            timestamp,
+            message,
+          });
+        }
+      }
+    }
+
+    // Pre-restore snapshots
+    const preRestoreRefs = git(
+      ['for-each-ref', 'refs/guard/pre-restore/', '--format=%(refname) %(objectname) %(*objectname) %(creatordate:iso-strict)', '--sort=-creatordate'],
+      { cwd: projectDir, allowFail: true }
+    );
+    if (preRestoreRefs) {
+      for (const line of preRestoreRefs.split('\n').filter(Boolean)) {
+        const parts = line.split(' ');
+        const ref = parts[0];
+        const hash = parts[1];
+        const timestamp = parts[3] || parts[2];
+        if (beforeDate && timestamp) {
+          const ms = Date.parse(timestamp);
+          if (!isNaN(ms) && ms > beforeDate.getTime()) continue;
+        }
+        sources.push({
+          type: 'git-pre-restore',
+          ref,
+          commitHash: hash,
+          shortHash: hash.substring(0, 7),
+          timestamp,
+        });
+      }
+    }
+
+    // Agent snapshot ref
+    const snapshotHash = git(['rev-parse', '--verify', 'refs/guard/snapshot'], { cwd: projectDir, allowFail: true });
+    if (snapshotHash) {
+      const ts = git(['log', '-1', '--format=%aI', 'refs/guard/snapshot'], { cwd: projectDir, allowFail: true });
+      const include = !beforeDate || (ts && Date.parse(ts) <= beforeDate.getTime());
+      if (include) {
+        sources.push({
+          type: 'git-snapshot',
+          ref: 'refs/guard/snapshot',
+          commitHash: snapshotHash,
+          shortHash: snapshotHash.substring(0, 7),
+          timestamp: ts || null,
+        });
+      }
+    }
+  }
+
+  // Shadow copy directories
+  const backupDir = path.join(projectDir, '.cursor-guard-backup');
+  if (fs.existsSync(backupDir)) {
+    try {
+      const dirs = fs.readdirSync(backupDir, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name)
+        .sort()
+        .reverse();
+
+      for (const name of dirs) {
+        const isPreRestore = name.startsWith('pre-restore-');
+        const isTimestamp = /^\d{8}_\d{6}(_\d{3})?$/.test(name);
+        if (!isTimestamp && !isPreRestore) continue;
+
+        if (beforeDate) {
+          const tsName = isPreRestore ? name.slice('pre-restore-'.length) : name;
+          const snapDate = parseShadowTimestamp(tsName);
+          if (snapDate && snapDate.getTime() > beforeDate.getTime()) continue;
+        }
+
+        const dirPath = path.join(backupDir, name);
+
+        if (opts.file && !fs.existsSync(path.join(dirPath, opts.file))) continue;
+
+        sources.push({
+          type: isPreRestore ? 'shadow-pre-restore' : 'shadow',
+          timestamp: name,
+          path: dirPath,
+        });
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Unified time sort (newest first) across all sources, then truncate
+  sources.sort((a, b) => entryToMs(b) - entryToMs(a));
+
+  return { sources: sources.slice(0, limit) };
+}
+
+// ── Shadow retention ────────────────────────────────────────────
+
+/**
+ * Clean old shadow copy snapshots based on retention config.
+ *
+ * @param {string} backupDir - Path to .cursor-guard-backup/
+ * @param {object} cfg - Loaded config
+ * @returns {{ removed: number, mode: string, diskFreeGB?: number, diskWarning?: string }}
+ */
+function cleanShadowRetention(backupDir, cfg) {
+  const { mode, days, max_count, max_size_mb } = cfg.retention;
+  let dirs;
+  try {
+    dirs = fs.readdirSync(backupDir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && /^\d{8}_\d{6}(_\d{3})?$/.test(d.name))
+      .map(d => d.name)
+      .sort()
+      .reverse();
+  } catch { return { removed: 0, mode }; }
+  if (!dirs || dirs.length === 0) return { removed: 0, mode };
+
+  let removed = 0;
+
+  if (mode === 'days') {
+    const cutoff = Date.now() - days * 86400000;
+    for (const name of dirs) {
+      const dt = parseShadowTimestamp(name);
+      if (!dt) continue;
+      if (dt.getTime() < cutoff) {
+        fs.rmSync(path.join(backupDir, name), { recursive: true, force: true });
+        removed++;
+      }
+    }
+  } else if (mode === 'count') {
+    if (dirs.length > max_count) {
+      for (const name of dirs.slice(max_count)) {
+        fs.rmSync(path.join(backupDir, name), { recursive: true, force: true });
+        removed++;
+      }
+    }
+  } else if (mode === 'size') {
+    let totalBytes = 0;
+    try {
+      const allFiles = walkDir(backupDir, backupDir);
+      for (const f of allFiles) {
+        try { totalBytes += fs.statSync(f.full).size; } catch { /* skip */ }
+      }
+    } catch { /* ignore */ }
+    const oldestFirst = [...dirs].reverse();
+    for (const name of oldestFirst) {
+      if (totalBytes / (1024 * 1024) <= max_size_mb) break;
+      const dirPath = path.join(backupDir, name);
+      let dirSize = 0;
+      try {
+        const files = walkDir(dirPath, dirPath);
+        for (const f of files) {
+          try { dirSize += fs.statSync(f.full).size; } catch { /* skip */ }
+        }
+      } catch { /* ignore */ }
+      fs.rmSync(dirPath, { recursive: true, force: true });
+      totalBytes -= dirSize;
+      removed++;
+    }
+  }
+
+  const result = { removed, mode };
+
+  const freeGB = diskFreeGB(backupDir);
+  if (freeGB !== null) {
+    result.diskFreeGB = parseFloat(freeGB.toFixed(1));
+    if (freeGB < 1) result.diskWarning = 'critically low';
+    else if (freeGB < 5) result.diskWarning = 'low';
+  }
+
+  return result;
+}
+
+// ── Git retention ───────────────────────────────────────────────
+
+/**
+ * Clean old git auto-backup commits by rebuilding the branch as an orphan chain.
+ *
+ * @param {string} branchRef
+ * @param {string} gitDirPath
+ * @param {object} cfg - Loaded config
+ * @param {string} cwd - Project directory
+ * @returns {{ kept: number, pruned: number, mode: string, rebuilt: boolean, skipped?: boolean, reason?: string }}
+ */
+function cleanGitRetention(branchRef, gitDirPath, cfg, cwd) {
+  const { mode, days, max_count } = cfg.git_retention;
+  if (!cfg.git_retention.enabled) {
+    return { kept: 0, pruned: 0, mode, rebuilt: false, skipped: true, reason: 'retention disabled' };
+  }
+
+  const out = git(['log', branchRef, '--format=%H %aI %cI %s'], { cwd, allowFail: true });
+  if (!out) {
+    return { kept: 0, pruned: 0, mode, rebuilt: false, skipped: true, reason: 'no commits on ref' };
+  }
+
+  const lines = out.split('\n').filter(Boolean);
+  const guardCommits = [];
+  for (const line of lines) {
+    const firstSpace = line.indexOf(' ');
+    const secondSpace = line.indexOf(' ', firstSpace + 1);
+    const thirdSpace = line.indexOf(' ', secondSpace + 1);
+    const hash = line.substring(0, firstSpace);
+    const authorDate = line.substring(firstSpace + 1, secondSpace);
+    const committerDate = line.substring(secondSpace + 1, thirdSpace);
+    const subject = line.substring(thirdSpace + 1);
+    if (subject.startsWith('guard: auto-backup') || subject.startsWith('guard: snapshot')) {
+      guardCommits.push({ hash, authorDate, committerDate, subject });
+    }
+    // Non-guard commits are silently skipped; continue scanning older history
+  }
+
+  const total = guardCommits.length;
+  if (total === 0) {
+    return { kept: 0, pruned: 0, mode, rebuilt: false, skipped: true, reason: 'no guard commits found' };
+  }
+
+  let keepCount = total;
+  if (mode === 'count') {
+    keepCount = Math.min(total, max_count);
+  } else if (mode === 'days') {
+    const cutoff = Date.now() - days * 86400000;
+    keepCount = 0;
+    for (const c of guardCommits) {
+      if (new Date(c.authorDate).getTime() >= cutoff) keepCount++;
+      else break;
+    }
+    keepCount = Math.max(keepCount, 10);
+  }
+
+  if (keepCount >= total) {
+    return { kept: total, pruned: 0, mode, rebuilt: false };
+  }
+
+  const toKeep = guardCommits.slice(0, keepCount).reverse();
+
+  function commitTreeWithDate(args, commit) {
+    const env = {
+      ...process.env,
+      GIT_AUTHOR_DATE: commit.authorDate,
+      GIT_COMMITTER_DATE: commit.committerDate,
+    };
+    try {
+      return execFileSync('git', args, { cwd, env, stdio: 'pipe', encoding: 'utf-8' }).trim() || null;
+    } catch { return null; }
+  }
+
+  const rootTree = git(['rev-parse', `${toKeep[0].hash}^{tree}`], { cwd, allowFail: true });
+  if (!rootTree) {
+    return { kept: total, pruned: 0, mode, rebuilt: false, reason: 'could not resolve root tree' };
+  }
+  let prevHash = commitTreeWithDate(['commit-tree', rootTree, '-m', toKeep[0].subject], toKeep[0]);
+  if (!prevHash) {
+    return { kept: total, pruned: 0, mode, rebuilt: false, reason: 'commit-tree failed for root' };
+  }
+
+  for (let i = 1; i < toKeep.length; i++) {
+    const tree = git(['rev-parse', `${toKeep[i].hash}^{tree}`], { cwd, allowFail: true });
+    if (!tree) {
+      return { kept: total, pruned: 0, mode, rebuilt: false, reason: `could not resolve tree for commit ${i}` };
+    }
+    prevHash = commitTreeWithDate(['commit-tree', tree, '-p', prevHash, '-m', toKeep[i].subject], toKeep[i]);
+    if (!prevHash) {
+      return { kept: total, pruned: 0, mode, rebuilt: false, reason: `commit-tree failed at index ${i}` };
+    }
+  }
+
+  git(['update-ref', branchRef, prevHash], { cwd, allowFail: true });
+
+  return { kept: keepCount, pruned: total - keepCount, mode, rebuilt: true };
+}
+
+module.exports = { listBackups, cleanShadowRetention, cleanGitRetention, parseShadowTimestamp };