cursor-guard 2.1.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "2.1.1",
+  "version": "3.0.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",
@@ -24,16 +24,18 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node references/lib/utils.test.js"
+    "test": "node references/lib/utils.test.js && node references/lib/core/core.test.js && node references/mcp/mcp.test.js"
   },
   "bin": {
     "cursor-guard-backup": "references/bin/cursor-guard-backup.js",
-    "cursor-guard-doctor": "references/bin/cursor-guard-doctor.js"
+    "cursor-guard-doctor": "references/bin/cursor-guard-doctor.js",
+    "cursor-guard-mcp": "references/mcp/server.js"
   },
   "files": [
     "SKILL.md",
     "README.md",
     "README.zh-CN.md",
+    "ROADMAP.md",
     "LICENSE",
     "references/auto-backup.ps1",
     "references/auto-backup.sh",
@@ -43,11 +45,18 @@
     "references/lib/auto-backup.js",
     "references/lib/guard-doctor.js",
     "references/lib/utils.js",
+    "references/lib/core/",
+    "references/mcp/",
     "references/config-reference.md",
     "references/config-reference.zh-CN.md",
     "references/cursor-guard.example.json",
     "references/cursor-guard.schema.json",
-    "references/recovery.md"
+    "references/recovery.md",
+    "references/quickstart.zh-CN.md"
   ],
-  "main": "SKILL.md"
+  "main": "SKILL.md",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  }
 }

package/references/config-reference.md

@@ -1,175 +1,175 @@
-# 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 ref `refs/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 the auto-backup script 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: `.env`, `.env.*`, `*.key`, `*.pem`, `*.p12`, `*.pfx`, `credentials*`.
-
-**Setting this field replaces the built-in defaults entirely.** If you only need to add patterns, use `secrets_patterns_extra` instead.
-
-```json
-"secrets_patterns": [".env", ".env.*", "*.key", "*.pem"]
-```
-
----
-
-## `secrets_patterns_extra`
-
-- **Type**: `string[]` (glob patterns)
-- **Default**: not set
-
-Additional glob patterns **appended** to the current `secrets_patterns` (including defaults). Use this to add custom patterns without losing the built-in protection for `.p12`, `.pfx`, `credentials*`, etc.
-
-```json
-"secrets_patterns_extra": ["*.secret", "tokens.*"]
-```
-
----
-
-## `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
-}
-```
-
----
-
-## `git_retention`
-
-- **Type**: `object`
-- **Default**: `{ "enabled": false, "mode": "count", "max_count": 200 }`
-
-Retention policy for the **`refs/guard/auto-backup` Git ref**. By default, auto-backup commits accumulate indefinitely. Enable this to automatically prune old commits.
-
-### Sub-fields
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `enabled` | `boolean` | `false` | Enable automatic pruning. When false, branch grows without limit. |
-| `mode` | `"days"` \| `"count"` | `"count"` | Pruning strategy |
-| `days` | `integer` | `30` | Keep commits from last N days (when mode=days) |
-| `max_count` | `integer` | `200` | Keep N newest commits (when mode=count, minimum 10) |
-
-```json
-"git_retention": {
-  "enabled": true,
-  "mode": "count",
-  "max_count": 200
-}
-```
+# 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 ref `refs/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 the auto-backup script 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: `.env`, `.env.*`, `*.key`, `*.pem`, `*.p12`, `*.pfx`, `credentials*`.
+
+**Setting this field replaces the built-in defaults entirely.** If you only need to add patterns, use `secrets_patterns_extra` instead.
+
+```json
+"secrets_patterns": [".env", ".env.*", "*.key", "*.pem"]
+```
+
+---
+
+## `secrets_patterns_extra`
+
+- **Type**: `string[]` (glob patterns)
+- **Default**: not set
+
+Additional glob patterns **appended** to the current `secrets_patterns` (including defaults). Use this to add custom patterns without losing the built-in protection for `.p12`, `.pfx`, `credentials*`, etc.
+
+```json
+"secrets_patterns_extra": ["*.secret", "tokens.*"]
+```
+
+---
+
+## `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
+}
+```
+
+---
+
+## `git_retention`
+
+- **Type**: `object`
+- **Default**: `{ "enabled": false, "mode": "count", "max_count": 200 }`
+
+Retention policy for the **`refs/guard/auto-backup` Git ref**. By default, auto-backup commits accumulate indefinitely. Enable this to automatically prune old commits.
+
+### Sub-fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable automatic pruning. When false, branch grows without limit. |
+| `mode` | `"days"` \| `"count"` | `"count"` | Pruning strategy |
+| `days` | `integer` | `30` | Keep commits from last N days (when mode=days) |
+| `max_count` | `integer` | `200` | Keep N newest commits (when mode=count, minimum 10) |
+
+```json
+"git_retention": {
+  "enabled": true,
+  "mode": "count",
+  "max_count": 200
+}
+```