cursor-guard 4.5.8 → 4.6.0

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.5.8`（V4 最终版）  
-> **文档状态**：`V2` ~ `V4.5.8` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.6.0`  
+> **文档状态**：`V2` ~ `V4.6.0` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -464,7 +464,8 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | V4.5.4 | **Shadow 硬链接增量优化 + always_watch 强保护模式**：见下方详细说明 | ✅ |
 | V4.5.6 | **Bug 修复 + 告警 UX + init 优化**：见下方详细说明 | ✅ |
 | V4.5.7 | **文件详情 Modal 修复 + Dashboard 端口复用**：见下方详细说明 | ✅ |
-| V4.5.8 | **Dashboard 版本更新检测**：见下方详细说明 | ✅ |
+| V4.5.8 | **Dashboard 版本更新检测 + 一键重启**：见下方详细说明 | ✅ |
+| V4.6.0 | **告警 UX 全面升级**：见下方详细说明 | ✅ |
 
 #### V4.4.1 详细内容
 
@@ -674,14 +675,28 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 
 #### V4.5.8 详细内容
 
-**Dashboard 版本更新检测**：
+**Dashboard 版本更新检测 + 一键重启**：
 
 | 组件 | 说明 |
 |------|------|
-| `/api/version` 端点 | 新增无需 project id 的公共 API。返回 `serverVersion`（进程启动时 require cache 锁定）和 `installedVersion`（实时从磁盘读取 `package.json`），以及 `updateAvailable` 布尔值 |
-| 前端版本检查 | `init()` 完成后异步调用 `checkServerVersion()`，非阻塞，失败静默 |
-| 升级横幅 | `updateAvailable === true` 时，在 topbar 下方滑入黄色横幅，显示版本差异和重启提示。带"如何重启"按钮（展开命令示例）和关闭按钮 |
-| 双语支持 | 新增 `upgrade.banner` / `upgrade.dismiss` / `upgrade.restart` / `upgrade.hint` 四组 i18n key |
+| `/api/version` 端点 | 返回 `serverVersion`（启动时 require cache）和 `installedVersion`（实时从磁盘读取），以及 `updateAvailable` 布尔值 |
+| `/api/restart` 端点 (POST) | 触发服务热重启：关闭旧 HTTP server → `clearGuardCache()` 清除所有 cursor-guard 模块的 require cache → 更新 `SERVER_VERSION` → 在同端口重启新 server |
+| 懒加载 core deps | `handleApi` 中 `getDashboard`/`runDiagnostics`/`listBackups`/`getBackupFiles` 改为通过 `coreDeps()` 懒加载，重启后自动加载新代码 |
+| 升级横幅 | `updateAvailable === true` 时显示黄色横幅。包含"一键重启"按钮（发送 POST → 轮询等待 → 自动 reload）、"手动重启"按钮（展开命令示例）、关闭按钮 |
+| 重启流程 | 前端发 POST `/api/restart` → 显示"正在重启..." → 每 500ms 轮询 `/api/version`（最多 10s）→ 服务就绪后 `location.reload()` 自动刷新页面 |
+| 双语支持 | 新增 `upgrade.*` 共 8 组 i18n key（banner/dismiss/restartNow/restart/hint/restarting/waiting/failed） |
+
+#### V4.6.0 详细内容
+
+**告警 UX 全面升级**：
+
+| 修复项 | 说明 |
+|------|------|
+| 倒计时秒级实时更新 | `state.alertExpiresAt` 在 `renderAlertCard` 时记录过期时间；已有的 1 秒定时器 `updateRefreshDisplay` 中实时更新 `.alert-countdown` 元素，无需额外 `setInterval` |
+| 告警文件详情复制/恢复操作 | 告警详情弹窗现在传入 `commitHash`（从 `alerts.latest.commitHash` 或 `'HEAD'` 回退），使每行文件的"复制恢复命令"按钮正常显示和工作 |
+| 备份过时阈值修正 | 阈值从 `interval * 5 / 60` 分钟改为 `max(interval * 10, 300)` 秒（至少 5 分钟）；仅在 watcher 正在运行时才检查过时状态；文案从"stale"改为中性的"Last git backup: X ago" |
+| 告警历史常驻入口 | `buildAlertHistoryHtml()` 提取为独立函数，在活跃告警和无告警两种状态下都渲染"历史 N 条"折叠按钮，告警激活时也能查看历史 |
+| 告警历史 localStorage 持久化 | 新增 `loadAlertHistory()` / `saveAlertHistory()`，使用 `localStorage` key `cursorGuard_alertHistory` 持久化最近 20 条告警历史，刷新页面不丢失 |
 
 #### V4.5.x 新增配置参考
 
@@ -707,6 +722,15 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### V4.7 规划：IDE 集成（VSCode/Cursor Extension）
+
+| 项目 | 说明 |
+|------|------|
+| 定位 | 将 Dashboard 从浏览器迁移到 IDE 内置 WebView，减少上下文切换 |
+| 实现方式 | VSCode Extension + WebView Panel，复用现有 `dashboard/public/` 前端代码 |
+| 核心能力 | IDE 侧边栏入口、状态栏告警指示器、WebView 内嵌 Dashboard、一键快照按钮 |
+| 状态 | 🔮 规划中 |
+
 ### V4 不做的事
 
 - 不做自动恢复（恢复永远需要人确认，这是产品底线）

package/package.json

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

package/references/dashboard/public/app.js

@@ -142,8 +142,12 @@ const I18N = {
 
     'upgrade.banner':       'New version {installed} available (current server: {server}). Please restart the Dashboard service to load the latest features.',
     'upgrade.dismiss':      'Dismiss',
-    'upgrade.restart':      'How to restart',
+    'upgrade.restartNow':   'Restart Now',
+    'upgrade.restart':      'Manual restart',
     'upgrade.hint':         'Stop the current process (Ctrl+C), then run: cursor-guard-backup --path <dir> --dashboard',
+    'upgrade.restarting':   'Restarting...',
+    'upgrade.waiting':      'Waiting for server...',
+    'upgrade.failed':       'Restart failed, try manually',
 
     'strategy.git':    'Git',
     'strategy.shadow': 'Shadow',
@@ -362,8 +366,12 @@ const I18N = {
 
     'upgrade.banner':       '检测到新版本 {installed}（当前服务: {server}），请重启 Dashboard 服务以加载最新功能',
     'upgrade.dismiss':      '关闭',
-    'upgrade.restart':      '如何重启',
+    'upgrade.restartNow':   '一键重启',
+    'upgrade.restart':      '手动重启',
     'upgrade.hint':         '停止当前进程 (Ctrl+C)，然后运行: cursor-guard-backup --path <目录> --dashboard',
+    'upgrade.restarting':   '正在重启...',
+    'upgrade.waiting':      '等待服务就绪...',
+    'upgrade.failed':       '重启失败，请手动重启',
 
     'strategy.git':    'Git',
     'strategy.shadow': '影子',
@@ -462,10 +470,23 @@ const state = {
   tickTimer: null,
   lastRefreshAt: null,
   drawerOpen: null,
-  alertHistory: [],
+  alertHistory: loadAlertHistory(),
+  alertExpiresAt: null,
 };
 
 const REFRESH_MS = 15000;
+const ALERT_HISTORY_KEY = 'cursorGuard_alertHistory';
+
+function loadAlertHistory() {
+  try {
+    const raw = localStorage.getItem(ALERT_HISTORY_KEY);
+    return raw ? JSON.parse(raw) : [];
+  } catch { return []; }
+}
+
+function saveAlertHistory() {
+  try { localStorage.setItem(ALERT_HISTORY_KEY, JSON.stringify(state.alertHistory)); } catch { /* quota */ }
+}
 
 /* ── DOM helpers ──────────────────────────────────────────── */
 
@@ -729,9 +750,17 @@ async function manualRefresh() {
 
 function updateRefreshDisplay() {
   const el = $('#last-refresh');
-  if (!el || !state.lastRefreshAt) return;
-  const sec = Math.floor((Date.now() - state.lastRefreshAt) / 1000);
-  el.textContent = `${t('topbar.lastRefresh')}: ${sec}s`;
+  if (el && state.lastRefreshAt) {
+    const sec = Math.floor((Date.now() - state.lastRefreshAt) / 1000);
+    el.textContent = `${t('topbar.lastRefresh')}: ${sec}s`;
+  }
+
+  const cdEl = document.querySelector('.alert-countdown');
+  if (cdEl && state.alertExpiresAt) {
+    const remain = Math.max(0, state.alertExpiresAt - Date.now());
+    const s = Math.ceil(remain / 1000);
+    cdEl.textContent = s > 60 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${s}s`;
+  }
 }
 
 /* ── Rendering: Top bar ───────────────────────────────────── */
@@ -881,33 +910,35 @@ function alertFileBreakdown(files) {
   return t('alert.breakdown', { added, modified, deleted });
 }
 
+function buildAlertHistoryHtml() {
+  if (state.alertHistory.length === 0) return '';
+  const count = state.alertHistory.length;
+  const rows = state.alertHistory.slice(-5).reverse().map(h => {
+    const breakdown = alertFileBreakdown(h.files);
+    return `<div class="alert-history-row text-sm text-muted">
+      <span class="alert-history-time">${esc(formatTime(h.timestamp))}</span>
+      <span>${t('alert.detail', { count: h.fileCount, window: h.windowSeconds, threshold: h.threshold })}</span>
+      ${breakdown ? `<span class="alert-history-breakdown">${esc(breakdown)}</span>` : ''}
+      <span class="badge badge-expired">${t('alert.expired')}</span>
+    </div>`;
+  }).join('');
+  return `
+    <div class="alert-history-toggle-wrap">
+      <button class="alert-history-toggle-btn text-sm text-muted" data-alert-history-toggle>${t('alert.historyCount', { n: count })}</button>
+    </div>
+    <div class="alert-history alert-history-collapsed">
+      <div class="alert-history-label text-sm">${t('alert.history')}</div>${rows}
+    </div>`;
+}
+
 function renderAlertCard(alerts) {
   const el = $('#card-alert');
   if (!alerts?.active) {
-    let historyHtml = '';
-    if (state.alertHistory.length > 0) {
-      const count = state.alertHistory.length;
-      const rows = state.alertHistory.slice(-5).reverse().map(h => {
-        const breakdown = alertFileBreakdown(h.files);
-        return `<div class="alert-history-row text-sm text-muted">
-          <span class="alert-history-time">${esc(formatTime(h.timestamp))}</span>
-          <span>${t('alert.detail', { count: h.fileCount, window: h.windowSeconds, threshold: h.threshold })}</span>
-          ${breakdown ? `<span class="alert-history-breakdown">${esc(breakdown)}</span>` : ''}
-          <span class="badge badge-expired">${t('alert.expired')}</span>
-        </div>`;
-      }).join('');
-      historyHtml = `
-        <div class="alert-history-toggle-wrap">
-          <button class="alert-history-toggle-btn text-sm text-muted" data-alert-history-toggle>${t('alert.historyCount', { n: count })}</button>
-        </div>
-        <div class="alert-history alert-history-collapsed">
-          <div class="alert-history-label text-sm">${t('alert.history')}</div>${rows}
-        </div>`;
-    }
+    state.alertExpiresAt = null;
     el.innerHTML = `
       <div class="card-label">${t('alert.title')}</div>
       <div class="card-status"><span class="status-dot status-healthy"></span><span>${t('alert.none')}</span></div>
-      ${historyHtml}
+      ${buildAlertHistoryHtml()}
     `;
     return;
   }
@@ -917,10 +948,12 @@ function renderAlertCard(alerts) {
   if (a.timestamp && !state.alertHistory.some(h => h.timestamp === a.timestamp)) {
     state.alertHistory.push({ timestamp: a.timestamp, fileCount: a.fileCount, windowSeconds: a.windowSeconds, threshold: a.threshold, expiresAt: a.expiresAt, files: a.files });
     if (state.alertHistory.length > 20) state.alertHistory = state.alertHistory.slice(-20);
+    saveAlertHistory();
   }
 
   const triggeredAt = a.timestamp ? formatTime(a.timestamp) : '-';
   const expiresAt = a.expiresAt ? new Date(a.expiresAt) : null;
+  state.alertExpiresAt = expiresAt ? expiresAt.getTime() : null;
   const remainMs = expiresAt ? expiresAt.getTime() - Date.now() : 0;
   const remainSec = Math.max(0, Math.ceil(remainMs / 1000));
   const remainMin = Math.floor(remainSec / 60);
@@ -948,6 +981,7 @@ function renderAlertCard(alerts) {
       <div class="alert-detail-row alert-suggestion text-sm text-muted">${t('alert.suggestion')}</div>
     </div>
     ${filesHtml}
+    ${buildAlertHistoryHtml()}
   `;
 }
 
@@ -1554,7 +1588,8 @@ function setupEvents() {
       const files = alerts?.latest?.files || [];
       if (files.length > 0) {
         const proj = state.pageData?.dashboard?.watcher?.path || '';
-        openFileModal(t('modal.alertFiles'), files, proj, '');
+        const hash = alerts?.latest?.commitHash || 'HEAD';
+        openFileModal(t('modal.alertFiles'), files, proj, hash);
       }
       return;
     }
@@ -1606,7 +1641,8 @@ function showUpgradeBanner(data) {
   banner.className = 'upgrade-banner';
   banner.innerHTML = `
     <span class="upgrade-banner-text">${t('upgrade.banner', { installed: esc(data.installedVersion), server: esc(data.serverVersion) })}</span>
-    <button class="upgrade-banner-hint-btn" title="${t('upgrade.hint')}">${t('upgrade.restart')}</button>
+    <button class="upgrade-banner-restart-btn">${t('upgrade.restartNow')}</button>
+    <button class="upgrade-banner-hint-btn">${t('upgrade.restart')}</button>
     <button class="upgrade-banner-close" aria-label="${t('upgrade.dismiss')}">&times;</button>
   `;
   const topbar = $('#topbar');
@@ -1620,6 +1656,42 @@ function showUpgradeBanner(data) {
     el.innerHTML = `<code>${t('upgrade.hint')}</code>`;
     banner.appendChild(el);
   });
+  banner.querySelector('.upgrade-banner-restart-btn').addEventListener('click', () => {
+    restartServer(banner);
+  });
+}
+
+async function restartServer(banner) {
+  const btn = banner.querySelector('.upgrade-banner-restart-btn');
+  btn.disabled = true;
+  btn.textContent = t('upgrade.restarting');
+  banner.querySelector('.upgrade-banner-hint-btn').style.display = 'none';
+  banner.querySelector('.upgrade-banner-close').style.display = 'none';
+
+  try {
+    const sep = '/api/restart'.includes('?') ? '&' : '?';
+    const tokenParam = window.__GUARD_TOKEN__ ? `${sep}token=${window.__GUARD_TOKEN__}` : '';
+    await fetch('/api/restart' + tokenParam, { method: 'POST' });
+  } catch { /* server may close connection */ }
+
+  btn.textContent = t('upgrade.waiting');
+  let ready = false;
+  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__ : ''));
+      if (r.ok) { ready = true; break; }
+    } catch { /* still restarting */ }
+  }
+
+  if (ready) {
+    location.reload();
+  } else {
+    btn.textContent = t('upgrade.failed');
+    btn.disabled = false;
+    banner.querySelector('.upgrade-banner-hint-btn').style.display = '';
+    banner.querySelector('.upgrade-banner-close').style.display = '';
+  }
 }
 
 /* ── Init ─────────────────────────────────────────────────── */

package/references/dashboard/public/style.css

@@ -143,6 +143,25 @@ body {
 .upgrade-banner-text {
   flex: 1;
 }
+.upgrade-banner-restart-btn {
+  padding: 4px 14px;
+  font-size: 12px;
+  font-weight: 600;
+  border: 1px solid var(--yellow);
+  border-radius: var(--radius-sm);
+  background: var(--yellow);
+  color: var(--bg);
+  cursor: pointer;
+  white-space: nowrap;
+  transition: all 0.15s;
+}
+.upgrade-banner-restart-btn:hover {
+  filter: brightness(1.1);
+}
+.upgrade-banner-restart-btn:disabled {
+  opacity: 0.7;
+  cursor: wait;
+}
 .upgrade-banner-hint-btn {
   padding: 3px 10px;
   font-size: 11px;

package/references/dashboard/server.js

@@ -6,13 +6,26 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
-const { getDashboard } = require('../lib/core/dashboard');
-const { runDiagnostics } = require('../lib/core/doctor');
-const { listBackups, getBackupFiles } = require('../lib/core/backups');
+const GUARD_ROOT = path.resolve(__dirname, '..');
+
+function coreDeps() {
+  return {
+    getDashboard: require('../lib/core/dashboard').getDashboard,
+    runDiagnostics: require('../lib/core/doctor').runDiagnostics,
+    listBackups: require('../lib/core/backups').listBackups,
+    getBackupFiles: require('../lib/core/backups').getBackupFiles,
+  };
+}
+
+function clearGuardCache() {
+  Object.keys(require.cache).forEach(key => {
+    if (key.startsWith(GUARD_ROOT)) delete require.cache[key];
+  });
+}
 
 const PUBLIC_DIR = path.join(__dirname, 'public');
 const PKG_PATH = path.resolve(__dirname, '..', '..', 'package.json');
-const SERVER_VERSION = require('../../package.json').version;
+let SERVER_VERSION = require('../../package.json').version;
 const DEFAULT_PORT = 3120;
 const MAX_PORT_RETRIES = 10;
 const ALLOWED_HOSTS = /^(127\.0\.0\.1|localhost)(:\d+)?$/;
@@ -126,7 +139,7 @@ function serveStatic(reqUrl, res, serverToken) {
 
 /* ── API routes ─────────────────────────────────────────────── */
 
-function handleApi(pathname, query, registry, res) {
+function handleApi(pathname, query, registry, res, req) {
   if (pathname === '/api/version') {
     let installedVersion = SERVER_VERSION;
     try {
@@ -140,6 +153,17 @@ function handleApi(pathname, query, registry, res) {
     });
   }
 
+  if (pathname === '/api/restart') {
+    if (req.method !== 'POST') {
+      res.writeHead(405);
+      return res.end('Method Not Allowed');
+    }
+    if (!_instance) return json(res, { error: 'No running instance' }, 500);
+    json(res, { restarting: true });
+    setTimeout(() => restartDashboard(), 300);
+    return;
+  }
+
   if (pathname === '/api/projects') {
     const list = [...registry.values()].map(({ id, name, pathLabel }) => ({ id, name, pathLabel }));
     return json(res, list);
@@ -154,6 +178,8 @@ function handleApi(pathname, query, registry, res) {
     return json(res, { error: `Project directory not accessible: ${project.pathLabel}` }, 500);
   }
 
+  const { getDashboard, runDiagnostics, listBackups, getBackupFiles } = coreDeps();
+
   if (pathname === '/api/page-data') {
     const scope = query.get('scope');
     const result = { timestamp: new Date().toISOString() };
@@ -258,7 +284,7 @@ function startDashboardServer(paths, opts = {}) {
         return res.end('Forbidden: invalid host');
       }
 
-      if (req.method !== 'GET') {
+      if (req.method !== 'GET' && req.method !== 'POST') {
         res.writeHead(405);
         return res.end('Method Not Allowed');
       }
@@ -272,8 +298,9 @@ function startDashboardServer(paths, opts = {}) {
           res.writeHead(403);
           return res.end('Forbidden: invalid token');
         }
-        handleApi(parsed.pathname, parsed.searchParams, registry, res);
+        handleApi(parsed.pathname, parsed.searchParams, registry, res, req);
       } else {
+        if (req.method !== 'GET') { res.writeHead(405); return res.end('Method Not Allowed'); }
         serveStatic(req.url, res, token);
       }
     });
@@ -309,6 +336,26 @@ function startDashboardServer(paths, opts = {}) {
   });
 }
 
+/* ── Hot Restart ───────────────────────────────────────────── */
+
+async function restartDashboard() {
+  if (!_instance) return;
+  const paths = [..._instance.registry.values()].map(p => p._path);
+  const port = _instance.port;
+
+  _instance.server.close();
+  _instance = null;
+
+  clearGuardCache();
+  try {
+    const pkg = JSON.parse(fs.readFileSync(PKG_PATH, 'utf-8'));
+    SERVER_VERSION = pkg.version;
+  } catch { /* keep old version */ }
+
+  console.log(`  [dashboard] Restarting on port ${port}...`);
+  await startDashboardServer(paths, { port, silent: false });
+}
+
 /* ── CLI entry ─────────────────────────────────────────────── */
 
 if (require.main === module) {

package/references/lib/core/dashboard.js

@@ -168,12 +168,12 @@ function getDashboard(projectDir) {
     issues.push(`Disk space low (${status.disk.freeGB} GB free)`);
   }
 
-  if (status.lastBackup.git) {
+  if (status.lastBackup.git && status.watcher.running) {
     const lastTs = new Date(status.lastBackup.git.timestamp).getTime();
-    const staleMinutes = (Date.now() - lastTs) / 60000;
-    const staleThreshold = Math.min(cfg.auto_backup_interval_seconds * 5 / 60, 30);
-    if (staleMinutes > staleThreshold) {
-      issues.push(`Last git backup is stale (${relativeTime(status.lastBackup.git.timestamp)})`);
+    const staleSec = (Date.now() - lastTs) / 1000;
+    const staleThreshold = Math.max(cfg.auto_backup_interval_seconds * 10, 300);
+    if (staleSec > staleThreshold) {
+      issues.push(`Last git backup: ${relativeTime(status.lastBackup.git.timestamp)}`);
     }
   }