cursor-guard 2.1.0 → 3.0.0

package/references/lib/core/restore.js

@@ -0,0 +1,305 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  git, isGitRepo, gitDir: getGitDir, loadConfig,
+} = require('../utils');
+const { createGitSnapshot, formatTimestamp, removeSecretsFromIndex } = require('./snapshot');
+
+// ── Path safety ─────────────────────────────────────────────────
+
+function validateRelativePath(file) {
+  const normalized = path.normalize(file).replace(/\\/g, '/');
+  if (path.isAbsolute(normalized) || normalized.startsWith('..')) {
+    return { valid: false, error: 'file path must be relative and within project directory' };
+  }
+  return { valid: true, normalized };
+}
+
+const VALID_SHADOW_SOURCE = /^\d{8}_\d{6}$|^pre-restore-\d{8}_\d{6}$/;
+
+function validateShadowSource(source) {
+  if (!VALID_SHADOW_SOURCE.test(source)) {
+    return { valid: false };
+  }
+  return { valid: true };
+}
+
+/**
+ * Determine whether to create a pre-restore snapshot.
+ * Priority: explicit opts.preserveCurrent > config pre_restore_backup > default true.
+ */
+function resolvePreserve(projectDir, opts) {
+  if (typeof opts.preserveCurrent === 'boolean') return opts.preserveCurrent;
+  const { cfg } = loadConfig(projectDir);
+  if (cfg.pre_restore_backup === 'never') return false;
+  return true;
+}
+
+// ── Restore file ────────────────────────────────────────────────
+
+/**
+ * Restore a single file from a backup source.
+ *
+ * @param {string} projectDir
+ * @param {string} file - Relative path to the file
+ * @param {string} source - Commit hash, ref name, or shadow timestamp
+ * @param {object} [opts]
+ * @param {boolean} [opts.preserveCurrent=true] - Snapshot current state before restoring
+ * @returns {{ status: 'restored'|'error', preRestoreRef?: string, preRestoreShortHash?: string, restoredFrom: string, sourceType?: 'git'|'shadow', error?: string }}
+ */
+function restoreFile(projectDir, file, source, opts = {}) {
+  const pathCheck = validateRelativePath(file);
+  if (!pathCheck.valid) {
+    return { status: 'error', restoredFrom: source, error: pathCheck.error };
+  }
+
+  const preserveCurrent = resolvePreserve(projectDir, opts);
+  const repo = isGitRepo(projectDir);
+  const result = { restoredFrom: source };
+
+  // Determine source type — shadow source must be a valid timestamp directory name
+  const shadowCheck = validateShadowSource(source);
+  const shadowDir = shadowCheck.valid
+    ? path.join(projectDir, '.cursor-guard-backup', source, pathCheck.normalized)
+    : null;
+  const isShadowSource = shadowDir && fs.existsSync(shadowDir);
+
+  if (!isShadowSource && !repo) {
+    return { status: 'error', restoredFrom: source, error: 'not a git repo and source is not a shadow copy timestamp' };
+  }
+
+  // Pre-restore snapshot (git path)
+  if (preserveCurrent && repo) {
+    const preRestoreResult = createPreRestoreSnapshot(projectDir, file);
+    if (preRestoreResult.status === 'created') {
+      result.preRestoreRef = preRestoreResult.ref;
+      result.preRestoreShortHash = preRestoreResult.shortHash;
+    } else if (preRestoreResult.status === 'error') {
+      return { status: 'error', restoredFrom: source, error: `pre-restore snapshot failed: ${preRestoreResult.error}` };
+    }
+    // 'skipped' (no changes) is fine, proceed
+  }
+
+  // Pre-restore shadow copy (non-git path)
+  if (preserveCurrent && !repo) {
+    const targetFile = path.join(projectDir, file);
+    if (fs.existsSync(targetFile)) {
+      try {
+        const ts = formatTimestamp(new Date());
+        const preRestoreDir = path.join(projectDir, '.cursor-guard-backup', `pre-restore-${ts}`);
+        fs.mkdirSync(path.join(preRestoreDir, path.dirname(file)), { recursive: true });
+        fs.copyFileSync(targetFile, path.join(preRestoreDir, file));
+        result.preRestoreShadow = `pre-restore-${ts}`;
+      } catch (e) {
+        return { status: 'error', restoredFrom: source, error: `pre-restore shadow copy failed: ${e.message}` };
+      }
+    }
+  }
+
+  // Restore from shadow copy
+  if (isShadowSource) {
+    try {
+      const dest = path.join(projectDir, file);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(shadowDir, dest);
+      result.status = 'restored';
+      result.sourceType = 'shadow';
+      return result;
+    } catch (e) {
+      return { status: 'error', restoredFrom: source, error: e.message };
+    }
+  }
+
+  // Restore from git
+  try {
+    // Verify the source ref/hash is valid
+    const resolved = git(['rev-parse', '--verify', source], { cwd: projectDir, allowFail: true });
+    if (!resolved) {
+      return { status: 'error', restoredFrom: source, error: `cannot resolve git source: ${source}` };
+    }
+
+    // Check that the file exists in the source
+    const fileExists = git(['cat-file', '-e', `${resolved}:${file}`], { cwd: projectDir, allowFail: true });
+    if (fileExists === null) {
+      // cat-file -e returns empty on success with allowFail, null on error
+      // Try ls-tree instead
+      const lsOut = git(['ls-tree', resolved, '--', file], { cwd: projectDir, allowFail: true });
+      if (!lsOut) {
+        return { status: 'error', restoredFrom: source, error: `file '${file}' not found in source ${source}` };
+      }
+    }
+
+    execFileSync('git', ['restore', `--source=${resolved}`, '--', file], {
+      cwd: projectDir, stdio: 'pipe',
+    });
+
+    result.status = 'restored';
+    result.sourceType = 'git';
+    return result;
+  } catch (e) {
+    return { status: 'error', restoredFrom: source, error: e.message };
+  }
+}
+
+// ── Restore project (preview only for V3.0) ─────────────────────
+
+/**
+ * Preview which files would be affected by a full project restore.
+ *
+ * @param {string} projectDir
+ * @param {string} source - Commit hash or ref
+ * @returns {{ status: 'ok'|'error', files?: Array<{path: string, change: 'modified'|'added'|'deleted'}>, totalChanged?: number, error?: string }}
+ */
+function previewProjectRestore(projectDir, source) {
+  if (!isGitRepo(projectDir)) {
+    return { status: 'error', error: 'not a git repository' };
+  }
+
+  try {
+    const resolved = git(['rev-parse', '--verify', source], { cwd: projectDir, allowFail: true });
+    if (!resolved) {
+      return { status: 'error', error: `cannot resolve git source: ${source}` };
+    }
+
+    const diffOutput = git(
+      ['diff', '--name-status', resolved],
+      { cwd: projectDir, allowFail: true }
+    );
+
+    if (!diffOutput) {
+      return { status: 'ok', files: [], totalChanged: 0 };
+    }
+
+    const files = [];
+    for (const line of diffOutput.split('\n').filter(Boolean)) {
+      const tab = line.indexOf('\t');
+      const code = line.substring(0, tab).trim();
+      const filePath = line.substring(tab + 1).trim();
+      let change = 'modified';
+      if (code === 'A') change = 'added';
+      else if (code === 'D') change = 'deleted';
+      files.push({ path: filePath, change });
+    }
+
+    return { status: 'ok', files, totalChanged: files.length };
+  } catch (e) {
+    return { status: 'error', error: e.message };
+  }
+}
+
+// ── Execute project restore ─────────────────────────────────────
+
+/**
+ * Execute a full project restore to a given source commit.
+ * Creates a pre-restore snapshot first (unless opted out), then
+ * restores all changed files.
+ *
+ * @param {string} projectDir
+ * @param {string} source - Commit hash or ref
+ * @param {object} [opts]
+ * @param {boolean} [opts.preserveCurrent=true]
+ * @returns {{ status: 'restored'|'error', preRestoreRef?: string, preRestoreShortHash?: string, filesRestored: number, files?: Array<{path: string, change: string}>, error?: string }}
+ */
+function executeProjectRestore(projectDir, source, opts = {}) {
+  const preserveCurrent = resolvePreserve(projectDir, opts);
+
+  if (!isGitRepo(projectDir)) {
+    return { status: 'error', filesRestored: 0, error: 'not a git repository' };
+  }
+
+  const resolved = git(['rev-parse', '--verify', source], { cwd: projectDir, allowFail: true });
+  if (!resolved) {
+    return { status: 'error', filesRestored: 0, error: `cannot resolve git source: ${source}` };
+  }
+
+  const preview = previewProjectRestore(projectDir, source);
+  if (preview.status === 'error') {
+    return { status: 'error', filesRestored: 0, error: preview.error };
+  }
+  if (preview.totalChanged === 0) {
+    return { status: 'restored', filesRestored: 0, files: [], preRestoreRef: null };
+  }
+
+  const result = { filesRestored: 0, files: preview.files };
+
+  if (preserveCurrent) {
+    const snap = createPreRestoreSnapshot(projectDir, null);
+    if (snap.status === 'created') {
+      result.preRestoreRef = snap.ref;
+      result.preRestoreShortHash = snap.shortHash;
+    } else if (snap.status === 'error') {
+      return { status: 'error', filesRestored: 0, error: `pre-restore snapshot failed: ${snap.error}` };
+    }
+  }
+
+  try {
+    execFileSync('git', ['restore', `--source=${resolved}`, '--', '.'], {
+      cwd: projectDir, stdio: 'pipe',
+    });
+    result.status = 'restored';
+    result.filesRestored = preview.totalChanged;
+    return result;
+  } catch (e) {
+    return { status: 'error', filesRestored: 0, error: e.message };
+  }
+}
+
+// ── Pre-restore snapshot helper ─────────────────────────────────
+
+/**
+ * Create a pre-restore snapshot on refs/guard/pre-restore/<timestamp>.
+ * Uses temp index so the user's staging area is never touched.
+ *
+ * @param {string} projectDir
+ * @param {string} [scope] - Specific file to check for changes, or null for all
+ * @returns {{ status: 'created'|'skipped'|'error', ref?: string, shortHash?: string, error?: string }}
+ */
+function createPreRestoreSnapshot(projectDir, scope) {
+  const gDir = getGitDir(projectDir);
+  if (!gDir) return { status: 'error', error: 'not a git repository' };
+
+  const ts = formatTimestamp(new Date());
+  const ref = `refs/guard/pre-restore/${ts}`;
+  const guardIdx = path.join(gDir, 'guard-pre-restore-index');
+  const env = { ...process.env, GIT_INDEX_FILE: guardIdx };
+  const cwd = projectDir;
+
+  try { fs.unlinkSync(guardIdx); } catch { /* doesn't exist */ }
+
+  try {
+    const head = git(['rev-parse', 'HEAD'], { cwd, allowFail: true });
+    if (!head) return { status: 'skipped', reason: 'no HEAD commit' };
+
+    execFileSync('git', ['read-tree', 'HEAD'], { cwd, env, stdio: 'pipe' });
+    execFileSync('git', ['add', '-A'], { cwd, env, stdio: 'pipe' });
+
+    const { cfg } = loadConfig(projectDir);
+    removeSecretsFromIndex(cfg.secrets_patterns, cwd, env);
+
+    const tree = execFileSync('git', ['write-tree'], { cwd, env, stdio: 'pipe', encoding: 'utf-8' }).trim();
+    const headTree = git(['rev-parse', 'HEAD^{tree}'], { cwd, allowFail: true });
+
+    if (tree === headTree) {
+      return { status: 'skipped', reason: 'no changes to preserve' };
+    }
+
+    const commitHash = execFileSync('git', [
+      'commit-tree', tree, '-p', head, '-m', `guard: pre-restore snapshot ${ts}`,
+    ], { cwd, stdio: 'pipe', encoding: 'utf-8' }).trim();
+
+    if (!commitHash) return { status: 'error', error: 'commit-tree returned empty' };
+
+    git(['update-ref', ref, commitHash], { cwd });
+
+    return { status: 'created', ref, shortHash: commitHash.substring(0, 7) };
+  } catch (e) {
+    return { status: 'error', error: e.message };
+  } finally {
+    try { fs.unlinkSync(guardIdx); } catch { /* ignore */ }
+  }
+}
+
+module.exports = { restoreFile, previewProjectRestore, executeProjectRestore, createPreRestoreSnapshot, validateRelativePath, validateShadowSource };

package/references/lib/core/snapshot.js

@@ -0,0 +1,173 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  git, isGitRepo, gitDir: getGitDir, walkDir, filterFiles, matchesAny,
+} = require('../utils');
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+function formatTimestamp(d) {
+  const pad = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${pad(d.getMonth()+1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+function removeSecretsFromIndex(secretsPatterns, cwd, env) {
+  let files;
+  try {
+    const out = execFileSync('git', ['ls-files', '--cached'], {
+      cwd, env, stdio: 'pipe', encoding: 'utf-8',
+    }).trim();
+    files = out ? out.split('\n').filter(Boolean) : [];
+  } catch { return []; }
+
+  const excluded = [];
+  for (const f of files) {
+    const leaf = path.basename(f);
+    if (matchesAny(secretsPatterns, f) || matchesAny(secretsPatterns, leaf)) {
+      try {
+        execFileSync('git', ['rm', '--cached', '--ignore-unmatch', '-q', '--', f], {
+          cwd, env, stdio: 'pipe',
+        });
+      } catch { /* ignore */ }
+      excluded.push(f);
+    }
+  }
+  return excluded;
+}
+
+// ── Git snapshot ────────────────────────────────────────────────
+
+/**
+ * Create a git snapshot commit on a dedicated ref using plumbing commands.
+ * Does not touch the user's index or branch.
+ *
+ * @param {string} projectDir
+ * @param {object} cfg - Loaded config
+ * @param {object} [opts]
+ * @param {string} [opts.branchRef='refs/guard/auto-backup']
+ * @param {string} [opts.message] - Commit message (auto-generated if omitted)
+ * @returns {{ status: 'created'|'skipped'|'error', commitHash?: string, shortHash?: string, fileCount?: number, reason?: string, error?: string, secretsExcluded?: string[] }}
+ */
+function createGitSnapshot(projectDir, cfg, opts = {}) {
+  const branchRef = opts.branchRef || 'refs/guard/auto-backup';
+  const cwd = projectDir;
+  const gDir = getGitDir(projectDir);
+  if (!gDir) return { status: 'error', error: 'not a git repository' };
+
+  const guardIndex = path.join(gDir, 'cursor-guard-index');
+  const env = { ...process.env, GIT_INDEX_FILE: guardIndex };
+
+  try { fs.unlinkSync(guardIndex); } catch { /* doesn't exist */ }
+
+  try {
+    const parentHash = git(['rev-parse', '--verify', branchRef], { cwd, allowFail: true });
+    if (parentHash) {
+      execFileSync('git', ['read-tree', branchRef], { cwd, env, stdio: 'pipe' });
+    }
+
+    if (cfg.protect.length > 0) {
+      for (const p of cfg.protect) {
+        execFileSync('git', ['add', '--', p], { cwd, env, stdio: 'pipe' });
+      }
+    } else {
+      execFileSync('git', ['add', '-A'], { cwd, env, stdio: 'pipe' });
+    }
+
+    for (const ig of cfg.ignore) {
+      execFileSync('git', ['rm', '--cached', '--ignore-unmatch', '-rq', '--', ig], { cwd, env, stdio: 'pipe' });
+    }
+
+    const secretsExcluded = removeSecretsFromIndex(cfg.secrets_patterns, cwd, env);
+
+    const newTree = execFileSync('git', ['write-tree'], { cwd, env, stdio: 'pipe', encoding: 'utf-8' }).trim();
+    const parentTree = parentHash
+      ? git(['rev-parse', `${branchRef}^{tree}`], { cwd, allowFail: true })
+      : null;
+
+    if (newTree === parentTree) {
+      return { status: 'skipped', reason: 'tree unchanged' };
+    }
+
+    const ts = formatTimestamp(new Date());
+    const msg = opts.message || `guard: auto-backup ${ts}`;
+    const commitArgs = parentHash
+      ? ['commit-tree', newTree, '-p', parentHash, '-m', msg]
+      : ['commit-tree', newTree, '-m', msg];
+    const commitHash = execFileSync('git', commitArgs, { cwd, stdio: 'pipe', encoding: 'utf-8' }).trim();
+
+    if (!commitHash) {
+      return { status: 'error', error: 'commit-tree returned empty hash' };
+    }
+
+    git(['update-ref', branchRef, commitHash], { cwd });
+
+    let fileCount = 0;
+    if (parentTree) {
+      const diff = git(['diff-tree', '--no-commit-id', '--name-only', '-r', parentTree, newTree], { cwd, allowFail: true });
+      fileCount = diff ? diff.split('\n').filter(Boolean).length : 0;
+    } else {
+      const all = git(['ls-tree', '--name-only', '-r', newTree], { cwd, allowFail: true });
+      fileCount = all ? all.split('\n').filter(Boolean).length : 0;
+    }
+
+    return {
+      status: 'created',
+      commitHash,
+      shortHash: commitHash.substring(0, 7),
+      fileCount,
+      secretsExcluded: secretsExcluded.length > 0 ? secretsExcluded : undefined,
+    };
+  } catch (e) {
+    return { status: 'error', error: e.message };
+  } finally {
+    try { fs.unlinkSync(guardIndex); } catch { /* ignore */ }
+  }
+}
+
+// ── Shadow copy ─────────────────────────────────────────────────
+
+/**
+ * Create a shadow (file) copy of the project.
+ *
+ * @param {string} projectDir
+ * @param {object} cfg - Loaded config
+ * @param {object} [opts]
+ * @param {string} [opts.backupDir] - Override backup directory (default: projectDir/.cursor-guard-backup)
+ * @returns {{ status: 'created'|'empty'|'error', timestamp?: string, fileCount?: number, snapshotDir?: string, error?: string }}
+ */
+function createShadowCopy(projectDir, cfg, opts = {}) {
+  const backupDir = opts.backupDir || path.join(projectDir, '.cursor-guard-backup');
+  const ts = formatTimestamp(new Date());
+  const snapDir = path.join(backupDir, ts);
+
+  try {
+    fs.mkdirSync(snapDir, { recursive: true });
+
+    const allFiles = walkDir(projectDir, projectDir);
+    const files = filterFiles(allFiles, cfg);
+
+    let copied = 0;
+    for (const f of files) {
+      const dest = path.join(snapDir, f.rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      try {
+        fs.copyFileSync(f.full, dest);
+        copied++;
+      } catch { /* skip unreadable */ }
+    }
+
+    if (copied === 0) {
+      fs.rmSync(snapDir, { recursive: true, force: true });
+      return { status: 'empty', timestamp: ts };
+    }
+
+    return { status: 'created', timestamp: ts, fileCount: copied, snapshotDir: snapDir };
+  } catch (e) {
+    return { status: 'error', error: e.message };
+  }
+}
+
+module.exports = { createGitSnapshot, createShadowCopy, formatTimestamp, removeSecretsFromIndex };

package/references/lib/core/status.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  loadConfig, gitAvailable, git, isGitRepo, gitDir: getGitDir, diskFreeGB,
+} = require('../utils');
+
+/**
+ * Gather comprehensive backup system status.
+ *
+ * @param {string} projectDir
+ * @returns {{
+ *   watcher: { running: boolean, pid?: number, startedAt?: string, lockFile?: string, stale?: boolean },
+ *   config: { loaded: boolean, strategy: string, interval: number, retention: object, gitRetention: object, error?: string },
+ *   lastBackup: { git?: { ref: string, hash: string, shortHash: string, timestamp: string, message: string }, shadow?: { timestamp: string, path: string, fileCount: number } },
+ *   refs: { snapshot?: string, autoBackup?: { hash: string, commitCount: number }, preRestoreCount: number },
+ *   disk: { freeGB: number|null, warning?: string },
+ * }}
+ */
+function getBackupStatus(projectDir) {
+  const hasGit = gitAvailable();
+  const repo = hasGit && isGitRepo(projectDir);
+  const gDir = repo ? getGitDir(projectDir) : null;
+  const backupDir = path.join(projectDir, '.cursor-guard-backup');
+
+  // ── Watcher status ────────────────────────────────────────────
+  const lockFile = gDir
+    ? path.join(gDir, 'cursor-guard.lock')
+    : path.join(backupDir, 'cursor-guard.lock');
+
+  const watcher = { running: false };
+
+  if (fs.existsSync(lockFile)) {
+    watcher.lockFile = lockFile;
+    try {
+      const content = fs.readFileSync(lockFile, 'utf-8').trim();
+      const pidMatch = content.match(/pid=(\d+)/);
+      const startedMatch = content.match(/started=(.+)/);
+
+      if (pidMatch) {
+        const pid = parseInt(pidMatch[1], 10);
+        watcher.pid = pid;
+        try {
+          process.kill(pid, 0);
+          watcher.running = true;
+        } catch {
+          watcher.running = false;
+          watcher.stale = true;
+        }
+      }
+      if (startedMatch) {
+        watcher.startedAt = startedMatch[1].trim();
+      }
+    } catch { /* unreadable lock */ }
+  }
+
+  // ── Config ────────────────────────────────────────────────────
+  const { cfg, loaded, error } = loadConfig(projectDir);
+  const config = {
+    loaded,
+    strategy: cfg.backup_strategy,
+    interval: cfg.auto_backup_interval_seconds || 60,
+    retention: cfg.retention,
+    gitRetention: cfg.git_retention,
+  };
+  if (error) config.error = error;
+
+  // ── Last backup ───────────────────────────────────────────────
+  const lastBackup = {};
+
+  if (repo) {
+    const autoRef = 'refs/guard/auto-backup';
+    const autoExists = git(['rev-parse', '--verify', autoRef], { cwd: projectDir, allowFail: true });
+    if (autoExists) {
+      const logLine = git(
+        ['log', autoRef, '--format=%H %aI %s', '-1'],
+        { cwd: projectDir, allowFail: true }
+      );
+      if (logLine) {
+        const firstSpace = logLine.indexOf(' ');
+        const secondSpace = logLine.indexOf(' ', firstSpace + 1);
+        const hash = logLine.substring(0, firstSpace);
+        const timestamp = logLine.substring(firstSpace + 1, secondSpace);
+        const message = logLine.substring(secondSpace + 1);
+        lastBackup.git = {
+          ref: autoRef,
+          hash,
+          shortHash: hash.substring(0, 7),
+          timestamp,
+          message,
+        };
+      }
+    }
+  }
+
+  if (fs.existsSync(backupDir)) {
+    try {
+      const dirs = fs.readdirSync(backupDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && /^\d{8}_\d{6}$/.test(d.name))
+        .sort((a, b) => b.name.localeCompare(a.name));
+
+      if (dirs.length > 0) {
+        const latest = dirs[0].name;
+        const latestPath = path.join(backupDir, latest);
+        let fileCount = 0;
+        try {
+          const countFiles = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+              if (entry.isDirectory()) countFiles(path.join(dir, entry.name));
+              else fileCount++;
+            }
+          };
+          countFiles(latestPath);
+        } catch { /* ignore */ }
+
+        lastBackup.shadow = {
+          timestamp: latest,
+          path: latestPath,
+          fileCount,
+        };
+      }
+    } catch { /* ignore */ }
+  }
+
+  // ── Guard refs ────────────────────────────────────────────────
+  const refs = { preRestoreCount: 0 };
+
+  if (repo) {
+    const snapshotHash = git(['rev-parse', '--verify', 'refs/guard/snapshot'], { cwd: projectDir, allowFail: true });
+    if (snapshotHash) refs.snapshot = snapshotHash.substring(0, 7);
+
+    const autoRef = 'refs/guard/auto-backup';
+    const autoHash = git(['rev-parse', '--verify', autoRef], { cwd: projectDir, allowFail: true });
+    if (autoHash) {
+      const count = git(['rev-list', '--count', autoRef], { cwd: projectDir, allowFail: true });
+      refs.autoBackup = {
+        hash: autoHash.substring(0, 7),
+        commitCount: count ? parseInt(count, 10) : 0,
+      };
+    }
+
+    const preRestoreRefs = git(
+      ['for-each-ref', 'refs/guard/pre-restore/', '--format=%(refname)'],
+      { cwd: projectDir, allowFail: true }
+    );
+    if (preRestoreRefs) {
+      refs.preRestoreCount = preRestoreRefs.split('\n').filter(Boolean).length;
+    }
+  }
+
+  // ── Disk ──────────────────────────────────────────────────────
+  const freeGB = diskFreeGB(projectDir);
+  const disk = { freeGB };
+  if (freeGB !== null) {
+    if (freeGB < 1) disk.warning = 'critically low';
+    else if (freeGB < 5) disk.warning = 'low';
+  }
+
+  return { watcher, config, lastBackup, refs, disk };
+}
+
+module.exports = { getBackupStatus };