cursor-guard 4.3.1 → 4.3.3

package/README.md

@@ -375,6 +375,57 @@ The skill activates on these signals:
 
 ---
 
+## Changelog
+
+### v4.3.3
+
+- **Feature**: Intent context for snapshots — `snapshot_now` now accepts `intent`, `agent`, and `session` parameters, stored as Git commit trailers to form an audit trail per operation
+- **Feature**: Dashboard displays intent badge in backup table and full intent/agent/session fields in restore-point drawer
+- **Improve**: `parseCommitTrailers` refactored to a data-driven map, supporting all 6 trailer fields (Files-Changed, Summary, Trigger, Intent, Agent, Session)
+- **Improve**: SKILL.md updated to guide AI agents to pass `intent` describing the operation about to happen
+
+### 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,57 @@ node references\dashboard\server.js --path "D:\MyProject"
 
 ---
 
+## 更新日志
+
+### v4.3.3
+
+- **功能**：快照意图上下文——`snapshot_now` 新增 `intent`（操作意图）、`agent`（AI 模型）、`session`（会话 ID）参数，作为 Git commit trailer 存储，形成按操作事件的审计链
+- **功能**：仪表盘备份表格显示意图徽章，恢复点抽屉完整展示 intent/agent/session 字段
+- **改进**：`parseCommitTrailers` 重构为数据驱动映射表，支持全部 6 个 trailer 字段
+- **改进**：SKILL.md 更新指引，要求 AI agent 在调用 `snapshot_now` 时传入 `intent` 描述即将执行的操作
+
+### 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

@@ -147,14 +147,18 @@ When the target file of an edit **falls outside the protected scope**, the agent
 
 > **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:
+> **Best practice — intent context**: Always provide `intent` to describe *what operation you are about to perform and why*. This creates an audit trail so the user can later understand "what was the AI doing when this backup was made". Also pass `message` for the commit subject. Example:
 > ```json
 > {
 >   "path": "/project",
 >   "strategy": "git",
->   "message": "guard: before refactoring auth middleware — moving session logic from app.js to middleware/auth.js"
+>   "message": "guard: before refactoring auth middleware",
+>   "intent": "用户要求将 app.js 中的 session 逻辑拆分到 middleware/auth.js，涉及 3 个函数重写",
+>   "agent": "claude-4-opus",
+>   "session": "6290c87f"
 > }
 > ```
+> The `intent`, `agent`, and `session` fields are stored as Git commit trailers and displayed in the dashboard restore-point list and detail drawer, forming a complete audit trail per operation.
 
 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.1",
+  "version": "4.3.3",
   "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

@@ -100,6 +100,9 @@ const I18N = {
     'summary.deleted':      'Deleted',
     'summary.renamed':      'Renamed',
     'summary.files':        'files',
+    'drawer.field.intent':  'Intent',
+    'drawer.field.agent':   'Agent',
+    'drawer.field.session': 'Session',
 
     'error.fetchFailed':    'Failed to fetch data',
     'error.sectionFailed':  'This section failed to load',
@@ -278,6 +281,9 @@ const I18N = {
     'summary.deleted':      '删除',
     'summary.renamed':      '重命名',
     'summary.files':        '个文件',
+    'drawer.field.intent':  '操作意图',
+    'drawer.field.agent':   'AI 模型',
+    'drawer.field.session': '会话 ID',
 
     'error.fetchFailed':    '数据拉取失败',
     'error.sectionFailed':  '此区块加载失败',
@@ -821,7 +827,10 @@ function formatSummaryCell(b) {
     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:')) {
+  if (b.intent) {
+    const intentShort = b.intent.length > 60 ? b.intent.substring(0, 57) + '...' : b.intent;
+    parts.push(`<span class="badge badge-intent">${esc(intentShort)}</span>`);
+  } else 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>`);
   }
@@ -952,6 +961,9 @@ function openRestoreDrawer(backup) {
   if (backup.ref) fields.push({ key: 'drawer.field.ref', val: backup.ref });
   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.intent) fields.push({ key: 'drawer.field.intent', val: backup.intent });
+  if (backup.agent) fields.push({ key: 'drawer.field.agent', val: backup.agent });
+  if (backup.session) fields.push({ key: 'drawer.field.session', val: backup.session });
   if (backup.message) fields.push({ key: 'drawer.field.message', val: backup.message });
   if (backup.summary) fields.push({ key: 'drawer.field.summary', val: translateSummary(backup.summary) });
 

package/references/dashboard/public/style.css

@@ -248,9 +248,11 @@ main {
 .badge-shadow  { background: var(--amber-bg); color: var(--amber); }
 .badge-pre     { background: var(--purple-bg); color: var(--purple); }
 .badge-trigger { background: var(--bg-tertiary); color: var(--text-secondary); font-size: 0.7rem; }
+.badge-intent  { background: var(--blue-bg); color: var(--blue); font-size: 0.7rem; max-width: 220px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; display: inline-block; vertical-align: middle; }
 
-.backup-summary-cell { max-width: 280px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.backup-summary-cell { max-width: 340px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .backup-summary-cell .badge-trigger { margin-right: 4px; }
+.backup-summary-cell .badge-intent  { margin-left: 4px; }
 .backup-summary-cell .text-sm { font-size: 0.75rem; }
 
 /* ── Stats Row ────────────────────────────────────────────── */

package/references/lib/core/backups.js

@@ -41,15 +41,24 @@ function entryToMs(entry) {
   return d ? d.getTime() : 0;
 }
 
+const TRAILER_MAP = {
+  'Files-Changed': { key: 'filesChanged', parse: v => parseInt(v, 10) },
+  'Summary':       { key: 'summary' },
+  'Trigger':       { key: 'trigger' },
+  'Intent':        { key: 'intent' },
+  'Agent':         { key: 'agent' },
+  'Session':       { key: 'session' },
+};
+
 function parseCommitTrailers(body) {
   if (!body) return {};
   const result = {};
+  const pattern = new RegExp(`^(${Object.keys(TRAILER_MAP).join('|')}):\\s*(.+)$`);
   for (const line of body.split('\n')) {
-    const m = line.match(/^(Files-Changed|Summary|Trigger):\s*(.+)$/);
+    const m = line.match(pattern);
     if (m) {
-      const key = m[1] === 'Files-Changed' ? 'filesChanged'
-        : m[1] === 'Summary' ? 'summary' : 'trigger';
-      result[key] = key === 'filesChanged' ? parseInt(m[2], 10) : m[2];
+      const def = TRAILER_MAP[m[1]];
+      result[def.key] = def.parse ? def.parse(m[2]) : m[2];
     }
   }
   return result;

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/snapshot.js

@@ -65,6 +65,9 @@ function buildCommitMessage(ts, opts) {
   if (ctx.changedFileCount != null) trailers.push(`Files-Changed: ${ctx.changedFileCount}`);
   if (ctx.summary) trailers.push(`Summary: ${ctx.summary}`);
   if (ctx.trigger) trailers.push(`Trigger: ${ctx.trigger}`);
+  if (ctx.intent) trailers.push(`Intent: ${ctx.intent}`);
+  if (ctx.agent) trailers.push(`Agent: ${ctx.agent}`);
+  if (ctx.session) trailers.push(`Session: ${ctx.session}`);
 
   if (trailers.length === 0) return subject;
   return subject + '\n\n' + trailers.join('\n');
@@ -84,7 +87,10 @@ function buildCommitMessage(ts, opts) {
  * @param {object} [opts.context] - Backup context metadata
  * @param {string} [opts.context.trigger] - 'auto' | 'manual' | 'pre-restore'
  * @param {number} [opts.context.changedFileCount] - Number of changed files
- * @param {string} [opts.context.summary] - Short change summary (e.g. "M src/app.js, A new.ts")
+ * @param {string} [opts.context.summary] - Short change summary (e.g. "Modified 3: a.js, b.js; Added 1: c.js")
+ * @param {string} [opts.context.intent] - Why this snapshot was created (e.g. "refactoring auth middleware")
+ * @param {string} [opts.context.agent] - AI model identifier (e.g. "claude-4-opus")
+ * @param {string} [opts.context.session] - Conversation/session ID
  * @returns {{ status: 'created'|'skipped'|'error', commitHash?: string, shortHash?: string, fileCount?: number, reason?: string, error?: string, secretsExcluded?: string[] }}
  */
 function createGitSnapshot(projectDir, cfg, opts = {}) {

package/references/mcp/server.js

@@ -92,8 +92,11 @@ server.tool(
     strategy: z.enum(['git', 'shadow', 'both']).optional().describe('Backup strategy (default: from config, or "git")'),
     message: z.string().optional().describe('Custom commit message for git snapshot'),
     scope: z.enum(['protected', 'all']).optional().describe('Snapshot scope: "protected" = only files matching protect patterns (default when protect is configured); "all" = all files regardless of protect config'),
+    intent: z.string().optional().describe('Why this snapshot is being created — describe the operation about to happen (e.g. "refactoring auth middleware to use JWT")'),
+    agent: z.string().optional().describe('AI model identifier (e.g. "claude-4-opus")'),
+    session: z.string().optional().describe('Conversation or session ID for audit trail'),
   },
-  async ({ path: projectPath, strategy, message, scope }) => {
+  async ({ path: projectPath, strategy, message, scope, intent, agent, session }) => {
     const resolved = path.resolve(projectPath);
     const { loadConfig } = require('../lib/utils');
     const { cfg } = loadConfig(resolved);
@@ -109,10 +112,14 @@ server.tool(
     const results = {};
 
     if (effectiveStrategy === 'git' || effectiveStrategy === 'both') {
+      const context = { trigger: 'manual' };
+      if (intent) context.intent = intent;
+      if (agent) context.agent = agent;
+      if (session) context.session = session;
       results.git = createGitSnapshot(resolved, cfg, {
         branchRef: 'refs/guard/snapshot',
         message: message || `guard: manual snapshot ${new Date().toISOString()}`,
-        context: { trigger: 'manual' },
+        context,
       });
     }