cursor-guard 1.3.2 → 2.0.2

package/references/lib/guard-doctor.js

@@ -0,0 +1,233 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  color, loadConfig, gitAvailable, git, isGitRepo, gitDir, gitVersion,
+  walkDir, matchesAny, diskFreeGB,
+} = require('./utils');
+
+function runDoctor(projectDir) {
+  let pass = 0, warn = 0, fail = 0;
+
+  function check(name, status, detail) {
+    const tag = `[${status}]`;
+    const line = detail ? `  ${tag} ${name} — ${detail}` : `  ${tag} ${name}`;
+    switch (status) {
+      case 'PASS': pass++; console.log(color.green(line)); break;
+      case 'WARN': warn++; console.log(color.yellow(line)); break;
+      case 'FAIL': fail++; console.log(color.red(line)); break;
+      default: console.log(line);
+    }
+  }
+
+  console.log('');
+  console.log(color.cyan('=== Cursor Guard Doctor ==='));
+  console.log(color.cyan(`  Target: ${projectDir}`));
+  console.log('');
+
+  // 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 branch
+  if (repo) {
+    const branchRef = 'refs/heads/cursor-guard/auto-backup';
+    const exists = git(['rev-parse', '--verify', branchRef], { cwd: projectDir, allowFail: true });
+    if (exists) {
+      const count = git(['rev-list', '--count', branchRef], { cwd: projectDir, allowFail: true }) || '?';
+      check('Backup branch', 'PASS', `cursor-guard/auto-backup exists (${count} commits)`);
+    } else {
+      check('Backup branch', 'WARN', 'cursor-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`);
+  }
+
+  // Summary
+  console.log('');
+  console.log(color.cyan('=== Summary ==='));
+  const summaryColor = fail > 0 ? 'red' : warn > 0 ? 'yellow' : 'green';
+  console.log(color[summaryColor](`  PASS: ${pass}  |  WARN: ${warn}  |  FAIL: ${fail}`));
+  console.log('');
+  if (fail > 0) {
+    console.log(color.red('  Fix FAIL items before relying on Cursor Guard.'));
+  } else if (warn > 0) {
+    console.log(color.yellow('  Review WARN items to ensure everything works as expected.'));
+  } else {
+    console.log(color.green('  All checks passed. Cursor Guard is ready.'));
+  }
+  console.log('');
+
+  return fail > 0 ? 1 : 0;
+}
+
+module.exports = { runDoctor };

package/references/lib/utils.js

@@ -0,0 +1,325 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// ── ANSI colors ──────────────────────────────────────────────────
+
+const color = {
+  red:     s => `\x1b[31m${s}\x1b[0m`,
+  green:   s => `\x1b[32m${s}\x1b[0m`,
+  yellow:  s => `\x1b[33m${s}\x1b[0m`,
+  cyan:    s => `\x1b[36m${s}\x1b[0m`,
+  gray:    s => `\x1b[90m${s}\x1b[0m`,
+  reset:   '\x1b[0m',
+};
+
+// ── Glob matching (minimatch subset, zero deps) ─────────────────
+
+/**
+ * Match a relative path against a glob pattern.
+ * Supports: *, **, ? — enough for .cursor-guard.json patterns.
+ */
+function globMatch(pattern, relPath) {
+  const p = pattern.replace(/\\/g, '/');
+  const r = relPath.replace(/\\/g, '/');
+  const re = '^' + p
+    .replace(/[.+^${}()|[\]]/g, '\\$&')  // escape regex specials (except * and ?)
+    .replace(/\*\*/g, '\0')               // placeholder for **
+    .replace(/\*/g, '[^/]*')              // * = anything except /
+    .replace(/\?/g, '[^/]')              // ? = single char except /
+    .replace(/\0/g, '.*')                // ** = anything including /
+    + '$';
+  return new RegExp(re).test(r);
+}
+
+/**
+ * Check if a relative file path matches any pattern in a list.
+ * Also checks leaf filename for patterns like "*.log".
+ */
+function matchesAny(patterns, relPath) {
+  const leaf = path.basename(relPath);
+  for (const pat of patterns) {
+    if (globMatch(pat, relPath) || globMatch(pat, leaf)) return true;
+  }
+  return false;
+}
+
+// ── File traversal (recursive, no external deps) ────────────────
+
+const ALWAYS_SKIP = /[/\\](\.git|\.cursor-guard-backup|node_modules)[/\\]/;
+
+function walkDir(dir, rootDir) {
+  const results = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return results; }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    const rel = path.relative(rootDir, full).replace(/\\/g, '/');
+    if (ALWAYS_SKIP.test('/' + rel + '/')) continue;
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      results.push(...walkDir(full, rootDir));
+    } else if (entry.isFile()) {
+      results.push({ full, rel, name: entry.name });
+    }
+  }
+  return results;
+}
+
+// ── Config loading ──────────────────────────────────────────────
+
+const DEFAULT_SECRETS = ['.env', '.env.*', '*.key', '*.pem', '*.p12', '*.pfx', 'credentials*'];
+
+const DEFAULT_CONFIG = {
+  protect: [],
+  ignore: [],
+  secrets_patterns: DEFAULT_SECRETS,
+  backup_strategy: 'git',
+  auto_backup_interval_seconds: 60,
+  pre_restore_backup: 'always',
+  retention: { mode: 'days', days: 30, max_count: 100, max_size_mb: 500 },
+  git_retention: { enabled: false, mode: 'count', days: 30, max_count: 200 },
+};
+
+function loadConfig(projectDir) {
+  const cfgPath = path.join(projectDir, '.cursor-guard.json');
+  const cfg = { ...DEFAULT_CONFIG };
+  cfg.retention = { ...DEFAULT_CONFIG.retention };
+  cfg.git_retention = { ...DEFAULT_CONFIG.git_retention };
+
+  if (!fs.existsSync(cfgPath)) return { cfg, loaded: false, error: null };
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    if (Array.isArray(raw.protect))          cfg.protect = raw.protect;
+    if (Array.isArray(raw.ignore))           cfg.ignore = raw.ignore;
+    if (Array.isArray(raw.secrets_patterns)) cfg.secrets_patterns = raw.secrets_patterns;
+    if (Array.isArray(raw.secrets_patterns_extra)) {
+      const merged = [...new Set([...cfg.secrets_patterns, ...raw.secrets_patterns_extra])];
+      cfg.secrets_patterns = merged;
+    }
+    if (typeof raw.backup_strategy === 'string')          cfg.backup_strategy = raw.backup_strategy;
+    if (typeof raw.auto_backup_interval_seconds === 'number') cfg.auto_backup_interval_seconds = raw.auto_backup_interval_seconds;
+    if (typeof raw.pre_restore_backup === 'string')       cfg.pre_restore_backup = raw.pre_restore_backup;
+    if (raw.retention) {
+      if (raw.retention.mode)        cfg.retention.mode = raw.retention.mode;
+      if (raw.retention.days)        cfg.retention.days = raw.retention.days;
+      if (raw.retention.max_count)   cfg.retention.max_count = raw.retention.max_count;
+      if (raw.retention.max_size_mb) cfg.retention.max_size_mb = raw.retention.max_size_mb;
+    }
+    if (raw.git_retention) {
+      if (raw.git_retention.enabled === true)  cfg.git_retention.enabled = true;
+      if (raw.git_retention.mode)              cfg.git_retention.mode = raw.git_retention.mode;
+      if (raw.git_retention.days)              cfg.git_retention.days = raw.git_retention.days;
+      if (raw.git_retention.max_count)         cfg.git_retention.max_count = raw.git_retention.max_count;
+    }
+    return { cfg, loaded: true, error: null };
+  } catch (e) {
+    return { cfg, loaded: false, error: e.message };
+  }
+}
+
+// ── Git helpers ─────────────────────────────────────────────────
+
+function gitAvailable() {
+  try {
+    execFileSync('git', ['--version'], { stdio: 'pipe' });
+    return true;
+  } catch { return false; }
+}
+
+function git(args, opts = {}) {
+  const options = {
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    ...opts,
+  };
+  try {
+    return execFileSync('git', args, options).trim();
+  } catch (e) {
+    if (opts.allowFail) return null;
+    throw e;
+  }
+}
+
+function isGitRepo(cwd) {
+  try {
+    const result = execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd, stdio: 'pipe', encoding: 'utf-8',
+    }).trim();
+    return result === 'true';
+  } catch { return false; }
+}
+
+function gitDir(cwd) {
+  try {
+    const dir = execFileSync('git', ['rev-parse', '--git-dir'], {
+      cwd, stdio: 'pipe', encoding: 'utf-8',
+    }).trim();
+    return path.resolve(cwd, dir);
+  } catch { return null; }
+}
+
+function gitVersion() {
+  try {
+    return execFileSync('git', ['--version'], { stdio: 'pipe', encoding: 'utf-8' })
+      .trim().replace('git version ', '');
+  } catch { return null; }
+}
+
+// ── Manifest (for shadow-mode change detection) ─────────────────
+
+function buildManifest(files) {
+  const manifest = {};
+  for (const f of files) {
+    try {
+      const st = fs.statSync(f.full);
+      manifest[f.rel] = { mtimeMs: st.mtimeMs, size: st.size };
+    } catch { /* skip unreadable files */ }
+  }
+  return manifest;
+}
+
+function manifestPath(backupDir) {
+  return path.join(backupDir, '.manifest.json');
+}
+
+function loadManifest(backupDir) {
+  const p = manifestPath(backupDir);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); }
+  catch { return null; }
+}
+
+function saveManifest(backupDir, manifest) {
+  fs.writeFileSync(manifestPath(backupDir), JSON.stringify(manifest, null, 2));
+}
+
+function manifestChanged(oldM, newM) {
+  if (!oldM) return true;
+  const oldKeys = Object.keys(oldM);
+  const newKeys = Object.keys(newM);
+  if (oldKeys.length !== newKeys.length) return true;
+  for (const k of newKeys) {
+    if (!oldM[k]) return true;
+    if (oldM[k].mtimeMs !== newM[k].mtimeMs || oldM[k].size !== newM[k].size) return true;
+  }
+  return false;
+}
+
+// ── Disk space (cross-platform) ─────────────────────────────────
+
+function diskFreeGB(dir) {
+  try {
+    if (process.platform === 'win32') {
+      const drive = path.parse(dir).root.replace(/\\$/, '');
+      // Try PowerShell first (works on all modern Windows)
+      try {
+        const out = execFileSync('powershell', [
+          '-NoProfile', '-Command',
+          `(Get-PSDrive ${drive[0]}).Free`,
+        ], { stdio: 'pipe', encoding: 'utf-8' });
+        const bytes = parseInt(out.trim(), 10);
+        if (!isNaN(bytes)) return bytes / (1024 ** 3);
+      } catch { /* fall through */ }
+      // Fallback to wmic
+      try {
+        const out = execFileSync('wmic', [
+          'logicaldisk', 'where', `DeviceID="${drive}"`, 'get', 'FreeSpace', '/value',
+        ], { stdio: 'pipe', encoding: 'utf-8' });
+        const m = out.match(/FreeSpace=(\d+)/);
+        return m ? parseFloat(m[1]) / (1024 ** 3) : null;
+      } catch { return null; }
+    }
+    const out = execFileSync('df', ['-k', dir], { stdio: 'pipe', encoding: 'utf-8' });
+    const lines = out.trim().split('\n');
+    if (lines.length < 2) return null;
+    const parts = lines[1].split(/\s+/);
+    const availKB = parseInt(parts[3], 10);
+    return isNaN(availKB) ? null : availKB / (1024 * 1024);
+  } catch { return null; }
+}
+
+// ── Logging ─────────────────────────────────────────────────────
+
+function timestamp() {
+  return new Date().toISOString().replace('T', ' ').substring(0, 19);
+}
+
+function createLogger(logFilePath) {
+  return {
+    log(msg, c = 'green') {
+      const line = `${timestamp()}  ${msg}`;
+      try { fs.appendFileSync(logFilePath, line + '\n'); } catch { /* ignore */ }
+      console.log(color[c] ? color[c](`[guard] ${line}`) : `[guard] ${line}`);
+    },
+    info(msg) { this.log(msg, 'cyan'); },
+    warn(msg) { this.log(msg, 'yellow'); },
+    error(msg) { this.log(msg, 'red'); },
+  };
+}
+
+// ── CLI arg parsing (zero deps) ─────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    }
+  }
+  return args;
+}
+
+// ── Filter files by config ──────────────────────────────────────
+
+function filterFiles(files, cfg) {
+  let result = files;
+  if (cfg.protect.length > 0) {
+    result = result.filter(f => matchesAny(cfg.protect, f.rel));
+  }
+  result = result.filter(f => {
+    if (cfg.ignore.length > 0 && matchesAny(cfg.ignore, f.rel)) return false;
+    if (matchesAny(cfg.secrets_patterns, f.rel)) return false;
+    return true;
+  });
+  return result;
+}
+
+// ── Exports ─────────────────────────────────────────────────────
+
+module.exports = {
+  color,
+  globMatch,
+  matchesAny,
+  walkDir,
+  loadConfig,
+  DEFAULT_CONFIG,
+  DEFAULT_SECRETS,
+  gitAvailable,
+  git,
+  isGitRepo,
+  gitDir,
+  gitVersion,
+  buildManifest,
+  manifestPath,
+  loadManifest,
+  saveManifest,
+  manifestChanged,
+  diskFreeGB,
+  timestamp,
+  createLogger,
+  parseArgs,
+  filterFiles,
+};