cursor-guard 4.0.0 → 4.2.0

package/README.md

@@ -24,45 +24,53 @@ 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
 
 ---
 
 ## Installation
 
-### Method 1: npm
+### Method 1: npm (Recommended)
 
 ```bash
 npm install cursor-guard
+npx cursor-guard-init
 ```
 
-After installation, copy the skill files to your Cursor skills directory:
+The `init` command copies skill files to `.cursor/skills/cursor-guard/`, installs MCP dependencies, and adds `.gitignore` entries — all in one step.
 
-**Windows (PowerShell):**
+Options:
 
-```powershell
-# Global (all projects)
-Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
-
-# Per-project (current project only)
-Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
+```bash
+npx cursor-guard-init              # project-local (default)
+npx cursor-guard-init --global     # global (~/.cursor/skills/)
+npx cursor-guard-init --path /my/project  # specify project root
 ```
 
-**macOS / Linux:**
+After init, the npm package in `node_modules` is no longer needed:
 
 ```bash
-# Global
-cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
-
-# Per-project
-cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+npm uninstall cursor-guard
 ```
 
-After copying, you can remove the npm dependency if you don't need it in `node_modules`:
+<details>
+<summary>Manual installation (without init command)</summary>
+
+If you prefer manual setup, copy files then install dependencies:
 
 ```bash
-npm uninstall cursor-guard
+# Copy
+cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+
+# Install MCP dependencies in the skill directory
+cd .cursor/skills/cursor-guard && npm install --omit=dev && cd -
+
+# Add to .gitignore so node_modules aren't captured by git snapshots
+echo ".cursor/skills/**/node_modules/" >> .gitignore
 ```
 
+</details>
+
 ### Method 2: Git clone
 
 ```bash
@@ -108,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/
@@ -242,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
@@ -318,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,45 +24,53 @@
 - **自动诊断修复** — `doctor_fix` 一键修补缺失配置、未初始化 Git、gitignore 遗漏等常见问题
 - **主动变更频率告警（V4）** — 自动检测异常文件变更模式并发出风险预警
 - **备份健康看板（V4）** — 一次调用全面查看：策略、数量、磁盘占用、保护范围、健康状态
+- **Web 仪表盘（V4.2）** — 本地只读 Web 页面 `http://127.0.0.1:3120`——健康状态、备份、恢复点、诊断、保护范围一目了然。中英双语、每 15 秒自动刷新、支持多项目监控
 
 ---
 
 ## 安装
 
-### 方式一：npm 安装
+### 方式一：npm 安装（推荐）
 
 ```bash
 npm install cursor-guard
+npx cursor-guard-init
 ```
 
-安装后，将技能文件复制到 Cursor 技能目录：
+`init` 命令一键完成：复制技能文件到 `.cursor/skills/cursor-guard/`、安装 MCP 依赖、添加 `.gitignore` 条目。
 
-**Windows (PowerShell):**
+可选参数：
 
-```powershell
-# 全局安装（所有项目生效）
-Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
-
-# 项目级安装（仅当前项目生效）
-Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
+```bash
+npx cursor-guard-init              # 项目级安装（默认）
+npx cursor-guard-init --global     # 全局安装（~/.cursor/skills/）
+npx cursor-guard-init --path /my/project  # 指定项目根目录
 ```
 
-**macOS / Linux:**
+初始化完成后，`node_modules` 中的 npm 包已不再需要：
 
 ```bash
-# 全局安装
-cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
-
-# 项目级安装
-cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+npm uninstall cursor-guard
 ```
 
-复制完成后，如果不需要保留在 `node_modules` 中，可以卸载：
+<details>
+<summary>手动安装（不使用 init 命令）</summary>
+
+如果你更喜欢手动操作，复制文件后需要手动安装依赖：
 
 ```bash
-npm uninstall cursor-guard
+# 复制
+cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+
+# 在 skill 目录中安装 MCP 依赖
+cd .cursor/skills/cursor-guard && npm install --omit=dev && cd -
+
+# 添加到 .gitignore，防止 node_modules 被 git 快照捕获
+echo ".cursor/skills/**/node_modules/" >> .gitignore
 ```
 
+</details>
+
 ### 方式二：Git 克隆
 
 ```bash
@@ -108,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/
@@ -242,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 已有核心模块
+
 ---
 
 ## 恢复
@@ -318,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

@@ -202,7 +202,7 @@ git update-ref refs/guard/snapshot $commit
 
 1. **Quick git init** (preferred):
    ```
-   git init && git add -A && git commit -m "guard: initial snapshot" --no-verify
+   git init; git add -A; git commit -m "guard: initial snapshot" --no-verify
    ```
 2. **Shadow copy** (fallback if user declines git):
    - Copy the target file(s) to `.cursor-guard-backup/<timestamp>/` via Shell.
@@ -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.0.0",
+  "version": "4.2.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",
@@ -27,9 +27,11 @@
     "test": "node references/lib/utils.test.js && node references/lib/core/core.test.js && node references/mcp/mcp.test.js"
   },
   "bin": {
+    "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",
@@ -47,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

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`Usage: cursor-guard-init [options]
+
+Installs cursor-guard skill into your Cursor skills directory, including
+MCP dependencies and .gitignore entries.
+
+Options:
+  --global             Install to ~/.cursor/skills/ (default: project-local)
+  --path <dir>         Project directory (default: current dir)
+  --help, -h           Show this help message
+  --version, -v        Show version number`);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const isGlobal = args.includes('--global');
+const pathIdx = args.indexOf('--path');
+const projectDir = path.resolve(pathIdx >= 0 && args[pathIdx + 1] ? args[pathIdx + 1] : '.');
+
+const skillSource = path.resolve(__dirname, '../..');
+const skillTarget = isGlobal
+  ? path.join(process.env.USERPROFILE || process.env.HOME || os.homedir(), '.cursor', 'skills', 'cursor-guard')
+  : path.join(projectDir, '.cursor', 'skills', 'cursor-guard');
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (path.basename(src) === 'node_modules') return;
+    if (path.basename(src) === '.git') return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+console.log(`\n  cursor-guard init\n`);
+console.log(`  Source:  ${skillSource}`);
+console.log(`  Target:  ${skillTarget}`);
+console.log(`  Mode:    ${isGlobal ? 'global (~/.cursor/skills/)' : 'project-local (.cursor/skills/)'}\n`);
+
+// Step 1: Copy skill files (excluding node_modules and .git)
+console.log('  [1/4] Copying skill files...');
+if (fs.existsSync(skillTarget)) {
+  fs.rmSync(skillTarget, { recursive: true, force: true });
+}
+copyRecursive(skillSource, skillTarget);
+console.log('        Done.');
+
+// Step 2: Install MCP dependencies in skill directory
+console.log('  [2/4] Installing MCP dependencies...');
+try {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  execFileSync(npmCmd, ['install', '--omit=dev', '--ignore-scripts'], {
+    cwd: skillTarget,
+    stdio: 'pipe',
+  });
+  console.log('        Done.');
+} catch (e) {
+  console.log(`        Warning: npm install failed (${e.message}). MCP tools may not work.`);
+  console.log('        You can fix this later: cd "' + skillTarget + '" ; npm install');
+}
+
+// Step 3: Add .gitignore entries for skill node_modules
+console.log('  [3/4] Updating .gitignore...');
+const gitignorePath = path.join(projectDir, '.gitignore');
+const entries = ['.cursor/skills/**/node_modules/'];
+let gitignoreUpdated = false;
+if (!isGlobal) {
+  let existing = '';
+  try { existing = fs.readFileSync(gitignorePath, 'utf-8'); } catch { /* doesn't exist */ }
+  const missing = entries.filter(e => !existing.includes(e));
+  if (missing.length > 0) {
+    const newline = existing.endsWith('\n') || !existing ? '' : '\n';
+    fs.appendFileSync(gitignorePath, `${newline}# cursor-guard skill dependencies\n${missing.join('\n')}\n`);
+    gitignoreUpdated = true;
+    console.log('        Added: ' + missing.join(', '));
+  } else {
+    console.log('        Already configured.');
+  }
+} else {
+  console.log('        Skipped (global install, not inside a project).');
+}
+
+// Step 4: Summary
+console.log('  [4/4] Verifying...');
+const serverExists = fs.existsSync(path.join(skillTarget, 'references', 'mcp', 'server.js'));
+const sdkExists = fs.existsSync(path.join(skillTarget, 'node_modules', '@modelcontextprotocol', 'sdk'));
+const skillMdExists = fs.existsSync(path.join(skillTarget, 'SKILL.md'));
+
+console.log(`        SKILL.md:   ${skillMdExists ? 'OK' : 'MISSING'}`);
+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:');
+console.log(`     cp "${path.join(skillTarget, 'references', 'cursor-guard.example.json')}" .cursor-guard.json`);
+console.log('  3. (Optional) Enable MCP — add to .cursor/mcp.json:');
+console.log(`     { "mcpServers": { "cursor-guard": { "command": "node", "args": ["${path.join(skillTarget, 'references', 'mcp', 'server.js').replace(/\\/g, '/')}"] } } }`);
+console.log('  4. (Optional) Start auto-backup:');
+console.log(`     npx cursor-guard-backup --path "${projectDir}"\n`);