cursor-guard 2.0.2 → 2.1.0

package/README.md

@@ -179,7 +179,7 @@ npx cursor-guard-backup --path /my/project --interval 30
 ./references/auto-backup.sh /my/project
 ```
 
-The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup` branch — it never switches branches or touches your working index. Supports `shadow` mode for non-Git directories.
+The script uses Git plumbing commands to snapshot to `refs/guard/auto-backup` — it never switches branches or touches your working index. The ref lives outside `refs/heads/` so `git push --all` won't push it. Supports `shadow` mode for non-Git directories.
 
 ### Health Check
 
@@ -229,7 +229,7 @@ If the pre-restore backup fails, the agent will **not** proceed — it will wait
 ### Recovery priority
 
 1. **Git** — `git restore`, `git reset`, `git reflog`
-2. **Auto-backup branch** — `cursor-guard/auto-backup`
+2. **Auto-backup ref** — `refs/guard/auto-backup`
 3. **Shadow copies** — `.cursor-guard-backup/<timestamp>/`
 4. **Conversation context** — Original file content captured by agent Read calls
 5. **Editor history** — VS Code/Cursor Timeline (auxiliary)

package/README.zh-CN.md

@@ -179,7 +179,7 @@ npx cursor-guard-backup --path /my/project --interval 30
 ./references/auto-backup.sh /my/project
 ```
 
-脚本使用 Git 底层命令快照到 `cursor-guard/auto-backup` 分支——不会切换分支，也不会影响你的工作索引。支持 `shadow` 模式用于非 Git 目录。
+脚本使用 Git 底层命令快照到 `refs/guard/auto-backup`——不会切换分支，也不会影响你的工作索引。该引用位于 `refs/heads/` 之外，`git push --all` 不会推送它。支持 `shadow` 模式用于非 Git 目录。
 
 ### 健康检查
 
@@ -229,7 +229,7 @@ npx cursor-guard-doctor --path /my/project
 ### 恢复优先级
 
 1. **Git** — `git restore`, `git reset`, `git reflog`
-2. **自动备份分支** — `cursor-guard/auto-backup`
+2. **自动备份引用** — `refs/guard/auto-backup`
 3. **影子拷贝** — `.cursor-guard-backup/<时间戳>/`
 4. **对话上下文** — 代理 Read 调用捕获的原始文件内容
 5. **编辑器历史** — VS Code/Cursor Timeline（辅助）

package/SKILL.md

@@ -204,16 +204,16 @@ There are two distinct backup mechanisms. Do not confuse them:
 
 | | **Git branch snapshot** | **Shadow copy** |
 |---|---|---|
-| **What** | Commits to `cursor-guard/auto-backup` branch via plumbing | File copies to `.cursor-guard-backup/<timestamp>/` |
+| **What** | Commits to `refs/guard/auto-backup` via plumbing | File copies to `.cursor-guard-backup/<timestamp>/` |
 | **Who creates** | Auto-backup script (when `backup_strategy` = `git` or `both`) | Auto-backup script (when `backup_strategy` = `shadow` or `both`); or the agent manually (§2b) |
 | **Who cleans up** | `git_retention` config (auto, opt-in); or manual `git branch -D` | `retention` config (auto); or manual |
-| **Restore** | `git restore --source=cursor-guard/auto-backup -- <file>` | Copy file from `.cursor-guard-backup/<ts>/<file>` to original path |
+| **Restore** | `git restore --source=guard/auto-backup -- <file>` | Copy file from `.cursor-guard-backup/<ts>/<file>` to original path |
 | **Requires Git** | Yes | No (fallback for non-git repos) |
 
 **Priority order for the agent:**
 
 1. **Guard ref snapshot** (`refs/guard/snapshot`) — agent creates before each high-risk edit using temp index (§2a). Does not pollute user's branch or staging area.
-2. **Git branch auto-backup** (`cursor-guard/auto-backup`) — periodic snapshots by auto-backup script.
+2. **Git auto-backup ref** (`refs/guard/auto-backup`) — periodic snapshots by auto-backup script. Lives outside `refs/heads/` so `git push --all` won't push it.
 3. **Shadow copy** (`.cursor-guard-backup/`) — fallback for non-git repos, or as extra insurance when `backup_strategy = "both"`.
 4. **Editor habits** — Ctrl+S frequently; optional extensions are user-configured, mention only if asked.
 
@@ -267,7 +267,7 @@ If unclear, ask: "你想恢复哪个文件？还是整个项目？" / "Which fil
 git log --oneline --before="5 minutes ago" -5 -- <file>
 
 # Auto-backup branch (if exists)
-git log cursor-guard/auto-backup --oneline --before="5 minutes ago" -5 -- <file>
+git log guard/auto-backup --oneline --before="5 minutes ago" -5 -- <file>
 
 # Reflog as fallback (shows all HEAD movements)
 git reflog --before="5 minutes ago" -5
@@ -291,7 +291,7 @@ git log --oneline -<N+5> -- <file>
 git show HEAD~<N>:<file>
 
 # Auto-backup branch
-git log cursor-guard/auto-backup --oneline -<N+5> -- <file>
+git log guard/auto-backup --oneline -<N+5> -- <file>
 ```
 
 ### Step 3: Present Candidates to User
@@ -314,7 +314,7 @@ Recommended: #1 (closest to target time). Restore this one? / 推荐 #1（最接
 - If only ONE candidate is found, confirm with the user before restoring.
 - If MULTIPLE candidates, pre-select #1 (closest before target) but let the user pick another.
 - If NO candidates before the target time:
-  - Check auto-backup branch: `git rev-parse --verify cursor-guard/auto-backup`
+  - Check auto-backup ref: `git rev-parse --verify refs/guard/auto-backup`
   - Check shadow copies: `Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending`
   - If still nothing, report clearly: "No snapshot found before that time. The earliest available is [hash] at [time]. Do you want to use it?"
 - **Never silently pick a version.** Always show and confirm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Protects code from accidental AI overwrite or deletion in Cursor IDE — mandatory pre-write snapshots, review-before-apply, local Git safety net, and deterministic recovery. | 保护代码免受 Cursor AI 代理意外覆写或删除——强制写前快照、预览再执行、本地 Git 安全网、确定性恢复。",
   "keywords": [
     "cursor",
@@ -23,6 +23,9 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "test": "node references/lib/utils.test.js"
+  },
   "bin": {
     "cursor-guard-backup": "references/bin/cursor-guard-backup.js",
     "cursor-guard-doctor": "references/bin/cursor-guard-doctor.js"
@@ -32,7 +35,8 @@
     "README.md",
     "README.zh-CN.md",
     "LICENSE",
-    "references/"
+    "references/",
+    "!references/lib/utils.test.js"
   ],
   "main": "SKILL.md"
 }

package/references/bin/cursor-guard-backup.js

@@ -5,9 +5,26 @@ const path = require('path');
 const { parseArgs } = require('../lib/utils');
 
 const args = parseArgs(process.argv);
+
+if (args.help || args.h) {
+  console.log(`Usage: cursor-guard-backup [options]
+
+Options:
+  --path <dir>       Project directory to watch (default: current dir)
+  --interval <sec>   Override backup interval in seconds
+  --help, -h         Show this help message
+  --version, -v      Show version number`);
+  process.exit(0);
+}
+
+if (args.version || args.v) {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
 const targetPath = args.path || '.';
 const interval = parseInt(args.interval, 10) || 0;
-
 const resolved = path.resolve(targetPath);
 
 const { runBackup } = require('../lib/auto-backup');

package/references/bin/cursor-guard-doctor.js

@@ -5,6 +5,23 @@ const path = require('path');
 const { parseArgs } = require('../lib/utils');
 
 const args = parseArgs(process.argv);
+
+if (args.help || args.h) {
+  console.log(`Usage: cursor-guard-doctor [options]
+
+Options:
+  --path <dir>       Project directory to check (default: current dir)
+  --help, -h         Show this help message
+  --version, -v      Show version number`);
+  process.exit(0);
+}
+
+if (args.version || args.v) {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
 const targetPath = args.path || '.';
 const resolved = path.resolve(targetPath);
 

package/references/config-reference.md

@@ -51,7 +51,7 @@ Blacklist glob patterns. Matching files are excluded from protection even if the
 
 | Value | Description |
 |-------|-------------|
-| `"git"` | Local commits to dedicated branch `cursor-guard/auto-backup` |
+| `"git"` | Local commits to dedicated ref `refs/guard/auto-backup` |
 | `"shadow"` | File copies to `.cursor-guard-backup/<timestamp>/` |
 | `"both"` | Git branch snapshot + shadow copies |
 
@@ -155,7 +155,7 @@ Retention policy for **shadow copies** only. Git branch snapshots are not auto-c
 - **Type**: `object`
 - **Default**: `{ "enabled": false, "mode": "count", "max_count": 200 }`
 
-Retention policy for the **`cursor-guard/auto-backup` Git branch**. By default, auto-backup commits accumulate indefinitely. Enable this to automatically prune old commits.
+Retention policy for the **`refs/guard/auto-backup` Git ref**. By default, auto-backup commits accumulate indefinitely. Enable this to automatically prune old commits.
 
 ### Sub-fields
 

package/references/config-reference.zh-CN.md

@@ -51,7 +51,7 @@
 
 | 值 | 说明 |
 |----|------|
-| `"git"` | 提交到专用分支 `cursor-guard/auto-backup` |
+| `"git"` | 提交到专用引用 `refs/guard/auto-backup` |
 | `"shadow"` | 文件拷贝到 `.cursor-guard-backup/<timestamp>/` |
 | `"both"` | Git 分支快照 + 影子拷贝同时进行 |
 
@@ -155,7 +155,7 @@
 - **类型**：`object`
 - **默认值**：`{ "enabled": false, "mode": "count", "max_count": 200 }`
 
-**`cursor-guard/auto-backup` Git 分支**的保留策略。默认情况下自动备份提交会无限累积。启用此项可自动裁剪旧提交。
+**`refs/guard/auto-backup` Git 引用**的保留策略。默认情况下自动备份提交会无限累积。启用此项可自动裁剪旧提交。
 
 ### 子字段
 

package/references/cursor-guard.schema.json

@@ -75,7 +75,7 @@
     },
     "git_retention": {
       "type": "object",
-      "description": "Controls automatic cleanup of old commits on the cursor-guard/auto-backup branch.",
+      "description": "Controls automatic cleanup of old commits on refs/guard/auto-backup.",
       "properties": {
         "enabled": {
           "type": "boolean",

package/references/lib/auto-backup.js

@@ -312,8 +312,6 @@ function isProcessAlive(pid) {
 // ── Main ────────────────────────────────────────────────────────
 
 async function runBackup(projectDir, intervalOverride) {
-  process.chdir(projectDir);
-
   const hasGit = gitAvailable();
   const repo = hasGit && isGitRepo(projectDir);
   const gDir = repo ? getGitDir(projectDir) : null;
@@ -326,7 +324,7 @@ async function runBackup(projectDir, intervalOverride) {
   const guardIndex = gDir ? path.join(gDir, 'cursor-guard-index') : null;
 
   // Load config
-  let { cfg, loaded, error } = loadConfig(projectDir);
+  let { cfg, loaded, error, warnings } = loadConfig(projectDir);
   let interval = intervalOverride || cfg.auto_backup_interval_seconds || 60;
   if (interval < 5) interval = 5;
   let cfgMtime = 0;
@@ -337,6 +335,9 @@ async function runBackup(projectDir, intervalOverride) {
     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
@@ -399,13 +400,24 @@ async function runBackup(projectDir, intervalOverride) {
   process.on('exit', cleanup);
 
   // Git-specific setup
-  const branch = 'cursor-guard/auto-backup';
-  const branchRef = `refs/heads/${branch}`;
+  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) {
-      git(['branch', branch, 'HEAD'], { cwd: projectDir, allowFail: true });
-      console.log(color.green(`[guard] Created branch: ${branch}`));
+      // Migrate from legacy refs/heads/ location if it 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 {
+        const head = git(['rev-parse', 'HEAD'], { cwd: projectDir, allowFail: true });
+        if (head) {
+          git(['update-ref', branchRef, head], { cwd: projectDir, allowFail: true });
+          console.log(color.green(`[guard] Created ref: ${branchRef}`));
+        }
+      }
     }
 
     const excludeFile = path.join(gDir, 'info', 'exclude');
@@ -420,10 +432,20 @@ async function runBackup(projectDir, intervalOverride) {
 
   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}`);
+  });
+
   // 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}  |  Branch: ${branch}  |  Retention: ${cfg.retention.mode}`));
+  console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
   console.log(color.cyan(`[guard] Log: ${logFilePath}`));
   console.log('');
 

package/references/lib/guard-doctor.js

@@ -81,15 +81,20 @@ function runDoctor(projectDir) {
     check('Strategy compatibility', 'FAIL', `unknown backup_strategy='${strategy}' (must be git/shadow/both)`);
   }
 
-  // 5. Backup branch
+  // 5. Backup ref
   if (repo) {
-    const branchRef = 'refs/heads/cursor-guard/auto-backup';
-    const exists = git(['rev-parse', '--verify', branchRef], { cwd: projectDir, allowFail: true });
+    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', branchRef], { cwd: projectDir, allowFail: true }) || '?';
-      check('Backup branch', 'PASS', `cursor-guard/auto-backup exists (${count} commits)`);
+      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 branch', 'WARN', 'cursor-guard/auto-backup not created yet (will be created on first backup)');
+      check('Backup ref', 'WARN', 'refs/guard/auto-backup not created yet (will be created on first backup)');
     }
   }
 

package/references/lib/utils.js

@@ -52,18 +52,22 @@ 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 });
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); }
+    catch { continue; }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      const rel = path.relative(rootDir, full).replace(/\\/g, '/');
+      if (ALWAYS_SKIP.test('/' + rel + '/')) continue;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile()) {
+        results.push({ full, rel, name: entry.name });
+      }
     }
   }
   return results;
@@ -73,6 +77,11 @@ function walkDir(dir, rootDir) {
 
 const DEFAULT_SECRETS = ['.env', '.env.*', '*.key', '*.pem', '*.p12', '*.pfx', 'credentials*'];
 
+const VALID_STRATEGIES = ['git', 'shadow', 'both'];
+const VALID_PRE_RESTORE = ['always', 'ask', 'never'];
+const VALID_RETENTION_MODES = ['days', 'count', 'size'];
+const VALID_GIT_RETENTION_MODES = ['days', 'count'];
+
 const DEFAULT_CONFIG = {
   protect: [],
   ignore: [],
@@ -101,22 +110,47 @@ function loadConfig(projectDir) {
       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;
+    const warnings = [];
+    if (typeof raw.backup_strategy === 'string') {
+      if (VALID_STRATEGIES.includes(raw.backup_strategy)) {
+        cfg.backup_strategy = raw.backup_strategy;
+      } else {
+        warnings.push(`Unknown backup_strategy "${raw.backup_strategy}", using default "${cfg.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 (typeof raw.pre_restore_backup === 'string') {
+      if (VALID_PRE_RESTORE.includes(raw.pre_restore_backup)) {
+        cfg.pre_restore_backup = raw.pre_restore_backup;
+      } else {
+        warnings.push(`Unknown pre_restore_backup "${raw.pre_restore_backup}", using default "${cfg.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.retention.mode) {
+        if (VALID_RETENTION_MODES.includes(raw.retention.mode)) {
+          cfg.retention.mode = raw.retention.mode;
+        } else {
+          warnings.push(`Unknown retention.mode "${raw.retention.mode}", using default "${cfg.retention.mode}"`);
+        }
+      }
+      if (typeof raw.retention.days === 'number')        cfg.retention.days = raw.retention.days;
+      if (typeof raw.retention.max_count === 'number')   cfg.retention.max_count = raw.retention.max_count;
+      if (typeof raw.retention.max_size_mb === 'number') 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;
+      if (raw.git_retention.mode) {
+        if (VALID_GIT_RETENTION_MODES.includes(raw.git_retention.mode)) {
+          cfg.git_retention.mode = raw.git_retention.mode;
+        } else {
+          warnings.push(`Unknown git_retention.mode "${raw.git_retention.mode}", using default "${cfg.git_retention.mode}"`);
+        }
+      }
+      if (typeof raw.git_retention.days === 'number')      cfg.git_retention.days = raw.git_retention.days;
+      if (typeof raw.git_retention.max_count === 'number') cfg.git_retention.max_count = raw.git_retention.max_count;
     }
-    return { cfg, loaded: true, error: null };
+    return { cfg, loaded: true, error: null, warnings };
   } catch (e) {
     return { cfg, loaded: false, error: e.message };
   }
@@ -249,11 +283,23 @@ function timestamp() {
   return new Date().toISOString().replace('T', ' ').substring(0, 19);
 }
 
-function createLogger(logFilePath) {
+function createLogger(logFilePath, maxSizeMB = 10) {
+  let writeCount = 0;
+  function rotateIfNeeded() {
+    if (++writeCount % 100 !== 0) return;
+    try {
+      const stat = fs.statSync(logFilePath);
+      if (stat.size > maxSizeMB * 1024 * 1024) {
+        const old = logFilePath + '.old';
+        try { fs.unlinkSync(old); } catch { /* ignore */ }
+        fs.renameSync(logFilePath, old);
+      }
+    } catch { /* ignore */ }
+  }
   return {
     log(msg, c = 'green') {
       const line = `${timestamp()}  ${msg}`;
-      try { fs.appendFileSync(logFilePath, line + '\n'); } catch { /* ignore */ }
+      try { fs.appendFileSync(logFilePath, line + '\n'); rotateIfNeeded(); } catch { /* ignore */ }
       console.log(color[c] ? color[c](`[guard] ${line}`) : `[guard] ${line}`);
     },
     info(msg) { this.log(msg, 'cyan'); },

package/references/recovery.md

@@ -268,24 +268,24 @@ The `auto-backup.ps1` script stores periodic snapshots on a dedicated branch via
 
 ```bash
 # List recent auto-backup snapshots
-git log cursor-guard/auto-backup --oneline -20
+git log guard/auto-backup --oneline -20
 
 # Restore a file from the latest auto-backup
-git restore --source=cursor-guard/auto-backup -- <path/to/file>
+git restore --source=guard/auto-backup -- <path/to/file>
 
 # Restore from a specific auto-backup snapshot
 git restore --source=<commit-hash> -- <path/to/file>
 
 # Diff your working copy against the auto-backup version
-git diff cursor-guard/auto-backup -- <path/to/file>
+git diff guard/auto-backup -- <path/to/file>
 
 # Time-based: find auto-backup snapshot from before N minutes ago
 # 按时间查找：N 分钟前之前最近的自动备份快照
-git log cursor-guard/auto-backup --oneline --before="5 minutes ago" -5 -- <path/to/file>
+git log guard/auto-backup --oneline --before="5 minutes ago" -5 -- <path/to/file>
 
 # Version-based: list recent N auto-backup snapshots
 # 按版本查找：最近 N 个自动备份快照
-git log cursor-guard/auto-backup --oneline -10 -- <path/to/file>
+git log guard/auto-backup --oneline -10 -- <path/to/file>
 ```
 
 ## If not a Git repo yet
@@ -374,10 +374,10 @@ Get-ChildItem .cursor-guard-backup/ -Directory | Where-Object {
 
 ```bash
 # View auto-backup history
-git log cursor-guard/auto-backup --oneline -30
+git log guard/auto-backup --oneline -30
 
 # Delete the branch entirely (script will recreate it on next run)
-git branch -D cursor-guard/auto-backup
+git update-ref -d refs/guard/auto-backup
 
 # Reclaim disk space after removing old branches
 git gc --prune=now

package/references/lib/utils.test.js

@@ -1,329 +0,0 @@
-'use strict';
-
-const assert = require('assert');
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-const {
-  globMatch, matchesAny, loadConfig, DEFAULT_CONFIG, DEFAULT_SECRETS,
-  filterFiles, buildManifest, manifestChanged, parseArgs, walkDir,
-} = require('./utils');
-
-let passed = 0;
-let failed = 0;
-
-function test(name, fn) {
-  try {
-    fn();
-    passed++;
-    console.log(`  \x1b[32m✓\x1b[0m ${name}`);
-  } catch (e) {
-    failed++;
-    console.log(`  \x1b[31m✗\x1b[0m ${name}`);
-    console.log(`    ${e.message}`);
-  }
-}
-
-// ── globMatch ────────────────────────────────────────────────────
-
-console.log('\nglobMatch:');
-
-test('exact filename match', () => {
-  assert.strictEqual(globMatch('.env', '.env'), true);
-  assert.strictEqual(globMatch('.env', '.envx'), false);
-});
-
-test('* matches within a single segment', () => {
-  assert.strictEqual(globMatch('*.js', 'foo.js'), true);
-  assert.strictEqual(globMatch('*.js', 'bar.ts'), false);
-  assert.strictEqual(globMatch('*.js', 'dir/foo.js'), false);
-});
-
-test('** matches across directories', () => {
-  assert.strictEqual(globMatch('**/*.js', 'src/foo.js'), true);
-  assert.strictEqual(globMatch('**/*.js', 'a/b/c/foo.js'), true);
-  // **/*.js requires a slash — root-level 'foo.js' doesn't match (matchesAny checks leaf separately)
-  assert.strictEqual(globMatch('**/*.js', 'foo.js'), false);
-  assert.strictEqual(globMatch('**/*.js', 'foo.ts'), false);
-});
-
-test('? matches single character', () => {
-  assert.strictEqual(globMatch('?.txt', 'a.txt'), true);
-  assert.strictEqual(globMatch('?.txt', 'ab.txt'), false);
-});
-
-test('.env.* pattern', () => {
-  assert.strictEqual(globMatch('.env.*', '.env.local'), true);
-  assert.strictEqual(globMatch('.env.*', '.env.production'), true);
-  assert.strictEqual(globMatch('.env.*', '.env'), false);
-});
-
-test('credentials* pattern', () => {
-  assert.strictEqual(globMatch('credentials*', 'credentials'), true);
-  assert.strictEqual(globMatch('credentials*', 'credentials.json'), true);
-  assert.strictEqual(globMatch('credentials*', 'my-credentials'), false);
-});
-
-test('directory pattern src/**', () => {
-  assert.strictEqual(globMatch('src/**', 'src/foo.js'), true);
-  assert.strictEqual(globMatch('src/**', 'src/a/b.js'), true);
-  assert.strictEqual(globMatch('src/**', 'lib/foo.js'), false);
-});
-
-test('backslash normalization', () => {
-  assert.strictEqual(globMatch('src/**/*.ts', 'src\\components\\App.ts'), true);
-});
-
-test('regex special chars in pattern are escaped', () => {
-  assert.strictEqual(globMatch('file(1).txt', 'file(1).txt'), true);
-  assert.strictEqual(globMatch('file[0].txt', 'file[0].txt'), true); // [] escaped as literals
-});
-
-// ── matchesAny ───────────────────────────────────────────────────
-
-console.log('\nmatchesAny:');
-
-test('matches when any pattern hits', () => {
-  assert.strictEqual(matchesAny(['*.js', '*.ts'], 'foo.js'), true);
-  assert.strictEqual(matchesAny(['*.js', '*.ts'], 'foo.ts'), true);
-  assert.strictEqual(matchesAny(['*.js', '*.ts'], 'foo.py'), false);
-});
-
-test('checks leaf filename for deep paths', () => {
-  assert.strictEqual(matchesAny(['*.key'], 'secrets/server.key'), true);
-  assert.strictEqual(matchesAny(['.env'], 'config/.env'), true);
-});
-
-test('empty patterns matches nothing', () => {
-  assert.strictEqual(matchesAny([], 'anything'), false);
-});
-
-// ── loadConfig ───────────────────────────────────────────────────
-
-console.log('\nloadConfig:');
-
-test('returns defaults when no config file', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
-  try {
-    const { cfg, loaded, error } = loadConfig(tmpDir);
-    assert.strictEqual(loaded, false);
-    assert.strictEqual(error, null);
-    assert.deepStrictEqual(cfg.protect, []);
-    assert.deepStrictEqual(cfg.ignore, []);
-    assert.deepStrictEqual(cfg.secrets_patterns, DEFAULT_SECRETS);
-    assert.strictEqual(cfg.backup_strategy, 'git');
-    assert.strictEqual(cfg.git_retention.enabled, false);
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-test('loads and merges custom config', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
-  try {
-    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
-      protect: ['src/**'],
-      backup_strategy: 'both',
-      retention: { mode: 'count', max_count: 50 },
-    }));
-    const { cfg, loaded, error } = loadConfig(tmpDir);
-    assert.strictEqual(loaded, true);
-    assert.strictEqual(error, null);
-    assert.deepStrictEqual(cfg.protect, ['src/**']);
-    assert.strictEqual(cfg.backup_strategy, 'both');
-    assert.strictEqual(cfg.retention.mode, 'count');
-    assert.strictEqual(cfg.retention.max_count, 50);
-    assert.strictEqual(cfg.retention.days, 30); // default preserved
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-test('handles malformed JSON gracefully', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
-  try {
-    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), '{ broken }');
-    const { cfg, loaded, error } = loadConfig(tmpDir);
-    assert.strictEqual(loaded, false);
-    assert.ok(error, 'should have an error message');
-    assert.deepStrictEqual(cfg.protect, []);
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-test('secrets_patterns override replaces defaults entirely', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
-  try {
-    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
-      secrets_patterns: ['my-secret'],
-    }));
-    const { cfg } = loadConfig(tmpDir);
-    assert.deepStrictEqual(cfg.secrets_patterns, ['my-secret']);
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-test('secrets_patterns_extra appends to defaults', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
-  try {
-    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
-      secrets_patterns_extra: ['*.secret', 'tokens.*'],
-    }));
-    const { cfg } = loadConfig(tmpDir);
-    assert.ok(cfg.secrets_patterns.includes('.env'), 'should keep default .env');
-    assert.ok(cfg.secrets_patterns.includes('*.p12'), 'should keep default *.p12');
-    assert.ok(cfg.secrets_patterns.includes('*.secret'), 'should include extra *.secret');
-    assert.ok(cfg.secrets_patterns.includes('tokens.*'), 'should include extra tokens.*');
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-test('secrets_patterns_extra merges with custom secrets_patterns', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
-  try {
-    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
-      secrets_patterns: ['.env'],
-      secrets_patterns_extra: ['.env', '*.secret'],
-    }));
-    const { cfg } = loadConfig(tmpDir);
-    assert.deepStrictEqual(cfg.secrets_patterns, ['.env', '*.secret']);
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-test('non-string backup_strategy is ignored', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
-  try {
-    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
-      backup_strategy: 123,
-      auto_backup_interval_seconds: 'bad',
-    }));
-    const { cfg } = loadConfig(tmpDir);
-    assert.strictEqual(cfg.backup_strategy, 'git');
-    assert.strictEqual(cfg.auto_backup_interval_seconds, 60);
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-// ── filterFiles ──────────────────────────────────────────────────
-
-console.log('\nfilterFiles:');
-
-const makeFiles = names => names.map(n => ({ full: `/fake/${n}`, rel: n, name: path.basename(n) }));
-
-test('no protect/ignore returns all non-secret files', () => {
-  const files = makeFiles(['a.js', 'b.ts', '.env', 'credentials.json']);
-  const cfg = { ...DEFAULT_CONFIG };
-  const result = filterFiles(files, cfg);
-  const rels = result.map(f => f.rel);
-  assert.ok(!rels.includes('.env'));
-  assert.ok(!rels.includes('credentials.json'));
-  assert.ok(rels.includes('a.js'));
-  assert.ok(rels.includes('b.ts'));
-});
-
-test('protect narrows scope', () => {
-  const files = makeFiles(['src/a.js', 'lib/b.js', 'README.md']);
-  const cfg = { ...DEFAULT_CONFIG, protect: ['src/**'] };
-  const result = filterFiles(files, cfg);
-  assert.strictEqual(result.length, 1);
-  assert.strictEqual(result[0].rel, 'src/a.js');
-});
-
-test('ignore excludes files', () => {
-  const files = makeFiles(['src/a.js', 'src/a.test.js', 'src/b.js']);
-  const cfg = { ...DEFAULT_CONFIG, ignore: ['**/*.test.js'] };
-  const result = filterFiles(files, cfg);
-  const rels = result.map(f => f.rel);
-  assert.ok(!rels.includes('src/a.test.js'));
-  assert.ok(rels.includes('src/a.js'));
-});
-
-// ── manifestChanged ──────────────────────────────────────────────
-
-console.log('\nmanifestChanged:');
-
-test('null old manifest means changed', () => {
-  assert.strictEqual(manifestChanged(null, { 'a.js': { mtimeMs: 1, size: 100 } }), true);
-});
-
-test('identical manifests are not changed', () => {
-  const m = { 'a.js': { mtimeMs: 1, size: 100 } };
-  assert.strictEqual(manifestChanged(m, { ...m }), false);
-});
-
-test('different mtime means changed', () => {
-  const old = { 'a.js': { mtimeMs: 1, size: 100 } };
-  const nw = { 'a.js': { mtimeMs: 2, size: 100 } };
-  assert.strictEqual(manifestChanged(old, nw), true);
-});
-
-test('new file means changed', () => {
-  const old = { 'a.js': { mtimeMs: 1, size: 100 } };
-  const nw = { 'a.js': { mtimeMs: 1, size: 100 }, 'b.js': { mtimeMs: 2, size: 50 } };
-  assert.strictEqual(manifestChanged(old, nw), true);
-});
-
-// ── parseArgs ────────────────────────────────────────────────────
-
-console.log('\nparseArgs:');
-
-test('parses --key value pairs', () => {
-  const args = parseArgs(['node', 'script', '--path', '/tmp', '--interval', '30']);
-  assert.strictEqual(args.path, '/tmp');
-  assert.strictEqual(args.interval, '30');
-});
-
-test('parses boolean flags', () => {
-  const args = parseArgs(['node', 'script', '--verbose']);
-  assert.strictEqual(args.verbose, true);
-});
-
-test('empty args returns empty object', () => {
-  const args = parseArgs(['node', 'script']);
-  assert.deepStrictEqual(args, {});
-});
-
-// ── walkDir ──────────────────────────────────────────────────────
-
-console.log('\nwalkDir:');
-
-test('discovers files recursively', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-walk-'));
-  try {
-    fs.mkdirSync(path.join(tmpDir, 'sub'), { recursive: true });
-    fs.writeFileSync(path.join(tmpDir, 'a.txt'), 'a');
-    fs.writeFileSync(path.join(tmpDir, 'sub', 'b.txt'), 'b');
-    const files = walkDir(tmpDir, tmpDir);
-    const rels = files.map(f => f.rel).sort();
-    assert.deepStrictEqual(rels, ['a.txt', 'sub/b.txt']);
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-test('skips .git and node_modules', () => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-walk-'));
-  try {
-    fs.mkdirSync(path.join(tmpDir, '.git'), { recursive: true });
-    fs.mkdirSync(path.join(tmpDir, 'node_modules'), { recursive: true });
-    fs.writeFileSync(path.join(tmpDir, '.git', 'HEAD'), 'ref');
-    fs.writeFileSync(path.join(tmpDir, 'node_modules', 'x.js'), 'x');
-    fs.writeFileSync(path.join(tmpDir, 'real.js'), 'y');
-    const files = walkDir(tmpDir, tmpDir);
-    assert.strictEqual(files.length, 1);
-    assert.strictEqual(files[0].rel, 'real.js');
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-});
-
-// ── Summary ──────────────────────────────────────────────────────
-
-console.log(`\n${passed + failed} tests: \x1b[32m${passed} passed\x1b[0m` + (failed ? `, \x1b[31m${failed} failed\x1b[0m` : ''));
-process.exit(failed > 0 ? 1 : 0);