cursor-guard 4.7.3 → 4.7.6

package/references/vscode-extension/dist/lib/auto-backup.js

@@ -0,0 +1,323 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  color, loadConfig, gitAvailable, git, isGitRepo, gitDir: getGitDir,
+  walkDir, filterFiles, buildManifest, loadManifest, saveManifest,
+  manifestChanged, createLogger,
+} = require('./utils');
+const { createGitSnapshot, createShadowCopy } = require('./core/snapshot');
+const { cleanShadowRetention, cleanGitRetention } = require('./core/backups');
+const { createChangeTracker, recordChange, checkAnomaly, saveAlert, clearExpiredAlert } = require('./core/anomaly');
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function isProcessAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
+// ── Main ────────────────────────────────────────────────────────
+
+async function runBackup(projectDir, intervalOverride, opts = {}) {
+  const hasGit = gitAvailable();
+  const repo = hasGit && isGitRepo(projectDir);
+  const gDir = repo ? getGitDir(projectDir) : null;
+
+  const backupDir = path.join(projectDir, '.cursor-guard-backup');
+  const logFilePath = path.join(backupDir, 'backup.log');
+  const lockFile = gDir
+    ? path.join(gDir, 'cursor-guard.lock')
+    : path.join(backupDir, 'cursor-guard.lock');
+
+  // Load config
+  let { cfg, loaded, error, warnings } = loadConfig(projectDir);
+  let interval = intervalOverride || cfg.auto_backup_interval_seconds || 60;
+  if (interval < 5) interval = 5;
+  let cfgMtime = 0;
+  const cfgPath = path.join(projectDir, '.cursor-guard.json');
+  try { cfgMtime = fs.statSync(cfgPath).mtimeMs; } catch { /* no config */ }
+
+  if (error) {
+    console.log(color.yellow(`[guard] WARNING: .cursor-guard.json parse error — using defaults. ${error}`));
+  } else if (loaded) {
+    console.log(color.cyan(`[guard] Config loaded  protect=${cfg.protect.length}  ignore=${cfg.ignore.length}  strategy=${cfg.backup_strategy}  git_retention=${cfg.git_retention.enabled ? 'on' : 'off'}`));
+    if (warnings && warnings.length > 0) {
+      for (const w of warnings) console.log(color.yellow(`[guard] WARNING: ${w}`));
+    }
+  }
+
+  // Strategy check
+  const needsGit = cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both';
+  if (needsGit && !repo) {
+    if (!hasGit) {
+      console.log(color.red(`[guard] ERROR: backup_strategy='${cfg.backup_strategy}' requires Git, but git is not installed.`));
+      console.log(color.yellow("  Either install Git or set backup_strategy to 'shadow' in .cursor-guard.json."));
+      process.exit(1);
+    }
+    console.log(color.red(`[guard] ERROR: backup_strategy='${cfg.backup_strategy}' but directory is not a Git repo.`));
+    console.log(color.yellow("  Run 'git init' first, or set backup_strategy to 'shadow'."));
+    process.exit(1);
+  }
+  if (!repo && cfg.backup_strategy === 'shadow') {
+    console.log(color.cyan('[guard] Non-Git directory detected. Running in shadow-only mode.'));
+  }
+
+  // Ensure backup dir
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  // Lock file with stale detection (PID + age)
+  const LOCK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+  if (fs.existsSync(lockFile)) {
+    let stale = false;
+    let reason = '';
+    try {
+      const content = fs.readFileSync(lockFile, 'utf-8');
+      const pidMatch = content.match(/pid=(\d+)/);
+      const startedMatch = content.match(/started=(.+)/);
+      const oldPid = pidMatch ? parseInt(pidMatch[1], 10) : null;
+      const startedAt = startedMatch ? Date.parse(startedMatch[1]) : NaN;
+
+      if (oldPid && !isProcessAlive(oldPid)) {
+        stale = true;
+        reason = `pid ${oldPid} not running`;
+      } else if (!isNaN(startedAt) && Date.now() - startedAt > LOCK_MAX_AGE_MS) {
+        stale = true;
+        reason = `lock age > 24h (started ${startedMatch[1]})`;
+      } else if (!oldPid) {
+        const stat = fs.statSync(lockFile);
+        if (Date.now() - stat.mtimeMs > LOCK_MAX_AGE_MS) {
+          stale = true;
+          reason = 'lock file too old (no PID, mtime > 24h)';
+        }
+      }
+    } catch { /* ignore */ }
+    if (stale) {
+      console.log(color.yellow(`[guard] Stale lock detected (${reason}). Cleaning up.`));
+      try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+    } else {
+      console.log(color.red(`[guard] ERROR: Lock file exists (${lockFile}).`));
+      console.log(color.red('  Another watcher instance may be running.'));
+      console.log(color.red('  If no other instance is running, delete the lock file and retry.'));
+      process.exit(1);
+    }
+  }
+  try {
+    fs.writeFileSync(lockFile, `pid=${process.pid}\nstarted=${new Date().toISOString()}`, { flag: 'wx' });
+  } catch (e) {
+    if (e.code === 'EEXIST') {
+      console.log(color.red('[guard] ERROR: Another instance just acquired the lock.'));
+      process.exit(1);
+    }
+    throw e;
+  }
+
+  // Cleanup on exit
+  const guardIndex = gDir ? path.join(gDir, 'cursor-guard-index') : null;
+  function cleanup() {
+    try { if (guardIndex) fs.unlinkSync(guardIndex); } catch { /* ignore */ }
+    try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+  }
+  process.on('SIGINT', () => { cleanup(); console.log(color.cyan('\n[guard] Stopped.')); process.exit(0); });
+  process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+  process.on('exit', cleanup);
+
+  // Git-specific setup
+  const branchRef = 'refs/guard/auto-backup';
+  const legacyRef = 'refs/heads/cursor-guard/auto-backup';
+  if (repo) {
+    const exists = git(['rev-parse', '--verify', branchRef], { cwd: projectDir, allowFail: true });
+    if (!exists) {
+      const legacyHash = git(['rev-parse', '--verify', legacyRef], { cwd: projectDir, allowFail: true });
+      if (legacyHash) {
+        git(['update-ref', branchRef, legacyHash], { cwd: projectDir, allowFail: true });
+        git(['update-ref', '-d', legacyRef], { cwd: projectDir, allowFail: true });
+        console.log(color.green(`[guard] Migrated ${legacyRef} → ${branchRef}`));
+      } else {
+        console.log(color.cyan(`[guard] Ref ${branchRef} does not exist yet — will be created on first snapshot.`));
+      }
+    }
+
+    const excludeFile = path.join(gDir, 'info', 'exclude');
+    fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
+    const entry = '.cursor-guard-backup/';
+    let content = '';
+    try { content = fs.readFileSync(excludeFile, 'utf-8'); } catch { /* doesn't exist yet */ }
+    if (!content.includes(entry)) {
+      fs.appendFileSync(excludeFile, `\n${entry}\n`);
+    }
+  }
+
+  const logger = createLogger(logFilePath);
+
+  // Global error handlers
+  process.on('uncaughtException', (err) => {
+    logger.error(`Uncaught exception: ${err.message}`);
+    cleanup();
+    process.exit(1);
+  });
+  process.on('unhandledRejection', (reason) => {
+    logger.error(`Unhandled rejection: ${reason}`);
+  });
+
+  // V4: Initialize change tracker for anomaly detection
+  let tracker = createChangeTracker(cfg);
+  if (cfg.proactive_alert) {
+    console.log(color.cyan(`[guard] Proactive alert: ON  (threshold: ${cfg.alert_thresholds.files_per_window} files / ${cfg.alert_thresholds.window_seconds}s)`));
+  }
+
+  // Banner
+  console.log('');
+  console.log(color.cyan(`[guard] Watching '${projectDir}' every ${interval}s  (Ctrl+C to stop)`));
+  console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
+  console.log(color.cyan(`[guard] Log: ${logFilePath}`));
+
+  // Optional embedded dashboard
+  if (opts.dashboardPort) {
+    try {
+      const { startDashboardServer } = require('../dashboard/server');
+      const { port } = await startDashboardServer([projectDir], { port: opts.dashboardPort, silent: true });
+      console.log(color.cyan(`[guard] Dashboard: http://127.0.0.1:${port}`));
+    } catch (e) {
+      console.log(color.yellow(`[guard] Dashboard failed to start: ${e.message}`));
+    }
+  }
+
+  console.log('');
+
+  // Main loop
+  let cycle = 0;
+  while (true) {
+    await sleep(interval * 1000);
+    cycle++;
+
+    // Hot-reload config every 10 cycles
+    if (cycle % 10 === 0) {
+      try {
+        const newMtime = fs.statSync(cfgPath).mtimeMs;
+        if (newMtime !== cfgMtime) {
+          const reload = loadConfig(projectDir);
+          if (reload.loaded && !reload.error) {
+            cfg = reload.cfg;
+            cfgMtime = newMtime;
+            tracker = createChangeTracker(cfg);
+            logger.info('Config reloaded (file changed)');
+          }
+        }
+      } catch { /* no config file or read error, keep current */ }
+    }
+
+    // Detect changes
+    let hasChanges = false;
+    let pendingManifest = null;
+    let lastManifest = null;
+    try {
+      if (repo) {
+        const dirty = git(['status', '--porcelain'], { cwd: projectDir, allowFail: true });
+        hasChanges = !!dirty;
+      } else {
+        const allFiles = walkDir(projectDir, projectDir);
+        const filtered = filterFiles(allFiles, cfg);
+        const newManifest = buildManifest(filtered);
+        lastManifest = loadManifest(backupDir);
+        hasChanges = manifestChanged(lastManifest, newManifest);
+        if (hasChanges) pendingManifest = newManifest;
+      }
+    } catch (e) {
+      logger.error(`Change detection failed: ${e.message}`);
+      continue;
+    }
+    if (!hasChanges) continue;
+
+    // Shadow: pre-compute changed file count from manifest diff (already accurate)
+    let changedFileCount = 0;
+    if (!repo && pendingManifest) {
+      if (!lastManifest) {
+        changedFileCount = Object.keys(pendingManifest).length;
+      } else {
+        const newKeys = new Set(Object.keys(pendingManifest));
+        const oldKeys = new Set(Object.keys(lastManifest));
+        let diffCount = 0;
+        for (const k of newKeys) {
+          if (!oldKeys.has(k) || lastManifest[k].mtimeMs !== pendingManifest[k].mtimeMs || lastManifest[k].size !== pendingManifest[k].size) diffCount++;
+        }
+        for (const k of oldKeys) {
+          if (!newKeys.has(k)) diffCount++;
+        }
+        changedFileCount = diffCount;
+      }
+    }
+
+    // Git snapshot via Core — changedFileCount comes from diff-tree (accurate incremental)
+    let changedFiles;
+    if ((cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both') && repo) {
+      const context = { trigger: 'auto' };
+      const snapResult = createGitSnapshot(projectDir, cfg, { branchRef, context });
+      if (snapResult.status === 'created') {
+        changedFileCount = snapResult.changedCount != null ? snapResult.changedCount : 0;
+        changedFiles = snapResult.changedFiles;
+        let msg = `Git snapshot ${snapResult.shortHash} (${snapResult.fileCount} files)`;
+        if (snapResult.secretsExcluded) {
+          msg += ` [secrets excluded: ${snapResult.secretsExcluded.join(', ')}]`;
+        }
+        logger.log(msg);
+      } else if (snapResult.status === 'skipped') {
+        console.log(color.gray(`[guard] ${new Date().toTimeString().slice(0,8)} tree unchanged, skipped.`));
+      } else if (snapResult.status === 'error') {
+        logger.error(`Git snapshot failed: ${snapResult.error}`);
+      }
+    }
+
+    // V4: Record change event and check for anomalies (after snapshot, using accurate count)
+    recordChange(tracker, changedFileCount, changedFiles);
+    const anomalyResult = checkAnomaly(tracker);
+    if (anomalyResult.anomaly && anomalyResult.alert && !anomalyResult.suppressed) {
+      saveAlert(projectDir, anomalyResult.alert);
+      logger.warn(`ALERT: ${anomalyResult.alert.fileCount} files changed in ${anomalyResult.alert.windowSeconds}s (threshold: ${anomalyResult.alert.threshold})`);
+    }
+
+    // Shadow copy via Core
+    if (cfg.backup_strategy === 'shadow' || cfg.backup_strategy === 'both') {
+      const shadowResult = createShadowCopy(projectDir, cfg, { backupDir });
+      if (shadowResult.status === 'created') {
+        const linkInfo = shadowResult.linkedCount ? ` [${shadowResult.linkedCount} hard-linked]` : '';
+        logger.log(`Shadow copy ${shadowResult.timestamp} (${shadowResult.fileCount} files${linkInfo})`);
+        if (pendingManifest) {
+          saveManifest(backupDir, pendingManifest);
+          pendingManifest = null;
+        }
+      } else if (shadowResult.status === 'error') {
+        logger.error(`Shadow copy failed: ${shadowResult.error}`);
+      }
+    }
+
+    // Periodic retention every 10 cycles via Core
+    if (cycle % 10 === 0) {
+      const retResult = cleanShadowRetention(backupDir, cfg);
+      if (retResult.removed > 0) {
+        logger.log(`Retention (${retResult.mode}): cleaned ${retResult.removed} old snapshot(s)`, 'gray');
+      }
+      if (retResult.diskWarning === 'critically low') {
+        logger.error(`WARNING: disk critically low — ${retResult.diskFreeGB} GB free`);
+      } else if (retResult.diskWarning === 'low') {
+        logger.warn(`Disk note: ${retResult.diskFreeGB} GB free`);
+      }
+
+      if (repo) {
+        const gitRetResult = cleanGitRetention(branchRef, gDir, cfg, projectDir);
+        if (gitRetResult.rebuilt) {
+          logger.log(`Git retention (${gitRetResult.mode}): rebuilt branch with ${gitRetResult.kept} newest snapshots, pruned ${gitRetResult.pruned}. Run 'git gc' to reclaim space.`, 'gray');
+        }
+      }
+
+      clearExpiredAlert(projectDir);
+    }
+  }
+}
+
+module.exports = { runBackup };

package/references/vscode-extension/dist/lib/auto-setup.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function detectIdeDir(vscode) {
+  const appName = (vscode.env.appName || '').toLowerCase();
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+
+  const ideDirs = [];
+
+  if (appName.includes('cursor')) {
+    ideDirs.push('.cursor');
+  } else if (appName.includes('windsurf')) {
+    ideDirs.push('.windsurf');
+  } else if (appName.includes('trae')) {
+    ideDirs.push('.trae');
+  }
+
+  ideDirs.push('.cursor', '.windsurf', '.vscode');
+
+  const seen = new Set();
+  for (const dir of ideDirs) {
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    const full = path.join(home, dir);
+    if (fs.existsSync(full)) return { dirName: dir, homePath: full };
+  }
+
+  return { dirName: ideDirs[0], homePath: path.join(home, ideDirs[0]) };
+}
+
+function getExtensionRoot(context) {
+  return context.extensionPath;
+}
+
+function findBundledSkill(extRoot) {
+  const skillDir = path.join(extRoot, 'skill');
+  if (fs.existsSync(path.join(skillDir, 'SKILL.md'))) return skillDir;
+  const fromRefs = path.resolve(extRoot, '..', '..', 'SKILL.md');
+  if (fs.existsSync(fromRefs)) return path.resolve(extRoot, '..', '..');
+  return null;
+}
+
+async function autoSetup(context, vscode) {
+  const extRoot = getExtensionRoot(context);
+  const { dirName, homePath } = detectIdeDir(vscode);
+  const workspaceFolders = vscode.workspace.workspaceFolders;
+  const wsRoot = workspaceFolders?.[0]?.uri.fsPath;
+
+  const actions = [];
+
+  try { actions.push(...autoInstallSkill(extRoot, homePath, dirName)); } catch { /* non-critical */ }
+  try { actions.push(...autoRegisterMcp(extRoot, homePath, wsRoot)); } catch { /* non-critical */ }
+  if (wsRoot) {
+    try { actions.push(...autoCreateConfig(extRoot, wsRoot)); } catch { /* non-critical */ }
+  }
+
+  if (actions.length > 0) {
+    vscode.window.showInformationMessage(`Cursor Guard: auto-setup complete — ${actions.join(', ')}`);
+  }
+}
+
+function autoInstallSkill(extRoot, homePath, dirName) {
+  const actions = [];
+  const skillSrc = findBundledSkill(extRoot);
+  if (!skillSrc) return actions;
+
+  const skillTarget = path.join(homePath, 'skills', 'cursor-guard');
+  const skillMdTarget = path.join(skillTarget, 'SKILL.md');
+
+  if (fs.existsSync(skillMdTarget)) return actions;
+
+  fs.mkdirSync(skillTarget, { recursive: true });
+
+  const skillMdSrc = path.join(skillSrc, 'SKILL.md');
+  if (fs.existsSync(skillMdSrc)) {
+    fs.copyFileSync(skillMdSrc, skillMdTarget);
+    actions.push('SKILL.md installed');
+  }
+
+  const roadmapSrc = path.join(skillSrc, 'ROADMAP.md');
+  if (fs.existsSync(roadmapSrc)) {
+    fs.copyFileSync(roadmapSrc, path.join(skillTarget, 'ROADMAP.md'));
+  }
+
+  const refsTarget = path.join(skillTarget, 'references');
+  fs.mkdirSync(refsTarget, { recursive: true });
+
+  const configRef = path.join(skillSrc, 'config-reference.md');
+  if (fs.existsSync(configRef)) fs.copyFileSync(configRef, path.join(refsTarget, 'config-reference.md'));
+  const configRefCn = path.join(skillSrc, 'config-reference.zh-CN.md');
+  if (fs.existsSync(configRefCn)) fs.copyFileSync(configRefCn, path.join(refsTarget, 'config-reference.zh-CN.md'));
+  const recoveryMd = path.join(skillSrc, 'recovery.md');
+  if (fs.existsSync(recoveryMd)) fs.copyFileSync(recoveryMd, path.join(refsTarget, 'recovery.md'));
+  const schemaSrc = path.join(skillSrc, 'cursor-guard.schema.json');
+  if (fs.existsSync(schemaSrc)) fs.copyFileSync(schemaSrc, path.join(refsTarget, 'cursor-guard.schema.json'));
+
+  return actions;
+}
+
+function autoRegisterMcp(extRoot, homePath, wsRoot) {
+  const actions = [];
+  const mcpServerPath = path.join(extRoot, 'mcp', 'server.js');
+  if (!fs.existsSync(mcpServerPath)) return actions;
+
+  const mcpJsonPaths = [
+    wsRoot ? path.join(wsRoot, '.cursor', 'mcp.json') : null,
+    wsRoot ? path.join(wsRoot, '.windsurf', 'mcp.json') : null,
+    path.join(homePath, 'mcp.json'),
+  ].filter(Boolean);
+
+  for (const mcpJsonPath of mcpJsonPaths) {
+    const dir = path.dirname(mcpJsonPath);
+    if (!fs.existsSync(dir)) continue;
+
+    let mcpConfig = { mcpServers: {} };
+    if (fs.existsSync(mcpJsonPath)) {
+      try { mcpConfig = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8')); } catch { continue; }
+    }
+
+    if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+    if (mcpConfig.mcpServers['cursor-guard']) return actions;
+
+    const vendorDir = path.join(extRoot, 'vendor');
+    const nmDir = path.join(extRoot, 'node_modules');
+    const nodePath = fs.existsSync(vendorDir) ? vendorDir : fs.existsSync(nmDir) ? nmDir : '';
+
+    const entry = {
+      command: 'node',
+      args: [mcpServerPath.replace(/\\/g, '/')],
+    };
+    if (nodePath) {
+      entry.env = { NODE_PATH: nodePath.replace(/\\/g, '/') };
+    }
+    mcpConfig.mcpServers['cursor-guard'] = entry;
+
+    fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2));
+    actions.push('MCP registered');
+    return actions;
+  }
+
+  return actions;
+}
+
+function autoCreateConfig(extRoot, wsRoot) {
+  const actions = [];
+  const configTarget = path.join(wsRoot, '.cursor-guard.json');
+  if (fs.existsSync(configTarget)) return actions;
+
+  const exampleSrc = path.join(extRoot, 'skill', 'cursor-guard.example.json');
+  const exampleFromRefs = path.join(extRoot, '..', 'cursor-guard.example.json');
+  const src = fs.existsSync(exampleSrc) ? exampleSrc : fs.existsSync(exampleFromRefs) ? exampleFromRefs : null;
+
+  if (src) {
+    fs.copyFileSync(src, configTarget);
+    actions.push('.cursor-guard.json created');
+  }
+
+  return actions;
+}
+
+module.exports = { autoSetup, detectIdeDir };