cursor-guard 4.7.3 → 4.7.4

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.7.3`  
-> **文档状态**：`V2` ~ `V4.7.3` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.7.4`  
+> **文档状态**：`V2` ~ `V4.7.4` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,6 +734,16 @@ 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：可视化图表侧边栏 ✅
 
 | 组件 | 说明 |

package/package.json

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

@@ -36,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();
     }),

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);
@@ -78,8 +79,8 @@ class DashboardManager {
   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) {
@@ -91,7 +92,7 @@ class DashboardManager {
     if (!projectPath) return null;
     const existingPid = this.getWatcherPid(projectPath);
     if (existingPid) return existingPid;
-    const cliScript = path.resolve(__dirname, '..', '..', 'bin', 'cursor-guard-backup.js');
+    const cliScript = guardPath('bin', 'cursor-guard-backup.js');
     const child = spawn(process.execPath, [cliScript, '--path', projectPath], {
       cwd: projectPath,
       stdio: 'ignore',

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/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) {