cursor-guard 1.2.0 → 1.3.0

package/README.md

@@ -157,7 +157,9 @@ The script uses Git plumbing commands to snapshot to `cursor-guard/auto-backup`
 
 ## Recovery
 
-If something goes wrong, just tell the AI agent in natural language:
+If something goes wrong, just tell the AI agent in natural language.
+
+**Default behavior**: Before any restore, the agent automatically preserves your current version so you can undo the restore if needed. You don't need to ask for this — it happens by default. To skip, explicitly say "don't preserve current version" or "skip backup before restore".
 
 ### By time
 
@@ -176,7 +178,14 @@ If something goes wrong, just tell the AI agent in natural language:
 > "restore src/app.py to 10 minutes ago"
 > "restore src/app.py to the previous version"
 
-The agent will automatically search Git history and auto-backup snapshots, show you matching versions to choose from, and restore after your confirmation.
+The agent will:
+1. **Preserve your current version** first (unless you opt out)
+2. Search Git history and auto-backup snapshots
+3. Show matching versions for you to choose
+4. Restore after your confirmation
+5. Report both the pre-restore backup ref and the restore result
+
+If the pre-restore backup fails, the agent will **not** proceed — it will wait for your explicit confirmation before restoring without a safety net.
 
 ### Recovery priority
 

package/README.zh-CN.md

@@ -157,7 +157,9 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 
 ## 恢复
 
-出问题时，直接用自然语言告诉 AI 代理即可：
+出问题时，直接用自然语言告诉 AI 代理即可。
+
+**默认行为**：执行任何恢复操作前，代理会自动保留你的当前版本，方便恢复后反悔。无需额外请求，这是默认行为。如需跳过，请明确说"不保留当前版本"或"直接覆盖恢复"。
 
 ### 按时间恢复
 
@@ -176,7 +178,14 @@ cp .cursor/skills/cursor-guard/references/cursor-guard.example.json .cursor-guar
 > "把 src/app.py 恢复到10分钟前"
 > "把 src/app.py 恢复到上一个版本"
 
-代理会自动搜索 Git 历史和自动备份快照，列出匹配版本供你选择，确认后执行恢复。
+代理会：
+1. **先保留你的当前版本**（除非你明确选择跳过）
+2. 搜索 Git 历史和自动备份快照
+3. 列出匹配版本供你选择
+4. 确认后执行恢复
+5. 报告恢复前备份引用和恢复结果
+
+如果保留当前版本失败，代理**不会**继续恢复——会等你明确确认后才会在没有安全网的情况下恢复。
 
 ### 恢复优先级
 

package/SKILL.md

@@ -302,7 +302,104 @@ 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: Execute Recovery
+### Step 4: Preserve Current Version Before Restore (MANDATORY)
+
+> **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.
+
+**4a. Check if user opted out**
+
+Skip preservation ONLY if the user explicitly said one of:
+- "不保留当前版本" / "不用备份当前版本" / "直接覆盖恢复"
+- "skip backup before restore" / "don't preserve current" / "just restore"
+
+If opted out, inform: "你已明确表示不保留当前版本，我将直接恢复。" and jump to Step 5.
+
+**4b. Determine preservation scope**
+
+| Restore scope | What to preserve |
+|---------------|-----------------|
+| Single file | Only that file's current state |
+| Multiple files | All files that will be overwritten |
+| Entire project | Full project snapshot |
+
+**4c. Check if there are changes to preserve**
+
+```bash
+# For single file: check if file differs from the restore target
+git diff <target-commit> -- <file>
+
+# For project: check overall status
+git status --porcelain
+```
+
+If the file/project is **identical** to the restore target (no diff), inform:
+"当前版本与目标版本相同，无需保留，跳过备份。" / "Current version is identical to target, no backup needed."
+Then jump to Step 5.
+
+If the working tree is clean AND HEAD matches the restore target, inform:
+"当前无可保留变更，直接恢复。" / "No changes to preserve, proceeding with restore."
+Then jump to Step 5.
+
+**4d. Create preservation snapshot**
+
+Use the same temp-index plumbing as §2a to avoid polluting the user's staging area:
+
+**Git repo (preferred):**
+
+```powershell
+$guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
+$env:GIT_INDEX_FILE = $guardIdx
+
+# For single file: read HEAD tree then update just the target file
+git read-tree HEAD
+git add -- <file>
+
+# For project: snapshot everything
+git read-tree HEAD
+git add -A
+
+$tree = git write-tree
+$env:GIT_INDEX_FILE = $null
+Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
+
+$commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore to <target>"
+git update-ref refs/guard/pre-restore $commit
+```
+
+Record the short hash and the ref `refs/guard/pre-restore`.
+
+**Non-Git fallback (shadow copy):**
+
+```powershell
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
+$dir = ".cursor-guard-backup/pre-restore-$ts"
+New-Item -ItemType Directory -Force $dir | Out-Null
+Copy-Item "<file>" "$dir/<file>"
+```
+
+**4e. Handle preservation failure**
+
+If the snapshot fails (e.g. disk full, permission error):
+1. **Do NOT proceed with restore.** Default is to abort.
+2. Inform the user: "当前版本保留失败。默认不继续恢复；如果你确认不保留当前状态也要继续，请明确说明。" / "Failed to preserve current version. Restore aborted by default. If you want to continue without backup, please confirm explicitly."
+3. Only proceed if the user explicitly confirms: "即使不保留也继续" / "continue without backup".
+
+**4f. Inform user of preservation result**
+
+Before executing restore, tell the user:
+```
+在恢复前，我已保留当前版本：
+- 备份引用: refs/guard/pre-restore (abc1234)
+- 恢复方式: git restore --source=refs/guard/pre-restore -- <file>
+
+Current version preserved before restore:
+- Backup ref: refs/guard/pre-restore (abc1234)
+- To undo: git restore --source=refs/guard/pre-restore -- <file>
+```
+
+### Step 5: Execute Recovery
 
 **Single file recovery:**
 
@@ -330,12 +427,23 @@ Get-ChildItem .cursor-guard-backup/ -Directory | Sort-Object Name -Descending
 Copy-Item ".cursor-guard-backup/<timestamp>/<file>" "<original-path>"
 ```
 
-### Step 5: Verify & Report
+### Step 6: Verify & Report
 
 After restoring, always:
 1. Show the restored file content (or diff) so the user can verify
-2. Report the recovery in the status block (§6)
-3. Suggest creating a new snapshot of the current (restored) state
+2. Report the recovery in the status block (§6a), including **both** the pre-restore backup ref and the restore target
+3. Tell the user how to undo the restore if needed
+
+**Status block for restore operations:**
+
+```markdown
+**Cursor Guard — restore status**
+- **Pre-restore backup**: `refs/guard/pre-restore` (`<short-hash>`) or `shadow copy at .cursor-guard-backup/pre-restore-<ts>/` or `skipped (user opted out)` or `skipped (no changes)`
+- **Restored to**: `<target-hash>` / `<target description>`
+- **Scope**: single file `<path>` / N files / entire project
+- **Result**: success / failed
+- **To undo restore**: `git restore --source=refs/guard/pre-restore -- <file>`
+```
 
 ---
 
@@ -360,15 +468,17 @@ Skip the block for unrelated turns.
 
 1. **MUST snapshot before high-risk ops** — git commit or shadow copy. No exceptions unless user explicitly declines.
 2. **MUST Read before Write** — never overwrite a file the agent hasn't read in the current turn.
-3. **Do not** treat Timeline/Checkpoints as the only or primary recovery path.
-4. **Do not** recommend Checkpoints as long-term or sole backup.
-5. **No automatic push** to remotes; local commits only unless user requests push.
-6. **Be honest** about limits: terminal side effects, binary files, and non-tracked paths are not fully reversible without prior commits.
-7. **Do not** run `git clean`, `reset --hard`, or other destructive Git commands unless the user clearly asked; always show what would be affected first.
-8. **Do not** delete files via the Delete tool without explicit per-file confirmation from the user.
-9. **Do not** modify or delete `.cursor-guard.json` unless the user explicitly asks — accidental config changes silently alter protection scope.
-10. **Use `--no-verify`** on all guard snapshot commits to bypass pre-commit hooks that could fail or modify files.
-11. **Concurrent agents**: if multiple Agent threads are active, warn the user to avoid simultaneous writes to the same file. Snapshots cannot prevent race conditions between parallel agents.
+3. **MUST preserve current version before restore** — every restore operation must first snapshot the current state (§5a Step 4). Skip ONLY when: (a) user explicitly opts out, (b) current state is identical to target, or (c) no changes exist. If preservation fails, abort restore by default.
+4. **Do not** treat Timeline/Checkpoints as the only or primary recovery path.
+5. **Do not** recommend Checkpoints as long-term or sole backup.
+6. **No automatic push** to remotes; local commits only unless user requests push.
+7. **Be honest** about limits: terminal side effects, binary files, and non-tracked paths are not fully reversible without prior commits.
+8. **Do not** run `git clean`, `reset --hard`, or other destructive Git commands unless the user clearly asked; always show what would be affected first.
+9. **Do not** delete files via the Delete tool without explicit per-file confirmation from the user.
+10. **Do not** modify or delete `.cursor-guard.json` unless the user explicitly asks — accidental config changes silently alter protection scope.
+11. **Use `--no-verify`** on all guard snapshot commits to bypass pre-commit hooks that could fail or modify files.
+12. **Concurrent agents**: if multiple Agent threads are active, warn the user to avoid simultaneous writes to the same file. Snapshots cannot prevent race conditions between parallel agents.
+13. **Preservation must not pollute** — all pre-restore backups use temp index + dedicated ref (`refs/guard/pre-restore`). The user's staging area, working tree, and commit history on their branch are never modified by the preservation process.
 
 ---
 

package/package.json

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

@@ -4,6 +4,72 @@ Replace `<path>` / `<file>` with real paths. Run from repository root. **Review
 
 ---
 
+## Preserve current version before restore / 恢复前保留当前版本
+
+> **Default behavior**: Every restore operation must first preserve current state.
+>
+> **默认行为**：每次恢复操作前必须先保留当前版本。
+
+### Single file / 单文件
+
+```powershell
+# Preserve current file state via temp index (does not touch staging area)
+# 通过临时索引保留当前文件（不影响暂存区）
+$guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
+$env:GIT_INDEX_FILE = $guardIdx
+git read-tree HEAD
+git add -- <file>
+$tree = git write-tree
+$env:GIT_INDEX_FILE = $null
+Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
+$commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore"
+git update-ref refs/guard/pre-restore $commit
+Write-Host "Pre-restore backup: $($commit.Substring(0,7))"
+```
+
+### Entire project / 整个项目
+
+```powershell
+# Same as above but with git add -A
+$guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
+$env:GIT_INDEX_FILE = $guardIdx
+git read-tree HEAD
+git add -A
+$tree = git write-tree
+$env:GIT_INDEX_FILE = $null
+Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
+$commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore"
+git update-ref refs/guard/pre-restore $commit
+Write-Host "Pre-restore backup: $($commit.Substring(0,7))"
+```
+
+### Non-Git fallback (shadow copy) / 非 Git 备选方案
+
+```powershell
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
+$dir = ".cursor-guard-backup/pre-restore-$ts"
+New-Item -ItemType Directory -Force $dir | Out-Null
+Copy-Item "<file>" "$dir/<filename>"
+Write-Host "Pre-restore shadow copy: $dir"
+```
+
+### Undo a restore (recover pre-restore state) / 撤销恢复（回到恢复前的状态）
+
+```bash
+# Restore single file to pre-restore state
+# 将单个文件恢复到恢复前的状态
+git restore --source=refs/guard/pre-restore -- <file>
+
+# Restore entire project to pre-restore state
+# 将整个项目恢复到恢复前的状态
+git restore --source=refs/guard/pre-restore -- .
+
+# From shadow copy / 从影子拷贝恢复
+Copy-Item ".cursor-guard-backup/pre-restore-<ts>/<file>" "<original-path>"
+```
+
+---
+
 ## Inspect current state
 
 ```bash