cursor-guard 4.2.1 → 4.3.0

package/package.json

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

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

@@ -110,7 +110,16 @@ 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('  ⚠  If MCP was already configured, restart Cursor (or Ctrl+Shift+P →');
+
+// Detect git repo and recommend committing
+let isGitRepoDir = false;
+try { isGitRepoDir = fs.existsSync(path.join(projectDir, '.git')); } catch { /* ignore */ }
+if (!isGlobal && isGitRepoDir) {
+  console.log('  ** Important: commit now to prevent restore from reverting the skill **');
+  console.log(`     git add .cursor/ .cursor-guard.json && git commit -m "chore: install cursor-guard"\n`);
+}
+
+console.log('  If MCP was already configured, restart Cursor (or Ctrl+Shift+P ->');
 console.log('     "Developer: Reload Window") to load the updated MCP server.\n');
 console.log('  Next steps:');
 console.log('  1. The skill activates automatically in Cursor Agent conversations.');

package/references/dashboard/public/app.js

@@ -88,6 +88,13 @@ 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',
 
     'error.fetchFailed':    'Failed to fetch data',
     'error.sectionFailed':  'This section failed to load',
@@ -254,6 +261,13 @@ 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':  '变更',
 
     'error.fetchFailed':    '数据拉取失败',
     'error.sectionFailed':  '此区块加载失败',
@@ -779,6 +793,17 @@ function renderFilterBar() {
   ).join('');
 }
 
+function formatSummaryCell(b) {
+  const parts = [];
+  if (b.filesChanged != null) parts.push(`<span class="text-sm">${b.filesChanged} 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;
+    parts.push(`<span class="text-muted text-sm">${esc(short)}</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 +820,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 +835,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 +923,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: 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,12 @@ 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) {
+        const pLines = porcelain.split('\n').filter(Boolean).slice(0, 20);
+        context.summary = pLines.map(l => l.substring(0, 2).trim() + ' ' + l.substring(3)).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,10 +21,13 @@ 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'];
 
 function isToolPath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
-  return TOOL_DIRS.some(d => normalized.startsWith(d));
+  if (TOOL_DIRS.some(d => normalized.startsWith(d))) return true;
+  if (GUARD_CONFIGS.includes(normalized)) return true;
+  return false;
 }
 
 function validateShadowSource(source) {
@@ -217,7 +220,7 @@ function previewProjectRestore(projectDir, source) {
 
     for (const f of files) {
       if (isToolPath(f.path)) {
-        f.warning = 'tool directory — restoring may downgrade cursor-guard or other tools';
+        f.warning = 'protected path — will be preserved from HEAD to prevent tool/config downgrade';
       }
     }
 
@@ -282,14 +285,16 @@ function executeProjectRestore(projectDir, source, opts = {}) {
       cwd: projectDir, stdio: 'pipe',
     });
 
-    // Restore .cursor/ back from HEAD to prevent tool/skill downgrade
+    // Restore protected paths from HEAD to prevent tool/skill/config downgrade
     const head = git(['rev-parse', 'HEAD'], { cwd: projectDir, allowFail: true });
     if (head) {
-      try {
-        execFileSync('git', ['restore', `--source=HEAD`, '--', '.cursor/'], {
-          cwd: projectDir, stdio: 'pipe',
-        });
-      } catch { /* .cursor/ may not exist in HEAD, that's fine */ }
+      for (const p of ['.cursor/', ...GUARD_CONFIGS]) {
+        try {
+          execFileSync('git', ['restore', `--source=HEAD`, '--', p], {
+            cwd: projectDir, stdio: 'pipe',
+          });
+        } catch { /* may not exist in HEAD, that's fine */ }
+      }
     }
 
     let untrackedCleaned = 0;
@@ -365,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 = {}) {
@@ -109,7 +131,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];

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' },
       });
     }