cursor-guard 4.5.9 → 4.6.1

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.5.9`（V4 最终版）  
-> **文档状态**：`V2` ~ `V4.5.9` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.6.1`  
+> **文档状态**：`V2` ~ `V4.6.1` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -465,6 +465,8 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | V4.5.6 | **Bug 修复 + 告警 UX + init 优化**：见下方详细说明 | ✅ |
 | V4.5.7 | **文件详情 Modal 修复 + Dashboard 端口复用**：见下方详细说明 | ✅ |
 | V4.5.8 | **Dashboard 版本更新检测 + 一键重启**：见下方详细说明 | ✅ |
+| V4.6.0 | **告警 UX 全面升级**：见下方详细说明 | ✅ |
+| V4.6.1 | **告警历史弹窗化**：见下方详细说明 | ✅ |
 
 #### V4.4.1 详细内容
 
@@ -685,6 +687,29 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | 重启流程 | 前端发 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.6.1 详细内容
+
+**告警历史弹窗化**：
+
+| 改动 | 说明 |
+|------|------|
+| 历史按钮改为弹窗触发 | "历史 N 条"按钮点击后打开全屏 Modal（复用 `file-modal`），不再内联折叠展开 |
+| 历史表格化展示 | Modal 内以表格呈现所有历史告警：触发时间、详情、文件类型分布、文件列表按钮 |
+| 嵌套文件详情 | 每条历史告警的"查看文件"按钮可再打开文件详情 Modal，查看具体变更文件列表 |
+| 新增 i18n keys | `alert.col.detail` / `alert.col.breakdown` / `alert.col.files`（中英双语） |
+
 #### V4.5.x 新增配置参考
 
 | 字段 | 类型 | 默认值 | 引入版本 | 说明 |
@@ -709,6 +734,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.9",
+  "version": "4.6.1",
   "description": "Protects code from accidental AI overwrite or deletion in Cursor IDE — mandatory pre-write snapshots, review-before-apply, local Git safety net, and deterministic recovery. | 保护代码免受 Cursor AI 代理意外覆写或删除——强制写前快照、预览再执行、本地 Git 安全网、确定性恢复。",
   "keywords": [
     "cursor",

package/references/dashboard/public/app.js

@@ -52,6 +52,9 @@ const I18N = {
     'alert.col.file':   'File',
     'alert.col.action': 'Action',
     'alert.col.changes':'Changes',
+    'alert.col.detail': 'Detail',
+    'alert.col.breakdown': 'Breakdown',
+    'alert.col.files': 'Files',
     'alert.action.modified': 'Modified',
     'alert.action.added':    'Added',
     'alert.action.deleted':  'Deleted',
@@ -276,6 +279,9 @@ const I18N = {
     'alert.col.file':   '文件',
     'alert.col.action': '操作',
     'alert.col.changes':'变化量',
+    'alert.col.detail': '详情',
+    'alert.col.breakdown': '文件类型',
+    'alert.col.files': '文件列表',
     'alert.action.modified': '修改',
     'alert.action.added':    '新增',
     'alert.action.deleted':  '删除',
@@ -470,10 +476,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 ──────────────────────────────────────────── */
 
@@ -737,9 +756,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 ───────────────────────────────────── */
@@ -889,33 +916,66 @@ function alertFileBreakdown(files) {
   return t('alert.breakdown', { added, modified, deleted });
 }
 
+function buildAlertHistoryHtml() {
+  if (state.alertHistory.length === 0) return '';
+  const count = state.alertHistory.length;
+  return `
+    <div class="alert-history-toggle-wrap">
+      <button class="alert-history-toggle-btn text-sm text-muted" data-alert-history-modal>${t('alert.historyCount', { n: count })}</button>
+    </div>`;
+}
+
+function openAlertHistoryModal() {
+  const list = [...state.alertHistory].reverse();
+  if (list.length === 0) return;
+  $('#file-modal-title').textContent = t('alert.history');
+  const body = $('#file-modal-body');
+
+  const rows = list.map((h, i) => {
+    const breakdown = alertFileBreakdown(h.files);
+    const fileCount = Array.isArray(h.files) ? h.files.length : 0;
+    return `<tr>
+      <td class="text-mono">${esc(formatTime(h.timestamp))}</td>
+      <td>${t('alert.detail', { count: h.fileCount, window: h.windowSeconds, threshold: h.threshold })}</td>
+      <td>${breakdown ? esc(breakdown) : '-'}</td>
+      <td>${fileCount > 0 ? `<button class="modal-restore-btn" data-history-files="${i}">${t('alert.viewFiles', { n: fileCount })}</button>` : '-'}</td>
+    </tr>`;
+  }).join('');
+
+  body.innerHTML = `<table>
+    <thead><tr>
+      <th>${t('alert.triggered')}</th>
+      <th>${t('alert.col.detail')}</th>
+      <th>${t('alert.col.breakdown')}</th>
+      <th>${t('alert.col.files')}</th>
+    </tr></thead>
+    <tbody>${rows}</tbody>
+  </table>`;
+
+  body.addEventListener('click', (e) => {
+    const btn = e.target.closest('[data-history-files]');
+    if (btn) {
+      const idx = parseInt(btn.dataset.historyFiles);
+      const h = list[idx];
+      if (h?.files?.length > 0) {
+        const proj = state.pageData?.dashboard?.watcher?.path || '';
+        openFileModal(t('modal.alertFiles'), h.files, proj, '');
+      }
+    }
+  });
+
+  $('#file-modal-overlay').classList.add('active');
+  document.body.style.overflow = 'hidden';
+}
+
 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;
   }
@@ -925,10 +985,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);
@@ -956,6 +1018,7 @@ function renderAlertCard(alerts) {
       <div class="alert-detail-row alert-suggestion text-sm text-muted">${t('alert.suggestion')}</div>
     </div>
     ${filesHtml}
+    ${buildAlertHistoryHtml()}
   `;
 }
 
@@ -1547,13 +1610,11 @@ function setupEvents() {
     if (backup) openRestoreDrawer(backup);
   });
 
-  // Alert history toggle + file modal (event delegation)
+  // Alert history modal + file modal (event delegation)
   $('#card-alert').addEventListener('click', (e) => {
-    const historyToggle = e.target.closest('[data-alert-history-toggle]');
-    if (historyToggle) {
-      const card = historyToggle.closest('#card-alert');
-      const history = card?.querySelector('.alert-history');
-      if (history) history.classList.toggle('alert-history-collapsed');
+    const historyBtn = e.target.closest('[data-alert-history-modal]');
+    if (historyBtn) {
+      openAlertHistoryModal();
       return;
     }
     const modalBtn = e.target.closest('[data-alert-files-modal]');
@@ -1562,7 +1623,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;
     }

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)}`);
     }
   }