cursor-guard 4.7.1 → 4.7.4

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.7.1`  
-> **文档状态**：`V2` ~ `V4.7.1` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.7.4`  
+> **文档状态**：`V2` ~ `V4.7.4` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,6 +734,40 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### V4.7.4：路径解析器 + 4 Bug 修复 ✅
+
+| 修复 | 说明 |
+|------|------|
+| **根本修复：`paths.js` 路径解析器** | 新增智能路径解析模块，支持 3 种安装方式：① Skill 目录结构（`references/vscode-extension/lib/` → `../../`）② VSIX 扁平结构（`lib/` → `../`）③ 全局 skill 目录回退（`~/.cursor/skills/cursor-guard/references/`）。所有模块统一使用 `guardPath()` 替代硬编码 `../../` |
+| **Bug #1: Dashboard 无法启动** | `dashboard-manager.js` 中 `require('../../dashboard/server')` 等 5 处路径在 VSIX 扁平结构中全部失败。改为 `require(guardPath('dashboard', 'server'))` |
+| **Bug #2: Snapshot Now 报错** | `snapshotNow` 中 `require('../../lib/core/snapshot')` 路径错误 + `loadConfig` 解构已在 v4.7.1 修复但 `require` 路径仍错。改为 `guardPath('lib', 'core', 'snapshot')` |
+| **Bug #3: snapshot skipped 未处理** | `createGitSnapshot` 无变更时返回 `{ status: 'skipped' }`，但 `extension.js` 只处理了 `created` 和 `unchanged`，导致显示 "snapshot failed"。新增 `skipped` 分支 |
+| **Bug #4: WebView PUBLIC_DIR 多一层 `..`** | `webview-provider.js` 的 `path.resolve(__dirname, '..', '..', 'dashboard', 'public')` 多了一层。改为 `getPublicDir()` 动态解析 |
+
+### V4.7.3：可视化图表侧边栏 ✅
+
+| 组件 | 说明 |
+|------|------|
+| **`sidebar-webview.js`** | 新增 `WebviewViewProvider`，在 Activity Bar 侧边栏底部渲染自定义 HTML/CSS 图表面板 |
+| **状态徽章行** | 4 个彩色卡片一行排列：Watcher（绿/红）、Alerts（红/绿）、Health（绿/黄/红）、Files（蓝） |
+| **告警横幅** | 活跃告警时显示红色横幅：文件数 + 窗口时间 + 阈值 + 倒计时 |
+| **进度条图表** | Backup Statistics 区域用 4 根彩色进度条展示：Git 备份数、Shadow 快照数、Git 磁盘、Shadow 磁盘，附系统剩余空间 |
+| **备份时间线** | Recent Backups 区域用圆点 + 时间 + 类型 + 摘要的紧凑列表展示最近 6 条备份 |
+| **健康问题列表** | 逐条展示 health issues，黄/红圆点标注严重度 |
+| **保护范围标签** | 用绿色/红色药丸标签展示 protect/ignore 规则 |
+| **快捷操作栏** | 4 个 hover 高亮按钮：Dashboard / Snapshot / Start / Stop |
+| **数据推送** | Poller 每 5 秒通过 `postMessage` 推送完整数据到 WebviewView，实时更新所有图表 |
+| **TreeView 精简** | 上方 TreeView 只保留项目概要（名称/状态/操作），详细数据全在图表面板 |
+
+### V4.7.2：Sidebar Mini Dashboard + Watcher 修复 ✅
+
+| 修复/增强 | 说明 |
+|----------|------|
+| **Watcher 无限重启修复** | `startWatcher` 误用 `lib/auto-backup.js`（库模块），改为正确的 CLI 入口 `bin/cursor-guard-backup.js`；新增防重复检查（已有进程则跳过） |
+| **TreeView Mini Dashboard** | 侧边栏从简单列表重构为 7 个信息密集的折叠区：Watcher 详情（PID/启动时间/策略）、告警详情（倒计时/文件列表 top 10）、近期备份（最近 8 条 + 摘要/时间/类型）、统计（git/shadow 数量 + 磁盘占用 + 系统剩余空间）、健康检查（逐条 issue）、保护范围（protect/ignore 规则 + 文件数）、快捷操作 |
+| **Poller 完整数据** | 后台轮询从只拉 `dashboard` scope 改为拉取完整 page data（含 backups/scope/doctor），驱动 TreeView 展示更多信息 |
+| **彩色区分** | 7 个 section 使用不同 ThemeColor（绿=正常/红=告警/蓝=备份/紫=统计/橙=配置/黄=警告），项目节点根据状态显示 Protected/Unprotected/ALERT |
+
 ### V4.7.1：IDE 插件 Bug 修复 + UX 增强 ✅
 
 | 修复/增强 | 说明 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.7.1",
+  "version": "4.7.4",
   "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",

package/references/vscode-extension/extension.js

@@ -6,8 +6,9 @@ const { WebViewProvider } = require('./lib/webview-provider');
 const { StatusBarController } = require('./lib/status-bar');
 const { GuardTreeView } = require('./lib/tree-view');
 const { Poller } = require('./lib/poller');
+const { SidebarDashboardProvider } = require('./lib/sidebar-webview');
 
-let dashMgr, poller, statusBar, treeView, webviewProvider;
+let dashMgr, poller, statusBar, treeView, webviewProvider, sidebarProvider;
 
 async function activate(context) {
   dashMgr = new DashboardManager();
@@ -15,8 +16,11 @@ async function activate(context) {
   statusBar = new StatusBarController(poller);
   treeView = new GuardTreeView(poller, dashMgr);
   webviewProvider = new WebViewProvider(context, dashMgr);
+  sidebarProvider = new SidebarDashboardProvider(poller);
 
   context.subscriptions.push(
+    vscode.window.registerWebviewViewProvider('cursorGuardDashboard', sidebarProvider),
+
     vscode.commands.registerCommand('cursorGuard.openDashboard', () => {
       if (!dashMgr.running) {
         vscode.window.showWarningMessage('Cursor Guard: no projects detected. Add .cursor-guard.json to your workspace.');
@@ -32,10 +36,12 @@ async function activate(context) {
       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') {
+      } else if (result?.status === 'unchanged' || result?.status === 'skipped') {
         vscode.window.showInformationMessage('Cursor Guard: no changes to snapshot');
+      } else if (result?.status === 'error') {
+        vscode.window.showWarningMessage(`Cursor Guard: ${result.error}`);
       } else {
-        vscode.window.showWarningMessage(`Cursor Guard: ${result?.error || 'snapshot failed'}`);
+        vscode.window.showWarningMessage(`Cursor Guard: snapshot returned status "${result?.status || 'unknown'}"`);
       }
       poller.forceRefresh();
     }),
@@ -83,6 +89,7 @@ async function activate(context) {
     poller,
     treeView,
     webviewProvider,
+    sidebarProvider,
   );
 
   const started = await dashMgr.autoStart(vscode.workspace.workspaceFolders);
@@ -105,6 +112,7 @@ function deactivate() {
   if (statusBar) statusBar.dispose();
   if (treeView) treeView.dispose();
   if (webviewProvider) webviewProvider.dispose();
+  if (sidebarProvider) sidebarProvider.dispose();
   if (dashMgr) dashMgr.dispose();
 }
 

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

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const http = require('http');
 const { spawn } = require('child_process');
+const { guardPath } = require('./paths');
 
 const CONFIG_FILE = '.cursor-guard.json';
 
@@ -30,7 +31,7 @@ class DashboardManager {
 
   async start(paths) {
     if (!this._serverModule) {
-      this._serverModule = require('../../dashboard/server');
+      this._serverModule = require(guardPath('dashboard', 'server'));
     }
     const { startDashboardServer, getInstance } = this._serverModule;
     const existing = getInstance();
@@ -46,7 +47,7 @@ class DashboardManager {
   async fetchApi(endpoint) {
     if (!this._instance) return null;
     const url = `${this.baseUrl}${endpoint}${endpoint.includes('?') ? '&' : '?'}token=${this.token}`;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
       http.get(url, (res) => {
         let data = '';
         res.on('data', chunk => data += chunk);
@@ -67,11 +68,19 @@ class DashboardManager {
     return this.fetchApi(`/api/page-data?id=${projectId}${scopeParam}`);
   }
 
+  async getFullPageData(projectId) {
+    return this.fetchApi(`/api/page-data?id=${projectId}`);
+  }
+
+  async getBackupFiles(projectId, hash) {
+    return this.fetchApi(`/api/backup-files?id=${projectId}&hash=${hash}`);
+  }
+
   async snapshotNow(projectPath) {
     if (!projectPath) return;
     try {
-      const { createGitSnapshot } = require('../../lib/core/snapshot');
-      const { loadConfig } = require('../../lib/utils');
+      const { createGitSnapshot } = require(guardPath('lib', 'core', 'snapshot'));
+      const { loadConfig } = require(guardPath('lib', 'utils'));
       const { cfg } = loadConfig(projectPath);
       return createGitSnapshot(projectPath, cfg, { message: 'guard: manual snapshot via IDE extension' });
     } catch (e) {
@@ -81,11 +90,14 @@ class DashboardManager {
 
   startWatcher(projectPath) {
     if (!projectPath) return null;
-    const backupScript = path.resolve(__dirname, '..', '..', 'lib', 'auto-backup.js');
-    const child = spawn(process.execPath, [backupScript, '--path', projectPath], {
+    const existingPid = this.getWatcherPid(projectPath);
+    if (existingPid) return existingPid;
+    const cliScript = guardPath('bin', 'cursor-guard-backup.js');
+    const child = spawn(process.execPath, [cliScript, '--path', projectPath], {
       cwd: projectPath,
       stdio: 'ignore',
       detached: true,
+      env: { ...process.env, GUARD_SPAWNED_BY_EXT: '1' },
     });
     child.unref();
     return child.pid;

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

@@ -0,0 +1,72 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+let _guardRoot = null;
+
+function getGuardRoot() {
+  if (_guardRoot) return _guardRoot;
+
+  const marker = path.join('dashboard', 'server.js');
+
+  // Strategy 1: skill dir structure — lib/ is inside references/vscode-extension/
+  const fromSkill = path.resolve(__dirname, '..', '..');
+  if (fs.existsSync(path.join(fromSkill, marker))) {
+    _guardRoot = fromSkill;
+    return _guardRoot;
+  }
+
+  // Strategy 2: VSIX flat — dashboard/ is sibling to lib/
+  const fromFlat = path.resolve(__dirname, '..');
+  if (fs.existsSync(path.join(fromFlat, marker))) {
+    _guardRoot = fromFlat;
+    return _guardRoot;
+  }
+
+  // Strategy 3: search common skill install locations
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+  const candidates = [
+    path.join(home, '.cursor', 'skills', 'cursor-guard', 'references'),
+    path.join(home, '.cursor', 'skills', 'cursor-guard'),
+  ];
+
+  // Strategy 4: search workspace node_modules
+  if (typeof require.main?.filename === 'string') {
+    const wsRoot = path.dirname(require.main.filename);
+    candidates.push(path.join(wsRoot, 'node_modules', 'cursor-guard', 'references'));
+  }
+
+  for (const dir of candidates) {
+    if (fs.existsSync(path.join(dir, marker))) {
+      _guardRoot = dir;
+      return _guardRoot;
+    }
+  }
+
+  throw new Error(
+    'Cannot locate cursor-guard installation. '
+    + 'Ensure cursor-guard is installed as a skill or via npm.'
+  );
+}
+
+function guardPath(...segments) {
+  return path.join(getGuardRoot(), ...segments);
+}
+
+function getPackageJson() {
+  const root = getGuardRoot();
+  // package.json is one level above references/ in skill structure
+  const skillPkg = path.resolve(root, '..', 'package.json');
+  if (fs.existsSync(skillPkg)) return skillPkg;
+  // or at the same level in flat structure
+  const flatPkg = path.join(root, 'package.json');
+  if (fs.existsSync(flatPkg)) return flatPkg;
+  return null;
+}
+
+function getPublicDir() {
+  return guardPath('dashboard', 'public');
+}
+
+module.exports = { getGuardRoot, guardPath, getPackageJson, getPublicDir };

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

@@ -41,8 +41,14 @@ class Poller {
       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 });
+        const fullData = await this._dashMgr.getFullPageData(p.id);
+        this._data.set(p.id, {
+          ...p,
+          dashboard: fullData?.dashboard || null,
+          backups: fullData?.backups || [],
+          scope: fullData?.scope || null,
+          doctor: fullData?.doctor || null,
+        });
       }
       this._emit();
     } catch { /* non-critical */ }

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

@@ -0,0 +1,383 @@
+'use strict';
+
+const vscode = require('vscode');
+
+class SidebarDashboardProvider {
+  constructor(poller) {
+    this._poller = poller;
+    this._view = null;
+    this._sub = poller.onChange(data => this._push(data));
+  }
+
+  resolveWebviewView(webviewView) {
+    this._view = webviewView;
+    webviewView.webview.options = { enableScripts: true };
+    webviewView.webview.html = _getHtml();
+
+    webviewView.webview.onDidReceiveMessage(msg => {
+      if (msg.cmd === 'ready') this._push(this._poller.data);
+      if (msg.cmd === 'exec') vscode.commands.executeCommand(msg.command);
+    });
+
+    webviewView.onDidChangeVisibility(() => {
+      if (webviewView.visible) this._push(this._poller.data);
+    });
+  }
+
+  _push(data) {
+    if (!this._view?.visible) return;
+    const payload = {};
+    for (const [id, p] of data) {
+      payload[id] = {
+        name: p.name || id,
+        dashboard: p.dashboard,
+        backups: (p.backups || []).slice(0, 6),
+      };
+    }
+    this._view.webview.postMessage({ type: 'update', data: payload });
+  }
+
+  dispose() {
+    this._sub?.dispose();
+  }
+}
+
+function _getHtml() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<style>
+:root {
+  --bg: #1e1e2e;
+  --surface: #282838;
+  --border: #383850;
+  --text: #cdd6f4;
+  --dim: #6c7086;
+  --green: #a6e3a1;
+  --red: #f38ba8;
+  --yellow: #f9e2af;
+  --blue: #89b4fa;
+  --purple: #cba6f7;
+  --orange: #fab387;
+  --teal: #94e2d5;
+  --radius: 6px;
+}
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body {
+  font: 11px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  color: var(--text);
+  background: transparent;
+  padding: 8px;
+}
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 8px 10px;
+  margin-bottom: 6px;
+}
+.card-title {
+  font-size: 9px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.8px;
+  color: var(--dim);
+  margin-bottom: 6px;
+}
+.status-row {
+  display: flex;
+  gap: 6px;
+  margin-bottom: 6px;
+}
+.status-badge {
+  flex: 1;
+  text-align: center;
+  padding: 6px 4px;
+  border-radius: var(--radius);
+  background: var(--bg);
+  border: 1px solid var(--border);
+}
+.status-badge .icon { font-size: 16px; display: block; }
+.status-badge .label { font-size: 9px; color: var(--dim); margin-top: 2px; }
+.status-badge .value { font-size: 11px; font-weight: 700; }
+.status-badge.ok { border-color: var(--green); }
+.status-badge.ok .value { color: var(--green); }
+.status-badge.warn { border-color: var(--yellow); }
+.status-badge.warn .value { color: var(--yellow); }
+.status-badge.danger { border-color: var(--red); }
+.status-badge.danger .value { color: var(--red); }
+.status-badge.info { border-color: var(--blue); }
+.status-badge.info .value { color: var(--blue); }
+
+.alert-bar {
+  background: rgba(243,139,168,0.15);
+  border: 1px solid var(--red);
+  border-radius: var(--radius);
+  padding: 6px 10px;
+  margin-bottom: 6px;
+  text-align: center;
+}
+.alert-bar .alert-title { color: var(--red); font-weight: 700; font-size: 12px; }
+.alert-bar .alert-detail { color: var(--dim); font-size: 10px; margin-top: 2px; }
+.alert-bar.hidden { display: none; }
+
+.bar-group { margin-bottom: 4px; }
+.bar-label {
+  display: flex;
+  justify-content: space-between;
+  font-size: 10px;
+  margin-bottom: 2px;
+}
+.bar-label .name { color: var(--text); }
+.bar-label .val { color: var(--dim); font-weight: 600; }
+.bar-track {
+  height: 6px;
+  background: var(--bg);
+  border-radius: 3px;
+  overflow: hidden;
+}
+.bar-fill {
+  height: 100%;
+  border-radius: 3px;
+  transition: width 0.4s ease;
+}
+.bar-fill.blue { background: var(--blue); }
+.bar-fill.purple { background: var(--purple); }
+.bar-fill.green { background: var(--green); }
+.bar-fill.orange { background: var(--orange); }
+.bar-fill.teal { background: var(--teal); }
+
+.backup-list { list-style: none; }
+.backup-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 0;
+  border-bottom: 1px solid var(--border);
+  font-size: 10px;
+}
+.backup-item:last-child { border: none; }
+.backup-dot {
+  width: 6px; height: 6px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+.backup-dot.auto { background: var(--blue); }
+.backup-dot.snapshot { background: var(--purple); }
+.backup-dot.restore { background: var(--orange); }
+.backup-time { color: var(--dim); white-space: nowrap; }
+.backup-type { font-weight: 600; min-width: 36px; }
+.backup-summary { color: var(--dim); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1; }
+
+.scope-tags { display: flex; flex-wrap: wrap; gap: 3px; margin-top: 4px; }
+.scope-tag {
+  font-size: 9px;
+  padding: 1px 6px;
+  border-radius: 10px;
+  background: var(--bg);
+}
+.scope-tag.protect { color: var(--green); border: 1px solid var(--green); }
+.scope-tag.ignore { color: var(--red); border: 1px solid var(--red); }
+
+.health-row { display: flex; align-items: center; gap: 4px; font-size: 10px; padding: 2px 0; }
+.health-dot { width: 5px; height: 5px; border-radius: 50%; flex-shrink: 0; }
+
+.actions-row { display: flex; gap: 4px; flex-wrap: wrap; }
+.action-btn {
+  flex: 1;
+  min-width: 70px;
+  padding: 5px 4px;
+  font-size: 9px;
+  font-weight: 600;
+  text-align: center;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--bg);
+  color: var(--text);
+  cursor: pointer;
+  transition: all 0.15s;
+}
+.action-btn:hover { border-color: var(--blue); color: var(--blue); }
+
+.empty-state {
+  text-align: center;
+  padding: 20px;
+  color: var(--dim);
+  font-size: 11px;
+}
+
+.ring-chart {
+  position: relative;
+  width: 56px; height: 56px;
+  margin: 0 auto 4px;
+}
+.ring-chart svg { transform: rotate(-90deg); }
+.ring-chart .ring-bg { stroke: var(--bg); }
+.ring-chart .ring-fill { transition: stroke-dashoffset 0.6s ease; }
+.ring-label {
+  position: absolute;
+  top: 50%; left: 50%;
+  transform: translate(-50%, -50%);
+  font-size: 12px;
+  font-weight: 700;
+}
+</style>
+</head>
+<body>
+<div id="root">
+  <div class="empty-state">Waiting for data...</div>
+</div>
+<script>
+const vscode = acquireVsCodeApi();
+window.addEventListener('message', e => {
+  if (e.data.type === 'update') render(e.data.data);
+});
+vscode.postMessage({ cmd: 'ready' });
+
+function render(projects) {
+  const ids = Object.keys(projects);
+  if (ids.length === 0) {
+    document.getElementById('root').innerHTML = '<div class="empty-state">No projects detected</div>';
+    return;
+  }
+  let html = '';
+  for (const id of ids) {
+    const p = projects[id];
+    const d = p.dashboard;
+    if (!d) { html += '<div class="empty-state">Loading ' + esc(p.name) + '...</div>'; continue; }
+    html += renderProject(p.name, d, p.backups || []);
+  }
+  html += renderActions();
+  document.getElementById('root').innerHTML = html;
+  document.querySelectorAll('.action-btn').forEach(btn => {
+    btn.addEventListener('click', () => vscode.postMessage({ cmd: 'exec', command: btn.dataset.cmd }));
+  });
+}
+
+function renderProject(name, d, backups) {
+  let h = '';
+
+  // Status badges row
+  const wOk = d.watcher?.running;
+  const hasAlert = d.alerts?.active;
+  const health = d.health?.status || 'unknown';
+
+  h += '<div class="status-row">';
+  h += badge(wOk ? '👁' : '🚫', 'Watcher', wOk ? 'Running' : 'Stopped', wOk ? 'ok' : 'danger');
+  h += badge(hasAlert ? '🔔' : '✅', 'Alerts', hasAlert ? (d.alerts.latest?.fileCount || '!') : 'None', hasAlert ? 'danger' : 'ok');
+  h += badge('💚', 'Health', health, health === 'healthy' ? 'ok' : health === 'critical' ? 'danger' : 'warn');
+  h += badge('📁', 'Files', d.protectionScope?.fileCount || 0, 'info');
+  h += '</div>';
+
+  // Alert bar
+  if (hasAlert) {
+    const a = d.alerts.latest;
+    const remain = a.expiresAt ? Math.max(0, Math.ceil((new Date(a.expiresAt).getTime() - Date.now()) / 1000)) : 0;
+    const display = remain > 60 ? Math.floor(remain/60) + 'm ' + (remain%60) + 's' : remain + 's';
+    h += '<div class="alert-bar">';
+    h += '<div class="alert-title">⚠ ' + (a.fileCount||'?') + ' files changed in ' + (a.windowSeconds||'?') + 's</div>';
+    h += '<div class="alert-detail">Threshold: ' + (a.threshold||'?') + ' · Expires: ' + display + '</div>';
+    h += '</div>';
+  }
+
+  // Backup stats bars
+  const gitC = d.counts?.git?.commits || 0;
+  const shadowC = d.counts?.shadow?.snapshots || 0;
+  const maxC = Math.max(gitC, shadowC, 1);
+  const gitDisk = d.diskUsage?.git?.display || '0B';
+  const shadowDisk = d.diskUsage?.shadow?.display || '0B';
+  const gitBytes = d.diskUsage?.git?.bytes || 0;
+  const shadowBytes = d.diskUsage?.shadow?.bytes || 0;
+  const maxBytes = Math.max(gitBytes, shadowBytes, 1);
+
+  h += '<div class="card">';
+  h += '<div class="card-title">Backup Statistics</div>';
+  h += bar('Git backups', gitC, gitC / maxC * 100, 'blue');
+  h += bar('Shadow snapshots', shadowC, shadowC / maxC * 100, 'purple');
+  h += bar('Git disk', gitDisk, gitBytes / maxBytes * 100, 'teal');
+  h += bar('Shadow disk', shadowDisk, shadowBytes / maxBytes * 100, 'orange');
+  if (d.disk) {
+    h += '<div class="bar-label" style="margin-top:4px"><span class="name">System free</span><span class="val">' + d.disk.freeGB + ' GB</span></div>';
+  }
+  h += '</div>';
+
+  // Recent backups timeline
+  h += '<div class="card">';
+  h += '<div class="card-title">Recent Backups</div>';
+  if (backups.length === 0) {
+    h += '<div style="color:var(--dim);font-size:10px">No backups yet</div>';
+  } else {
+    h += '<ul class="backup-list">';
+    for (const b of backups) {
+      const time = b.timestamp ? new Date(b.timestamp).toLocaleTimeString([], {hour:'2-digit',minute:'2-digit',second:'2-digit'}) : '?';
+      const type = b.type || 'auto';
+      const dotClass = type === 'git-snapshot' ? 'snapshot' : type === 'pre-restore' ? 'restore' : 'auto';
+      const typeLabel = type === 'git-snapshot' ? 'snap' : type === 'pre-restore' ? 'pre-rst' : 'auto';
+      const summary = b.summary ? truncate(b.summary, 30) : '';
+      const files = b.filesChanged ? b.filesChanged + ' files' : '';
+      h += '<li class="backup-item">';
+      h += '<span class="backup-dot ' + dotClass + '"></span>';
+      h += '<span class="backup-time">' + time + '</span>';
+      h += '<span class="backup-type">' + typeLabel + '</span>';
+      h += '<span class="backup-summary">' + esc(files + (files && summary ? ' · ' : '') + summary) + '</span>';
+      h += '</li>';
+    }
+    h += '</ul>';
+  }
+  h += '</div>';
+
+  // Health issues
+  if (d.health?.issues?.length > 0) {
+    h += '<div class="card">';
+    h += '<div class="card-title">Health Issues</div>';
+    for (const issue of d.health.issues) {
+      const critical = issue.includes('critically') || issue.includes('requires Git');
+      h += '<div class="health-row"><span class="health-dot" style="background:' + (critical ? 'var(--red)' : 'var(--yellow)') + '"></span>' + esc(issue) + '</div>';
+    }
+    h += '</div>';
+  }
+
+  // Protection scope
+  h += '<div class="card">';
+  h += '<div class="card-title">Protection Scope</div>';
+  const protect = d.protectionScope?.protect || ['**'];
+  const ignore = d.protectionScope?.ignore || [];
+  h += '<div style="font-size:10px;margin-bottom:4px">' + (d.protectionScope?.fileCount || 0) + ' files monitored</div>';
+  h += '<div class="scope-tags">';
+  for (const p of protect) h += '<span class="scope-tag protect">✓ ' + esc(p) + '</span>';
+  for (const i of ignore.slice(0, 6)) h += '<span class="scope-tag ignore">✗ ' + esc(i) + '</span>';
+  if (ignore.length > 6) h += '<span class="scope-tag ignore">+' + (ignore.length - 6) + ' more</span>';
+  h += '</div></div>';
+
+  return h;
+}
+
+function renderActions() {
+  return '<div class="card"><div class="card-title">Quick Actions</div><div class="actions-row">'
+    + '<button class="action-btn" data-cmd="cursorGuard.openDashboard">🖥 Dashboard</button>'
+    + '<button class="action-btn" data-cmd="cursorGuard.snapshotNow">📸 Snapshot</button>'
+    + '<button class="action-btn" data-cmd="cursorGuard.startWatcher">▶ Start</button>'
+    + '<button class="action-btn" data-cmd="cursorGuard.stopWatcher">⏹ Stop</button>'
+    + '</div></div>';
+}
+
+function badge(icon, label, value, cls) {
+  return '<div class="status-badge ' + cls + '">'
+    + '<span class="icon">' + icon + '</span>'
+    + '<span class="value">' + esc(String(value)) + '</span>'
+    + '<span class="label">' + label + '</span>'
+    + '</div>';
+}
+function bar(name, val, pct, color) {
+  return '<div class="bar-group"><div class="bar-label"><span class="name">' + name + '</span><span class="val">' + val + '</span></div>'
+    + '<div class="bar-track"><div class="bar-fill ' + color + '" style="width:' + Math.max(pct, 2) + '%"></div></div></div>';
+}
+function esc(s) { return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;'); }
+function truncate(s, n) { return s.length > n ? s.slice(0, n) + '...' : s; }
+</script>
+</body>
+</html>`;
+}
+
+module.exports = { SidebarDashboardProvider };

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

@@ -2,6 +2,15 @@
 
 const vscode = require('vscode');
 
+const C = {
+  green: new vscode.ThemeColor('charts.green'),
+  red: new vscode.ThemeColor('charts.red'),
+  yellow: new vscode.ThemeColor('charts.yellow'),
+  blue: new vscode.ThemeColor('charts.blue'),
+  purple: new vscode.ThemeColor('charts.purple'),
+  orange: new vscode.ThemeColor('charts.orange'),
+};
+
 class GuardTreeView {
   constructor(poller, dashMgr) {
     this._poller = poller;
@@ -11,179 +20,82 @@ class GuardTreeView {
 
     this._treeView = vscode.window.createTreeView('cursorGuardProjects', {
       treeDataProvider: this,
-      showCollapseAll: true,
+      showCollapseAll: false,
     });
 
     this._sub = poller.onChange(() => this._onDidChange.fire());
   }
 
   refresh() { this._onDidChange.fire(); }
+  getTreeItem(el) { return el; }
 
-  getTreeItem(element) { return element; }
-
-  getChildren(element) {
-    if (!element) return this._getRootItems();
-    if (element.contextValue === 'project') return this._getProjectChildren(element.projectId);
-    if (element.contextValue === 'actions') return this._getActionItems();
+  getChildren(el) {
+    if (!el) return this._getRootItems();
+    if (el.contextValue === 'project') return this._getProjectStatus(el.projectId);
     return [];
   }
 
   _getRootItems() {
     const data = this._poller.data;
-    const items = [];
-
     if (data.size === 0) {
-      const hint = new TreeItem('No projects detected', 'info', {
-        icon: new vscode.ThemeIcon('info', new vscode.ThemeColor('charts.yellow')),
-        description: 'Add .cursor-guard.json',
+      return [_item('No projects detected', 'info', { icon: 'info', color: C.yellow, desc: 'Add .cursor-guard.json' })];
+    }
+    const items = [];
+    for (const [id, p] of data) {
+      const d = p.dashboard;
+      const hasAlert = d?.alerts?.active;
+      const watcherOk = d?.watcher?.running;
+      const color = hasAlert ? C.red : watcherOk ? C.green : C.yellow;
+      const status = hasAlert ? `ALERT ${d.alerts.latest?.fileCount || ''} files` : watcherOk ? 'Protected' : 'Unprotected';
+      const item = _item(p.name || id, 'project', {
+        icon: hasAlert ? 'bell' : watcherOk ? 'shield' : 'eye-closed',
+        color,
+        desc: status,
+        collapsible: vscode.TreeItemCollapsibleState.Expanded,
       });
-      items.push(hint);
-    } else {
-      for (const [id, p] of data) {
-        const d = p.dashboard;
-        const hasAlert = d?.alerts?.active;
-        const watcherOk = d?.watcher?.running;
-        const iconColor = hasAlert
-          ? new vscode.ThemeColor('charts.red')
-          : watcherOk
-            ? new vscode.ThemeColor('charts.green')
-            : new vscode.ThemeColor('charts.yellow');
-        const icon = hasAlert
-          ? new vscode.ThemeIcon('shield', iconColor)
-          : watcherOk
-            ? new vscode.ThemeIcon('shield', iconColor)
-            : new vscode.ThemeIcon('shield', iconColor);
-
-        const item = new TreeItem(p.name || id, 'project', {
-          icon,
-          description: hasAlert ? 'ALERT' : watcherOk ? 'Protected' : 'Unprotected',
-          collapsible: vscode.TreeItemCollapsibleState.Expanded,
-        });
-        item.projectId = id;
-        items.push(item);
-      }
+      item.projectId = id;
+      items.push(item);
     }
-
-    const actionsItem = new TreeItem('Quick Actions', 'actions', {
-      icon: new vscode.ThemeIcon('zap', new vscode.ThemeColor('charts.blue')),
-      collapsible: vscode.TreeItemCollapsibleState.Collapsed,
-    });
-    items.push(actionsItem);
-
     return items;
   }
 
-  _getActionItems() {
-    const openDash = new TreeItem('Open Dashboard', 'action', {
-      icon: new vscode.ThemeIcon('dashboard', new vscode.ThemeColor('charts.blue')),
-    });
-    openDash.command = { command: 'cursorGuard.openDashboard', title: 'Open Dashboard' };
-
-    const snapshot = new TreeItem('Snapshot Now', 'action', {
-      icon: new vscode.ThemeIcon('device-camera', new vscode.ThemeColor('charts.purple')),
-    });
-    snapshot.command = { command: 'cursorGuard.snapshotNow', title: 'Snapshot Now' };
-
-    const startW = new TreeItem('Start Watcher', 'action', {
-      icon: new vscode.ThemeIcon('play', new vscode.ThemeColor('charts.green')),
-    });
-    startW.command = { command: 'cursorGuard.startWatcher', title: 'Start Watcher' };
-
-    const stopW = new TreeItem('Stop Watcher', 'action', {
-      icon: new vscode.ThemeIcon('debug-stop', new vscode.ThemeColor('charts.red')),
-    });
-    stopW.command = { command: 'cursorGuard.stopWatcher', title: 'Stop Watcher' };
-
-    const refresh = new TreeItem('Refresh', 'action', {
-      icon: new vscode.ThemeIcon('refresh', new vscode.ThemeColor('charts.orange')),
-    });
-    refresh.command = { command: 'cursorGuard.refreshTree', title: 'Refresh' };
-
-    return [openDash, snapshot, startW, stopW, refresh];
-  }
-
-  _getProjectChildren(projectId) {
-    const p = this._poller.data.get(projectId);
-    if (!p?.dashboard) {
-      return [new TreeItem('Loading...', 'loading', {
-        icon: new vscode.ThemeIcon('loading~spin', new vscode.ThemeColor('charts.blue')),
-      })];
-    }
+  _getProjectStatus(pid) {
+    const p = this._poller.data.get(pid);
+    if (!p?.dashboard) return [_item('Loading...', 'loading', { icon: 'loading~spin', color: C.blue })];
     const d = p.dashboard;
     const items = [];
 
     if (d.watcher?.running) {
-      const w = new TreeItem('Watcher: Running', 'watcher', {
-        icon: new vscode.ThemeIcon('eye', new vscode.ThemeColor('charts.green')),
-        description: d.watcher.pid ? `PID ${d.watcher.pid}` : '',
-      });
+      const w = _item('Watcher: Running', 'watcher', { icon: 'eye', color: C.green, desc: `PID ${d.watcher.pid || '?'}` });
       items.push(w);
     } else {
-      const w = new TreeItem('Watcher: Stopped', 'watcher', {
-        icon: new vscode.ThemeIcon('eye-closed', new vscode.ThemeColor('charts.red')),
-        description: 'Click Quick Actions > Start',
-      });
+      const w = _item('Watcher: Stopped', 'watcher', { icon: 'eye-closed', color: C.red });
+      w.command = { command: 'cursorGuard.startWatcher', title: 'Start Watcher' };
+      w.tooltip = 'Click to start watcher';
       items.push(w);
     }
 
-    if (d.alerts?.active) {
-      const a = d.alerts.latest || {};
-      const alertItem = new TreeItem(
-        `ALERT: ${a.fileCount || '?'} files in ${a.windowSeconds || '?'}s`,
-        'alert',
-        {
-          icon: new vscode.ThemeIcon('bell', new vscode.ThemeColor('charts.red')),
-          description: `threshold: ${a.threshold}`,
-        }
-      );
-      items.push(alertItem);
-    } else {
-      items.push(new TreeItem('No alerts', 'noalert', {
-        icon: new vscode.ThemeIcon('check', new vscode.ThemeColor('charts.green')),
-      }));
-    }
+    const gitC = d.counts?.git?.commits || 0;
+    const shadowC = d.counts?.shadow?.snapshots || 0;
+    const lastAgo = d.lastBackup?.git?.relativeTime || 'never';
+    items.push(_item(`Backups: ${gitC + shadowC}`, 'stat', { icon: 'history', color: C.blue, desc: `last ${lastAgo}` }));
 
-    if (d.lastBackup?.git) {
-      const ago = this._relativeTime(d.lastBackup.git.timestamp);
-      items.push(new TreeItem(`Last Backup: ${ago}`, 'backup', {
-        icon: new vscode.ThemeIcon('git-commit', new vscode.ThemeColor('charts.blue')),
-      }));
-    }
+    const health = d.health?.status || 'unknown';
+    const hColor = health === 'healthy' ? C.green : health === 'critical' ? C.red : C.yellow;
+    const hIcon = health === 'healthy' ? 'pass-filled' : health === 'critical' ? 'error' : 'warning';
+    items.push(_item(`Health: ${health}`, 'health', { icon: hIcon, color: hColor }));
 
-    if (d.counts) {
-      const gitCount = d.counts.git?.commits || 0;
-      const shadowCount = d.counts.shadow?.snapshots || 0;
-      items.push(new TreeItem(`Git: ${gitCount}  Shadow: ${shadowCount}`, 'counts', {
-        icon: new vscode.ThemeIcon('database', new vscode.ThemeColor('charts.purple')),
-      }));
-    }
+    const openItem = _item('Open Dashboard', 'action', { icon: 'browser', color: C.blue });
+    openItem.command = { command: 'cursorGuard.openDashboard', title: 'Open' };
+    items.push(openItem);
 
-    const health = d.health?.status || 'unknown';
-    const healthColor = health === 'healthy'
-      ? new vscode.ThemeColor('charts.green')
-      : health === 'critical'
-        ? new vscode.ThemeColor('charts.red')
-        : new vscode.ThemeColor('charts.yellow');
-    const healthIcon = health === 'healthy' ? 'pass-filled' : health === 'critical' ? 'error' : 'warning';
-    const healthItem = new TreeItem(`Health: ${health}`, 'health', {
-      icon: new vscode.ThemeIcon(healthIcon, healthColor),
-      description: d.health?.issues?.length > 0 ? d.health.issues[0] : '',
-    });
-    items.push(healthItem);
+    const snapItem = _item('Snapshot Now', 'action', { icon: 'device-camera', color: C.purple });
+    snapItem.command = { command: 'cursorGuard.snapshotNow', title: 'Snap' };
+    items.push(snapItem);
 
     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();
@@ -191,13 +103,12 @@ class GuardTreeView {
   }
 }
 
-class TreeItem extends vscode.TreeItem {
-  constructor(label, contextValue, opts = {}) {
-    super(label, opts.collapsible || vscode.TreeItemCollapsibleState.None);
-    this.contextValue = contextValue;
-    if (opts.icon) this.iconPath = opts.icon;
-    if (opts.description) this.description = opts.description;
-  }
+function _item(label, ctx, opts = {}) {
+  const ti = new vscode.TreeItem(label, opts.collapsible || vscode.TreeItemCollapsibleState.None);
+  ti.contextValue = ctx;
+  if (opts.icon) ti.iconPath = new vscode.ThemeIcon(opts.icon, opts.color);
+  if (opts.desc) ti.description = opts.desc;
+  return ti;
 }
 
 module.exports = { GuardTreeView };

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

@@ -3,8 +3,9 @@
 const vscode = require('vscode');
 const fs = require('fs');
 const path = require('path');
+const { getPublicDir } = require('./paths');
 
-const PUBLIC_DIR = path.resolve(__dirname, '..', '..', 'dashboard', 'public');
+const PUBLIC_DIR = getPublicDir();
 
 class WebViewProvider {
   constructor(context, dashMgr) {

package/references/vscode-extension/package.json

@@ -66,6 +66,11 @@
         {
           "id": "cursorGuardProjects",
           "name": "Projects"
+        },
+        {
+          "id": "cursorGuardDashboard",
+          "name": "Dashboard",
+          "type": "webview"
         }
       ]
     },