cursor-guard 4.5.7 → 4.5.8

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.5.7`（V4 最终版）  
-> **文档状态**：`V2` ~ `V4.5.7` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.5.8`（V4 最终版）  
+> **文档状态**：`V2` ~ `V4.5.8` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -464,6 +464,7 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | V4.5.4 | **Shadow 硬链接增量优化 + always_watch 强保护模式**：见下方详细说明 | ✅ |
 | V4.5.6 | **Bug 修复 + 告警 UX + init 优化**：见下方详细说明 | ✅ |
 | V4.5.7 | **文件详情 Modal 修复 + Dashboard 端口复用**：见下方详细说明 | ✅ |
+| V4.5.8 | **Dashboard 版本更新检测**：见下方详细说明 | ✅ |
 
 #### V4.4.1 详细内容
 
@@ -671,6 +672,17 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | 透明生效 | registry 是引用传递，已运行的 HTTP handler 闭包自动读取最新 registry，无需重启服务 |
 | 导出 `getInstance()` | 外部可通过 `getInstance()` 获取当前运行实例的 server/port/registry 信息 |
 
+#### V4.5.8 详细内容
+
+**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 |
+
 #### V4.5.x 新增配置参考
 
 | 字段 | 类型 | 默认值 | 引入版本 | 说明 |

package/package.json

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

@@ -140,6 +140,11 @@ const I18N = {
     'error.sectionFailed':  'This section failed to load',
     'empty.noData':         'No data available',
 
+    '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.hint':         'Stop the current process (Ctrl+C), then run: cursor-guard-backup --path <dir> --dashboard',
+
     'strategy.git':    'Git',
     'strategy.shadow': 'Shadow',
     'strategy.both':   'Both',
@@ -355,6 +360,11 @@ const I18N = {
     'error.sectionFailed':  '此区块加载失败',
     'empty.noData':         '暂无数据',
 
+    'upgrade.banner':       '检测到新版本 {installed}（当前服务: {server}），请重启 Dashboard 服务以加载最新功能',
+    'upgrade.dismiss':      '关闭',
+    'upgrade.restart':      '如何重启',
+    'upgrade.hint':         '停止当前进程 (Ctrl+C)，然后运行: cursor-guard-backup --path <目录> --dashboard',
+
     'strategy.git':    'Git',
     'strategy.shadow': '影子',
     'strategy.both':   '双重',
@@ -1580,6 +1590,38 @@ function setupEvents() {
   });
 }
 
+/* ── Version Check ────────────────────────────────────────── */
+
+async function checkServerVersion() {
+  try {
+    const data = await fetchJson('/api/version');
+    if (data.updateAvailable) showUpgradeBanner(data);
+  } catch { /* non-critical */ }
+}
+
+function showUpgradeBanner(data) {
+  if ($('#upgrade-banner')) return;
+  const banner = document.createElement('div');
+  banner.id = 'upgrade-banner';
+  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-close" aria-label="${t('upgrade.dismiss')}">&times;</button>
+  `;
+  const topbar = $('#topbar');
+  topbar.parentNode.insertBefore(banner, topbar.nextSibling);
+  banner.querySelector('.upgrade-banner-close').addEventListener('click', () => banner.remove());
+  banner.querySelector('.upgrade-banner-hint-btn').addEventListener('click', () => {
+    const hint = banner.querySelector('.upgrade-banner-hint');
+    if (hint) { hint.remove(); return; }
+    const el = document.createElement('div');
+    el.className = 'upgrade-banner-hint';
+    el.innerHTML = `<code>${t('upgrade.hint')}</code>`;
+    banner.appendChild(el);
+  });
+}
+
 /* ── Init ─────────────────────────────────────────────────── */
 
 async function init() {
@@ -1595,6 +1637,7 @@ async function init() {
     await loadPageData({ progressive: true });
     renderAll();
     startRefresh();
+    checkServerVersion();
   } catch (e) {
     showGlobalError(e.message);
   }

package/references/dashboard/public/style.css

@@ -118,6 +118,74 @@ body {
 
 #last-refresh { font-size: 12px; white-space: nowrap; opacity: .7; }
 
+/* ── Upgrade Banner ──────────────────────────────────────── */
+
+.upgrade-banner {
+  position: fixed;
+  top: var(--topbar-h);
+  left: 0; right: 0;
+  background: var(--yellow-bg);
+  border-bottom: 1px solid var(--yellow);
+  color: var(--yellow);
+  padding: 8px 24px;
+  font-size: 13px;
+  font-weight: 500;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  z-index: 49;
+  animation: slideDown 0.3s ease;
+}
+@keyframes slideDown {
+  from { transform: translateY(-100%); opacity: 0; }
+  to   { transform: translateY(0); opacity: 1; }
+}
+.upgrade-banner-text {
+  flex: 1;
+}
+.upgrade-banner-hint-btn {
+  padding: 3px 10px;
+  font-size: 11px;
+  border: 1px solid var(--yellow);
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--yellow);
+  cursor: pointer;
+  white-space: nowrap;
+  transition: all 0.15s;
+}
+.upgrade-banner-hint-btn:hover {
+  background: var(--yellow);
+  color: var(--bg);
+}
+.upgrade-banner-close {
+  background: none;
+  border: none;
+  color: var(--yellow);
+  font-size: 18px;
+  cursor: pointer;
+  padding: 0 4px;
+  opacity: 0.7;
+  transition: opacity 0.15s;
+}
+.upgrade-banner-close:hover { opacity: 1; }
+.upgrade-banner-hint {
+  width: 100%;
+  margin-top: 6px;
+  padding: 6px 10px;
+  background: rgba(0,0,0,0.2);
+  border-radius: var(--radius-sm);
+  font-size: 12px;
+}
+.upgrade-banner-hint code {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--text-primary);
+}
+.upgrade-banner + main {
+  margin-top: 38px;
+}
+
 /* ── Buttons ──────────────────────────────────────────────── */
 
 .btn {

package/references/dashboard/server.js

@@ -11,6 +11,8 @@ const { runDiagnostics } = require('../lib/core/doctor');
 const { listBackups, getBackupFiles } = require('../lib/core/backups');
 
 const PUBLIC_DIR = path.join(__dirname, 'public');
+const PKG_PATH = path.resolve(__dirname, '..', '..', 'package.json');
+const SERVER_VERSION = require('../../package.json').version;
 const DEFAULT_PORT = 3120;
 const MAX_PORT_RETRIES = 10;
 const ALLOWED_HOSTS = /^(127\.0\.0\.1|localhost)(:\d+)?$/;
@@ -125,6 +127,19 @@ function serveStatic(reqUrl, res, serverToken) {
 /* ── API routes ─────────────────────────────────────────────── */
 
 function handleApi(pathname, query, registry, res) {
+  if (pathname === '/api/version') {
+    let installedVersion = SERVER_VERSION;
+    try {
+      const pkg = JSON.parse(fs.readFileSync(PKG_PATH, 'utf-8'));
+      installedVersion = pkg.version;
+    } catch { /* fallback to server version */ }
+    return json(res, {
+      serverVersion: SERVER_VERSION,
+      installedVersion,
+      updateAvailable: SERVER_VERSION !== installedVersion,
+    });
+  }
+
   if (pathname === '/api/projects') {
     const list = [...registry.values()].map(({ id, name, pathLabel }) => ({ id, name, pathLabel }));
     return json(res, list);