cursor-guard 1.3.0 → 1.3.2

package/README.md

@@ -132,10 +132,23 @@ Edit `.cursor-guard.json` to define which files to protect:
   "ignore": ["node_modules/**", "dist/**"],
   "auto_backup_interval_seconds": 60,
   "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "pre_restore_backup": "always",
   "retention": { "mode": "days", "days": 30 }
 }
 ```
 
+#### `pre_restore_backup` — restore behavior control
+
+| Value | Behavior |
+|-------|----------|
+| `"always"` (default) | Automatically preserve current version before every restore. No prompt. |
+| `"ask"` | Prompt you each time: "Preserve current version before restore? (Y/n)" — you decide per restore. |
+| `"never"` | Never preserve current version before restore (not recommended). |
+
+Regardless of config, you can always override per-request:
+- Say "don't preserve current version" to skip even when config is `"always"`
+- Say "preserve current first" to force even when config is `"never"`
+
 ---
 
 ## Auto-Backup Script

package/README.zh-CN.md

@@ -132,10 +132,23 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
   "ignore": ["node_modules/**", "dist/**"],
   "auto_backup_interval_seconds": 60,
   "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
+  "pre_restore_backup": "always",
   "retention": { "mode": "days", "days": 30 }
 }
 ```
 
+#### `pre_restore_backup` — 恢复前保留行为控制
+
+| 值 | 行为 |
+|----|------|
+| `"always"`（默认） | 每次恢复前自动保留当前版本，无需确认。 |
+| `"ask"` | 每次恢复前询问你："恢复前是否保留当前版本？(Y/n)"——由你逐次决定。 |
+| `"never"` | 恢复前不保留当前版本（不推荐）。 |
+
+无论配置如何，你始终可以在单次请求中覆盖：
+- 说"不保留当前版本"可跳过保留（即使配置为 `"always"`）
+- 说"先保留当前版本"可强制保留（即使配置为 `"never"`）
+
 ---
 
 ## 自动备份脚本

package/SKILL.md

@@ -44,6 +44,12 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
   // Built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*
   "secrets_patterns": [".env", ".env.*", "*.key", "*.pem"],
 
+  // Controls behavior before restore operations.
+  // "always" (default): automatically preserve current version before every restore.
+  // "ask": prompt the user each time to decide.
+  // "never": skip preservation entirely (not recommended).
+  "pre_restore_backup": "always",
+
   // Retention for shadow copies. mode: "days" | "count" | "size"
   "retention": { "mode": "days", "days": 30, "max_count": 100, "max_size_mb": 500 }
 }
@@ -302,19 +308,26 @@ Recommended: #1 (closest to target time). Restore this one? / 推荐 #1（最接
   - If still nothing, report clearly: "No snapshot found before that time. The earliest available is [hash] at [time]. Do you want to use it?"
 - **Never silently pick a version.** Always show and confirm.
 
-### Step 4: Preserve Current Version Before Restore (MANDATORY)
+### Step 4: Preserve Current Version Before Restore
 
 > **Rule: `restore_requires_preserve_current_by_default`**
 >
-> Every restore operation MUST first preserve the current state, THEN restore. This is non-negotiable unless the user explicitly opts out.
+> The behavior is controlled by `pre_restore_backup` in `.cursor-guard.json` (default: `"always"`).
+
+**4a. Determine preservation mode**
 
-**4a. Check if user opted out**
+Read `pre_restore_backup` from config (§0). Three modes:
 
-Skip preservation ONLY if the user explicitly said one of:
-- "不保留当前版本" / "不用备份当前版本" / "直接覆盖恢复"
-- "skip backup before restore" / "don't preserve current" / "just restore"
+| Config value | Behavior |
+|-------------|----------|
+| `"always"` (default) | Automatically preserve current version. No prompt. Jump to 4b. |
+| `"ask"` | Prompt the user: "恢复前是否保留当前版本？(Y/n)" / "Preserve current version before restore? (Y/n)". If user answers yes/default → jump to 4b. If user answers no → inform and jump to Step 5. |
+| `"never"` | Skip preservation entirely. Inform: "配置已设为不保留当前版本 (pre_restore_backup=never)，直接恢复。" and jump to Step 5. |
 
-If opted out, inform: "你已明确表示不保留当前版本，我将直接恢复。" and jump to Step 5.
+**Override rules** (apply regardless of config):
+- If the user **explicitly** says "不保留当前版本" / "skip backup before restore" in the current message → skip, even if config is `"always"`.
+- If the user **explicitly** says "先保留当前版本" / "preserve current first" → preserve, even if config is `"never"`.
+- User's explicit instruction in the current message always takes priority over config.
 
 **4b. Determine preservation scope**
 
@@ -486,7 +499,7 @@ Skip the block for unrelated turns.
 
 - If the workspace has `.cursor-guard.json`, the agent MUST read and follow it (see §0).
 - If `.cursor-guard-backup/` folder exists, align shadow copy paths with it.
-- Template config: [references/cursor-guard.example.json](references/cursor-guard.example.json) — copy to workspace root and customize.
+- Template config: [references/cursor-guard.example.json](references/cursor-guard.example.json) — copy to workspace root and customize. Field docs: [references/config-reference.md](references/config-reference.md).
 
 ---
 
@@ -496,3 +509,5 @@ Skip the block for unrelated turns.
 - Auto-backup script: [references/auto-backup.ps1](references/auto-backup.ps1)
 - Config JSON Schema: [references/cursor-guard.schema.json](references/cursor-guard.schema.json)
 - Example config: [references/cursor-guard.example.json](references/cursor-guard.example.json)
+- Config field reference (EN): [references/config-reference.md](references/config-reference.md)
+- 配置参数说明（中文）: [references/config-reference.zh-CN.md](references/config-reference.zh-CN.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "1.3.0",
+  "version": "1.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/config-reference.md

@@ -0,0 +1,134 @@
+# Configuration Reference
+
+This document explains every field in `.cursor-guard.json`.
+
+> Example file: [cursor-guard.example.json](cursor-guard.example.json)
+>
+> JSON Schema: [cursor-guard.schema.json](cursor-guard.schema.json)
+
+---
+
+## `protect`
+
+- **Type**: `string[]` (glob patterns)
+- **Default**: not set (all files protected)
+
+Whitelist glob patterns relative to workspace root. Only matching files get backup protection. If empty or missing, all files are protected.
+
+```json
+"protect": ["src/**", "lib/**", "package.json"]
+```
+
+---
+
+## `ignore`
+
+- **Type**: `string[]` (glob patterns)
+- **Default**: not set
+
+Blacklist glob patterns. Matching files are excluded from protection even if they match `protect`. Applied on top of `.gitignore`.
+
+**Resolution rules**:
+
+| Scenario | Behavior |
+|----------|----------|
+| Both `protect` and `ignore` set | File must match `protect` AND not match `ignore` |
+| Only `protect` set | Only matching files are protected |
+| Only `ignore` set | Everything protected except matches |
+| Neither set | Protect everything |
+
+```json
+"ignore": ["node_modules/**", "dist/**", "*.log"]
+```
+
+---
+
+## `backup_strategy`
+
+- **Type**: `string`
+- **Allowed**: `"git"` | `"shadow"` | `"both"`
+- **Default**: `"git"`
+
+| Value | Description |
+|-------|-------------|
+| `"git"` | Local commits to dedicated branch `cursor-guard/auto-backup` |
+| `"shadow"` | File copies to `.cursor-guard-backup/<timestamp>/` |
+| `"both"` | Git branch snapshot + shadow copies |
+
+```json
+"backup_strategy": "git"
+```
+
+---
+
+## `auto_backup_interval_seconds`
+
+- **Type**: `integer`
+- **Minimum**: `5`
+- **Default**: `60`
+
+Interval in seconds for `auto-backup.ps1` to check for changes and create snapshots.
+
+```json
+"auto_backup_interval_seconds": 60
+```
+
+---
+
+## `secrets_patterns`
+
+- **Type**: `string[]` (glob patterns)
+- **Default**: built-in list (see below)
+
+Glob patterns for sensitive files. Matching files are **auto-excluded** from backup, even if within `protect` scope. Built-in defaults (always active): `.env`, `.env.*`, `*.key`, `*.pem`, `*.p12`, `*.pfx`, `credentials*`. Set this field to override with your own patterns.
+
+```json
+"secrets_patterns": [".env", ".env.*", "*.key", "*.pem"]
+```
+
+---
+
+## `pre_restore_backup`
+
+- **Type**: `string`
+- **Allowed**: `"always"` | `"ask"` | `"never"`
+- **Default**: `"always"`
+
+| Value | Description |
+|-------|-------------|
+| `"always"` | Auto-preserve current version before every restore. No prompt. |
+| `"ask"` | Prompt user each time: "Preserve current version?" |
+| `"never"` | Skip preservation entirely (not recommended). |
+
+Regardless of this config, the user's explicit instruction in the current message always takes priority. Say "don't preserve" to skip, or "preserve first" to force.
+
+```json
+"pre_restore_backup": "always"
+```
+
+---
+
+## `retention`
+
+- **Type**: `object`
+- **Default**: `{ "mode": "days", "days": 30 }`
+
+Retention policy for **shadow copies** only. Git branch snapshots are not auto-cleaned — manage them manually. Controls automatic cleanup of old `.cursor-guard-backup/` directories.
+
+### Sub-fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | `"days"` \| `"count"` \| `"size"` | `"days"` | Cleanup strategy |
+| `days` | `integer` | `30` | Keep snapshots from last N days (when mode=days) |
+| `max_count` | `integer` | `100` | Keep N newest snapshots (when mode=count) |
+| `max_size_mb` | `integer` | `500` | Keep total size under N MB (when mode=size) |
+
+```json
+"retention": {
+  "mode": "days",
+  "days": 30,
+  "max_count": 100,
+  "max_size_mb": 500
+}
+```

package/references/config-reference.zh-CN.md

@@ -0,0 +1,134 @@
+# 配置参数说明
+
+本文档说明 `.cursor-guard.json` 中的每个配置项。
+
+> 示例文件：[cursor-guard.example.json](cursor-guard.example.json)
+>
+> JSON Schema：[cursor-guard.schema.json](cursor-guard.schema.json)
+
+---
+
+## `protect`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：未设置（保护所有文件）
+
+白名单 glob 模式，相对于工作区根目录。只有匹配的文件才会被保护。留空或不设置则保护所有文件。
+
+```json
+"protect": ["src/**", "lib/**", "package.json"]
+```
+
+---
+
+## `ignore`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：未设置
+
+黑名单 glob 模式。匹配的文件即使被 `protect` 包含也会排除。在 `.gitignore` 基础上额外生效。
+
+**解析规则**：
+
+| 场景 | 行为 |
+|------|------|
+| 同时设置 `protect` 和 `ignore` | 文件须匹配 protect 且不匹配 ignore |
+| 仅设置 `protect` | 仅匹配文件被保护 |
+| 仅设置 `ignore` | 除匹配文件外全部保护 |
+| 都不设置 | 保护全部文件 |
+
+```json
+"ignore": ["node_modules/**", "dist/**", "*.log"]
+```
+
+---
+
+## `backup_strategy`
+
+- **类型**：`string`
+- **可选值**：`"git"` | `"shadow"` | `"both"`
+- **默认值**：`"git"`
+
+| 值 | 说明 |
+|----|------|
+| `"git"` | 提交到专用分支 `cursor-guard/auto-backup` |
+| `"shadow"` | 文件拷贝到 `.cursor-guard-backup/<timestamp>/` |
+| `"both"` | Git 分支快照 + 影子拷贝同时进行 |
+
+```json
+"backup_strategy": "git"
+```
+
+---
+
+## `auto_backup_interval_seconds`
+
+- **类型**：`integer`
+- **最小值**：`5`
+- **默认值**：`60`
+
+自动备份脚本 `auto-backup.ps1` 检查变更并创建快照的间隔秒数。
+
+```json
+"auto_backup_interval_seconds": 60
+```
+
+---
+
+## `secrets_patterns`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：内置列表（见下）
+
+敏感文件 glob 模式。匹配的文件**自动排除**备份，即使在 `protect` 范围内。内置默认值（始终生效）：`.env`、`.env.*`、`*.key`、`*.pem`、`*.p12`、`*.pfx`、`credentials*`。设置此字段可覆盖为自定义模式。
+
+```json
+"secrets_patterns": [".env", ".env.*", "*.key", "*.pem"]
+```
+
+---
+
+## `pre_restore_backup`
+
+- **类型**：`string`
+- **可选值**：`"always"` | `"ask"` | `"never"`
+- **默认值**：`"always"`
+
+| 值 | 说明 |
+|----|------|
+| `"always"` | 恢复前自动保留当前版本，无需确认。 |
+| `"ask"` | 每次恢复前询问用户是否保留当前版本。 |
+| `"never"` | 不保留当前版本（不推荐）。 |
+
+无论此配置如何，用户在当前消息中的明确指令始终优先。说"不保留当前版本"可跳过，说"先保留当前版本"可强制保留。
+
+```json
+"pre_restore_backup": "always"
+```
+
+---
+
+## `retention`
+
+- **类型**：`object`
+- **默认值**：`{ "mode": "days", "days": 30 }`
+
+仅针对**影子拷贝**的保留策略。Git 分支快照不会自动清理，需手动管理。控制 `.cursor-guard-backup/` 旧目录的自动清理。
+
+### 子字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `mode` | `"days"` \| `"count"` \| `"size"` | `"days"` | 清理策略 |
+| `days` | `integer` | `30` | 保留最近 N 天的快照（mode=days 时生效） |
+| `max_count` | `integer` | `100` | 保留最新 N 份快照（mode=count 时生效） |
+| `max_size_mb` | `integer` | `500` | 总大小不超过 N MB（mode=size 时生效） |
+
+```json
+"retention": {
+  "mode": "days",
+  "days": 30,
+  "max_count": 100,
+  "max_size_mb": 500
+}
+```

package/references/cursor-guard.example.json

@@ -1,8 +1,4 @@
 {
-  "_comment_schema": "Optional: add \"$schema\" pointing to cursor-guard.schema.json for IDE validation. Adjust the path to where you placed the schema file.",
-
-  "_comment_mode": "Two modes: whitelist (set 'protect') or blacklist (set 'ignore'). If both are set, 'protect' is checked first, then 'ignore' excludes from it.",
-
   "protect": [
     "src/**",
     "lib/**",
@@ -12,7 +8,6 @@
     "tsconfig.json",
     ".env.example"
   ],
-
   "ignore": [
     "node_modules/**",
     "dist/**",
@@ -23,19 +18,15 @@
     "*.tmp",
     ".cursor-guard-backup/**"
   ],
-
   "backup_strategy": "git",
   "auto_backup_interval_seconds": 60,
-
-  "_comment_secrets": "Glob patterns for sensitive files — auto-excluded from backup even if matched by 'protect'. Built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*",
   "secrets_patterns": [
     ".env",
     ".env.*",
     "*.key",
     "*.pem"
   ],
-
-  "_comment_retention": "Retention policy for shadow copies. mode: 'days' (default, keep N days), 'count' (keep N newest snapshots), 'size' (keep total under N MB).",
+  "pre_restore_backup": "always",
   "retention": {
     "mode": "days",
     "days": 30,

package/references/cursor-guard.schema.json

@@ -31,6 +31,12 @@
       "items": { "type": "string" },
       "description": "Glob patterns for sensitive files auto-excluded from backups. Built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*"
     },
+    "pre_restore_backup": {
+      "type": "string",
+      "enum": ["always", "ask", "never"],
+      "default": "always",
+      "description": "'always' (default): automatically preserve current version before every restore. 'ask': prompt the user each time to choose whether to preserve. 'never': skip preservation entirely (not recommended)."
+    },
     "retention": {
       "type": "object",
       "description": "Controls automatic cleanup of old shadow-copy snapshots.",