cursor-guard 4.2.2 → 4.3.1

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.2.2",
+  "version": "4.3.1",
   "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/dashboard/public/app.js

@@ -88,6 +88,18 @@ const I18N = {
     'drawer.field.hash':    'Commit Hash',
     'drawer.field.path':    'Path',
     'drawer.field.message': 'Message',
+    'drawer.field.filesChanged': 'Files Changed',
+    'drawer.field.summary': 'Change Summary',
+    'drawer.field.trigger': 'Trigger',
+    'trigger.auto':         'Auto (scheduled)',
+    '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',
@@ -254,6 +266,18 @@ const I18N = {
     'drawer.field.hash':    '提交 Hash',
     'drawer.field.path':    '路径',
     'drawer.field.message': '消息',
+    'drawer.field.filesChanged': '变更文件数',
+    'drawer.field.summary': '变更摘要',
+    'drawer.field.trigger': '触发方式',
+    'trigger.auto':         '自动（定时）',
+    'trigger.manual':       '手动（Agent）',
+    'trigger.pre-restore':  '恢复前快照',
+    'backups.col.summary':  '变更',
+    'summary.modified':     '修改',
+    'summary.added':        '新增',
+    'summary.deleted':      '删除',
+    'summary.renamed':      '重命名',
+    'summary.files':        '个文件',
 
     'error.fetchFailed':    '数据拉取失败',
     'error.sectionFailed':  '此区块加载失败',
@@ -779,6 +803,31 @@ 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} ${t('summary.files')}</span>`);
+  if (b.trigger) parts.push(`<span class="badge badge-trigger">${t('trigger.' + b.trigger)}</span>`);
+  if (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>';
+}
+
 function renderBackupTable(backups) {
   if (!Array.isArray(backups)) {
     $('#backup-table-wrap').innerHTML = `<div class="error-panel">${t('error.sectionFailed')}</div>`;
@@ -795,10 +844,12 @@ function renderBackupTable(backups) {
 
   const rows = state.filteredBackups.map((b, i) => {
     const badgeClass = b.type.startsWith('git') ? (b.type.includes('pre') ? 'badge-pre' : 'badge-git') : (b.type.includes('pre') ? 'badge-pre' : 'badge-shadow');
+    const summaryCell = formatSummaryCell(b);
     return `<tr data-bi="${i}">
       <td><div>${esc(formatTime(b.timestamp))}</div><div class="text-muted text-sm">${esc(relativeTime(b.timestamp))}</div></td>
       <td><span class="badge ${badgeClass}">${t('type.' + b.type)}</span></td>
       <td class="text-mono">${esc(b.shortHash || b.timestamp || '-')}</td>
+      <td class="backup-summary-cell">${summaryCell}</td>
     </tr>`;
   }).join('');
 
@@ -808,6 +859,7 @@ function renderBackupTable(backups) {
         <th>${t('backups.col.time')}</th>
         <th>${t('backups.col.type')}</th>
         <th>${t('backups.col.ref')}</th>
+        <th>${t('backups.col.summary')}</th>
       </tr></thead>
       <tbody>${rows}</tbody>
     </table>
@@ -895,10 +947,13 @@ function openRestoreDrawer(backup) {
     { key: 'drawer.field.time', val: formatTime(backup.timestamp) },
     { key: 'drawer.field.type', val: t('type.' + backup.type) },
   ];
+  if (backup.trigger) fields.push({ key: 'drawer.field.trigger', val: t('trigger.' + backup.trigger) });
+  if (backup.filesChanged != null) fields.push({ key: 'drawer.field.filesChanged', val: String(backup.filesChanged) });
   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.message) fields.push({ key: 'drawer.field.message', val: backup.message });
+  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/dashboard/public/style.css

@@ -244,9 +244,14 @@ main {
 .badge-warn { background: var(--yellow-bg); color: var(--yellow); }
 .badge-fail { background: var(--red-bg); color: var(--red); }
 
-.badge-git    { background: var(--blue-bg); color: var(--blue); }
-.badge-shadow { background: var(--amber-bg); color: var(--amber); }
-.badge-pre    { background: var(--purple-bg); color: var(--purple); }
+.badge-git     { background: var(--blue-bg); color: var(--blue); }
+.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; }
+
+.backup-summary-cell { max-width: 280px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.backup-summary-cell .badge-trigger { margin-right: 4px; }
+.backup-summary-cell .text-sm { font-size: 0.75rem; }
 
 /* ── Stats Row ────────────────────────────────────────────── */
 

package/references/lib/auto-backup.js

@@ -210,10 +210,10 @@ async function runBackup(projectDir, intervalOverride) {
 
     // V4: Record change event and check for anomalies
     let changedFileCount = 0;
+    let porcelain = '';
     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',
@@ -260,7 +260,41 @@ async function runBackup(projectDir, intervalOverride) {
 
     // Git snapshot via Core
     if ((cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both') && repo) {
-      const snapResult = createGitSnapshot(projectDir, cfg, { branchRef });
+      const context = { trigger: 'auto', changedFileCount };
+      if (porcelain) {
+        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') {
         let msg = `Git snapshot ${snapResult.shortHash} (${snapResult.fileCount} files)`;
         if (snapResult.secretsExcluded) {

package/references/lib/core/backups.js

@@ -41,6 +41,20 @@ function entryToMs(entry) {
   return d ? d.getTime() : 0;
 }
 
+function parseCommitTrailers(body) {
+  if (!body) return {};
+  const result = {};
+  for (const line of body.split('\n')) {
+    const m = line.match(/^(Files-Changed|Summary|Trigger):\s*(.+)$/);
+    if (m) {
+      const key = m[1] === 'Files-Changed' ? 'filesChanged'
+        : m[1] === 'Summary' ? 'summary' : 'trigger';
+      result[key] = key === 'filesChanged' ? parseInt(m[2], 10) : m[2];
+    }
+  }
+  return result;
+}
+
 // ── List backups ────────────────────────────────────────────────
 
 /**
@@ -52,7 +66,7 @@ function entryToMs(entry) {
  * @param {string} [opts.file] - Filter to commits touching this relative path
  * @param {string} [opts.before] - Time boundary (e.g. '10 minutes ago', ISO string)
  * @param {number} [opts.limit=20] - Max total results
- * @returns {{ sources: Array<{type: string, ref?: string, commitHash?: string, shortHash?: string, timestamp?: string, message?: string, path?: string}> }}
+ * @returns {{ sources: Array<{type: string, ref?: string, commitHash?: string, shortHash?: string, timestamp?: string, message?: string, path?: string, filesChanged?: number, summary?: string, trigger?: string}> }}
  */
 function listBackups(projectDir, opts = {}) {
   const limit = opts.limit || 20;
@@ -74,24 +88,27 @@ function listBackups(projectDir, opts = {}) {
     const autoRef = 'refs/guard/auto-backup';
     const autoExists = git(['rev-parse', '--verify', autoRef], { cwd: projectDir, allowFail: true });
     if (autoExists) {
-      const logArgs = ['log', autoRef, `--format=%H %aI %s`, `-${limit}`, '--grep=^guard:'];
+      const logArgs = ['log', autoRef, '--format=%H\x1f%aI\x1f%B\x1e', `-${limit}`, '--grep=^guard:'];
       if (opts.before) logArgs.push(`--before=${opts.before}`);
       if (opts.file) logArgs.push('--', opts.file);
       const out = git(logArgs, { cwd: projectDir, allowFail: true });
       if (out) {
-        for (const line of out.split('\n').filter(Boolean)) {
-          const firstSpace = line.indexOf(' ');
-          const secondSpace = line.indexOf(' ', firstSpace + 1);
-          const hash = line.substring(0, firstSpace);
-          const timestamp = line.substring(firstSpace + 1, secondSpace);
-          const message = line.substring(secondSpace + 1);
+        for (const record of out.split('\x1e').filter(r => r.trim())) {
+          const parts = record.split('\x1f');
+          if (parts.length < 3) continue;
+          const hash = parts[0].trim();
+          const timestamp = parts[1];
+          const body = parts[2];
+          const subject = body.split('\n')[0];
+          const trailers = parseCommitTrailers(body);
           sources.push({
             type: 'git-auto-backup',
             ref: autoRef,
             commitHash: hash,
             shortHash: hash.substring(0, 7),
             timestamp,
-            message,
+            message: subject,
+            ...trailers,
           });
         }
       }
@@ -112,20 +129,32 @@ function listBackups(projectDir, opts = {}) {
           const ms = Date.parse(timestamp);
           if (!isNaN(ms) && ms > beforeDate.getTime()) continue;
         }
-        sources.push({
+        const entry = {
           type: 'git-pre-restore',
           ref,
           commitHash: hash,
           shortHash: hash.substring(0, 7),
           timestamp,
-        });
+        };
+        const prBody = git(['log', '-1', '--format=%B', hash], { cwd: projectDir, allowFail: true });
+        if (prBody) {
+          const prSubject = prBody.split('\n')[0];
+          if (prSubject) entry.message = prSubject;
+          Object.assign(entry, parseCommitTrailers(prBody));
+        }
+        sources.push(entry);
       }
     }
 
     // Agent snapshot ref
     const snapshotHash = git(['rev-parse', '--verify', 'refs/guard/snapshot'], { cwd: projectDir, allowFail: true });
     if (snapshotHash) {
-      const ts = git(['log', '-1', '--format=%aI', 'refs/guard/snapshot'], { cwd: projectDir, allowFail: true });
+      const snapLog = git(['log', '-1', '--format=%aI\x1f%B', 'refs/guard/snapshot'], { cwd: projectDir, allowFail: true });
+      const snapParts = snapLog ? snapLog.split('\x1f') : [];
+      const ts = snapParts[0] || null;
+      const snapBody = snapParts[1] || '';
+      const snapTrailers = parseCommitTrailers(snapBody);
+      const snapSubject = snapBody.split('\n')[0] || '';
       const include = !beforeDate || (ts && Date.parse(ts) <= beforeDate.getTime());
       if (include) {
         sources.push({
@@ -133,7 +162,9 @@ function listBackups(projectDir, opts = {}) {
           ref: 'refs/guard/snapshot',
           commitHash: snapshotHash,
           shortHash: snapshotHash.substring(0, 7),
-          timestamp: ts || null,
+          timestamp: ts,
+          message: snapSubject || undefined,
+          ...snapTrailers,
         });
       }
     }

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, '/');
@@ -370,8 +370,10 @@ function createPreRestoreSnapshot(projectDir, scope) {
       return { status: 'skipped', reason: 'no changes to preserve' };
     }
 
+    let msg = `guard: pre-restore snapshot ${ts}`;
+    msg += '\n\nTrigger: pre-restore';
     const commitHash = execFileSync('git', [
-      'commit-tree', tree, '-p', head, '-m', `guard: pre-restore snapshot ${ts}`,
+      'commit-tree', tree, '-p', head, '-m', msg,
     ], { cwd, stdio: 'pipe', encoding: 'utf-8' }).trim();
 
     if (!commitHash) return { status: 'error', error: 'commit-tree returned empty' };

package/references/lib/core/snapshot.js

@@ -52,6 +52,24 @@ function removeSecretsFromIndex(secretsPatterns, cwd, env) {
   return excluded;
 }
 
+// ── Commit message builder ──────────────────────────────────────
+
+function buildCommitMessage(ts, opts) {
+  if (opts.message && !opts.context) return opts.message;
+
+  const ctx = opts.context || {};
+  const countTag = ctx.changedFileCount ? ` (${ctx.changedFileCount} files)` : '';
+  const subject = opts.message || `guard: auto-backup ${ts}${countTag}`;
+
+  const trailers = [];
+  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 (trailers.length === 0) return subject;
+  return subject + '\n\n' + trailers.join('\n');
+}
+
 // ── Git snapshot ────────────────────────────────────────────────
 
 /**
@@ -63,6 +81,10 @@ function removeSecretsFromIndex(secretsPatterns, cwd, env) {
  * @param {object} [opts]
  * @param {string} [opts.branchRef='refs/guard/auto-backup']
  * @param {string} [opts.message] - Commit message (auto-generated if omitted)
+ * @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")
  * @returns {{ status: 'created'|'skipped'|'error', commitHash?: string, shortHash?: string, fileCount?: number, reason?: string, error?: string, secretsExcluded?: string[] }}
  */
 function createGitSnapshot(projectDir, cfg, opts = {}) {
@@ -72,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 });
@@ -109,7 +133,7 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
     }
 
     const ts = formatTimestamp(new Date());
-    const msg = opts.message || `guard: auto-backup ${ts}`;
+    const msg = buildCommitMessage(ts, opts);
     const commitArgs = parentHash
       ? ['commit-tree', newTree, '-p', parentHash, '-m', msg]
       : ['commit-tree', newTree, '-m', msg];
@@ -142,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 */ }
   }
 }
 

package/references/mcp/server.js

@@ -112,6 +112,7 @@ server.tool(
       results.git = createGitSnapshot(resolved, cfg, {
         branchRef: 'refs/guard/snapshot',
         message: message || `guard: manual snapshot ${new Date().toISOString()}`,
+        context: { trigger: 'manual' },
       });
     }