cursor-guard 4.7.3 → 4.7.6

package/references/vscode-extension/dist/lib/core/anomaly.js

@@ -0,0 +1,239 @@
+'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 };
+  }
+
+  // Aggregate per-file details from recent events, deduplicated by path (latest wins)
+  const fileMap = new Map();
+  for (const e of recentEvents) {
+    if (Array.isArray(e.files)) {
+      for (const f of e.files) {
+        if (f && f.path) {
+          const existing = fileMap.get(f.path);
+          if (existing) {
+            existing.added = (existing.added || 0) + (f.added || 0);
+            existing.deleted = (existing.deleted || 0) + (f.deleted || 0);
+          } else {
+            fileMap.set(f.path, { path: f.path, action: f.action || 'modified', added: f.added || 0, deleted: f.deleted || 0 });
+          }
+        }
+      }
+    }
+  }
+  const alertFiles = [...fileMap.values()]
+    .sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted))
+    .slice(0, 50);
+
+  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.',
+    files: alertFiles.length > 0 ? alertFiles : undefined,
+  };
+
+  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/vscode-extension/dist/lib/core/backups.js

@@ -0,0 +1,462 @@
+'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;
+}
+
+const TRAILER_MAP = {
+  'Files-Changed': { key: 'filesChanged', parse: v => parseInt(v, 10) },
+  'Summary':       { key: 'summary' },
+  'Trigger':       { key: 'trigger' },
+  'Intent':        { key: 'intent' },
+  'Agent':         { key: 'agent' },
+  'Session':       { key: 'session' },
+  'From':          { key: 'from' },
+  'Restore-To':   { key: 'restoreTo' },
+  'File':          { key: 'restoreFile' },
+};
+
+function parseCommitTrailers(body) {
+  if (!body) return {};
+  const result = {};
+  const pattern = new RegExp(`^(${Object.keys(TRAILER_MAP).join('|')}):\\s*(.+)$`);
+  for (const line of body.split('\n')) {
+    const m = line.match(pattern);
+    if (m) {
+      const def = TRAILER_MAP[m[1]];
+      result[def.key] = def.parse ? def.parse(m[2]) : m[2];
+    }
+  }
+  return result;
+}
+
+// ── 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, filesChanged?: number, summary?: string, trigger?: 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\x1f%aI\x1f%B\x1e', `-${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 record of out.split('\x1e').filter(r => r.trim())) {
+          const parts = record.split('\x1f');
+          if (parts.length < 3) continue;
+          const hash = parts[0].trim();
+          const timestamp = parts[1];
+          const body = parts[2];
+          const subject = body.split('\n')[0];
+          const trailers = parseCommitTrailers(body);
+          sources.push({
+            type: 'git-auto-backup',
+            ref: autoRef,
+            commitHash: hash,
+            shortHash: hash.substring(0, 7),
+            timestamp,
+            message: subject,
+            ...trailers,
+          });
+        }
+      }
+    }
+
+    // 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;
+        }
+        const entry = {
+          type: 'git-pre-restore',
+          ref,
+          commitHash: hash,
+          shortHash: hash.substring(0, 7),
+          timestamp,
+        };
+        const prBody = git(['log', '-1', '--format=%B', hash], { cwd: projectDir, allowFail: true });
+        if (prBody) {
+          const prSubject = prBody.split('\n')[0];
+          if (prSubject) entry.message = prSubject;
+          Object.assign(entry, parseCommitTrailers(prBody));
+        }
+        sources.push(entry);
+      }
+    }
+
+    // Agent snapshot ref
+    const snapshotHash = git(['rev-parse', '--verify', 'refs/guard/snapshot'], { cwd: projectDir, allowFail: true });
+    if (snapshotHash) {
+      const snapLog = git(['log', '-1', '--format=%aI\x1f%B', 'refs/guard/snapshot'], { cwd: projectDir, allowFail: true });
+      const snapParts = snapLog ? snapLog.split('\x1f') : [];
+      const ts = snapParts[0] || null;
+      const snapBody = snapParts[1] || '';
+      const snapTrailers = parseCommitTrailers(snapBody);
+      const snapSubject = snapBody.split('\n')[0] || '';
+      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,
+          message: snapSubject || undefined,
+          ...snapTrailers,
+        });
+      }
+    }
+  }
+
+  // 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 RS = '\x1e', US = '\x1f';
+  const out = git(['log', branchRef, `--format=%H${US}%aI${US}%cI${US}%s${US}%B${RS}`], { cwd, allowFail: true });
+  if (!out) {
+    return { kept: 0, pruned: 0, mode, rebuilt: false, skipped: true, reason: 'no commits on ref' };
+  }
+
+  const records = out.split(RS).filter(r => r.trim());
+  const guardCommits = [];
+  for (const record of records) {
+    const fields = record.split(US);
+    if (fields.length < 5) continue;
+    const hash = fields[0].trim();
+    const authorDate = fields[1].trim();
+    const committerDate = fields[2].trim();
+    const subject = fields[3].trim();
+    const fullBody = fields[4].trim();
+    if (subject.startsWith('guard: auto-backup') || subject.startsWith('guard: snapshot')) {
+      guardCommits.push({ hash, authorDate, committerDate, subject, fullBody });
+    }
+  }
+
+  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' };
+  }
+  const msgOf = (c) => c.fullBody || c.subject;
+  let prevHash = commitTreeWithDate(['commit-tree', rootTree, '-m', msgOf(toKeep[0])], 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', msgOf(toKeep[i])], 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 };
+}
+
+// ── Get backup file details ─────────────────────────────────────
+
+/**
+ * Get structured file-level changes for a specific git backup commit.
+ * Runs diff-tree --numstat + --name-status against parent (or ls-tree for root).
+ *
+ * @param {string} projectDir
+ * @param {string} commitHash - Full or short commit hash
+ * @returns {{ files: Array<{path: string, action: string, added: number, deleted: number}>, error?: string }}
+ */
+function getBackupFiles(projectDir, commitHash) {
+  if (!isGitRepo(projectDir)) {
+    return { files: [], error: 'not a git repository' };
+  }
+
+  const resolved = git(['rev-parse', '--verify', commitHash], { cwd: projectDir, allowFail: true });
+  if (!resolved) {
+    return { files: [], error: `cannot resolve commit: ${commitHash}` };
+  }
+
+  const parentCheck = git(['rev-parse', '--verify', `${resolved}^`], { cwd: projectDir, allowFail: true });
+
+  if (!parentCheck) {
+    const lsOut = git(['ls-tree', '--name-only', '-r', resolved], { cwd: projectDir, allowFail: true });
+    if (!lsOut) return { files: [] };
+    return {
+      files: lsOut.split('\n').filter(Boolean).map(f => ({ path: f, action: 'added', added: 0, deleted: 0 })),
+    };
+  }
+
+  const nameStatusOut = git(['diff-tree', '--no-commit-id', '--name-status', '-r', `${resolved}^`, resolved], { cwd: projectDir, allowFail: true });
+  const numstatOut = git(['diff-tree', '--no-commit-id', '--numstat', '-r', `${resolved}^`, resolved], { cwd: projectDir, allowFail: true });
+
+  const stats = {};
+  if (numstatOut) {
+    for (const line of numstatOut.split('\n').filter(Boolean)) {
+      const [add, del, ...nameParts] = line.split('\t');
+      const fname = nameParts.join('\t');
+      stats[fname] = { added: add === '-' ? 0 : parseInt(add, 10), deleted: del === '-' ? 0 : parseInt(del, 10) };
+    }
+  }
+
+  const ACTION_MAP = { M: 'modified', A: 'added', D: 'deleted' };
+  const files = [];
+  if (nameStatusOut) {
+    for (const line of nameStatusOut.split('\n').filter(Boolean)) {
+      const tab = line.indexOf('\t');
+      if (tab < 0) continue;
+      const code = line.substring(0, tab).trim();
+      const filePart = line.substring(tab + 1);
+      const action = code.startsWith('R') ? 'renamed' : (ACTION_MAP[code] || 'modified');
+      const fileName = filePart.split('\t').pop();
+      const s = stats[fileName] || { added: 0, deleted: 0 };
+      files.push({ path: fileName, action, added: s.added, deleted: s.deleted });
+    }
+  }
+
+  files.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
+  return { files };
+}
+
+module.exports = { listBackups, getBackupFiles, cleanShadowRetention, cleanGitRetention, parseShadowTimestamp };