cursor-guard 4.9.0 → 4.9.6

package/references/lib/utils.js

@@ -133,19 +133,23 @@ const VALID_GIT_RETENTION_MODES = ['days', 'count'];
 
 const DEFAULT_IGNORE = ['.cursor/skills/**'];
 
-const DEFAULT_CONFIG = {
-  protect: [],
-  ignore: [...DEFAULT_IGNORE],
-  secrets_patterns: DEFAULT_SECRETS,
-  backup_strategy: 'git',
+const DEFAULT_CONFIG = {
+  protect: [],
+  ignore: [...DEFAULT_IGNORE],
+  secrets_patterns: DEFAULT_SECRETS,
+  backup_strategy: 'git',
   auto_backup_interval_seconds: 60,
   pre_restore_backup: 'always',
   retention: { mode: 'days', days: 30, max_count: 100, max_size_mb: 500 },
-  git_retention: { enabled: false, mode: 'count', days: 30, max_count: 200 },
-  proactive_alert: true,
-  alert_thresholds: { files_per_window: 20, window_seconds: 10, cooldown_seconds: 60 },
-  always_watch: false,
-};
+  git_retention: { enabled: false, mode: 'count', days: 30, max_count: 200 },
+  proactive_alert: true,
+  alert_thresholds: { files_per_window: 20, window_seconds: 10, cooldown_seconds: 60 },
+  always_watch: false,
+  enable_pre_warning: false,
+  pre_warning_threshold: 30,
+  pre_warning_mode: 'popup',
+  pre_warning_exclude_patterns: [],
+};
 
 function loadConfig(projectDir) {
   const cfgPath = path.join(projectDir, '.cursor-guard.json');
@@ -234,16 +238,38 @@ function loadConfig(projectDir) {
       if (typeof raw.alert_thresholds.cooldown_seconds === 'number' && raw.alert_thresholds.cooldown_seconds > 0)
         cfg.alert_thresholds.cooldown_seconds = raw.alert_thresholds.cooldown_seconds;
     }
-    if (raw.always_watch === true) {
-      cfg.always_watch = true;
-    } else if (raw.always_watch !== undefined && raw.always_watch !== false) {
-      warnings.push(`always_watch should be a boolean, got ${JSON.stringify(raw.always_watch)} — using default (false)`);
-    }
-    return { cfg, loaded: true, error: null, warnings };
-  } catch (e) {
-    return { cfg, loaded: false, error: e.message };
-  }
-}
+    if (raw.always_watch === true) {
+      cfg.always_watch = true;
+    } else if (raw.always_watch !== undefined && raw.always_watch !== false) {
+      warnings.push(`always_watch should be a boolean, got ${JSON.stringify(raw.always_watch)} — using default (false)`);
+    }
+    if (raw.enable_pre_warning === true) {
+      cfg.enable_pre_warning = true;
+    } else if (raw.enable_pre_warning !== undefined && raw.enable_pre_warning !== false) {
+      warnings.push(`enable_pre_warning should be a boolean, got ${JSON.stringify(raw.enable_pre_warning)} — using default (false)`);
+    }
+    if (typeof raw.pre_warning_threshold === 'number') {
+      if (raw.pre_warning_threshold >= 1 && raw.pre_warning_threshold <= 100) {
+        cfg.pre_warning_threshold = raw.pre_warning_threshold;
+      } else {
+        warnings.push(`pre_warning_threshold should be 1-100, got ${JSON.stringify(raw.pre_warning_threshold)} — using default (${cfg.pre_warning_threshold})`);
+      }
+    }
+    if (typeof raw.pre_warning_mode === 'string') {
+      if (['popup', 'dashboard', 'silent'].includes(raw.pre_warning_mode)) {
+        cfg.pre_warning_mode = raw.pre_warning_mode;
+      } else {
+        warnings.push(`Unknown pre_warning_mode "${raw.pre_warning_mode}", using default "${cfg.pre_warning_mode}"`);
+      }
+    }
+    if (Array.isArray(raw.pre_warning_exclude_patterns)) {
+      cfg.pre_warning_exclude_patterns = sanitizeStringArray(raw.pre_warning_exclude_patterns, 'pre_warning_exclude_patterns');
+    }
+    return { cfg, loaded: true, error: null, warnings };
+  } catch (e) {
+    return { cfg, loaded: false, error: e.message };
+  }
+}
 
 // ── Git helpers ─────────────────────────────────────────────────
 

package/references/mcp/mcp.test.js

@@ -350,18 +350,66 @@ async function run() {
     name: 'restore_project',
     arguments: { path: tmpDir, source: alertHead, preview: true },
   });
-  await test('restore_project response contains _activeAlert', () => {
-    const content = rpResp.result.content[0].text;
-    const data = JSON.parse(content);
-    if (!data._activeAlert) throw new Error('_activeAlert missing from restore_project');
-  });
-
-  // Clean up alert file
-  try { fs.unlinkSync(alertFile); } catch { /* ignore */ }
-
-  // Cleanup
-  serverProcess.kill();
-  fs.rmSync(tmpDir, { recursive: true, force: true });
+  await test('restore_project response contains _activeAlert', () => {
+    const content = rpResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!data._activeAlert) throw new Error('_activeAlert missing from restore_project');
+  });
+
+  // Clean up alert file
+  try { fs.unlinkSync(alertFile); } catch { /* ignore */ }
+
+  // Verify pre-warning injection
+  const preWarningFile = path.join(gitDir, 'cursor-guard-pre-warning.json');
+  const fakePreWarning = {
+    type: 'destructive_edit_risk',
+    detectedAt: Date.now(),
+    timestamp: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + 300000).toISOString(),
+    file: 'src/app.js',
+    summary: '1 method removed, 5 lines deleted (risk 68%)',
+    riskPercent: 68,
+    removedMethodCount: 1,
+    removedMethods: [{ name: 'login', lineNumber: 12 }],
+    deletedLines: 5,
+  };
+  fs.writeFileSync(preWarningFile, JSON.stringify({
+    updatedAt: new Date().toISOString(),
+    warnings: [fakePreWarning],
+  }, null, 2));
+
+  const toolsWithPreWarning = ['doctor', 'backup_status', 'dashboard'];
+  for (const toolName of toolsWithPreWarning) {
+    const resp = await rpc('tools/call', {
+      name: toolName,
+      arguments: { path: tmpDir },
+    });
+    await test(`${toolName} response contains _activePreWarning when warning exists`, () => {
+      const content = resp.result.content[0].text;
+      const data = JSON.parse(content);
+      if (!data._activePreWarning) throw new Error(`_activePreWarning missing from ${toolName}`);
+      if (data._activePreWarning.count !== 1) throw new Error(`unexpected warning count: ${data._activePreWarning.count}`);
+      if (data._activePreWarning.latest?.file !== 'src/app.js') {
+        throw new Error(`unexpected warning file: ${data._activePreWarning.latest?.file}`);
+      }
+    });
+  }
+
+  const snapshotPreWarningResp = await rpc('tools/call', {
+    name: 'snapshot_now',
+    arguments: { path: tmpDir, strategy: 'git' },
+  });
+  await test('snapshot_now response contains _activePreWarning', () => {
+    const content = snapshotPreWarningResp.result.content[0].text;
+    const data = JSON.parse(content);
+    if (!data._activePreWarning) throw new Error('_activePreWarning missing from snapshot_now');
+  });
+
+  try { fs.unlinkSync(preWarningFile); } catch { /* ignore */ }
+
+  // Cleanup
+  serverProcess.kill();
+  fs.rmSync(tmpDir, { recursive: true, force: true });
 
   console.log(`\n${passed + failed} tests: \x1b[32m${passed} passed\x1b[0m` + (failed ? `, \x1b[31m${failed} failed\x1b[0m` : ''));
   process.exit(failed > 0 ? 1 : 0);

package/references/mcp/server.js

@@ -10,10 +10,11 @@ const { runDiagnostics } = require('../lib/core/doctor');
 const { createGitSnapshot, createShadowCopy } = require('../lib/core/snapshot');
 const { listBackups } = require('../lib/core/backups');
 const { restoreFile, previewProjectRestore, executeProjectRestore } = require('../lib/core/restore');
-const { runFixes } = require('../lib/core/doctor-fix');
-const { getBackupStatus } = require('../lib/core/status');
-const { getDashboard } = require('../lib/core/dashboard');
-const { loadActiveAlert } = require('../lib/core/anomaly');
+const { runFixes } = require('../lib/core/doctor-fix');
+const { getBackupStatus } = require('../lib/core/status');
+const { getDashboard } = require('../lib/core/dashboard');
+const { loadActiveAlert } = require('../lib/core/anomaly');
+const { loadActivePreWarnings } = require('../lib/core/pre-warning');
 
 const { loadConfig, gitDir: getGitDir } = require('../lib/utils');
 
@@ -46,18 +47,29 @@ function ensureWatcher(projectPath) {
 
 // ── Alert injection helper ──────────────────────────────────────
 
-function injectAlert(projectPath, result) {
-  const alert = loadActiveAlert(projectPath);
-  if (alert) {
-    result._activeAlert = {
-      type: alert.type,
+function injectAlert(projectPath, result) {
+  const alert = loadActiveAlert(projectPath);
+  if (alert) {
+    result._activeAlert = {
+      type: alert.type,
       message: alert.recommendation || `${alert.fileCount} files changed in ${alert.windowSeconds}s`,
       timestamp: alert.timestamp,
       expiresAt: alert.expiresAt,
     };
   }
-  return result;
-}
+  return result;
+}
+
+function injectPreWarning(projectPath, result) {
+  const warnings = loadActivePreWarnings(projectPath);
+  if (warnings.length > 0) {
+    result._activePreWarning = {
+      count: warnings.length,
+      latest: warnings[0],
+    };
+  }
+  return result;
+}
 
 // ── Watcher status check ────────────────────────────────────────
 
@@ -101,12 +113,12 @@ server.tool(
   {
     path: z.string().describe('Absolute path to the project directory'),
   },
-  async ({ path: projectPath }) => {
-    const resolved = path.resolve(projectPath);
-    ensureWatcher(resolved);
-    const result = injectAlert(resolved, runDiagnostics(resolved));
-    injectWatcherWarning(resolved, result);
-    return {
+  async ({ path: projectPath }) => {
+    const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
+    const result = injectPreWarning(resolved, injectAlert(resolved, runDiagnostics(resolved)));
+    injectWatcherWarning(resolved, result);
+    return {
       content: [{
         type: 'text',
         text: JSON.stringify(result, null, 2),
@@ -126,11 +138,11 @@ server.tool(
     before: z.string().optional().describe('Only show backups before this time (e.g. "10 minutes ago", "2026-03-21T14:00:00")'),
     limit: z.number().optional().describe('Max results per source (default 20)'),
   },
-  async ({ path: projectPath, file, before, limit }) => {
-    const resolved = path.resolve(projectPath);
-    ensureWatcher(resolved);
-    const result = injectAlert(resolved, listBackups(resolved, { file, before, limit }));
-    return {
+  async ({ path: projectPath, file, before, limit }) => {
+    const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
+    const result = injectPreWarning(resolved, injectAlert(resolved, listBackups(resolved, { file, before, limit })));
+    return {
       content: [{
         type: 'text',
         text: JSON.stringify(result, null, 2),
@@ -180,12 +192,12 @@ server.tool(
       });
     }
 
-    if (effectiveStrategy === 'shadow' || effectiveStrategy === 'both') {
-      results.shadow = createShadowCopy(resolved, cfg);
-    }
-
-    injectAlert(resolved, results);
-    injectWatcherWarning(resolved, results);
+    if (effectiveStrategy === 'shadow' || effectiveStrategy === 'both') {
+      results.shadow = createShadowCopy(resolved, cfg);
+    }
+
+    injectPreWarning(resolved, injectAlert(resolved, results));
+    injectWatcherWarning(resolved, results);
 
     return {
       content: [{
@@ -207,13 +219,13 @@ server.tool(
     source: z.string().describe('Backup source: git commit hash, ref name, or shadow copy timestamp (e.g. "20260321_143205")'),
     preserve_current: z.boolean().optional().describe('Create pre-restore snapshot before restoring (default true)'),
   },
-  async ({ path: projectPath, file, source, preserve_current }) => {
-    const resolved = path.resolve(projectPath);
-    ensureWatcher(resolved);
-    const result = injectAlert(resolved, restoreFile(resolved, file, source, {
-      preserveCurrent: preserve_current,
-    }));
-    injectWatcherWarning(resolved, result);
+  async ({ path: projectPath, file, source, preserve_current }) => {
+    const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
+    const result = injectPreWarning(resolved, injectAlert(resolved, restoreFile(resolved, file, source, {
+      preserveCurrent: preserve_current,
+    })));
+    injectWatcherWarning(resolved, result);
     return {
       content: [{
         type: 'text',
@@ -239,16 +251,16 @@ server.tool(
     const resolved = path.resolve(projectPath);
     ensureWatcher(resolved);
 
-    if (preview !== false) {
-      const result = injectAlert(resolved, previewProjectRestore(resolved, source));
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    }
-
-    const result = injectAlert(resolved, executeProjectRestore(resolved, source, {
-      preserveCurrent: preserve_current,
-      cleanUntracked: clean_untracked,
-    }));
-    injectWatcherWarning(resolved, result);
+    if (preview !== false) {
+      const result = injectPreWarning(resolved, injectAlert(resolved, previewProjectRestore(resolved, source)));
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+
+    const result = injectPreWarning(resolved, injectAlert(resolved, executeProjectRestore(resolved, source, {
+      preserveCurrent: preserve_current,
+      cleanUntracked: clean_untracked,
+    })));
+    injectWatcherWarning(resolved, result);
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   }
 );
@@ -262,11 +274,11 @@ server.tool(
     path: z.string().describe('Absolute path to the project directory'),
     dry_run: z.boolean().optional().describe('If true, report what would be fixed without modifying anything (default false)'),
   },
-  async ({ path: projectPath, dry_run }) => {
-    const resolved = path.resolve(projectPath);
-    ensureWatcher(resolved);
-    const result = injectAlert(resolved, runFixes(resolved, { dryRun: !!dry_run }));
-    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  async ({ path: projectPath, dry_run }) => {
+    const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
+    const result = injectPreWarning(resolved, injectAlert(resolved, runFixes(resolved, { dryRun: !!dry_run })));
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   }
 );
 
@@ -278,11 +290,11 @@ server.tool(
   {
     path: z.string().describe('Absolute path to the project directory'),
   },
-  async ({ path: projectPath }) => {
-    const resolved = path.resolve(projectPath);
-    ensureWatcher(resolved);
-    const result = injectAlert(resolved, getBackupStatus(resolved));
-    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  async ({ path: projectPath }) => {
+    const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
+    const result = injectPreWarning(resolved, injectAlert(resolved, getBackupStatus(resolved)));
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   }
 );
 
@@ -294,11 +306,11 @@ server.tool(
   {
     path: z.string().describe('Absolute path to the project directory'),
   },
-  async ({ path: projectPath }) => {
-    const resolved = path.resolve(projectPath);
-    ensureWatcher(resolved);
-    const result = injectAlert(resolved, getDashboard(resolved));
-    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  async ({ path: projectPath }) => {
+    const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
+    const result = injectPreWarning(resolved, injectAlert(resolved, getDashboard(resolved)));
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   }
 );
 

package/references/quickstart.zh-CN.md

@@ -202,13 +202,17 @@ npx cursor-guard-backup --path .
 {
   "protect": ["src/**", "package.json", "README.md"],
   "ignore": ["dist/**", "node_modules/**", "*.log"],
-  "backup_strategy": "both",
-  "auto_backup_interval_seconds": 60,
-  "pre_restore_backup": "always",
-  "secrets_patterns_extra": ["*.secret", "tokens.*"],
-  "retention": {
-    "mode": "days",
-    "days": 30,
+  "backup_strategy": "both",
+  "auto_backup_interval_seconds": 60,
+  "pre_restore_backup": "always",
+  "secrets_patterns_extra": ["*.secret", "tokens.*"],
+  "enable_pre_warning": true,
+  "pre_warning_threshold": 30,
+  "pre_warning_mode": "popup",
+  "pre_warning_exclude_patterns": ["generated/**"],
+  "retention": {
+    "mode": "days",
+    "days": 30,
     "max_count": 100,
     "max_size_mb": 500
   },
@@ -230,12 +234,13 @@ npx cursor-guard-backup --path .
 
 - 只重点保护 `src/**`、`package.json`、`README.md`
 - 忽略产物目录和日志
-- 同时启用 Git 备份和影子拷贝
-- 每 60 秒检查一次变化
-- 恢复前默认先保留当前版本
-- 额外排除自定义敏感文件
-- 自动清理过旧备份
-- 开启主动变更频率检测（10 秒内 20+ 文件变更时告警）
+- 同时启用 Git 备份和影子拷贝
+- 每 60 秒检查一次变化
+- 恢复前默认先保留当前版本
+- 开启局部删除的事先预警，删方法/大段删行时会先提醒
+- 额外排除自定义敏感文件
+- 自动清理过旧备份
+- 开启主动变更频率检测（10 秒内 20+ 文件变更时告警）
 
 ---
 
@@ -274,16 +279,36 @@ npx cursor-guard-backup --path .
 
 控制 `refs/guard/auto-backup` 里的 Git 备份保留多久。
 
-### `proactive_alert`
-
-是否开启 V4 主动变更频率检测（默认 `true`）。开启后 watcher 会自动监控文件变更速率，异常时触发告警。
-
-### `alert_thresholds`
+### `proactive_alert`
+
+是否开启 V4 主动变更频率检测（默认 `true`）。开启后 watcher 会自动监控文件变更速率，异常时触发告警。
+
+### `alert_thresholds`
 
 告警阈值配置：
-- `files_per_window`：窗口内触发告警的文件数（默认 20）
-- `window_seconds`：滑动窗口秒数（默认 10）
-- `cooldown_seconds`：连续告警最小间隔（默认 60）
+- `files_per_window`：窗口内触发告警的文件数（默认 20）
+- `window_seconds`：滑动窗口秒数（默认 10）
+- `cooldown_seconds`：连续告警最小间隔（默认 60）
+
+### `enable_pre_warning`
+
+是否开启“事先预警”功能（默认 `false`）。开启后，IDE 扩展会对局部删代码、删方法这类高风险编辑先做提醒。
+
+### `pre_warning_threshold`
+
+删除风险阈值（默认 `30`）。删行比例达到这个值时触发预警。
+
+### `pre_warning_mode`
+
+预警展示模式：
+
+- `popup`：弹窗提醒，可快速撤销或看 diff
+- `dashboard`：只在仪表盘/状态栏/侧边栏高亮
+- `silent`：只记录，不主动打断
+
+### `pre_warning_exclude_patterns`
+
+哪些文件跳过事先预警评估。常用于生成文件、迁移脚本、第三方目录等。
 
 ---
 

package/references/vscode-extension/build-vsix.js

@@ -28,9 +28,10 @@ const copyMap = [
   { 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(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') },
+  { 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(ROOT, 'LICENSE'), dst: 'LICENSE' },
+  { src: path.join(REFS, 'cursor-guard.example.json'), dst: path.join('skill', 'cursor-guard.example.json') },
   { src: path.join(REFS, 'cursor-guard.schema.json'), dst: path.join('skill', 'cursor-guard.schema.json') },
   { src: path.join(REFS, 'config-reference.md'), dst: path.join('skill', 'config-reference.md') },
   { src: path.join(REFS, 'config-reference.zh-CN.md'), dst: path.join('skill', 'config-reference.zh-CN.md') },

package/references/vscode-extension/dist/LICENSE

@@ -0,0 +1,65 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             zhangqiang8vipp
+Licensed Work:        cursor-guard
+                      The Licensed Work is (c) 2026 zhangqiang8vipp
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you may not use the Licensed Work for a Commercial Use.
+                      "Commercial Use" means distribution, sale, licensing,
+                      sublicensing, or providing the Licensed Work (or any
+                      derivative work) to third parties as a paid product or
+                      service, or incorporating it into a paid product or
+                      service offered to third parties.
+Change Date:          2056-03-22
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: zhangqiang8vipp
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-commercial use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited commercial
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.