cursor-guard 4.0.0 → 4.1.0

package/README.md

@@ -29,40 +29,47 @@ When Cursor's AI agent edits your files, there's a risk of accidental overwrites
 
 ## Installation
 
-### Method 1: npm
+### Method 1: npm (Recommended)
 
 ```bash
 npm install cursor-guard
+npx cursor-guard-init
 ```
 
-After installation, copy the skill files to your Cursor skills directory:
+The `init` command copies skill files to `.cursor/skills/cursor-guard/`, installs MCP dependencies, and adds `.gitignore` entries — all in one step.
 
-**Windows (PowerShell):**
+Options:
 
-```powershell
-# Global (all projects)
-Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
-
-# Per-project (current project only)
-Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
+```bash
+npx cursor-guard-init              # project-local (default)
+npx cursor-guard-init --global     # global (~/.cursor/skills/)
+npx cursor-guard-init --path /my/project  # specify project root
 ```
 
-**macOS / Linux:**
+After init, the npm package in `node_modules` is no longer needed:
 
 ```bash
-# Global
-cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
-
-# Per-project
-cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+npm uninstall cursor-guard
 ```
 
-After copying, you can remove the npm dependency if you don't need it in `node_modules`:
+<details>
+<summary>Manual installation (without init command)</summary>
+
+If you prefer manual setup, copy files then install dependencies:
 
 ```bash
-npm uninstall cursor-guard
+# Copy
+cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+
+# Install MCP dependencies in the skill directory
+cd .cursor/skills/cursor-guard && npm install --omit=dev && cd -
+
+# Add to .gitignore so node_modules aren't captured by git snapshots
+echo ".cursor/skills/**/node_modules/" >> .gitignore
 ```
 
+</details>
+
 ### Method 2: Git clone
 
 ```bash

package/README.zh-CN.md

@@ -29,40 +29,47 @@
 
 ## 安装
 
-### 方式一：npm 安装
+### 方式一：npm 安装（推荐）
 
 ```bash
 npm install cursor-guard
+npx cursor-guard-init
 ```
 
-安装后，将技能文件复制到 Cursor 技能目录：
+`init` 命令一键完成：复制技能文件到 `.cursor/skills/cursor-guard/`、安装 MCP 依赖、添加 `.gitignore` 条目。
 
-**Windows (PowerShell):**
+可选参数：
 
-```powershell
-# 全局安装（所有项目生效）
-Copy-Item -Recurse node_modules/cursor-guard "$env:USERPROFILE/.cursor/skills/cursor-guard"
-
-# 项目级安装（仅当前项目生效）
-Copy-Item -Recurse node_modules/cursor-guard .cursor/skills/cursor-guard
+```bash
+npx cursor-guard-init              # 项目级安装（默认）
+npx cursor-guard-init --global     # 全局安装（~/.cursor/skills/）
+npx cursor-guard-init --path /my/project  # 指定项目根目录
 ```
 
-**macOS / Linux:**
+初始化完成后，`node_modules` 中的 npm 包已不再需要：
 
 ```bash
-# 全局安装
-cp -r node_modules/cursor-guard ~/.cursor/skills/cursor-guard
-
-# 项目级安装
-cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+npm uninstall cursor-guard
 ```
 
-复制完成后，如果不需要保留在 `node_modules` 中，可以卸载：
+<details>
+<summary>手动安装（不使用 init 命令）</summary>
+
+如果你更喜欢手动操作，复制文件后需要手动安装依赖：
 
 ```bash
-npm uninstall cursor-guard
+# 复制
+cp -r node_modules/cursor-guard .cursor/skills/cursor-guard
+
+# 在 skill 目录中安装 MCP 依赖
+cd .cursor/skills/cursor-guard && npm install --omit=dev && cd -
+
+# 添加到 .gitignore，防止 node_modules 被 git 快照捕获
+echo ".cursor/skills/**/node_modules/" >> .gitignore
 ```
 
+</details>
+
 ### 方式二：Git 克隆
 
 ```bash

package/SKILL.md

@@ -202,7 +202,7 @@ git update-ref refs/guard/snapshot $commit
 
 1. **Quick git init** (preferred):
    ```
-   git init && git add -A && git commit -m "guard: initial snapshot" --no-verify
+   git init; git add -A; git commit -m "guard: initial snapshot" --no-verify
    ```
 2. **Shadow copy** (fallback if user declines git):
    - Copy the target file(s) to `.cursor-guard-backup/<timestamp>/` via Shell.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.0.0",
+  "version": "4.1.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",
@@ -27,6 +27,7 @@
     "test": "node references/lib/utils.test.js && node references/lib/core/core.test.js && node references/mcp/mcp.test.js"
   },
   "bin": {
+    "cursor-guard-init": "references/bin/cursor-guard-init.js",
     "cursor-guard-backup": "references/bin/cursor-guard-backup.js",
     "cursor-guard-doctor": "references/bin/cursor-guard-doctor.js",
     "cursor-guard-mcp": "references/mcp/server.js"

package/references/bin/cursor-guard-init.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`Usage: cursor-guard-init [options]
+
+Installs cursor-guard skill into your Cursor skills directory, including
+MCP dependencies and .gitignore entries.
+
+Options:
+  --global             Install to ~/.cursor/skills/ (default: project-local)
+  --path <dir>         Project directory (default: current dir)
+  --help, -h           Show this help message
+  --version, -v        Show version number`);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  const pkg = require('../../package.json');
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const isGlobal = args.includes('--global');
+const pathIdx = args.indexOf('--path');
+const projectDir = path.resolve(pathIdx >= 0 && args[pathIdx + 1] ? args[pathIdx + 1] : '.');
+
+const skillSource = path.resolve(__dirname, '../..');
+const skillTarget = isGlobal
+  ? path.join(process.env.USERPROFILE || process.env.HOME || os.homedir(), '.cursor', 'skills', 'cursor-guard')
+  : path.join(projectDir, '.cursor', 'skills', 'cursor-guard');
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (path.basename(src) === 'node_modules') return;
+    if (path.basename(src) === '.git') return;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+console.log(`\n  cursor-guard init\n`);
+console.log(`  Source:  ${skillSource}`);
+console.log(`  Target:  ${skillTarget}`);
+console.log(`  Mode:    ${isGlobal ? 'global (~/.cursor/skills/)' : 'project-local (.cursor/skills/)'}\n`);
+
+// Step 1: Copy skill files (excluding node_modules and .git)
+console.log('  [1/4] Copying skill files...');
+if (fs.existsSync(skillTarget)) {
+  fs.rmSync(skillTarget, { recursive: true, force: true });
+}
+copyRecursive(skillSource, skillTarget);
+console.log('        Done.');
+
+// Step 2: Install MCP dependencies in skill directory
+console.log('  [2/4] Installing MCP dependencies...');
+try {
+  execFileSync('npm', ['install', '--omit=dev', '--ignore-scripts'], {
+    cwd: skillTarget,
+    stdio: 'pipe',
+    shell: process.platform === 'win32',
+  });
+  console.log('        Done.');
+} catch (e) {
+  console.log(`        Warning: npm install failed (${e.message}). MCP tools may not work.`);
+  console.log('        You can fix this later: cd "' + skillTarget + '" ; npm install');
+}
+
+// Step 3: Add .gitignore entries for skill node_modules
+console.log('  [3/4] Updating .gitignore...');
+const gitignorePath = path.join(projectDir, '.gitignore');
+const entries = ['.cursor/skills/**/node_modules/'];
+let gitignoreUpdated = false;
+if (!isGlobal) {
+  let existing = '';
+  try { existing = fs.readFileSync(gitignorePath, 'utf-8'); } catch { /* doesn't exist */ }
+  const missing = entries.filter(e => !existing.includes(e));
+  if (missing.length > 0) {
+    const newline = existing.endsWith('\n') || !existing ? '' : '\n';
+    fs.appendFileSync(gitignorePath, `${newline}# cursor-guard skill dependencies\n${missing.join('\n')}\n`);
+    gitignoreUpdated = true;
+    console.log('        Added: ' + missing.join(', '));
+  } else {
+    console.log('        Already configured.');
+  }
+} else {
+  console.log('        Skipped (global install, not inside a project).');
+}
+
+// Step 4: Summary
+console.log('  [4/4] Verifying...');
+const serverExists = fs.existsSync(path.join(skillTarget, 'references', 'mcp', 'server.js'));
+const sdkExists = fs.existsSync(path.join(skillTarget, 'node_modules', '@modelcontextprotocol', 'sdk'));
+const skillMdExists = fs.existsSync(path.join(skillTarget, 'SKILL.md'));
+
+console.log(`        SKILL.md:   ${skillMdExists ? 'OK' : 'MISSING'}`);
+console.log(`        MCP server: ${serverExists ? 'OK' : 'MISSING'}`);
+console.log(`        MCP SDK:    ${sdkExists ? 'OK' : 'MISSING — run npm install in skill dir'}`);
+
+console.log(`\n  Installation complete!\n`);
+console.log('  Next steps:');
+console.log('  1. The skill activates automatically in Cursor Agent conversations.');
+console.log('  2. (Optional) Copy example config to project root:');
+console.log(`     cp "${path.join(skillTarget, 'references', 'cursor-guard.example.json')}" .cursor-guard.json`);
+console.log('  3. (Optional) Enable MCP — add to .cursor/mcp.json:');
+console.log(`     { "mcpServers": { "cursor-guard": { "command": "node", "args": ["${path.join(skillTarget, 'references', 'mcp', 'server.js').replace(/\\/g, '/')}"] } } }`);
+console.log('  4. (Optional) Start auto-backup:');
+console.log(`     npx cursor-guard-backup --path "${projectDir}"\n`);

package/references/lib/core/doctor.js

@@ -217,17 +217,35 @@ function runDiagnostics(projectDir) {
 
   let mcpSdkAvailable = false;
   let mcpSdkVersion = null;
-  try {
-    const mcpPkgPath = require.resolve('@modelcontextprotocol/sdk/package.json');
-    const mcpPkg = JSON.parse(fs.readFileSync(mcpPkgPath, 'utf-8'));
-    mcpSdkAvailable = true;
-    mcpSdkVersion = mcpPkg.version;
-  } catch { /* not installed */ }
+  // Try resolving SDK from the skill package's own node_modules first,
+  // then fall back to the running process's require paths.
+  const skillRoot = path.resolve(__dirname, '../../..');
+  const sdkCandidates = [
+    path.join(skillRoot, 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json'),
+  ];
+  for (const candidate of sdkCandidates) {
+    try {
+      if (fs.existsSync(candidate)) {
+        const mcpPkg = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
+        mcpSdkAvailable = true;
+        mcpSdkVersion = mcpPkg.version;
+        break;
+      }
+    } catch { /* ignore */ }
+  }
+  if (!mcpSdkAvailable) {
+    try {
+      const mcpPkgPath = require.resolve('@modelcontextprotocol/sdk/package.json');
+      const mcpPkg = JSON.parse(fs.readFileSync(mcpPkgPath, 'utf-8'));
+      mcpSdkAvailable = true;
+      mcpSdkVersion = mcpPkg.version;
+    } catch { /* not installed */ }
+  }
 
   if (mcpServerExists && mcpSdkAvailable) {
     check('MCP server', 'PASS', `server.js found, SDK ${mcpSdkVersion}`);
   } else if (mcpServerExists && !mcpSdkAvailable) {
-    check('MCP server', 'WARN', 'server.js found but @modelcontextprotocol/sdk not installed — run npm install');
+    check('MCP server', 'WARN', 'server.js found but @modelcontextprotocol/sdk not installed — run: cd <skill-dir> && npm install');
   } else if (!mcpServerExists && mcpSdkAvailable) {
     check('MCP server', 'WARN', `SDK installed (${mcpSdkVersion}) but server.js not found at expected path`);
   } else {

package/references/lib/core/snapshot.js

@@ -121,13 +121,13 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
 
     git(['update-ref', branchRef, commitHash], { cwd });
 
-    let fileCount = 0;
+    const lsOut = git(['ls-tree', '--name-only', '-r', newTree], { cwd, allowFail: true });
+    const fileCount = lsOut ? lsOut.split('\n').filter(Boolean).length : 0;
+
+    let changedCount;
     if (parentTree) {
       const diff = git(['diff-tree', '--no-commit-id', '--name-only', '-r', parentTree, newTree], { cwd, allowFail: true });
-      fileCount = diff ? diff.split('\n').filter(Boolean).length : 0;
-    } else {
-      const all = git(['ls-tree', '--name-only', '-r', newTree], { cwd, allowFail: true });
-      fileCount = all ? all.split('\n').filter(Boolean).length : 0;
+      changedCount = diff ? diff.split('\n').filter(Boolean).length : 0;
     }
 
     return {
@@ -135,6 +135,7 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
       commitHash,
       shortHash: commitHash.substring(0, 7),
       fileCount,
+      changedCount,
       secretsExcluded: secretsExcluded.length > 0 ? secretsExcluded : undefined,
     };
   } catch (e) {

package/references/mcp/server.js

@@ -91,12 +91,20 @@ server.tool(
     path: z.string().describe('Absolute path to the project directory'),
     strategy: z.enum(['git', 'shadow', 'both']).optional().describe('Backup strategy (default: from config, or "git")'),
     message: z.string().optional().describe('Custom commit message for git snapshot'),
+    scope: z.enum(['protected', 'all']).optional().describe('Snapshot scope: "protected" = only files matching protect patterns (default when protect is configured); "all" = all files regardless of protect config'),
   },
-  async ({ path: projectPath, strategy, message }) => {
+  async ({ path: projectPath, strategy, message, scope }) => {
     const resolved = path.resolve(projectPath);
     const { loadConfig } = require('../lib/utils');
     const { cfg } = loadConfig(resolved);
 
+    if (scope === 'all') {
+      cfg.protect = [];
+    } else if (scope === 'protected' && cfg.protect.length === 0) {
+      // "protected" requested but no protect patterns configured — snapshot all
+      // (no way to filter without patterns)
+    }
+
     const effectiveStrategy = strategy || cfg.backup_strategy || 'git';
     const results = {};