cursor-guard 4.7.4 → 4.7.6

package/references/vscode-extension/dist/skill/config-reference.md

@@ -0,0 +1,215 @@
+# 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
+}
+```
+
+---
+
+## `proactive_alert`
+
+- **Type**: `boolean`
+- **Default**: `true`
+
+Enable V4 proactive change-velocity detection. When enabled, the auto-backup watcher monitors file change frequency and raises alerts when abnormal patterns are detected (e.g. 20+ files modified in 10 seconds). Alerts are persisted to a file so the MCP server can include them in tool responses.
+
+Set to `false` to disable proactive monitoring entirely.
+
+```json
+"proactive_alert": true
+```
+
+---
+
+## `alert_thresholds`
+
+- **Type**: `object`
+- **Default**: `{ "files_per_window": 20, "window_seconds": 10, "cooldown_seconds": 60 }`
+
+Thresholds for proactive change-velocity alerts. Only effective when `proactive_alert` is `true`.
+
+### Sub-fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `files_per_window` | `integer` | `20` | Number of file changes within the time window that triggers an alert |
+| `window_seconds` | `integer` | `10` | Sliding time window in seconds for counting file changes |
+| `cooldown_seconds` | `integer` | `60` | Minimum seconds between consecutive alerts to avoid noise |
+
+```json
+"alert_thresholds": {
+  "files_per_window": 20,
+  "window_seconds": 10,
+  "cooldown_seconds": 60
+}
+```

package/references/vscode-extension/dist/skill/config-reference.zh-CN.md

@@ -0,0 +1,215 @@
+# 配置参数说明
+
+本文档说明 `.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"` | 提交到专用引用 `refs/guard/auto-backup` |
+| `"shadow"` | 文件拷贝到 `.cursor-guard-backup/<timestamp>/` |
+| `"both"` | Git 分支快照 + 影子拷贝同时进行 |
+
+```json
+"backup_strategy": "git"
+```
+
+---
+
+## `auto_backup_interval_seconds`
+
+- **类型**：`integer`
+- **最小值**：`5`
+- **默认值**：`60`
+
+自动备份脚本检查变更并创建快照的间隔秒数。
+
+```json
+"auto_backup_interval_seconds": 60
+```
+
+---
+
+## `secrets_patterns`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：内置列表（见下）
+
+敏感文件 glob 模式。匹配的文件**自动排除**备份，即使在 `protect` 范围内。内置默认值：`.env`、`.env.*`、`*.key`、`*.pem`、`*.p12`、`*.pfx`、`credentials*`。
+
+**设置此字段会完全替换内置默认值。** 如果只想追加模式，请使用 `secrets_patterns_extra`。
+
+```json
+"secrets_patterns": [".env", ".env.*", "*.key", "*.pem"]
+```
+
+---
+
+## `secrets_patterns_extra`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：未设置
+
+追加到当前 `secrets_patterns`（含默认值）的额外 glob 模式。使用此字段可在不丢失 `.p12`、`.pfx`、`credentials*` 等内置保护的情况下添加自定义模式。
+
+```json
+"secrets_patterns_extra": ["*.secret", "tokens.*"]
+```
+
+---
+
+## `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
+}
+```
+
+---
+
+## `git_retention`
+
+- **类型**：`object`
+- **默认值**：`{ "enabled": false, "mode": "count", "max_count": 200 }`
+
+**`refs/guard/auto-backup` Git 引用**的保留策略。默认情况下自动备份提交会无限累积。启用此项可自动裁剪旧提交。
+
+### 子字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | `boolean` | `false` | 启用自动裁剪。关闭时分支无限增长。 |
+| `mode` | `"days"` \| `"count"` | `"count"` | 裁剪策略 |
+| `days` | `integer` | `30` | 保留最近 N 天的提交（mode=days 时生效） |
+| `max_count` | `integer` | `200` | 保留最新 N 个提交（mode=count 时生效，最少 10） |
+
+```json
+"git_retention": {
+  "enabled": true,
+  "mode": "count",
+  "max_count": 200
+}
+```
+
+---
+
+## `proactive_alert`
+
+- **类型**：`boolean`
+- **默认值**：`true`
+
+启用 V4 主动变更频率检测。开启后，自动备份 watcher 会监控文件变更频率，当检测到异常模式（如 10 秒内 20+ 文件被修改）时发出告警。告警会持久化到文件，以便 MCP 工具在响应中附加风险提示。
+
+设为 `false` 可完全禁用主动监控。
+
+```json
+"proactive_alert": true
+```
+
+---
+
+## `alert_thresholds`
+
+- **类型**：`object`
+- **默认值**：`{ "files_per_window": 20, "window_seconds": 10, "cooldown_seconds": 60 }`
+
+主动变更频率告警的阈值配置。仅在 `proactive_alert` 为 `true` 时生效。
+
+### 子字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `files_per_window` | `integer` | `20` | 时间窗口内触发告警的文件变更数量 |
+| `window_seconds` | `integer` | `10` | 统计文件变更的滑动时间窗口（秒） |
+| `cooldown_seconds` | `integer` | `60` | 连续告警之间的最小间隔（秒），避免噪声 |
+
+```json
+"alert_thresholds": {
+  "files_per_window": 20,
+  "window_seconds": 10,
+  "cooldown_seconds": 60
+}
+```

package/references/vscode-extension/dist/skill/cursor-guard.example.json

@@ -0,0 +1,43 @@
+{
+  "protect": [
+    "src/**",
+    "lib/**",
+    "*.config.js",
+    "*.config.ts",
+    "package.json",
+    "tsconfig.json",
+    ".env.example"
+  ],
+  "ignore": [
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    ".next/**",
+    "coverage/**",
+    "*.log",
+    "*.tmp",
+    ".cursor-guard-backup/**"
+  ],
+  "backup_strategy": "git",
+  "auto_backup_interval_seconds": 60,
+  "secrets_patterns_extra": [],
+  "pre_restore_backup": "always",
+  "retention": {
+    "mode": "days",
+    "days": 30,
+    "max_count": 100,
+    "max_size_mb": 500
+  },
+  "git_retention": {
+    "enabled": false,
+    "mode": "count",
+    "days": 30,
+    "max_count": 200
+  },
+  "proactive_alert": true,
+  "alert_thresholds": {
+    "files_per_window": 20,
+    "window_seconds": 10,
+    "cooldown_seconds": 60
+  }
+}

package/references/vscode-extension/dist/skill/cursor-guard.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Cursor Guard Configuration",
+  "description": "Controls which files are protected, backup strategy, secrets filtering, and retention policy for the cursor-guard skill.",
+  "type": "object",
+  "properties": {
+    "protect": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Whitelist glob patterns relative to workspace root. Only matching files get backup protection. If empty or missing, all files are protected."
+    },
+    "ignore": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Blacklist glob patterns. Matching files are excluded even if they match 'protect'. Applied on top of .gitignore."
+    },
+    "backup_strategy": {
+      "type": "string",
+      "enum": ["git", "shadow", "both"],
+      "default": "git",
+      "description": "Primary backup method: 'git' (local commits), 'shadow' (.cursor-guard-backup/ copies), or 'both'."
+    },
+    "auto_backup_interval_seconds": {
+      "type": "integer",
+      "minimum": 5,
+      "default": 60,
+      "description": "Interval in seconds for auto-backup script to check for changes."
+    },
+    "secrets_patterns": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns for sensitive files auto-excluded from backups. Overrides built-in defaults: .env, .env.*, *.key, *.pem, *.p12, *.pfx, credentials*. Use secrets_patterns_extra to add without replacing."
+    },
+    "secrets_patterns_extra": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Additional glob patterns appended to secrets_patterns (including defaults). Use this to add patterns without losing built-in protection."
+    },
+    "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.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["days", "count", "size"],
+          "default": "days",
+          "description": "'days': keep snapshots from the last N days. 'count': keep N newest snapshots. 'size': keep total size under N MB."
+        },
+        "days": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 30,
+          "description": "Number of days to retain snapshots (when mode='days')."
+        },
+        "max_count": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 100,
+          "description": "Maximum number of snapshots to keep (when mode='count')."
+        },
+        "max_size_mb": {
+          "type": "integer",
+          "minimum": 10,
+          "default": 500,
+          "description": "Maximum total size in MB for shadow copies (when mode='size')."
+        }
+      },
+      "additionalProperties": false
+    },
+    "git_retention": {
+      "type": "object",
+      "description": "Controls automatic cleanup of old commits on refs/guard/auto-backup.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable automatic pruning of old auto-backup commits. Default false (manual cleanup)."
+        },
+        "mode": {
+          "type": "string",
+          "enum": ["days", "count"],
+          "default": "count",
+          "description": "'days': keep commits from the last N days. 'count': keep N newest commits."
+        },
+        "days": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 30,
+          "description": "Number of days to keep auto-backup commits (when mode='days')."
+        },
+        "max_count": {
+          "type": "integer",
+          "minimum": 10,
+          "default": 200,
+          "description": "Maximum number of auto-backup commits to keep (when mode='count')."
+        }
+      },
+      "additionalProperties": false
+    },
+    "proactive_alert": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable V4 proactive change-velocity detection. When true, the auto-backup watcher monitors file change frequency and raises alerts when abnormal patterns are detected."
+    },
+    "alert_thresholds": {
+      "type": "object",
+      "description": "Thresholds for proactive change-velocity alerts (V4). Only effective when proactive_alert is true.",
+      "properties": {
+        "files_per_window": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 20,
+          "description": "Number of file changes within the time window that triggers an alert."
+        },
+        "window_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 10,
+          "description": "Sliding time window in seconds for counting file changes."
+        },
+        "cooldown_seconds": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 60,
+          "description": "Minimum seconds between consecutive alerts to avoid noise."
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}