cursor-guard 4.6.1 → 4.7.0

package/LICENSE

@@ -1,21 +1,65 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Business Source License 1.1
+
+Parameters
+
+Licensor:             zhangqiang8vipp
+Licensed Work:        cursor-guard
+                      The Licensed Work is (c) 2026 zhangqiang8vipp
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you may not use the Licensed Work for a Commercial Use.
+                      "Commercial Use" means distribution, sale, licensing,
+                      sublicensing, or providing the Licensed Work (or any
+                      derivative work) to third parties as a paid product or
+                      service, or incorporating it into a paid product or
+                      service offered to third parties.
+Change Date:          2056-03-22
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: zhangqiang8vipp
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-commercial use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited commercial
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -274,7 +274,7 @@ npx cursor-guard-dashboard --path /my/project --port 8080
 node references\dashboard\server.js --path "D:\MyProject"
 ```
 
-Then open `http://127.0.0.1:3120` in your browser.
+Then open `http://127.0.0.1:3120` in your browser. Or use the **IDE Extension** (see below) to embed the dashboard directly in your editor.
 
 Features:
 
@@ -287,6 +287,29 @@ Features:
 - **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
 
+### IDE Extension (VSCode / Cursor)
+
+Embed the full dashboard directly inside your IDE — no browser needed.
+
+The extension is located at `references/vscode-extension/`. To install:
+
+```bash
+# From the cursor-guard skill directory
+cd references/vscode-extension
+# Install as a development extension in your IDE
+code --install-extension .
+```
+
+Features:
+
+- **WebView Dashboard** — full dashboard embedded as an editor tab, identical to the browser version
+- **Status Bar Indicator** — shows `Guard: OK` (green) or `Guard: 22 files!` (yellow) in real-time
+- **Sidebar TreeView** — activity bar icon with project list, watcher status, backup stats, alerts, health
+- **Command Palette** — `Cursor Guard: Open Dashboard`, `Snapshot Now`, `Start Watcher`, `Refresh`
+- **Auto-activation** — detects `.cursor-guard.json` in workspace, starts dashboard server automatically
+- **Multi-project** — hot-loads all workspace folders with `.cursor-guard.json`
+- **Compatible** — works with VSCode ^1.74.0, Cursor, Windsurf, and all VSCode-based IDEs
+
 ---
 
 ## Recovery

package/README.zh-CN.md

@@ -274,7 +274,7 @@ npx cursor-guard-dashboard --path /my/project --port 8080
 node references\dashboard\server.js --path "D:\MyProject"
 ```
 
-然后在浏览器打开 `http://127.0.0.1:3120`。
+然后在浏览器打开 `http://127.0.0.1:3120`。也可以使用 **IDE 扩展**（见下方）将仪表盘直接嵌入编辑器。
 
 特性：
 
@@ -287,6 +287,29 @@ node references\dashboard\server.js --path "D:\MyProject"
 - **安全性** — 仅绑定 `127.0.0.1`（不暴露到局域网）、API 使用项目 ID 而非原始路径、静态文件服务严格限制在 `public/` 目录
 - **零额外依赖** — 使用 Node.js 内置 `http` 模块 + cursor-guard 已有核心模块
 
+### IDE 扩展（VSCode / Cursor）
+
+将完整仪表盘直接嵌入 IDE 内部，无需打开浏览器。
+
+扩展位于 `references/vscode-extension/`。安装方式：
+
+```bash
+# 从 cursor-guard skill 目录
+cd references/vscode-extension
+# 作为开发扩展安装到 IDE
+code --install-extension .
+```
+
+功能：
+
+- **WebView 仪表盘** — 完整仪表盘作为编辑器标签页嵌入，与浏览器版本完全一致
+- **状态栏指示器** — 实时显示 `Guard: OK`（绿色）或 `Guard: 22 files!`（黄色告警）
+- **侧边栏 TreeView** — Activity Bar 图标，树形展示项目列表、Watcher 状态、备份统计、告警、健康评估
+- **命令面板** — `Cursor Guard: Open Dashboard`、`Snapshot Now`、`Start Watcher`、`Refresh`
+- **自动激活** — 检测到工作区有 `.cursor-guard.json` 时自动启动 Dashboard 服务
+- **多项目** — 热加载所有包含 `.cursor-guard.json` 的工作区文件夹
+- **兼容性** — 支持 VSCode ^1.74.0、Cursor、Windsurf 及所有基于 VSCode 的 IDE
+
 ---
 
 ## 恢复

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.6.1`  
-> **文档状态**：`V2` ~ `V4.6.1` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.7.0`  
+> **文档状态**：`V2` ~ `V4.7.0` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,14 +734,19 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
-### V4.7 规划：IDE 集成（VSCode/Cursor Extension）
+### V4.7.0：IDE 集成（VSCode/Cursor Extension） ✅
 
-| 项目 | 说明 |
+| 组件 | 说明 |
 |------|------|
-| 定位 | 将 Dashboard 从浏览器迁移到 IDE 内置 WebView，减少上下文切换 |
-| 实现方式 | VSCode Extension + WebView Panel，复用现有 `dashboard/public/` 前端代码 |
-| 核心能力 | IDE 侧边栏入口、状态栏告警指示器、WebView 内嵌 Dashboard、一键快照按钮 |
-| 状态 | 🔮 规划中 |
+| `extension.js` | 扩展入口。自动检测 `.cursor-guard.json` 激活，启动内嵌 Dashboard Server，注册所有命令和视图 |
+| `dashboard-manager.js` | 复用现有 `dashboard/server.js` 单例模式，在扩展宿主进程内直接 require，零额外开销。支持多 workspace folder 热加载 |
+| `webview-provider.js` | WebView Panel 管理。加载 `dashboard/public/` 前端，通过 `asWebviewUri()` 转换资源路径，注入 `__GUARD_TOKEN__` + `__GUARD_BASE_URL__` + `__IN_VSCODE__` |
+| `status-bar.js` | 状态栏告警指示器。正常时显示 `$(shield) Guard: OK`，告警时黄色背景 `$(warning) Guard: 22 files!`，点击打开 Dashboard |
+| `tree-view.js` | Activity Bar 侧边栏。树形展示项目列表，每个项目下显示 Watcher 状态、最近备份时间、备份统计、活跃告警、健康评估 |
+| `poller.js` | 后台每 5 秒轮询 `/api/page-data`，驱动状态栏和 TreeView 实时更新 |
+| `app.js` 适配 | `fetchJson` 支持 `window.__GUARD_BASE_URL__` 前缀（兼容浏览器和 WebView）；`copyText` 在 VSCode 中通过 `postMessage` 桥接到 `vscode.env.clipboard` |
+| 命令面板 | `Open Dashboard` / `Snapshot Now` / `Start/Stop Watcher` / `Refresh` |
+| 兼容性 | VSCode ^1.74.0，覆盖 Cursor、Windsurf 等所有 VSCode 衍生 IDE |
 
 ### V4 不做的事
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.6.1",
+  "version": "4.7.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",
@@ -14,7 +14,7 @@
     "cross-platform"
   ],
   "author": "zhangqiang8vipp",
-  "license": "MIT",
+  "license": "BUSL-1.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/zhangqiang8vipp/cursor-guard.git"
@@ -50,6 +50,7 @@
     "references/lib/core/",
     "references/mcp/",
     "references/dashboard/",
+    "references/vscode-extension/",
     "references/config-reference.md",
     "references/config-reference.zh-CN.md",
     "references/cursor-guard.example.json",

package/references/dashboard/public/app.js

@@ -674,9 +674,10 @@ function relativeTime(ts) {
 /* ── Data fetching ────────────────────────────────────────── */
 
 async function fetchJson(url) {
+  const base = window.__GUARD_BASE_URL__ || '';
   const sep = url.includes('?') ? '&' : '?';
   const tokenParam = window.__GUARD_TOKEN__ ? `${sep}token=${window.__GUARD_TOKEN__}` : '';
-  const r = await fetch(url + tokenParam);
+  const r = await fetch(base + url + tokenParam);
   if (!r.ok) throw new Error(`HTTP ${r.status}`);
   return r.json();
 }
@@ -1526,16 +1527,21 @@ function openDoctorDrawer() {
 /* ── Copy to clipboard ────────────────────────────────────── */
 
 async function copyText(text) {
-  try {
-    await navigator.clipboard.writeText(text);
-  } catch {
-    const ta = document.createElement('textarea');
-    ta.value = text;
-    ta.style.cssText = 'position:fixed;left:-9999px';
-    document.body.appendChild(ta);
-    ta.select();
-    document.execCommand('copy');
-    document.body.removeChild(ta);
+  if (window.__IN_VSCODE__ && window.acquireVsCodeApi) {
+    try { window.__vscodeApi = window.__vscodeApi || acquireVsCodeApi(); } catch { /* already acquired */ }
+    window.__vscodeApi?.postMessage({ type: 'copy', text });
+  } else {
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      const ta = document.createElement('textarea');
+      ta.value = text;
+      ta.style.cssText = 'position:fixed;left:-9999px';
+      document.body.appendChild(ta);
+      ta.select();
+      document.execCommand('copy');
+      document.body.removeChild(ta);
+    }
   }
   showToast(t('drawer.copied'));
 }
@@ -1704,9 +1710,10 @@ async function restartServer(banner) {
   banner.querySelector('.upgrade-banner-close').style.display = 'none';
 
   try {
+    const base = window.__GUARD_BASE_URL__ || '';
     const sep = '/api/restart'.includes('?') ? '&' : '?';
     const tokenParam = window.__GUARD_TOKEN__ ? `${sep}token=${window.__GUARD_TOKEN__}` : '';
-    await fetch('/api/restart' + tokenParam, { method: 'POST' });
+    await fetch(base + '/api/restart' + tokenParam, { method: 'POST' });
   } catch { /* server may close connection */ }
 
   btn.textContent = t('upgrade.waiting');
@@ -1714,7 +1721,7 @@ async function restartServer(banner) {
   for (let i = 0; i < 20; i++) {
     await new Promise(r => setTimeout(r, 500));
     try {
-      const r = await fetch('/api/version' + (window.__GUARD_TOKEN__ ? '?token=' + window.__GUARD_TOKEN__ : ''));
+      const r = await fetch((window.__GUARD_BASE_URL__ || '') + '/api/version' + (window.__GUARD_TOKEN__ ? '?token=' + window.__GUARD_TOKEN__ : ''));
       if (r.ok) { ready = true; break; }
     } catch { /* still restarting */ }
   }

package/references/vscode-extension/.vscodeignore

@@ -0,0 +1,4 @@
+.vscode/**
+node_modules/**
+*.md
+.gitignore

package/references/vscode-extension/extension.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const vscode = require('vscode');
+const { DashboardManager } = require('./lib/dashboard-manager');
+const { WebViewProvider } = require('./lib/webview-provider');
+const { StatusBarController } = require('./lib/status-bar');
+const { GuardTreeView } = require('./lib/tree-view');
+const { Poller } = require('./lib/poller');
+
+let dashMgr, poller, statusBar, treeView, webviewProvider;
+
+async function activate(context) {
+  dashMgr = new DashboardManager();
+  poller = new Poller(dashMgr);
+  statusBar = new StatusBarController(poller);
+  treeView = new GuardTreeView(poller, dashMgr);
+  webviewProvider = new WebViewProvider(context, dashMgr);
+
+  context.subscriptions.push(
+    vscode.commands.registerCommand('cursorGuard.openDashboard', () => {
+      if (!dashMgr.running) {
+        vscode.window.showWarningMessage('Cursor Guard: no projects detected. Add .cursor-guard.json to your workspace.');
+        return;
+      }
+      webviewProvider.show();
+    }),
+
+    vscode.commands.registerCommand('cursorGuard.snapshotNow', async () => {
+      const folders = vscode.workspace.workspaceFolders;
+      if (!folders || folders.length === 0) return;
+      const projectPath = folders[0].uri.fsPath;
+      const result = await dashMgr.snapshotNow(projectPath);
+      if (result?.status === 'created') {
+        vscode.window.showInformationMessage(`Cursor Guard: snapshot created (${result.changedCount || 0} changes)`);
+      } else if (result?.status === 'unchanged') {
+        vscode.window.showInformationMessage('Cursor Guard: no changes to snapshot');
+      } else {
+        vscode.window.showWarningMessage(`Cursor Guard: ${result?.error || 'snapshot failed'}`);
+      }
+      poller.forceRefresh();
+    }),
+
+    vscode.commands.registerCommand('cursorGuard.startWatcher', () => {
+      vscode.window.showInformationMessage(
+        'Cursor Guard: run `cursor-guard-backup --path <dir> --dashboard` in terminal to start the watcher.'
+      );
+    }),
+
+    vscode.commands.registerCommand('cursorGuard.stopWatcher', () => {
+      vscode.window.showInformationMessage(
+        'Cursor Guard: stop the watcher by terminating its terminal process (Ctrl+C).'
+      );
+    }),
+
+    vscode.commands.registerCommand('cursorGuard.refreshTree', () => {
+      poller.forceRefresh();
+      treeView.refresh();
+    }),
+
+    statusBar,
+    poller,
+    treeView,
+    webviewProvider,
+  );
+
+  const started = await dashMgr.autoStart(vscode.workspace.workspaceFolders);
+  if (started) {
+    poller.start();
+    vscode.window.showInformationMessage(`Cursor Guard: dashboard started on port ${dashMgr.port}`);
+  }
+
+  context.subscriptions.push(
+    vscode.workspace.onDidChangeWorkspaceFolders(async () => {
+      const restarted = await dashMgr.autoStart(vscode.workspace.workspaceFolders);
+      if (restarted && !poller._timer) poller.start();
+      poller.forceRefresh();
+    })
+  );
+}
+
+function deactivate() {
+  if (poller) poller.dispose();
+  if (statusBar) statusBar.dispose();
+  if (treeView) treeView.dispose();
+  if (webviewProvider) webviewProvider.dispose();
+  if (dashMgr) dashMgr.dispose();
+}
+
+module.exports = { activate, deactivate };

package/references/vscode-extension/lib/dashboard-manager.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+
+const CONFIG_FILE = '.cursor-guard.json';
+
+class DashboardManager {
+  constructor() {
+    this._instance = null;
+    this._serverModule = null;
+  }
+
+  get running() { return !!this._instance; }
+  get port() { return this._instance?.port; }
+  get token() { return this._instance?.token; }
+  get baseUrl() { return this._instance ? `http://127.0.0.1:${this._instance.port}` : null; }
+  get registry() { return this._instance?.registry; }
+
+  async autoStart(workspaceFolders) {
+    if (!workspaceFolders || workspaceFolders.length === 0) return false;
+    const paths = workspaceFolders
+      .map(f => f.uri.fsPath)
+      .filter(p => fs.existsSync(path.join(p, CONFIG_FILE)));
+    if (paths.length === 0) return false;
+    return this.start(paths);
+  }
+
+  async start(paths) {
+    if (!this._serverModule) {
+      this._serverModule = require('../../dashboard/server');
+    }
+    const { startDashboardServer, getInstance } = this._serverModule;
+    const existing = getInstance();
+    if (existing) {
+      await startDashboardServer(paths, { silent: true });
+      this._instance = getInstance();
+    } else {
+      this._instance = await startDashboardServer(paths, { port: 3120, silent: true });
+    }
+    return true;
+  }
+
+  async fetchApi(endpoint) {
+    if (!this._instance) return null;
+    const url = `${this.baseUrl}${endpoint}${endpoint.includes('?') ? '&' : '?'}token=${this.token}`;
+    return new Promise((resolve, reject) => {
+      http.get(url, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try { resolve(JSON.parse(data)); }
+          catch { resolve(null); }
+        });
+      }).on('error', () => resolve(null));
+    });
+  }
+
+  async getProjects() {
+    return this.fetchApi('/api/projects') || [];
+  }
+
+  async getPageData(projectId, scope) {
+    const scopeParam = scope ? `&scope=${scope}` : '';
+    return this.fetchApi(`/api/page-data?id=${projectId}${scopeParam}`);
+  }
+
+  async snapshotNow(projectPath) {
+    if (!projectPath) return;
+    try {
+      const { createGitSnapshot } = require('../../lib/core/snapshot');
+      const { loadConfig } = require('../../lib/utils');
+      const cfg = loadConfig(projectPath);
+      return createGitSnapshot(projectPath, cfg, { message: 'guard: manual snapshot via IDE extension' });
+    } catch (e) {
+      return { status: 'error', error: e.message };
+    }
+  }
+
+  dispose() {
+    this._instance = null;
+  }
+}
+
+module.exports = { DashboardManager };

package/references/vscode-extension/lib/poller.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const vscode = require('vscode');
+
+const POLL_INTERVAL = 5000;
+
+class Poller {
+  constructor(dashMgr) {
+    this._dashMgr = dashMgr;
+    this._timer = null;
+    this._listeners = [];
+    this._data = new Map();
+  }
+
+  get data() { return this._data; }
+
+  onChange(fn) {
+    this._listeners.push(fn);
+    return { dispose: () => { this._listeners = this._listeners.filter(l => l !== fn); } };
+  }
+
+  _emit() {
+    for (const fn of this._listeners) {
+      try { fn(this._data); } catch { /* listener error */ }
+    }
+  }
+
+  start() {
+    if (this._timer) return;
+    this._poll();
+    this._timer = setInterval(() => this._poll(), POLL_INTERVAL);
+  }
+
+  stop() {
+    if (this._timer) { clearInterval(this._timer); this._timer = null; }
+  }
+
+  async _poll() {
+    if (!this._dashMgr.running) return;
+    try {
+      const projects = await this._dashMgr.getProjects();
+      if (!Array.isArray(projects)) return;
+      for (const p of projects) {
+        const pageData = await this._dashMgr.getPageData(p.id, 'dashboard');
+        this._data.set(p.id, { ...p, dashboard: pageData?.dashboard || null });
+      }
+      this._emit();
+    } catch { /* non-critical */ }
+  }
+
+  async forceRefresh() {
+    await this._poll();
+  }
+
+  dispose() {
+    this.stop();
+    this._listeners = [];
+  }
+}
+
+module.exports = { Poller };

package/references/vscode-extension/lib/status-bar.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const vscode = require('vscode');
+
+class StatusBarController {
+  constructor(poller) {
+    this._item = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Left, 100);
+    this._item.command = 'cursorGuard.openDashboard';
+    this._item.tooltip = 'Cursor Guard — click to open dashboard';
+    this._setIdle();
+    this._item.show();
+
+    this._sub = poller.onChange(data => this._update(data));
+  }
+
+  _setIdle() {
+    this._item.text = '$(shield) Guard';
+    this._item.backgroundColor = undefined;
+  }
+
+  _update(data) {
+    let hasAlert = false;
+    let watcherRunning = false;
+    let alertFileCount = 0;
+
+    for (const [, p] of data) {
+      const d = p.dashboard;
+      if (!d) continue;
+      if (d.alerts?.active) {
+        hasAlert = true;
+        alertFileCount = d.alerts.latest?.fileCount || 0;
+      }
+      if (d.watcher?.running) watcherRunning = true;
+    }
+
+    if (hasAlert) {
+      this._item.text = `$(warning) Guard: ${alertFileCount} files!`;
+      this._item.backgroundColor = new vscode.ThemeColor('statusBarItem.warningBackground');
+      this._item.tooltip = `Cursor Guard — ALERT: ${alertFileCount} files changed rapidly`;
+    } else if (watcherRunning) {
+      this._item.text = '$(shield) Guard: OK';
+      this._item.backgroundColor = undefined;
+      this._item.tooltip = 'Cursor Guard — watcher running, no alerts';
+    } else {
+      this._item.text = '$(shield) Guard';
+      this._item.backgroundColor = undefined;
+      this._item.tooltip = 'Cursor Guard — watcher not running';
+    }
+  }
+
+  dispose() {
+    this._sub?.dispose();
+    this._item.dispose();
+  }
+}
+
+module.exports = { StatusBarController };

package/references/vscode-extension/lib/tree-view.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const vscode = require('vscode');
+
+class GuardTreeView {
+  constructor(poller, dashMgr) {
+    this._poller = poller;
+    this._dashMgr = dashMgr;
+    this._onDidChange = new vscode.EventEmitter();
+    this.onDidChangeTreeData = this._onDidChange.event;
+
+    this._treeView = vscode.window.createTreeView('cursorGuardProjects', {
+      treeDataProvider: this,
+      showCollapseAll: true,
+    });
+
+    this._sub = poller.onChange(() => this._onDidChange.fire());
+  }
+
+  refresh() { this._onDidChange.fire(); }
+
+  getTreeItem(element) { return element; }
+
+  getChildren(element) {
+    if (!element) return this._getRootItems();
+    if (element.contextValue === 'project') return this._getProjectChildren(element.projectId);
+    return [];
+  }
+
+  _getRootItems() {
+    const data = this._poller.data;
+    if (data.size === 0) {
+      return [new TreeItem('No projects detected', 'info', { icon: 'info' })];
+    }
+    const items = [];
+    for (const [id, p] of data) {
+      const item = new TreeItem(p.name || id, 'project', {
+        icon: 'folder',
+        description: p.pathLabel,
+        collapsible: vscode.TreeItemCollapsibleState.Expanded,
+      });
+      item.projectId = id;
+      items.push(item);
+    }
+    return items;
+  }
+
+  _getProjectChildren(projectId) {
+    const p = this._poller.data.get(projectId);
+    if (!p?.dashboard) return [new TreeItem('Loading...', 'loading', { icon: 'loading~spin' })];
+    const d = p.dashboard;
+    const items = [];
+
+    const watcherStatus = d.watcher?.running ? 'Running' : 'Stopped';
+    const watcherIcon = d.watcher?.running ? 'eye' : 'eye-closed';
+    const watcherItem = new TreeItem(`Watcher: ${watcherStatus}`, 'watcher', { icon: watcherIcon });
+    if (d.watcher?.pid) watcherItem.description = `PID ${d.watcher.pid}`;
+    items.push(watcherItem);
+
+    if (d.lastBackup?.git) {
+      const ago = this._relativeTime(d.lastBackup.git.timestamp);
+      items.push(new TreeItem(`Last Backup: ${ago}`, 'backup', { icon: 'git-commit' }));
+    }
+
+    if (d.counts) {
+      const gitCount = d.counts.git?.commits || 0;
+      const shadowCount = d.counts.shadow?.snapshots || 0;
+      items.push(new TreeItem(`Backups: ${gitCount} git, ${shadowCount} shadow`, 'counts', { icon: 'database' }));
+    }
+
+    if (d.alerts?.active) {
+      const a = d.alerts.latest || {};
+      const alertItem = new TreeItem(
+        `ALERT: ${a.fileCount || '?'} files in ${a.windowSeconds || '?'}s`,
+        'alert',
+        { icon: 'warning' }
+      );
+      alertItem.description = `threshold: ${a.threshold}`;
+      items.push(alertItem);
+    }
+
+    const health = d.health?.status || 'unknown';
+    const healthIcon = health === 'healthy' ? 'pass' : health === 'critical' ? 'error' : 'warning';
+    const healthItem = new TreeItem(`Health: ${health}`, 'health', { icon: healthIcon });
+    if (d.health?.issues?.length > 0) {
+      healthItem.description = d.health.issues[0];
+    }
+    items.push(healthItem);
+
+    return items;
+  }
+
+  _relativeTime(ts) {
+    const diff = Date.now() - new Date(ts).getTime();
+    const sec = Math.floor(diff / 1000);
+    if (sec < 60) return `${sec}s ago`;
+    const min = Math.floor(sec / 60);
+    if (min < 60) return `${min}m ago`;
+    const hr = Math.floor(min / 60);
+    return `${hr}h ago`;
+  }
+
+  dispose() {
+    this._sub?.dispose();
+    this._treeView.dispose();
+    this._onDidChange.dispose();
+  }
+}
+
+class TreeItem extends vscode.TreeItem {
+  constructor(label, contextValue, opts = {}) {
+    super(label, opts.collapsible || vscode.TreeItemCollapsibleState.None);
+    this.contextValue = contextValue;
+    if (opts.icon) this.iconPath = new vscode.ThemeIcon(opts.icon);
+    if (opts.description) this.description = opts.description;
+  }
+}
+
+module.exports = { GuardTreeView };

package/references/vscode-extension/lib/webview-provider.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const vscode = require('vscode');
+const fs = require('fs');
+const path = require('path');
+
+const PUBLIC_DIR = path.resolve(__dirname, '..', '..', 'dashboard', 'public');
+
+class WebViewProvider {
+  constructor(context, dashMgr) {
+    this._context = context;
+    this._dashMgr = dashMgr;
+    this._panel = null;
+  }
+
+  show() {
+    if (this._panel) {
+      this._panel.reveal();
+      return;
+    }
+
+    this._panel = vscode.window.createWebviewPanel(
+      'cursorGuardDashboard',
+      'Cursor Guard Dashboard',
+      vscode.ViewColumn.One,
+      {
+        enableScripts: true,
+        retainContextWhenHidden: true,
+        localResourceRoots: [vscode.Uri.file(PUBLIC_DIR)],
+      }
+    );
+
+    this._panel.webview.html = this._buildHtml(this._panel.webview);
+    this._panel.iconPath = new vscode.ThemeIcon('shield');
+
+    this._panel.onDidDispose(() => { this._panel = null; });
+
+    this._panel.webview.onDidReceiveMessage(msg => {
+      if (msg.type === 'copy') {
+        vscode.env.clipboard.writeText(msg.text);
+        vscode.window.showInformationMessage('Copied to clipboard');
+      }
+    });
+  }
+
+  _buildHtml(webview) {
+    const htmlPath = path.join(PUBLIC_DIR, 'index.html');
+    let html = fs.readFileSync(htmlPath, 'utf-8');
+
+    const styleUri = webview.asWebviewUri(vscode.Uri.file(path.join(PUBLIC_DIR, 'style.css')));
+    const scriptUri = webview.asWebviewUri(vscode.Uri.file(path.join(PUBLIC_DIR, 'app.js')));
+
+    html = html.replace(/href="style\.css"/g, `href="${styleUri}"`);
+    html = html.replace(/src="app\.js"/g, `src="${scriptUri}"`);
+
+    const baseUrl = this._dashMgr.baseUrl || '';
+    const token = this._dashMgr.token || '';
+    const nonce = _getNonce();
+
+    html = html.replace(
+      '</head>',
+      `<script nonce="${nonce}">
+  window.__GUARD_TOKEN__ = "${token}";
+  window.__GUARD_BASE_URL__ = "${baseUrl}";
+  window.__IN_VSCODE__ = true;
+</script>
+</head>`
+    );
+
+    return html;
+  }
+
+  dispose() {
+    if (this._panel) { this._panel.dispose(); this._panel = null; }
+  }
+}
+
+function _getNonce() {
+  let text = '';
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  for (let i = 0; i < 32; i++) text += chars.charAt(Math.floor(Math.random() * chars.length));
+  return text;
+}
+
+module.exports = { WebViewProvider };

package/references/vscode-extension/media/ICON_README.md

@@ -0,0 +1,5 @@
+## Extension Icon
+
+Place a 128x128 PNG file named `icon.png` in this directory for the VS Code marketplace listing.
+
+The `guard-icon.svg` is used for the activity bar sidebar icon.

package/references/vscode-extension/media/guard-icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/>
+  <path d="M9 12l2 2 4-4"/>
+</svg>

package/references/vscode-extension/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "cursor-guard-ide",
+  "displayName": "Cursor Guard",
+  "description": "AI code protection dashboard embedded in your IDE — real-time alerts, backup history, one-click snapshots",
+  "version": "4.7.0",
+  "publisher": "zhangqiang8vipp",
+  "license": "BUSL-1.1",
+  "engines": {
+    "vscode": "^1.74.0"
+  },
+  "categories": ["Other", "Visualization"],
+  "keywords": ["cursor", "ai-safety", "code-protection", "git-backup", "dashboard"],
+  "icon": "media/icon.png",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhangqiang8vipp/cursor-guard"
+  },
+  "main": "./extension.js",
+  "activationEvents": [
+    "workspaceContains:.cursor-guard.json"
+  ],
+  "contributes": {
+    "commands": [
+      {
+        "command": "cursorGuard.openDashboard",
+        "title": "Open Dashboard",
+        "category": "Cursor Guard",
+        "icon": "$(dashboard)"
+      },
+      {
+        "command": "cursorGuard.snapshotNow",
+        "title": "Snapshot Now",
+        "category": "Cursor Guard",
+        "icon": "$(device-camera)"
+      },
+      {
+        "command": "cursorGuard.startWatcher",
+        "title": "Start Watcher",
+        "category": "Cursor Guard",
+        "icon": "$(eye)"
+      },
+      {
+        "command": "cursorGuard.stopWatcher",
+        "title": "Stop Watcher",
+        "category": "Cursor Guard",
+        "icon": "$(eye-closed)"
+      },
+      {
+        "command": "cursorGuard.refreshTree",
+        "title": "Refresh",
+        "category": "Cursor Guard",
+        "icon": "$(refresh)"
+      }
+    ],
+    "viewsContainers": {
+      "activitybar": [
+        {
+          "id": "cursorGuard",
+          "title": "Cursor Guard",
+          "icon": "media/guard-icon.svg"
+        }
+      ]
+    },
+    "views": {
+      "cursorGuard": [
+        {
+          "id": "cursorGuardProjects",
+          "name": "Projects"
+        }
+      ]
+    },
+    "menus": {
+      "view/title": [
+        {
+          "command": "cursorGuard.openDashboard",
+          "when": "view == cursorGuardProjects",
+          "group": "navigation"
+        },
+        {
+          "command": "cursorGuard.refreshTree",
+          "when": "view == cursorGuardProjects",
+          "group": "navigation"
+        }
+      ]
+    }
+  }
+}