cursor-guard 4.1.0 → 4.2.1

package/README.md

@@ -24,6 +24,7 @@ When Cursor's AI agent edits your files, there's a risk of accidental overwrites
 - **Auto-fix diagnostics** — `doctor_fix` automatically patches missing configs, uninitialized Git repos, gitignore gaps, and stale locks
 - **Proactive change-velocity alerts (V4)** — Auto-detects abnormal file change patterns and raises risk warnings
 - **Backup health dashboard (V4)** — One-call comprehensive view: strategy, counts, disk usage, protection scope, health status
+- **Web dashboard (V4.2)** — Local read-only web UI at `http://127.0.0.1:3120` — see health, backups, restore points, diagnostics, protection scope at a glance. Dual-language (zh-CN / en-US), auto-refresh every 15s, multi-project support
 
 ---
 
@@ -115,6 +116,12 @@ After installation, your directory structure should look like this:
     │       ├── status.js               # Backup system status
     │       ├── anomaly.js             # V4: Change-velocity detection
     │       └── dashboard.js           # V4: Health dashboard aggregation
+    ├── dashboard/
+    │   ├── server.js                   # Dashboard HTTP server + API
+    │   └── public/                     # Web UI (HTML/CSS/JS)
+    │       ├── index.html
+    │       ├── style.css
+    │       └── app.js
     ├── mcp/
     │   └── server.js                   # MCP Server (9 tools)
     ├── bin/
@@ -249,6 +256,37 @@ npx cursor-guard-doctor --path /my/project
 
 > **Note**: Run backup/doctor scripts in a separate terminal, NOT inside Cursor's integrated terminal.
 
+### Web Dashboard
+
+A local read-only web page for monitoring backup health, restore points, protection scope, and diagnostics — all in one view.
+
+```bash
+# Monitor a single project
+npx cursor-guard-dashboard --path /my/project
+
+# Monitor multiple projects
+npx cursor-guard-dashboard --path /project-a --path /project-b
+
+# Custom port (default: 3120)
+npx cursor-guard-dashboard --path /my/project --port 8080
+
+# Windows PowerShell (from skill directory)
+node references\dashboard\server.js --path "D:\MyProject"
+```
+
+Then open `http://127.0.0.1:3120` in your browser.
+
+Features:
+
+- **Read-only** — no write operations, safe to run anytime
+- **Dual-language** — zh-CN / en-US, auto-detects system language, manual toggle in top-right
+- **Auto-refresh** — pulls data every 15 seconds, plus manual refresh button
+- **Multi-project** — pass multiple `--path` args to monitor several projects from one page
+- **4 sections**: Overview (health + watcher + alerts + latest backups), Backups & Recovery (restore point table with type filters), Protection Scope (protect/ignore patterns), Diagnostics (doctor checks)
+- **2 detail drawers**: Restore Point drawer (preview JSON, copy ref/hash), Doctor drawer (full check list, WARN/FAIL expanded by default)
+- **Security** — binds to `127.0.0.1` only (not exposed to LAN), API uses project IDs instead of raw file paths, static file serving restricted to `public/` directory
+- **Zero extra dependencies** — uses Node.js built-in `http` module + existing cursor-guard core modules
+
 ---
 
 ## Recovery
@@ -325,6 +363,8 @@ The skill activates on these signals:
 | `references/lib/utils.js` | Shared utilities (config, glob, git, manifest) |
 | `references/bin/cursor-guard-backup.js` | CLI entry: `npx cursor-guard-backup` |
 | `references/bin/cursor-guard-doctor.js` | CLI entry: `npx cursor-guard-doctor` |
+| `references/dashboard/server.js` | Dashboard HTTP server + REST API |
+| `references/dashboard/public/` | Dashboard web UI (index.html, style.css, app.js) |
 | `references/auto-backup.ps1` / `.sh` | Thin wrappers (Windows / macOS+Linux) |
 | `references/guard-doctor.ps1` / `.sh` | Thin wrappers (Windows / macOS+Linux) |
 | `references/recovery.md` | Recovery command templates |

package/README.zh-CN.md

@@ -24,6 +24,7 @@
 - **自动诊断修复** — `doctor_fix` 一键修补缺失配置、未初始化 Git、gitignore 遗漏等常见问题
 - **主动变更频率告警（V4）** — 自动检测异常文件变更模式并发出风险预警
 - **备份健康看板（V4）** — 一次调用全面查看：策略、数量、磁盘占用、保护范围、健康状态
+- **Web 仪表盘（V4.2）** — 本地只读 Web 页面 `http://127.0.0.1:3120`——健康状态、备份、恢复点、诊断、保护范围一目了然。中英双语、每 15 秒自动刷新、支持多项目监控
 
 ---
 
@@ -115,6 +116,12 @@ git clone https://github.com/zhangqiang8vipp/cursor-guard.git .cursor/skills/cur
     │       ├── status.js               # 备份系统状态
     │       ├── anomaly.js             # V4：变更频率检测
     │       └── dashboard.js           # V4：健康看板聚合
+    ├── dashboard/
+    │   ├── server.js                   # 仪表盘 HTTP 服务 + API
+    │   └── public/                     # Web UI（HTML/CSS/JS）
+    │       ├── index.html
+    │       ├── style.css
+    │       └── app.js
     ├── mcp/
     │   └── server.js                   # MCP Server（9 个工具）
     ├── bin/
@@ -249,6 +256,37 @@ npx cursor-guard-doctor --path /my/project
 
 > **注意**：请在独立终端窗口中运行备份/检查脚本，不要在 Cursor 集成终端中运行。
 
+### Web 仪表盘
+
+本地只读 Web 页面，一页查看备份健康状态、恢复点、保护范围和诊断结果。
+
+```bash
+# 监控单个项目
+npx cursor-guard-dashboard --path /my/project
+
+# 监控多个项目
+npx cursor-guard-dashboard --path /project-a --path /project-b
+
+# 自定义端口（默认 3120）
+npx cursor-guard-dashboard --path /my/project --port 8080
+
+# Windows PowerShell（从 skill 目录运行）
+node references\dashboard\server.js --path "D:\MyProject"
+```
+
+然后在浏览器打开 `http://127.0.0.1:3120`。
+
+特性：
+
+- **只读** — 不执行任何写操作，随时可以安全运行
+- **中英双语** — zh-CN / en-US，自动检测系统语言，右上角手动切换
+- **自动刷新** — 每 15 秒拉取数据，支持手动刷新按钮
+- **多项目** — 传多个 `--path` 参数可从一个页面监控多个项目
+- **4 个区块**：总览（健康状态 + 守护进程 + 告警 + 最近备份）、备份与恢复（恢复点表格，按类型过滤）、保护范围（protect/ignore 规则）、诊断（doctor 检查项）
+- **2 个详情抽屉**：恢复点抽屉（预览 JSON、复制引用/hash）、诊断抽屉（完整检查列表，WARN/FAIL 默认展开）
+- **安全性** — 仅绑定 `127.0.0.1`（不暴露到局域网）、API 使用项目 ID 而非原始路径、静态文件服务严格限制在 `public/` 目录
+- **零额外依赖** — 使用 Node.js 内置 `http` 模块 + cursor-guard 已有核心模块
+
 ---
 
 ## 恢复
@@ -325,6 +363,8 @@ npx cursor-guard-doctor --path /my/project
 | `references/lib/utils.js` | 共享工具库（配置、glob、git、manifest） |
 | `references/bin/cursor-guard-backup.js` | CLI 入口：`npx cursor-guard-backup` |
 | `references/bin/cursor-guard-doctor.js` | CLI 入口：`npx cursor-guard-doctor` |
+| `references/dashboard/server.js` | 仪表盘 HTTP 服务 + REST API |
+| `references/dashboard/public/` | 仪表盘 Web UI（index.html、style.css、app.js） |
 | `references/auto-backup.ps1` / `.sh` | 薄封装（Windows / macOS+Linux） |
 | `references/guard-doctor.ps1` / `.sh` | 薄封装（Windows / macOS+Linux） |
 | `references/recovery.md` | 恢复命令模板 |

package/SKILL.md

@@ -488,6 +488,7 @@ Current version preserved before restore:
 > - Project preview: `restore_project { "path": "<project>", "source": "<hash>", "preview": true }` — returns the list of files that would change.
 > - Project execute: after user confirms, `restore_project { "path": "<project>", "source": "<hash>", "preview": false, "preserve_current": true }` — creates pre-restore snapshot, then restores all files in one call. Returns `{ filesRestored, preRestoreRef, files }`.
 > - MCP `restore_file` and `restore_project` respect `pre_restore_backup` config (§Step 4) automatically. The response includes `preRestoreRef` if a snapshot was created.
+> - **`.cursor/` protection**: `restore_project` automatically preserves the `.cursor/` directory (including skills, MCP configs, rules) from HEAD after restoring. Preview results mark `.cursor/` files with a `warning` field. If a user explicitly wants to restore `.cursor/` contents, they must do so file-by-file via `restore_file`.
 
 **Single file recovery:**
 
@@ -568,6 +569,7 @@ Skip the block for unrelated turns.
 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.
+14. **Do not restore `.cursor/` directory** — `.cursor/skills/`, `.cursor/rules/`, and `.cursor/mcp.json` are tool infrastructure, not project code. `restore_project` automatically protects this directory. Never include `.cursor/` in manual restore commands unless the user explicitly requests it. Restoring `.cursor/skills/cursor-guard/` would downgrade the protection tool itself.
 
 ---
 
@@ -586,6 +588,7 @@ Skip the block for unrelated turns.
 - Guard doctor (Node.js core): [references/lib/guard-doctor.js](references/lib/guard-doctor.js)
 - Core modules: [references/lib/core/](references/lib/core/) (doctor, doctor-fix, snapshot, backups, restore, status, anomaly, dashboard)
 - MCP server: [references/mcp/server.js](references/mcp/server.js) (9 tools: doctor, doctor_fix, backup_status, list_backups, snapshot_now, restore_file, restore_project, dashboard, alert_status)
+- Web dashboard: [references/dashboard/](references/dashboard/) (local read-only web UI — `node references/dashboard/server.js --path <project>`)
 - Shared utilities: [references/lib/utils.js](references/lib/utils.js)
 - 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "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",
@@ -30,7 +30,8 @@
     "cursor-guard-init": "references/bin/cursor-guard-init.js",
     "cursor-guard-backup": "references/bin/cursor-guard-backup.js",
     "cursor-guard-doctor": "references/bin/cursor-guard-doctor.js",
-    "cursor-guard-mcp": "references/mcp/server.js"
+    "cursor-guard-mcp": "references/mcp/server.js",
+    "cursor-guard-dashboard": "references/dashboard/server.js"
   },
   "files": [
     "SKILL.md",
@@ -48,6 +49,7 @@
     "references/lib/utils.js",
     "references/lib/core/",
     "references/mcp/",
+    "references/dashboard/",
     "references/config-reference.md",
     "references/config-reference.zh-CN.md",
     "references/cursor-guard.example.json",

package/references/bin/cursor-guard-init.js

@@ -67,10 +67,10 @@ console.log('        Done.');
 // Step 2: Install MCP dependencies in skill directory
 console.log('  [2/4] Installing MCP dependencies...');
 try {
-  execFileSync('npm', ['install', '--omit=dev', '--ignore-scripts'], {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  execFileSync(npmCmd, ['install', '--omit=dev', '--ignore-scripts'], {
     cwd: skillTarget,
     stdio: 'pipe',
-    shell: process.platform === 'win32',
   });
   console.log('        Done.');
 } catch (e) {
@@ -110,6 +110,8 @@ console.log(`        MCP server: ${serverExists ? 'OK' : 'MISSING'}`);
 console.log(`        MCP SDK:    ${sdkExists ? 'OK' : 'MISSING — run npm install in skill dir'}`);
 
 console.log(`\n  Installation complete!\n`);
+console.log('  ⚠  If MCP was already configured, restart Cursor (or Ctrl+Shift+P →');
+console.log('     "Developer: Reload Window") to load the updated MCP server.\n');
 console.log('  Next steps:');
 console.log('  1. The skill activates automatically in Cursor Agent conversations.');
 console.log('  2. (Optional) Copy example config to project root:');