cursor-guard 4.7.9 → 4.8.2

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.7.9`  
-> **文档状态**：`V2` ~ `V4.7.8` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.8.2`  
+> **文档状态**：`V2` ~ `V4.8.2` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -734,6 +734,29 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 }
 ```
 
+### V4.8.2：Skill 目录运行时完整安装 ✅
+
+| 修复 | 说明 |
+|------|------|
+| **autoInstallSkill 创建 references/ junction** | 之前只复制文档文件（SKILL.md、config-reference.md 等），导致 SKILL.md 中引用的 `references/mcp/server.js`、`references/lib/core/`、`references/dashboard/` 等全部 404。改为创建 `references/` → 扩展目录的 junction link（Windows 不需管理员权限），所有运行时文件通过链接自动可用 |
+| **package.json 安装** | 复制 `package.json` 到 skill 目录，解决源码模式下 `require('../../package.json')` 失败 |
+| **junction 失败降级** | 极少数环境无法创建 junction 时，fallback 到只复制文档文件（与之前行为一致） |
+
+### V4.8.1：MCP Server esbuild 单文件打包 ✅
+
+| 修复/增强 | 说明 |
+|----------|------|
+| **esbuild 单文件 bundle** | 彻底解决 VSIX MCP 依赖缺失问题。不再手动拷贝 `vendor/` 目录（`@modelcontextprotocol/sdk`、`zod`、`zod-to-json-schema`、`ajv` 等），改用 esbuild 将 `mcp/server.js` 及其所有依赖打成一个自包含的 CJS bundle（~1.5 MB）。任何新增的 SDK 传递依赖都会自动包含 |
+| **VSIX 体积大幅缩减** | 从 1543 文件 / 3.18 MB 缩减到 42 文件 / 1.27 MB（-60%）。vendor/ 目录完全移除 |
+| **auto-setup.js 简化** | MCP server 注册不再需要 `NODE_PATH` 环境变量（bundle 自包含），命令从 `{ command: "node", args: [...], env: { NODE_PATH: "..." } }` 简化为 `{ command: "node", args: [...] }` |
+| **build-vsix.js 容错** | esbuild 失败时自动 fallback 到源码拷贝，不会中断打包流程 |
+
+### V4.8.0：VSIX MCP 依赖补全 ✅
+
+| 修复 | 说明 |
+|------|------|
+| **`zod-to-json-schema` 缺失修复** | MCP server 启动时报 `Cannot find module 'zod-to-json-schema'`。`@modelcontextprotocol/sdk` 内部依赖 `zod-to-json-schema`，但 `build-vsix.js` 只打包了 `zod`，遗漏了此包。修复后 vendor 打包列表改为循环写法，包含 `zod` 和 `zod-to-json-schema` 两个依赖 |
+
 ### V4.7.8：告警倒计时实时更新 + Open Dashboard CORS/Fallback 修复 ✅
 
 | 修复/增强 | 说明 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.7.9",
+  "version": "4.8.2",
   "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/build-vsix.js

@@ -17,21 +17,17 @@ if (fs.existsSync(DIST)) fs.rmSync(DIST, { recursive: true, force: true });
 fs.mkdirSync(DIST, { recursive: true });
 
 const copyMap = [
-  // Extension core
   { src: 'extension.js' },
   { src: 'lib', type: 'dir' },
   { src: 'media', type: 'dir' },
 
-  // Cursor-guard runtime deps (from references/)
   { src: path.join(REFS, 'dashboard'), dst: 'dashboard', type: 'dir' },
   { src: path.join(REFS, 'lib', 'core'), dst: path.join('lib', 'core'), type: 'dir' },
   { src: path.join(REFS, 'lib', 'utils.js'), dst: path.join('lib', 'utils.js') },
   { src: path.join(REFS, 'lib', 'auto-backup.js'), dst: path.join('lib', 'auto-backup.js') },
   { src: path.join(REFS, 'lib', 'guard-doctor.js'), dst: path.join('lib', 'guard-doctor.js') },
   { src: path.join(REFS, 'bin'), dst: 'bin', type: 'dir' },
-  { src: path.join(REFS, 'mcp'), dst: 'mcp', type: 'dir' },
 
-  // Skill files
   { src: path.join(ROOT, 'SKILL.md'), dst: path.join('skill', 'SKILL.md') },
   { src: path.join(ROOT, 'ROADMAP.md'), dst: path.join('skill', 'ROADMAP.md') },
   { src: path.join(REFS, 'cursor-guard.example.json'), dst: path.join('skill', 'cursor-guard.example.json') },
@@ -54,17 +50,21 @@ for (const entry of copyMap) {
   console.log(`  COPY: ${path.relative(DIST, dst)}`);
 }
 
-// Copy MCP SDK dependencies to vendor/ (not node_modules/ — vsce excludes that)
-const sdkSrc = path.join(ROOT, 'node_modules', '@modelcontextprotocol');
-if (fs.existsSync(sdkSrc)) {
-  const sdkDst = path.join(DIST, 'vendor', '@modelcontextprotocol');
-  copyDir(sdkSrc, sdkDst);
-  console.log('  COPY: vendor/@modelcontextprotocol/');
-}
-const zodSrc = path.join(ROOT, 'node_modules', 'zod');
-if (fs.existsSync(zodSrc)) {
-  copyDir(zodSrc, path.join(DIST, 'vendor', 'zod'));
-  console.log('  COPY: vendor/zod/');
+// ── Bundle MCP server with esbuild (all deps inlined, no vendor/ needed) ──
+const mcpEntry = path.join(REFS, 'mcp', 'server.js');
+const mcpOut = path.join(DIST, 'mcp', 'server.js');
+fs.mkdirSync(path.join(DIST, 'mcp'), { recursive: true });
+
+try {
+  const { execSync } = require('child_process');
+  const cmd = `npx esbuild "${mcpEntry}" --bundle --platform=node --target=node18 --format=cjs --outfile="${mcpOut}" --log-level=warning`;
+  execSync(cmd, { cwd: ROOT, stdio: 'pipe' });
+  const size = (fs.statSync(mcpOut).size / 1024).toFixed(0);
+  console.log(`  BUNDLE: mcp/server.js (${size} KB, self-contained)`);
+} catch (err) {
+  console.error(`  ERROR: esbuild bundle failed:\n${err.stderr?.toString() || err.message}`);
+  console.error('  Falling back to source copy...');
+  fs.copyFileSync(mcpEntry, mcpOut);
 }
 
 // Generate merged package.json

package/references/vscode-extension/dist/guard-version.json

@@ -1 +1 @@
-{"version":"4.7.8"}
+{"version":"4.8.2"}

package/references/vscode-extension/dist/lib/auto-setup.js

@@ -84,21 +84,41 @@ function autoInstallSkill(extRoot, homePath, dirName) {
     fs.copyFileSync(roadmapSrc, path.join(skillTarget, 'ROADMAP.md'));
   }
 
+  // Link references/ → extension directory so SKILL.md paths resolve correctly
+  // (mcp/server.js, lib/core/*, dashboard/, bin/ etc.)
   const refsTarget = path.join(skillTarget, 'references');
-  fs.mkdirSync(refsTarget, { recursive: true });
+  if (!fs.existsSync(refsTarget)) {
+    try {
+      fs.symlinkSync(extRoot, refsTarget, 'junction');
+      actions.push('references/ linked');
+    } catch {
+      // junction failed (rare) — fall back to copying essential docs only
+      fs.mkdirSync(refsTarget, { recursive: true });
+      _copyDocFiles(skillSrc, refsTarget);
+    }
+  }
 
-  const configRef = path.join(skillSrc, 'config-reference.md');
-  if (fs.existsSync(configRef)) fs.copyFileSync(configRef, path.join(refsTarget, 'config-reference.md'));
-  const configRefCn = path.join(skillSrc, 'config-reference.zh-CN.md');
-  if (fs.existsSync(configRefCn)) fs.copyFileSync(configRefCn, path.join(refsTarget, 'config-reference.zh-CN.md'));
-  const recoveryMd = path.join(skillSrc, 'recovery.md');
-  if (fs.existsSync(recoveryMd)) fs.copyFileSync(recoveryMd, path.join(refsTarget, 'recovery.md'));
-  const schemaSrc = path.join(skillSrc, 'cursor-guard.schema.json');
-  if (fs.existsSync(schemaSrc)) fs.copyFileSync(schemaSrc, path.join(refsTarget, 'cursor-guard.schema.json'));
+  // Copy package.json so `require('../../package.json')` in source mode works
+  const pkgSrc = path.join(extRoot, '..', '..', 'package.json');
+  const pkgDst = path.join(skillTarget, 'package.json');
+  if (fs.existsSync(pkgSrc) && !fs.existsSync(pkgDst)) {
+    fs.copyFileSync(pkgSrc, pkgDst);
+  }
 
   return actions;
 }
 
+function _copyDocFiles(skillSrc, refsTarget) {
+  const docs = [
+    'config-reference.md', 'config-reference.zh-CN.md',
+    'recovery.md', 'cursor-guard.schema.json', 'cursor-guard.example.json',
+  ];
+  for (const f of docs) {
+    const src = path.join(skillSrc, f);
+    if (fs.existsSync(src)) fs.copyFileSync(src, path.join(refsTarget, f));
+  }
+}
+
 function autoRegisterMcp(extRoot, homePath, wsRoot) {
   const actions = [];
   const mcpServerPath = path.join(extRoot, 'mcp', 'server.js');
@@ -122,18 +142,10 @@ function autoRegisterMcp(extRoot, homePath, wsRoot) {
     if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
     if (mcpConfig.mcpServers['cursor-guard']) return actions;
 
-    const vendorDir = path.join(extRoot, 'vendor');
-    const nmDir = path.join(extRoot, 'node_modules');
-    const nodePath = fs.existsSync(vendorDir) ? vendorDir : fs.existsSync(nmDir) ? nmDir : '';
-
-    const entry = {
+    mcpConfig.mcpServers['cursor-guard'] = {
       command: 'node',
       args: [mcpServerPath.replace(/\\/g, '/')],
     };
-    if (nodePath) {
-      entry.env = { NODE_PATH: nodePath.replace(/\\/g, '/') };
-    }
-    mcpConfig.mcpServers['cursor-guard'] = entry;
 
     fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2));
     actions.push('MCP registered');