cursor-guard 4.3.0 → 4.3.2

package/README.md

@@ -375,6 +375,50 @@ The skill activates on these signals:
 
 ---
 
+## Changelog
+
+### v4.3.2
+
+- **Fix**: `cursor-guard-init` now adds `node_modules/` (root-level) to `.gitignore` — prevents `git add -A` from scanning thousands of npm dependency files after `npm install cursor-guard --save-dev`
+- **Improve**: Doctor "MCP version" mismatch warning now includes the reload keybinding (`Ctrl+Shift+P -> "Developer: Reload Window"`) for faster action
+
+### v4.3.1
+
+- **Fix**: `restore_project` now protects `.gitignore` — added to `GUARD_CONFIGS` so it is restored from HEAD after recovery, preventing post-restore full-tree scans (2500+ files)
+- **Fix**: `cursor-guard-index.lock` cleanup — `createGitSnapshot` now removes stale `.lock` files on entry and in the `finally` block, preventing lock file remnants from blocking subsequent operations
+- **Improve**: Auto-backup summary now filtered by `protect`/`ignore` patterns, excluding `.cursor/skills/` and other non-protected files
+- **Improve**: Summary format changed from flat `M file1, A file2` to categorized `Modified 3: a.js; Added 1: b.js` with i18n support
+- **Improve**: Manual snapshot `message` (from `snapshot_now`) now displayed in dashboard backup table and restore-point drawer
+- **Improve**: SKILL.md adds best-practice guidance for AI agents to provide descriptive `message` when calling `snapshot_now`
+
+### v4.3.0
+
+- **Feature**: Backup context metadata — structured Git commit messages with `Files-Changed`, `Summary`, and `Trigger` trailers
+- **Feature**: `listBackups` parses commit trailers and returns `filesChanged`, `summary`, `trigger` fields
+- **Feature**: Dashboard backup table adds "Changes" column; restore-point drawer shows trigger, files changed, and summary
+
+### v4.2.2
+
+- **Fix**: `restore_project` now protects `.cursor-guard.json` during restore (prevents config loss)
+- **Fix**: Post-restore HEAD recovery loop extended to restore both `.cursor/` and `.cursor-guard.json`
+- **Improve**: `cursor-guard-init` now reminds users to `git commit` after installation in Git repos
+
+### v4.2.1
+
+- **Fix**: `t()` function uses `replaceAll` for i18n placeholder substitution
+- **Fix**: Removed unused `loadActiveAlert` import from dashboard server
+- **Fix**: Added `git-snapshot` type to dashboard filter bar
+- **Fix**: Replaced `&&` with `;` in `detail.mcp_no_sdk` i18n string for cross-platform compatibility
+- **Fix**: Deduplicated `sdkCandidates` in `doctor.js`
+
+### v4.2.0
+
+- **Feature**: Web dashboard — local read-only UI with health overview, backup table, restore-point drawers, diagnostics, protection scope
+- **Feature**: Dual-language (zh-CN / en-US) with full i18n coverage including doctor checks, health issues, alert messages
+- **Feature**: Multi-project support via CLI `--path` args and frontend project selector
+
+---
+
 ## Known Limitations
 
 - **Binary files**: Git diffs and snapshots work on text files. Binary files (images, compiled assets) are stored but cannot be meaningfully diffed or partially restored.

package/README.zh-CN.md

@@ -375,6 +375,50 @@ node references\dashboard\server.js --path "D:\MyProject"
 
 ---
 
+## 更新日志
+
+### v4.3.2
+
+- **修复**：`cursor-guard-init` 现在会将根目录 `node_modules/` 加入 `.gitignore`——防止 `npm install cursor-guard --save-dev` 后 `git add -A` 扫描数千个依赖文件导致极度缓慢
+- **改进**：Doctor "MCP version" 版本不一致警告现在包含重载快捷键提示（`Ctrl+Shift+P -> "Developer: Reload Window"`），方便快速操作
+
+### v4.3.1
+
+- **修复**：`restore_project` 现在保护 `.gitignore`——加入 `GUARD_CONFIGS`，恢复后从 HEAD 还原，防止 `.gitignore` 丢失导致全量扫描（2500+ 文件）
+- **修复**：`cursor-guard-index.lock` 清理——`createGitSnapshot` 在入口和 `finally` 块中清除过期 `.lock` 文件，防止锁文件残留阻塞后续操作
+- **改进**：自动备份 summary 现按 `protect`/`ignore` 模式过滤，排除 `.cursor/skills/` 等非保护文件
+- **改进**：summary 格式从扁平的 `M file1, A file2` 改为分类格式 `修改 3: a.js; 新增 1: b.js`，支持中英双语
+- **改进**：手动快照的 `message`（来自 `snapshot_now`）现显示在仪表盘备份表格和恢复点抽屉中
+- **改进**：SKILL.md 新增最佳实践指引，建议 AI agent 在调用 `snapshot_now` 时传入描述性 `message`
+
+### v4.3.0
+
+- **功能**：备份上下文元数据——Git commit 消息使用结构化 trailer（`Files-Changed`、`Summary`、`Trigger`）
+- **功能**：`listBackups` 解析 commit trailer，返回 `filesChanged`、`summary`、`trigger` 字段
+- **功能**：仪表盘备份表格新增"变更"列；恢复点抽屉展示触发方式、变更文件数、变更摘要
+
+### v4.2.2
+
+- **修复**：`restore_project` 恢复时保护 `.cursor-guard.json`（防止配置丢失）
+- **修复**：恢复后 HEAD 恢复循环扩展为同时还原 `.cursor/` 和 `.cursor-guard.json`
+- **改进**：`cursor-guard-init` 在 Git 仓库中安装后提醒用户执行 `git commit`
+
+### v4.2.1
+
+- **修复**：`t()` 函数改用 `replaceAll` 替换 i18n 占位符
+- **修复**：移除仪表盘 server 中未使用的 `loadActiveAlert` 导入
+- **修复**：仪表盘过滤栏补充 `git-snapshot` 类型选项
+- **修复**：`detail.mcp_no_sdk` i18n 字符串中 `&&` 替换为 `;`，确保跨平台兼容
+- **修复**：`doctor.js` 中 `sdkCandidates` 去重
+
+### v4.2.0
+
+- **功能**：Web 仪表盘——本地只读 UI，健康总览、备份表格、恢复点抽屉、诊断、保护范围
+- **功能**：中英双语（zh-CN / en-US），完整 i18n 覆盖含 doctor 检查项、健康问题、告警消息
+- **功能**：多项目支持——CLI `--path` 参数 + 前端项目选择器
+
+---
+
 ## 已知限制
 
 - **二进制文件**：Git 快照可以存储二进制文件（图片、编译产物），但无法进行有意义的 diff 或部分恢复。

package/SKILL.md

@@ -146,6 +146,15 @@ When the target file of an edit **falls outside the protected scope**, the agent
 **Before any High-risk operation on a protected file:**
 
 > **MCP shortcut**: if `snapshot_now` tool is available, call it with `{ "path": "<project>", "strategy": "git" }` instead of the shell commands below. The tool handles temp index, secrets exclusion, and ref creation internally, and returns `{ "git": { "status": "created", "commitHash": "...", "shortHash": "..." } }`. Report the `shortHash` to the user and proceed.
+>
+> **Best practice — descriptive messages**: Always provide a meaningful `message` parameter that describes *why* this snapshot is being created and *what* changes are at risk. This message appears in the dashboard restore-point list, helping users identify which snapshot to restore from. Example:
+> ```json
+> {
+>   "path": "/project",
+>   "strategy": "git",
+>   "message": "guard: before refactoring auth middleware — moving session logic from app.js to middleware/auth.js"
+> }
+> ```
 
 Use a **temporary index and dedicated ref** so the user's staged/unstaged state is never touched:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.3.0",
+  "version": "4.3.2",
   "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",

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

@@ -81,7 +81,7 @@ try {
 // 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/'];
+const entries = ['node_modules/', '.cursor/skills/**/node_modules/'];
 let gitignoreUpdated = false;
 if (!isGlobal) {
   let existing = '';

package/references/dashboard/public/app.js

@@ -95,6 +95,11 @@ const I18N = {
     'trigger.manual':       'Manual (agent)',
     'trigger.pre-restore':  'Pre-Restore',
     'backups.col.summary':  'Changes',
+    'summary.modified':     'Modified',
+    'summary.added':        'Added',
+    'summary.deleted':      'Deleted',
+    'summary.renamed':      'Renamed',
+    'summary.files':        'files',
 
     'error.fetchFailed':    'Failed to fetch data',
     'error.sectionFailed':  'This section failed to load',
@@ -268,6 +273,11 @@ const I18N = {
     'trigger.manual':       '手动（Agent）',
     'trigger.pre-restore':  '恢复前快照',
     'backups.col.summary':  '变更',
+    'summary.modified':     '修改',
+    'summary.added':        '新增',
+    'summary.deleted':      '删除',
+    'summary.renamed':      '重命名',
+    'summary.files':        '个文件',
 
     'error.fetchFailed':    '数据拉取失败',
     'error.sectionFailed':  '此区块加载失败',
@@ -793,14 +803,28 @@ function renderFilterBar() {
   ).join('');
 }
 
+function translateSummary(raw) {
+  if (!raw) return raw;
+  return raw
+    .replace(/\bModified (\d+)/g, (_, n) => `${t('summary.modified')} ${n}`)
+    .replace(/\bAdded (\d+)/g, (_, n) => `${t('summary.added')} ${n}`)
+    .replace(/\bDeleted (\d+)/g, (_, n) => `${t('summary.deleted')} ${n}`)
+    .replace(/\bRenamed (\d+)/g, (_, n) => `${t('summary.renamed')} ${n}`);
+}
+
 function formatSummaryCell(b) {
   const parts = [];
-  if (b.filesChanged != null) parts.push(`<span class="text-sm">${b.filesChanged} files</span>`);
+  if (b.filesChanged != null) parts.push(`<span class="text-sm">${b.filesChanged} ${t('summary.files')}</span>`);
   if (b.trigger) parts.push(`<span class="badge badge-trigger">${t('trigger.' + b.trigger)}</span>`);
   if (b.summary) {
-    const short = b.summary.length > 60 ? b.summary.substring(0, 57) + '...' : b.summary;
+    const translated = translateSummary(b.summary);
+    const short = translated.length > 80 ? translated.substring(0, 77) + '...' : translated;
     parts.push(`<span class="text-muted text-sm">${esc(short)}</span>`);
   }
+  if (b.message && !b.message.startsWith('guard:')) {
+    const msgShort = b.message.length > 50 ? b.message.substring(0, 47) + '...' : b.message;
+    parts.push(`<span class="text-muted text-sm">${esc(msgShort)}</span>`);
+  }
   return parts.length > 0 ? parts.join(' ') : '<span class="text-muted text-sm">-</span>';
 }
 
@@ -929,7 +953,7 @@ function openRestoreDrawer(backup) {
   if (backup.commitHash) fields.push({ key: 'drawer.field.hash', val: backup.commitHash });
   if (backup.path) fields.push({ key: 'drawer.field.path', val: backup.path });
   if (backup.message) fields.push({ key: 'drawer.field.message', val: backup.message });
-  if (backup.summary) fields.push({ key: 'drawer.field.summary', val: backup.summary });
+  if (backup.summary) fields.push({ key: 'drawer.field.summary', val: translateSummary(backup.summary) });
 
   const refText = backup.ref || backup.shortHash || backup.timestamp || '';
   const jsonText = JSON.stringify(backup, null, 2);

package/references/lib/auto-backup.js

@@ -262,8 +262,37 @@ async function runBackup(projectDir, intervalOverride) {
     if ((cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both') && repo) {
       const context = { trigger: 'auto', changedFileCount };
       if (porcelain) {
-        const pLines = porcelain.split('\n').filter(Boolean).slice(0, 20);
-        context.summary = pLines.map(l => l.substring(0, 2).trim() + ' ' + l.substring(3)).join(', ');
+        let pLines = porcelain.split('\n').filter(Boolean);
+        if (cfg.protect.length > 0 || cfg.ignore.length > 0) {
+          pLines = pLines.filter(line => {
+            const filePart = line.substring(3);
+            const arrowIdx = filePart.indexOf(' -> ');
+            const raw = arrowIdx >= 0 ? filePart.substring(arrowIdx + 4) : filePart;
+            const rel = unquoteGitPath(raw);
+            const fakeFile = { rel, full: path.join(projectDir, rel) };
+            return filterFiles([fakeFile], cfg).length > 0;
+          });
+        }
+        if (pLines.length > 0) {
+          const groups = { M: [], A: [], D: [], R: [] };
+          for (const l of pLines) {
+            const code = l.substring(0, 2).trim();
+            const filePart = l.substring(3);
+            const arrowIdx = filePart.indexOf(' -> ');
+            const file = arrowIdx >= 0 ? filePart.substring(arrowIdx + 4) : filePart;
+            const key = code.startsWith('R') ? 'R'
+              : code.includes('D') ? 'D'
+              : code.includes('A') || code === '??' ? 'A'
+              : 'M';
+            groups[key].push(file);
+          }
+          const parts = [];
+          if (groups.M.length) parts.push(`Modified ${groups.M.length}: ${groups.M.slice(0, 5).join(', ')}`);
+          if (groups.A.length) parts.push(`Added ${groups.A.length}: ${groups.A.slice(0, 5).join(', ')}`);
+          if (groups.D.length) parts.push(`Deleted ${groups.D.length}: ${groups.D.slice(0, 5).join(', ')}`);
+          if (groups.R.length) parts.push(`Renamed ${groups.R.length}: ${groups.R.slice(0, 5).join(', ')}`);
+          context.summary = parts.join('; ');
+        }
       }
       const snapResult = createGitSnapshot(projectDir, cfg, { branchRef, context });
       if (snapResult.status === 'created') {

package/references/lib/core/doctor.js

@@ -266,7 +266,7 @@ function runDiagnostics(projectDir) {
     const memPkg = require('../../../package.json');
     if (diskPkg.version !== memPkg.version) {
       check('MCP version', 'WARN',
-        `running v${memPkg.version} but disk has v${diskPkg.version} — restart Cursor to load the new version`);
+        `running v${memPkg.version} but disk has v${diskPkg.version} — restart Cursor (Ctrl+Shift+P -> "Developer: Reload Window") to load the new version`);
     } else {
       check('MCP version', 'PASS', `v${memPkg.version}`);
     }

package/references/lib/core/restore.js

@@ -21,7 +21,7 @@ function validateRelativePath(file) {
 const VALID_SHADOW_SOURCE = /^\d{8}_\d{6}(_\d{3})?$|^pre-restore-\d{8}_\d{6}(_\d{3})?$/;
 
 const TOOL_DIRS = ['.cursor/', '.cursor\\'];
-const GUARD_CONFIGS = ['.cursor-guard.json'];
+const GUARD_CONFIGS = ['.cursor-guard.json', '.gitignore'];
 
 function isToolPath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');

package/references/lib/core/snapshot.js

@@ -94,9 +94,11 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
   if (!gDir) return { status: 'error', error: 'not a git repository' };
 
   const guardIndex = path.join(gDir, 'cursor-guard-index');
+  const guardIndexLock = guardIndex + '.lock';
   const env = { ...process.env, GIT_INDEX_FILE: guardIndex };
 
   try { fs.unlinkSync(guardIndex); } catch { /* doesn't exist */ }
+  try { fs.unlinkSync(guardIndexLock); } catch { /* doesn't exist */ }
 
   try {
     const parentHash = git(['rev-parse', '--verify', branchRef], { cwd, allowFail: true });
@@ -164,6 +166,7 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
     return { status: 'error', error: e.message };
   } finally {
     try { fs.unlinkSync(guardIndex); } catch { /* ignore */ }
+    try { fs.unlinkSync(guardIndexLock); } catch { /* ignore */ }
   }
 }