cursor-guard 3.4.0 → 4.1.0

package/SKILL.md

@@ -23,6 +23,8 @@ Use this skill when any of the following appear:
 - **Health check**: e.g. "guard doctor", "检查备份配置", "自检", "诊断guard", "check guard setup", "MCP 能用吗". If MCP `doctor` tool is available, call `doctor { "path": "<project>" }` and format the result; otherwise run `guard-doctor.ps1` and report results. Doctor output includes an "MCP server" check (SDK installed + server.js present). If doctor reports FAIL items, suggest running `doctor_fix` (MCP) or guide the user through manual fixes.
 - **Auto-fix**: e.g. "guard fix", "修复配置", "自动修复". If MCP `doctor_fix` tool is available, call `doctor_fix { "path": "<project>", "dry_run": true }` first to preview, then `doctor_fix { "path": "<project>" }` to apply. Without MCP, guide the user through manual steps based on doctor output.
 - **Backup status**: e.g. "备份状态", "guard status", "watcher 在跑吗", "最近一次备份". If MCP `backup_status` tool is available, call `backup_status { "path": "<project>" }` and format the structured result for the user (watcher running/stale, last backup time, strategy, ref counts, disk). Without MCP, check lock file existence and `git log` manually.
+- **Health dashboard**: e.g. "看板", "dashboard", "健康状态", "备份总览", "guard 概况". If MCP `dashboard` tool is available, call `dashboard { "path": "<project>" }` and present the structured dashboard (strategy, last backup, counts, disk usage, protection scope, health status, alerts). Format as a clear summary for the user.
+- **Alert check**: e.g. "有告警吗", "alert status", "变更异常", "风险提示". If MCP `alert_status` tool is available, call `alert_status { "path": "<project>" }` to check for active change-velocity alerts. Report whether an alert is active and its details.
 
 If none of the above, do not expand scope; answer normally.
 
@@ -58,7 +60,17 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
 
   // Retention for Git auto-backup branch. Disabled by default.
   // "count": keep N newest commits. "days": keep commits from last N days.
-  "git_retention": { "enabled": false, "mode": "count", "max_count": 200 }
+  "git_retention": { "enabled": false, "mode": "count", "max_count": 200 },
+
+  // V4: Proactive change-velocity detection (default: on).
+  // When enabled, the watcher monitors file change frequency and raises
+  // alerts when abnormal patterns are detected (e.g. 20+ files in 10s).
+  "proactive_alert": true,
+  "alert_thresholds": {
+    "files_per_window": 20,  // trigger threshold
+    "window_seconds": 10,    // sliding window
+    "cooldown_seconds": 60   // min gap between alerts
+  }
 }
 ```
 
@@ -81,7 +93,7 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
 
 cursor-guard provides an **MCP server** (`cursor-guard-mcp`) as an optional enhancement. When available, prefer MCP tool calls over shell commands — they are faster, return structured JSON, and consume fewer tokens.
 
-**Detection**: at the start of a session, check if the following MCP tools are available in your tool list: `doctor`, `list_backups`, `snapshot_now`, `restore_file`, `restore_project`. If **any** of them exists, use MCP for that operation; otherwise, fall back to shell commands as described in the sections below.
+**Detection**: at the start of a session, check if the following MCP tools are available in your tool list: `doctor`, `list_backups`, `snapshot_now`, `restore_file`, `restore_project`, `dashboard`, `alert_status`. If **any** of them exists, use MCP for that operation; otherwise, fall back to shell commands as described in the sections below.
 
 **Routing table** (MCP tool → replaces which shell workflow):
 
@@ -95,6 +107,8 @@ cursor-guard provides an **MCP server** (`cursor-guard-mcp`) as an optional enha
 | Restore single file | `restore_file` | §5a Step 5 git restore |
 | Preview project restore | `restore_project` (preview=true) | §5a Step 5 git diff |
 | Execute project restore | `restore_project` (preview=false) | §5a Step 5 git restore -- . |
+| Backup health dashboard | `dashboard` | manual: combine backup_status + git/shadow stats |
+| Change-velocity alerts | `alert_status` | manual: check alert file in .git/ or .cursor-guard-backup/ |
 
 **Rules**:
 - MCP results are JSON — parse `status`, `error`, and data fields; do not re-run shell to verify.
@@ -188,7 +202,7 @@ git update-ref refs/guard/snapshot $commit
 
 1. **Quick git init** (preferred):
    ```
-   git init && git add -A && git commit -m "guard: initial snapshot" --no-verify
+   git init; git add -A; git commit -m "guard: initial snapshot" --no-verify
    ```
 2. **Shadow copy** (fallback if user declines git):
    - Copy the target file(s) to `.cursor-guard-backup/<timestamp>/` via Shell.
@@ -570,8 +584,8 @@ Skip the block for unrelated turns.
 - Recovery commands: [references/recovery.md](references/recovery.md)
 - Auto-backup (Node.js core): [references/lib/auto-backup.js](references/lib/auto-backup.js)
 - Guard doctor (Node.js core): [references/lib/guard-doctor.js](references/lib/guard-doctor.js)
-- Core modules: [references/lib/core/](references/lib/core/) (doctor, doctor-fix, snapshot, backups, restore, status)
-- MCP server: [references/mcp/server.js](references/mcp/server.js) (7 tools: doctor, doctor_fix, backup_status, list_backups, snapshot_now, restore_file, restore_project)
+- Core modules: [references/lib/core/](references/lib/core/) (doctor, doctor-fix, snapshot, backups, restore, status, anomaly, dashboard)
+- MCP server: [references/mcp/server.js](references/mcp/server.js) (9 tools: doctor, doctor_fix, backup_status, list_backups, snapshot_now, restore_file, restore_project, dashboard, alert_status)
 - Shared utilities: [references/lib/utils.js](references/lib/utils.js)
 - Config JSON Schema: [references/cursor-guard.schema.json](references/cursor-guard.schema.json)
 - Example config: [references/cursor-guard.example.json](references/cursor-guard.example.json)
@@ -614,4 +628,4 @@ If your Cursor config supports MCP, add `cursor-guard` as an MCP server for lowe
 }
 ```
 
-Once configured, the 7 tools (`doctor`, `doctor_fix`, `backup_status`, `list_backups`, `snapshot_now`, `restore_file`, `restore_project`) are available as MCP tool calls. See §0a for routing logic.
+Once configured, the 9 tools (`doctor`, `doctor_fix`, `backup_status`, `list_backups`, `snapshot_now`, `restore_file`, `restore_project`, `dashboard`, `alert_status`) are available as MCP tool calls. See §0a for routing logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "3.4.0",
+  "version": "4.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",
@@ -27,6 +27,7 @@
     "test": "node references/lib/utils.test.js && node references/lib/core/core.test.js && node references/mcp/mcp.test.js"
   },
   "bin": {
+    "cursor-guard-init": "references/bin/cursor-guard-init.js",
     "cursor-guard-backup": "references/bin/cursor-guard-backup.js",
     "cursor-guard-doctor": "references/bin/cursor-guard-doctor.js",
     "cursor-guard-mcp": "references/mcp/server.js"

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

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`Usage: cursor-guard-init [options]
+
+Installs cursor-guard skill into your Cursor skills directory, including
+MCP dependencies and .gitignore entries.
+
+Options:
+  --global             Install to ~/.cursor/skills/ (default: project-local)
+  --path <dir>         Project directory (default: current dir)
+  --help, -h           Show this help message
+  --version, -v        Show version number`);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const isGlobal = args.includes('--global');
+const pathIdx = args.indexOf('--path');
+const projectDir = path.resolve(pathIdx >= 0 && args[pathIdx + 1] ? args[pathIdx + 1] : '.');
+
+const skillSource = path.resolve(__dirname, '../..');
+const skillTarget = isGlobal
+  ? path.join(process.env.USERPROFILE || process.env.HOME || os.homedir(), '.cursor', 'skills', 'cursor-guard')
+  : path.join(projectDir, '.cursor', 'skills', 'cursor-guard');
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (path.basename(src) === 'node_modules') return;
+    if (path.basename(src) === '.git') return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+console.log(`\n  cursor-guard init\n`);
+console.log(`  Source:  ${skillSource}`);
+console.log(`  Target:  ${skillTarget}`);
+console.log(`  Mode:    ${isGlobal ? 'global (~/.cursor/skills/)' : 'project-local (.cursor/skills/)'}\n`);
+
+// Step 1: Copy skill files (excluding node_modules and .git)
+console.log('  [1/4] Copying skill files...');
+if (fs.existsSync(skillTarget)) {
+  fs.rmSync(skillTarget, { recursive: true, force: true });
+}
+copyRecursive(skillSource, skillTarget);
+console.log('        Done.');
+
+// Step 2: Install MCP dependencies in skill directory
+console.log('  [2/4] Installing MCP dependencies...');
+try {
+  execFileSync('npm', ['install', '--omit=dev', '--ignore-scripts'], {
+    cwd: skillTarget,
+    stdio: 'pipe',
+    shell: process.platform === 'win32',
+  });
+  console.log('        Done.');
+} catch (e) {
+  console.log(`        Warning: npm install failed (${e.message}). MCP tools may not work.`);
+  console.log('        You can fix this later: cd "' + skillTarget + '" ; npm install');
+}
+
+// Step 3: Add .gitignore entries for skill node_modules
+console.log('  [3/4] Updating .gitignore...');
+const gitignorePath = path.join(projectDir, '.gitignore');
+const entries = ['.cursor/skills/**/node_modules/'];
+let gitignoreUpdated = false;
+if (!isGlobal) {
+  let existing = '';
+  try { existing = fs.readFileSync(gitignorePath, 'utf-8'); } catch { /* doesn't exist */ }
+  const missing = entries.filter(e => !existing.includes(e));
+  if (missing.length > 0) {
+    const newline = existing.endsWith('\n') || !existing ? '' : '\n';
+    fs.appendFileSync(gitignorePath, `${newline}# cursor-guard skill dependencies\n${missing.join('\n')}\n`);
+    gitignoreUpdated = true;
+    console.log('        Added: ' + missing.join(', '));
+  } else {
+    console.log('        Already configured.');
+  }
+} else {
+  console.log('        Skipped (global install, not inside a project).');
+}
+
+// Step 4: Summary
+console.log('  [4/4] Verifying...');
+const serverExists = fs.existsSync(path.join(skillTarget, 'references', 'mcp', 'server.js'));
+const sdkExists = fs.existsSync(path.join(skillTarget, 'node_modules', '@modelcontextprotocol', 'sdk'));
+const skillMdExists = fs.existsSync(path.join(skillTarget, 'SKILL.md'));
+
+console.log(`        SKILL.md:   ${skillMdExists ? 'OK' : 'MISSING'}`);
+console.log(`        MCP server: ${serverExists ? 'OK' : 'MISSING'}`);
+console.log(`        MCP SDK:    ${sdkExists ? 'OK' : 'MISSING — run npm install in skill dir'}`);
+
+console.log(`\n  Installation complete!\n`);
+console.log('  Next steps:');
+console.log('  1. The skill activates automatically in Cursor Agent conversations.');
+console.log('  2. (Optional) Copy example config to project root:');
+console.log(`     cp "${path.join(skillTarget, 'references', 'cursor-guard.example.json')}" .cursor-guard.json`);
+console.log('  3. (Optional) Enable MCP — add to .cursor/mcp.json:');
+console.log(`     { "mcpServers": { "cursor-guard": { "command": "node", "args": ["${path.join(skillTarget, 'references', 'mcp', 'server.js').replace(/\\/g, '/')}"] } } }`);
+console.log('  4. (Optional) Start auto-backup:');
+console.log(`     npx cursor-guard-backup --path "${projectDir}"\n`);

package/references/config-reference.md

@@ -173,3 +173,43 @@ Retention policy for the **`refs/guard/auto-backup` Git ref**. By default, auto-
   "max_count": 200
 }
 ```
+
+---
+
+## `proactive_alert`
+
+- **Type**: `boolean`
+- **Default**: `true`
+
+Enable V4 proactive change-velocity detection. When enabled, the auto-backup watcher monitors file change frequency and raises alerts when abnormal patterns are detected (e.g. 20+ files modified in 10 seconds). Alerts are persisted to a file so the MCP server can include them in tool responses.
+
+Set to `false` to disable proactive monitoring entirely.
+
+```json
+"proactive_alert": true
+```
+
+---
+
+## `alert_thresholds`
+
+- **Type**: `object`
+- **Default**: `{ "files_per_window": 20, "window_seconds": 10, "cooldown_seconds": 60 }`
+
+Thresholds for proactive change-velocity alerts. Only effective when `proactive_alert` is `true`.
+
+### Sub-fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `files_per_window` | `integer` | `20` | Number of file changes within the time window that triggers an alert |
+| `window_seconds` | `integer` | `10` | Sliding time window in seconds for counting file changes |
+| `cooldown_seconds` | `integer` | `60` | Minimum seconds between consecutive alerts to avoid noise |
+
+```json
+"alert_thresholds": {
+  "files_per_window": 20,
+  "window_seconds": 10,
+  "cooldown_seconds": 60
+}
+```

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

@@ -173,3 +173,43 @@
   "max_count": 200
 }
 ```
+
+---
+
+## `proactive_alert`
+
+- **类型**：`boolean`
+- **默认值**：`true`
+
+启用 V4 主动变更频率检测。开启后，自动备份 watcher 会监控文件变更频率，当检测到异常模式（如 10 秒内 20+ 文件被修改）时发出告警。告警会持久化到文件，以便 MCP 工具在响应中附加风险提示。
+
+设为 `false` 可完全禁用主动监控。
+
+```json
+"proactive_alert": true
+```
+
+---
+
+## `alert_thresholds`
+
+- **类型**：`object`
+- **默认值**：`{ "files_per_window": 20, "window_seconds": 10, "cooldown_seconds": 60 }`
+
+主动变更频率告警的阈值配置。仅在 `proactive_alert` 为 `true` 时生效。
+
+### 子字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `files_per_window` | `integer` | `20` | 时间窗口内触发告警的文件变更数量 |
+| `window_seconds` | `integer` | `10` | 统计文件变更的滑动时间窗口（秒） |
+| `cooldown_seconds` | `integer` | `60` | 连续告警之间的最小间隔（秒），避免噪声 |
+
+```json
+"alert_thresholds": {
+  "files_per_window": 20,
+  "window_seconds": 10,
+  "cooldown_seconds": 60
+}
+```

package/references/cursor-guard.example.json

@@ -33,5 +33,11 @@
     "mode": "count",
     "days": 30,
     "max_count": 200
+  },
+  "proactive_alert": true,
+  "alert_thresholds": {
+    "files_per_window": 20,
+    "window_seconds": 10,
+    "cooldown_seconds": 60
   }
 }

package/references/cursor-guard.schema.json

@@ -102,6 +102,36 @@
         }
       },
       "additionalProperties": false
+    },
+    "proactive_alert": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable V4 proactive change-velocity detection. When true, the auto-backup watcher monitors file change frequency and raises alerts when abnormal patterns are detected."
+    },
+    "alert_thresholds": {
+      "type": "object",
+      "description": "Thresholds for proactive change-velocity alerts (V4). Only effective when proactive_alert is true.",
+      "properties": {
+        "files_per_window": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 20,
+          "description": "Number of file changes within the time window that triggers an alert."
+        },
+        "window_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 10,
+          "description": "Sliding time window in seconds for counting file changes."
+        },
+        "cooldown_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 60,
+          "description": "Minimum seconds between consecutive alerts to avoid noise."
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

package/references/lib/auto-backup.js

@@ -2,13 +2,15 @@
 
 const fs = require('fs');
 const path = require('path');
+const { execFileSync } = require('child_process');
 const {
   color, loadConfig, gitAvailable, git, isGitRepo, gitDir: getGitDir,
   walkDir, filterFiles, buildManifest, loadManifest, saveManifest,
-  manifestChanged, createLogger,
+  manifestChanged, createLogger, unquoteGitPath,
 } = require('./utils');
 const { createGitSnapshot, createShadowCopy } = require('./core/snapshot');
 const { cleanShadowRetention, cleanGitRetention } = require('./core/backups');
+const { createChangeTracker, recordChange, checkAnomaly, saveAlert, clearExpiredAlert } = require('./core/anomaly');
 
 // ── Helpers ─────────────────────────────────────────────────────
 
@@ -123,11 +125,7 @@ async function runBackup(projectDir, intervalOverride) {
         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}`));
-        }
+        console.log(color.cyan(`[guard] Ref ${branchRef} does not exist yet — will be created on first snapshot.`));
       }
     }
 
@@ -153,6 +151,12 @@ async function runBackup(projectDir, intervalOverride) {
     logger.error(`Unhandled rejection: ${reason}`);
   });
 
+  // V4: Initialize change tracker for anomaly detection
+  let tracker = createChangeTracker(cfg);
+  if (cfg.proactive_alert) {
+    console.log(color.cyan(`[guard] Proactive alert: ON  (threshold: ${cfg.alert_thresholds.files_per_window} files / ${cfg.alert_thresholds.window_seconds}s)`));
+  }
+
   // Banner
   console.log('');
   console.log(color.cyan(`[guard] Watching '${projectDir}' every ${interval}s  (Ctrl+C to stop)`));
@@ -175,6 +179,7 @@ async function runBackup(projectDir, intervalOverride) {
           if (reload.loaded && !reload.error) {
             cfg = reload.cfg;
             cfgMtime = newMtime;
+            tracker = createChangeTracker(cfg);
             logger.info('Config reloaded (file changed)');
           }
         }
@@ -184,6 +189,7 @@ async function runBackup(projectDir, intervalOverride) {
     // Detect changes
     let hasChanges = false;
     let pendingManifest = null;
+    let lastManifest = null;
     try {
       if (repo) {
         const dirty = git(['status', '--porcelain'], { cwd: projectDir, allowFail: true });
@@ -192,8 +198,8 @@ async function runBackup(projectDir, intervalOverride) {
         const allFiles = walkDir(projectDir, projectDir);
         const filtered = filterFiles(allFiles, cfg);
         const newManifest = buildManifest(filtered);
-        const oldManifest = loadManifest(backupDir);
-        hasChanges = manifestChanged(oldManifest, newManifest);
+        lastManifest = loadManifest(backupDir);
+        hasChanges = manifestChanged(lastManifest, newManifest);
         if (hasChanges) pendingManifest = newManifest;
       }
     } catch (e) {
@@ -202,6 +208,56 @@ async function runBackup(projectDir, intervalOverride) {
     }
     if (!hasChanges) continue;
 
+    // V4: Record change event and check for anomalies
+    let changedFileCount = 0;
+    if (repo) {
+      // Use execFileSync directly — git() helper's trim() strips leading spaces
+      // from porcelain output, corrupting the first line when it starts with ' '.
+      let porcelain = '';
+      try {
+        porcelain = execFileSync('git', ['status', '--porcelain'], {
+          cwd: projectDir, stdio: 'pipe', encoding: 'utf-8',
+        });
+      } catch { /* ignore */ }
+      if (porcelain) {
+        const lines = porcelain.split('\n').filter(Boolean);
+        if (cfg.protect.length === 0 && cfg.ignore.length === 0) {
+          changedFileCount = lines.length;
+        } else {
+          const changedPaths = lines.map(line => {
+            const filePart = line.substring(3);
+            const arrowIdx = filePart.indexOf(' -> ');
+            const raw = arrowIdx >= 0 ? filePart.substring(arrowIdx + 4) : filePart;
+            return unquoteGitPath(raw);
+          });
+          const fakeFiles = changedPaths.map(rel => ({ rel, full: path.join(projectDir, rel) }));
+          changedFileCount = filterFiles(fakeFiles, cfg).length;
+        }
+      }
+    } else if (pendingManifest) {
+      if (!lastManifest) {
+        changedFileCount = Object.keys(pendingManifest).length;
+      } else {
+        const newKeys = new Set(Object.keys(pendingManifest));
+        const oldKeys = new Set(Object.keys(lastManifest));
+        let diffCount = 0;
+        for (const k of newKeys) {
+          if (!oldKeys.has(k) || lastManifest[k].mtimeMs !== pendingManifest[k].mtimeMs || lastManifest[k].size !== pendingManifest[k].size) diffCount++;
+        }
+        for (const k of oldKeys) {
+          if (!newKeys.has(k)) diffCount++;
+        }
+        changedFileCount = diffCount;
+      }
+    }
+
+    recordChange(tracker, changedFileCount);
+    const anomalyResult = checkAnomaly(tracker);
+    if (anomalyResult.anomaly && anomalyResult.alert && !anomalyResult.suppressed) {
+      saveAlert(projectDir, anomalyResult.alert);
+      logger.warn(`ALERT: ${anomalyResult.alert.fileCount} files changed in ${anomalyResult.alert.windowSeconds}s (threshold: ${anomalyResult.alert.threshold})`);
+    }
+
     // Git snapshot via Core
     if ((cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both') && repo) {
       const snapResult = createGitSnapshot(projectDir, cfg, { branchRef });
@@ -250,6 +306,8 @@ async function runBackup(projectDir, intervalOverride) {
           logger.log(`Git retention (${gitRetResult.mode}): rebuilt branch with ${gitRetResult.kept} newest snapshots, pruned ${gitRetResult.pruned}. Run 'git gc' to reclaim space.`, 'gray');
         }
       }
+
+      clearExpiredAlert(projectDir);
     }
   }
 }