cursor-guard 2.1.1 → 3.1.0

package/references/lib/core/doctor-fix.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  loadConfig, gitAvailable, git, isGitRepo, gitDir,
+} = require('../utils');
+
+/**
+ * Auto-fix common configuration and environment issues detected by doctor.
+ *
+ * Each fix is idempotent — running it when nothing is wrong is a no-op.
+ * Returns a list of actions taken (or skipped).
+ *
+ * @param {string} projectDir
+ * @param {object} [opts]
+ * @param {boolean} [opts.dryRun=false] - If true, report what would be fixed without modifying anything.
+ * @returns {{ actions: Array<{name: string, status: 'fixed'|'skipped'|'error', detail: string}>, totalFixed: number }}
+ */
+function runFixes(projectDir, opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const actions = [];
+  let totalFixed = 0;
+
+  function action(name, status, detail) {
+    actions.push({ name, status, detail });
+    if (status === 'fixed') totalFixed++;
+  }
+
+  const hasGit = gitAvailable();
+  const repo = hasGit && isGitRepo(projectDir);
+
+  // Fix 1: Create .cursor-guard.json with defaults if missing
+  const configPath = path.join(projectDir, '.cursor-guard.json');
+  if (!fs.existsSync(configPath)) {
+    const examplePath = path.resolve(__dirname, '../../cursor-guard.example.json');
+    if (fs.existsSync(examplePath)) {
+      if (dryRun) {
+        action('Create config', 'skipped', 'would copy cursor-guard.example.json → .cursor-guard.json (dry-run)');
+      } else {
+        try {
+          fs.copyFileSync(examplePath, configPath);
+          action('Create config', 'fixed', 'copied cursor-guard.example.json → .cursor-guard.json');
+        } catch (e) {
+          action('Create config', 'error', e.message);
+        }
+      }
+    } else {
+      const defaultConfig = {
+        protect: [],
+        ignore: ["node_modules/**", "dist/**", "*.log"],
+        backup_strategy: "git",
+        auto_backup_interval_seconds: 60,
+        pre_restore_backup: "always",
+        retention: { mode: "days", days: 30 },
+      };
+      if (dryRun) {
+        action('Create config', 'skipped', 'would create .cursor-guard.json with defaults (dry-run)');
+      } else {
+        try {
+          fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n');
+          action('Create config', 'fixed', 'created .cursor-guard.json with defaults');
+        } catch (e) {
+          action('Create config', 'error', e.message);
+        }
+      }
+    }
+  } else {
+    action('Create config', 'skipped', '.cursor-guard.json already exists');
+  }
+
+  // Fix 2: Init git repo if missing
+  if (hasGit && !repo) {
+    if (dryRun) {
+      action('Init Git repo', 'skipped', 'would run git init (dry-run)');
+    } else {
+      try {
+        execFileSync('git', ['init'], { cwd: projectDir, stdio: 'pipe' });
+        // Ensure git commit works even without global user config
+        try { execFileSync('git', ['config', 'user.email'], { cwd: projectDir, stdio: 'pipe' }); }
+        catch { execFileSync('git', ['config', 'user.email', 'cursor-guard@local'], { cwd: projectDir, stdio: 'pipe' }); }
+        try { execFileSync('git', ['config', 'user.name'], { cwd: projectDir, stdio: 'pipe' }); }
+        catch { execFileSync('git', ['config', 'user.name', 'cursor-guard'], { cwd: projectDir, stdio: 'pipe' }); }
+        // Ensure .gitignore contains backup dir + secrets patterns BEFORE git add
+        const { cfg: initCfg } = loadConfig(projectDir);
+        const gitignorePath = path.join(projectDir, '.gitignore');
+        const existingIgnore = fs.existsSync(gitignorePath)
+          ? fs.readFileSync(gitignorePath, 'utf-8')
+          : '';
+        const missingPatterns = [];
+        if (!existingIgnore.includes('.cursor-guard-backup')) {
+          missingPatterns.push('# cursor-guard shadow copies', '.cursor-guard-backup/', '');
+        }
+        const missingSecrets = initCfg.secrets_patterns.filter(p => !existingIgnore.includes(p));
+        if (missingSecrets.length > 0) {
+          missingPatterns.push('# Secrets (cursor-guard defaults)', ...missingSecrets, '');
+        }
+        if (missingPatterns.length > 0) {
+          const separator = existingIgnore && !existingIgnore.endsWith('\n') ? '\n' : '';
+          const block = separator + missingPatterns.join('\n');
+          if (existingIgnore) {
+            fs.appendFileSync(gitignorePath, block);
+          } else {
+            fs.writeFileSync(gitignorePath, block);
+          }
+        }
+        execFileSync('git', ['add', '-A'], { cwd: projectDir, stdio: 'pipe' });
+        execFileSync('git', ['commit', '-m', 'guard: initial snapshot', '--no-verify', '--allow-empty'], {
+          cwd: projectDir, stdio: 'pipe',
+        });
+        action('Init Git repo', 'fixed', 'initialized git repo with .gitignore and initial commit');
+      } catch (e) {
+        action('Init Git repo', 'error', e.message);
+      }
+    }
+  } else if (repo) {
+    action('Init Git repo', 'skipped', 'already a git repo');
+  } else {
+    action('Init Git repo', 'skipped', 'git not available');
+  }
+
+  // Fix 3: Add .cursor-guard-backup/ to .gitignore
+  const effectiveRepo = hasGit && isGitRepo(projectDir);
+  if (effectiveRepo) {
+    const ignored = git(['check-ignore', '.cursor-guard-backup/test'], { cwd: projectDir, allowFail: true });
+    if (!ignored) {
+      const gitignorePath = path.join(projectDir, '.gitignore');
+      const entry = '\n# cursor-guard shadow copies\n.cursor-guard-backup/\n';
+      if (dryRun) {
+        action('Gitignore backup dir', 'skipped', 'would add .cursor-guard-backup/ to .gitignore (dry-run)');
+      } else {
+        try {
+          if (fs.existsSync(gitignorePath)) {
+            const content = fs.readFileSync(gitignorePath, 'utf-8');
+            if (!content.includes('.cursor-guard-backup')) {
+              fs.appendFileSync(gitignorePath, entry);
+              action('Gitignore backup dir', 'fixed', 'appended .cursor-guard-backup/ to .gitignore');
+            } else {
+              action('Gitignore backup dir', 'skipped', 'entry exists but git check-ignore failed — may need manual fix');
+            }
+          } else {
+            fs.writeFileSync(gitignorePath, entry.trimStart());
+            action('Gitignore backup dir', 'fixed', 'created .gitignore with .cursor-guard-backup/ entry');
+          }
+        } catch (e) {
+          action('Gitignore backup dir', 'error', e.message);
+        }
+      }
+    } else {
+      action('Gitignore backup dir', 'skipped', '.cursor-guard-backup/ already git-ignored');
+    }
+  } else {
+    action('Gitignore backup dir', 'skipped', 'not a git repo');
+  }
+
+  // Fix 4: Create .cursor-guard-backup/ directory if shadow strategy
+  const { cfg } = loadConfig(projectDir);
+  if (cfg.backup_strategy === 'shadow' || cfg.backup_strategy === 'both') {
+    const backupDir = path.join(projectDir, '.cursor-guard-backup');
+    if (!fs.existsSync(backupDir)) {
+      if (dryRun) {
+        action('Create backup dir', 'skipped', 'would create .cursor-guard-backup/ (dry-run)');
+      } else {
+        try {
+          fs.mkdirSync(backupDir, { recursive: true });
+          action('Create backup dir', 'fixed', 'created .cursor-guard-backup/');
+        } catch (e) {
+          action('Create backup dir', 'error', e.message);
+        }
+      }
+    } else {
+      action('Create backup dir', 'skipped', '.cursor-guard-backup/ already exists');
+    }
+  }
+
+  // Fix 5: Remove stale lock file
+  const gDir = effectiveRepo ? gitDir(projectDir) : null;
+  const lockFile = gDir
+    ? path.join(gDir, 'cursor-guard.lock')
+    : path.join(projectDir, '.cursor-guard-backup', 'cursor-guard.lock');
+  if (fs.existsSync(lockFile)) {
+    let stale = false;
+    try {
+      const content = fs.readFileSync(lockFile, 'utf-8').trim();
+      const pidMatch = content.match(/pid[:\s]+(\d+)/i);
+      if (pidMatch) {
+        const pid = parseInt(pidMatch[1], 10);
+        try { process.kill(pid, 0); } catch { stale = true; }
+      } else {
+        const stat = fs.statSync(lockFile);
+        if (Date.now() - stat.mtimeMs > 300000) stale = true;
+      }
+    } catch {
+      stale = true;
+    }
+
+    if (stale) {
+      if (dryRun) {
+        action('Remove stale lock', 'skipped', 'would remove stale cursor-guard.lock (dry-run)');
+      } else {
+        try {
+          fs.unlinkSync(lockFile);
+          action('Remove stale lock', 'fixed', 'removed stale cursor-guard.lock');
+        } catch (e) {
+          action('Remove stale lock', 'error', e.message);
+        }
+      }
+    } else {
+      action('Remove stale lock', 'skipped', 'lock file is active — another instance is running');
+    }
+  }
+
+  // Fix 6: Fix config strategy mismatch — if strategy is git/both but no repo
+  // (Already handled by Fix 2 above — this reports if the combo is still wrong)
+  const { cfg: freshCfg } = loadConfig(projectDir);
+  const freshRepo = hasGit && isGitRepo(projectDir);
+  if ((freshCfg.backup_strategy === 'git' || freshCfg.backup_strategy === 'both') && !freshRepo) {
+    if (dryRun) {
+      action('Fix strategy mismatch', 'skipped', "would switch backup_strategy to 'shadow' since no git repo (dry-run)");
+    } else {
+      try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        parsed.backup_strategy = 'shadow';
+        fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2) + '\n');
+        action('Fix strategy mismatch', 'fixed', "changed backup_strategy to 'shadow' (no git repo available)");
+      } catch (e) {
+        action('Fix strategy mismatch', 'error', e.message);
+      }
+    }
+  }
+
+  return { actions, totalFixed };
+}
+
+module.exports = { runFixes };

package/references/lib/core/doctor.js

@@ -0,0 +1,248 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  loadConfig, gitAvailable, git, isGitRepo, gitDir, gitVersion,
+  walkDir, matchesAny, diskFreeGB,
+} = require('../utils');
+
+/**
+ * Run all diagnostic checks for a project directory.
+ *
+ * @param {string} projectDir - Absolute path to the project root.
+ * @returns {{ checks: Array<{name: string, status: 'PASS'|'WARN'|'FAIL', detail?: string}>, summary: {pass: number, warn: number, fail: number} }}
+ */
+function runDiagnostics(projectDir) {
+  const checks = [];
+
+  function check(name, status, detail) {
+    checks.push({ name, status, detail: detail || null });
+  }
+
+  // 1. Git availability
+  const hasGit = gitAvailable();
+  if (hasGit) {
+    check('Git installed', 'PASS', `version ${gitVersion()}`);
+  } else {
+    check('Git installed', 'WARN', 'git not found in PATH; only shadow strategy available');
+  }
+
+  // 2. Git repo status
+  let repo = false;
+  let gDir = null;
+  let isWorktree = false;
+  if (hasGit) {
+    repo = isGitRepo(projectDir);
+    if (repo) {
+      gDir = gitDir(projectDir);
+      try {
+        const commonDir = git(['rev-parse', '--git-common-dir'], { cwd: projectDir, allowFail: true });
+        const currentDir = git(['rev-parse', '--git-dir'], { cwd: projectDir, allowFail: true });
+        isWorktree = commonDir && currentDir && commonDir !== currentDir;
+      } catch { /* ignore */ }
+      if (isWorktree) {
+        check('Git repository', 'PASS', `worktree detected (git-dir: ${gDir})`);
+      } else {
+        check('Git repository', 'PASS', 'standard repo');
+      }
+    } else {
+      check('Git repository', 'WARN', 'not a Git repo; git/both strategies won\'t work');
+    }
+  }
+
+  // 3. Config file
+  const { cfg, loaded, error } = loadConfig(projectDir);
+  if (loaded) {
+    check('Config file', 'PASS', '.cursor-guard.json found and valid JSON');
+  } else if (error) {
+    check('Config file', 'FAIL', `JSON parse error: ${error}`);
+  } else {
+    check('Config file', 'WARN', 'no .cursor-guard.json found; using defaults (protect everything)');
+  }
+
+  // 4. Strategy vs environment
+  const strategy = cfg.backup_strategy;
+  if (strategy === 'git' || strategy === 'both') {
+    if (!repo) {
+      check('Strategy compatibility', 'FAIL', `backup_strategy='${strategy}' but directory is not a Git repo`);
+    } else {
+      check('Strategy compatibility', 'PASS', `backup_strategy='${strategy}' and Git repo exists`);
+    }
+  } else if (strategy === 'shadow') {
+    check('Strategy compatibility', 'PASS', "backup_strategy='shadow' — no Git required");
+  } else {
+    check('Strategy compatibility', 'FAIL', `unknown backup_strategy='${strategy}' (must be git/shadow/both)`);
+  }
+
+  // 5. Backup ref
+  if (repo) {
+    const guardRef = 'refs/guard/auto-backup';
+    const legacyRef = 'refs/heads/cursor-guard/auto-backup';
+    const exists = git(['rev-parse', '--verify', guardRef], { cwd: projectDir, allowFail: true });
+    const legacyExists = git(['rev-parse', '--verify', legacyRef], { cwd: projectDir, allowFail: true });
+    if (exists) {
+      const count = git(['rev-list', '--count', guardRef], { cwd: projectDir, allowFail: true }) || '?';
+      check('Backup ref', 'PASS', `refs/guard/auto-backup exists (${count} commits)`);
+    } else if (legacyExists) {
+      const count = git(['rev-list', '--count', legacyRef], { cwd: projectDir, allowFail: true }) || '?';
+      check('Backup ref', 'WARN', `legacy refs/heads/cursor-guard/auto-backup found (${count} commits) — run auto-backup once to migrate`);
+    } else {
+      check('Backup ref', 'WARN', 'refs/guard/auto-backup not created yet (will be created on first backup)');
+    }
+  }
+
+  // 6. Guard refs
+  if (repo) {
+    const refs = git(['for-each-ref', 'refs/guard/', '--format=%(refname)'], { cwd: projectDir, allowFail: true });
+    if (refs) {
+      const refList = refs.split('\n').filter(Boolean);
+      const preRestoreCount = refList.filter(r => r.includes('pre-restore/')).length;
+      check('Guard refs', 'PASS', `${refList.length} ref(s) found (${preRestoreCount} pre-restore snapshots)`);
+    } else {
+      check('Guard refs', 'WARN', 'no guard refs yet (created on first snapshot or restore)');
+    }
+  }
+
+  // 7. Shadow copy directory
+  const backupDir = path.join(projectDir, '.cursor-guard-backup');
+  if (fs.existsSync(backupDir)) {
+    let snapCount = 0;
+    let totalBytes = 0;
+    try {
+      const dirs = fs.readdirSync(backupDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && (/^\d{8}_\d{6}$/.test(d.name) || d.name.startsWith('pre-restore-')));
+      snapCount = dirs.length;
+    } catch { /* ignore */ }
+    try {
+      const allFiles = walkDir(backupDir, backupDir);
+      for (const f of allFiles) {
+        try { totalBytes += fs.statSync(f.full).size; } catch { /* skip */ }
+      }
+    } catch { /* ignore */ }
+    const totalMB = (totalBytes / (1024 * 1024)).toFixed(1);
+    check('Shadow copies', 'PASS', `${snapCount} snapshot(s), ${totalMB} MB total`);
+  } else {
+    check('Shadow copies', 'WARN', '.cursor-guard-backup/ not found (will be created on first shadow backup)');
+  }
+
+  // 8. .gitignore / exclude coverage
+  if (repo) {
+    const ignored = git(['check-ignore', '.cursor-guard-backup/test'], { cwd: projectDir, allowFail: true });
+    if (ignored) {
+      check('Backup dir ignored', 'PASS', '.cursor-guard-backup/ is git-ignored');
+    } else {
+      check('Backup dir ignored', 'WARN', '.cursor-guard-backup/ may NOT be git-ignored — backup changes could trigger commits');
+    }
+  }
+
+  // 9. Config field validation
+  if (loaded) {
+    const validStrategies = ['git', 'shadow', 'both'];
+    if (cfg.backup_strategy && !validStrategies.includes(cfg.backup_strategy)) {
+      check('Config: backup_strategy', 'FAIL', `invalid value '${cfg.backup_strategy}'`);
+    }
+    const validPreRestore = ['always', 'ask', 'never'];
+    if (cfg.pre_restore_backup && !validPreRestore.includes(cfg.pre_restore_backup)) {
+      check('Config: pre_restore_backup', 'FAIL', `invalid value '${cfg.pre_restore_backup}'`);
+    } else if (cfg.pre_restore_backup === 'never') {
+      check('Config: pre_restore_backup', 'WARN', "set to 'never' — restores won't auto-preserve current version");
+    }
+    if (cfg.auto_backup_interval_seconds && cfg.auto_backup_interval_seconds < 5) {
+      check('Config: interval', 'WARN', `${cfg.auto_backup_interval_seconds}s is below minimum (5s), will be clamped`);
+    }
+    if (cfg.retention && cfg.retention.mode) {
+      const validModes = ['days', 'count', 'size'];
+      if (!validModes.includes(cfg.retention.mode)) {
+        check('Config: retention.mode', 'FAIL', `invalid value '${cfg.retention.mode}'`);
+      }
+    }
+    if (cfg.git_retention && cfg.git_retention.mode) {
+      const validGitModes = ['days', 'count'];
+      if (!validGitModes.includes(cfg.git_retention.mode)) {
+        check('Config: git_retention.mode', 'FAIL', `invalid value '${cfg.git_retention.mode}'`);
+      }
+    }
+  }
+
+  // 10. Protect / Ignore effectiveness
+  if (loaded && cfg.protect.length > 0) {
+    const allFiles = walkDir(projectDir, projectDir);
+    let protectedCount = 0;
+    for (const f of allFiles) {
+      if (matchesAny(cfg.protect, f.rel)) protectedCount++;
+    }
+    check('Protect patterns', 'PASS', `${protectedCount} / ${allFiles.length} files matched by protect patterns`);
+  }
+
+  // 11. Disk space
+  const freeGB = diskFreeGB(projectDir);
+  if (freeGB !== null) {
+    const rounded = freeGB.toFixed(1);
+    if (freeGB < 1) {
+      check('Disk space', 'FAIL', `${rounded} GB free — critically low`);
+    } else if (freeGB < 5) {
+      check('Disk space', 'WARN', `${rounded} GB free`);
+    } else {
+      check('Disk space', 'PASS', `${rounded} GB free`);
+    }
+  } else {
+    check('Disk space', 'WARN', 'could not determine free space');
+  }
+
+  // 12. Lock file
+  const lockFile = gDir
+    ? path.join(gDir, 'cursor-guard.lock')
+    : path.join(backupDir, 'cursor-guard.lock');
+  if (fs.existsSync(lockFile)) {
+    let content = '';
+    try { content = fs.readFileSync(lockFile, 'utf-8').trim(); } catch { /* ignore */ }
+    check('Lock file', 'WARN', `lock file exists — another instance may be running. ${content}`);
+  } else {
+    check('Lock file', 'PASS', 'no lock file (no running instance)');
+  }
+
+  // 13. Node.js version
+  const nodeVer = process.version;
+  const major = parseInt(nodeVer.slice(1), 10);
+  if (major >= 18) {
+    check('Node.js', 'PASS', `${nodeVer}`);
+  } else {
+    check('Node.js', 'WARN', `${nodeVer} — recommended >=18`);
+  }
+
+  // 14. MCP server status
+  const mcpServerPath = path.resolve(__dirname, '../../mcp/server.js');
+  const mcpServerExists = fs.existsSync(mcpServerPath);
+
+  let mcpSdkAvailable = false;
+  let mcpSdkVersion = null;
+  try {
+    const mcpPkgPath = require.resolve('@modelcontextprotocol/sdk/package.json');
+    const mcpPkg = JSON.parse(fs.readFileSync(mcpPkgPath, 'utf-8'));
+    mcpSdkAvailable = true;
+    mcpSdkVersion = mcpPkg.version;
+  } catch { /* not installed */ }
+
+  if (mcpServerExists && mcpSdkAvailable) {
+    check('MCP server', 'PASS', `server.js found, SDK ${mcpSdkVersion}`);
+  } else if (mcpServerExists && !mcpSdkAvailable) {
+    check('MCP server', 'WARN', 'server.js found but @modelcontextprotocol/sdk not installed — run npm install');
+  } else if (!mcpServerExists && mcpSdkAvailable) {
+    check('MCP server', 'WARN', `SDK installed (${mcpSdkVersion}) but server.js not found at expected path`);
+  } else {
+    check('MCP server', 'WARN', 'MCP not configured (optional — cursor-guard works without it)');
+  }
+
+  // Build summary
+  let pass = 0, warn = 0, fail = 0;
+  for (const c of checks) {
+    if (c.status === 'PASS') pass++;
+    else if (c.status === 'WARN') warn++;
+    else if (c.status === 'FAIL') fail++;
+  }
+
+  return { checks, summary: { pass, warn, fail } };
+}
+
+module.exports = { runDiagnostics };