cursor-guard 4.3.2 → 4.3.3

package/README.md

@@ -377,6 +377,13 @@ 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`

package/README.zh-CN.md

@@ -377,6 +377,13 @@ 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` 扫描数千个依赖文件导致极度缓慢

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.2",
+  "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/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/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,
       });
     }