cursor-guard 1.3.2 → 2.0.2

package/references/lib/utils.test.js

@@ -0,0 +1,329 @@
+'use strict';
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const {
+  globMatch, matchesAny, loadConfig, DEFAULT_CONFIG, DEFAULT_SECRETS,
+  filterFiles, buildManifest, manifestChanged, parseArgs, walkDir,
+} = require('./utils');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  \x1b[32m✓\x1b[0m ${name}`);
+  } catch (e) {
+    failed++;
+    console.log(`  \x1b[31m✗\x1b[0m ${name}`);
+    console.log(`    ${e.message}`);
+  }
+}
+
+// ── globMatch ────────────────────────────────────────────────────
+
+console.log('\nglobMatch:');
+
+test('exact filename match', () => {
+  assert.strictEqual(globMatch('.env', '.env'), true);
+  assert.strictEqual(globMatch('.env', '.envx'), false);
+});
+
+test('* matches within a single segment', () => {
+  assert.strictEqual(globMatch('*.js', 'foo.js'), true);
+  assert.strictEqual(globMatch('*.js', 'bar.ts'), false);
+  assert.strictEqual(globMatch('*.js', 'dir/foo.js'), false);
+});
+
+test('** matches across directories', () => {
+  assert.strictEqual(globMatch('**/*.js', 'src/foo.js'), true);
+  assert.strictEqual(globMatch('**/*.js', 'a/b/c/foo.js'), true);
+  // **/*.js requires a slash — root-level 'foo.js' doesn't match (matchesAny checks leaf separately)
+  assert.strictEqual(globMatch('**/*.js', 'foo.js'), false);
+  assert.strictEqual(globMatch('**/*.js', 'foo.ts'), false);
+});
+
+test('? matches single character', () => {
+  assert.strictEqual(globMatch('?.txt', 'a.txt'), true);
+  assert.strictEqual(globMatch('?.txt', 'ab.txt'), false);
+});
+
+test('.env.* pattern', () => {
+  assert.strictEqual(globMatch('.env.*', '.env.local'), true);
+  assert.strictEqual(globMatch('.env.*', '.env.production'), true);
+  assert.strictEqual(globMatch('.env.*', '.env'), false);
+});
+
+test('credentials* pattern', () => {
+  assert.strictEqual(globMatch('credentials*', 'credentials'), true);
+  assert.strictEqual(globMatch('credentials*', 'credentials.json'), true);
+  assert.strictEqual(globMatch('credentials*', 'my-credentials'), false);
+});
+
+test('directory pattern src/**', () => {
+  assert.strictEqual(globMatch('src/**', 'src/foo.js'), true);
+  assert.strictEqual(globMatch('src/**', 'src/a/b.js'), true);
+  assert.strictEqual(globMatch('src/**', 'lib/foo.js'), false);
+});
+
+test('backslash normalization', () => {
+  assert.strictEqual(globMatch('src/**/*.ts', 'src\\components\\App.ts'), true);
+});
+
+test('regex special chars in pattern are escaped', () => {
+  assert.strictEqual(globMatch('file(1).txt', 'file(1).txt'), true);
+  assert.strictEqual(globMatch('file[0].txt', 'file[0].txt'), true); // [] escaped as literals
+});
+
+// ── matchesAny ───────────────────────────────────────────────────
+
+console.log('\nmatchesAny:');
+
+test('matches when any pattern hits', () => {
+  assert.strictEqual(matchesAny(['*.js', '*.ts'], 'foo.js'), true);
+  assert.strictEqual(matchesAny(['*.js', '*.ts'], 'foo.ts'), true);
+  assert.strictEqual(matchesAny(['*.js', '*.ts'], 'foo.py'), false);
+});
+
+test('checks leaf filename for deep paths', () => {
+  assert.strictEqual(matchesAny(['*.key'], 'secrets/server.key'), true);
+  assert.strictEqual(matchesAny(['.env'], 'config/.env'), true);
+});
+
+test('empty patterns matches nothing', () => {
+  assert.strictEqual(matchesAny([], 'anything'), false);
+});
+
+// ── loadConfig ───────────────────────────────────────────────────
+
+console.log('\nloadConfig:');
+
+test('returns defaults when no config file', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
+  try {
+    const { cfg, loaded, error } = loadConfig(tmpDir);
+    assert.strictEqual(loaded, false);
+    assert.strictEqual(error, null);
+    assert.deepStrictEqual(cfg.protect, []);
+    assert.deepStrictEqual(cfg.ignore, []);
+    assert.deepStrictEqual(cfg.secrets_patterns, DEFAULT_SECRETS);
+    assert.strictEqual(cfg.backup_strategy, 'git');
+    assert.strictEqual(cfg.git_retention.enabled, false);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('loads and merges custom config', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
+  try {
+    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
+      protect: ['src/**'],
+      backup_strategy: 'both',
+      retention: { mode: 'count', max_count: 50 },
+    }));
+    const { cfg, loaded, error } = loadConfig(tmpDir);
+    assert.strictEqual(loaded, true);
+    assert.strictEqual(error, null);
+    assert.deepStrictEqual(cfg.protect, ['src/**']);
+    assert.strictEqual(cfg.backup_strategy, 'both');
+    assert.strictEqual(cfg.retention.mode, 'count');
+    assert.strictEqual(cfg.retention.max_count, 50);
+    assert.strictEqual(cfg.retention.days, 30); // default preserved
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('handles malformed JSON gracefully', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
+  try {
+    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), '{ broken }');
+    const { cfg, loaded, error } = loadConfig(tmpDir);
+    assert.strictEqual(loaded, false);
+    assert.ok(error, 'should have an error message');
+    assert.deepStrictEqual(cfg.protect, []);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('secrets_patterns override replaces defaults entirely', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
+  try {
+    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
+      secrets_patterns: ['my-secret'],
+    }));
+    const { cfg } = loadConfig(tmpDir);
+    assert.deepStrictEqual(cfg.secrets_patterns, ['my-secret']);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('secrets_patterns_extra appends to defaults', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
+  try {
+    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
+      secrets_patterns_extra: ['*.secret', 'tokens.*'],
+    }));
+    const { cfg } = loadConfig(tmpDir);
+    assert.ok(cfg.secrets_patterns.includes('.env'), 'should keep default .env');
+    assert.ok(cfg.secrets_patterns.includes('*.p12'), 'should keep default *.p12');
+    assert.ok(cfg.secrets_patterns.includes('*.secret'), 'should include extra *.secret');
+    assert.ok(cfg.secrets_patterns.includes('tokens.*'), 'should include extra tokens.*');
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('secrets_patterns_extra merges with custom secrets_patterns', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
+  try {
+    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
+      secrets_patterns: ['.env'],
+      secrets_patterns_extra: ['.env', '*.secret'],
+    }));
+    const { cfg } = loadConfig(tmpDir);
+    assert.deepStrictEqual(cfg.secrets_patterns, ['.env', '*.secret']);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('non-string backup_strategy is ignored', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-test-'));
+  try {
+    fs.writeFileSync(path.join(tmpDir, '.cursor-guard.json'), JSON.stringify({
+      backup_strategy: 123,
+      auto_backup_interval_seconds: 'bad',
+    }));
+    const { cfg } = loadConfig(tmpDir);
+    assert.strictEqual(cfg.backup_strategy, 'git');
+    assert.strictEqual(cfg.auto_backup_interval_seconds, 60);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+// ── filterFiles ──────────────────────────────────────────────────
+
+console.log('\nfilterFiles:');
+
+const makeFiles = names => names.map(n => ({ full: `/fake/${n}`, rel: n, name: path.basename(n) }));
+
+test('no protect/ignore returns all non-secret files', () => {
+  const files = makeFiles(['a.js', 'b.ts', '.env', 'credentials.json']);
+  const cfg = { ...DEFAULT_CONFIG };
+  const result = filterFiles(files, cfg);
+  const rels = result.map(f => f.rel);
+  assert.ok(!rels.includes('.env'));
+  assert.ok(!rels.includes('credentials.json'));
+  assert.ok(rels.includes('a.js'));
+  assert.ok(rels.includes('b.ts'));
+});
+
+test('protect narrows scope', () => {
+  const files = makeFiles(['src/a.js', 'lib/b.js', 'README.md']);
+  const cfg = { ...DEFAULT_CONFIG, protect: ['src/**'] };
+  const result = filterFiles(files, cfg);
+  assert.strictEqual(result.length, 1);
+  assert.strictEqual(result[0].rel, 'src/a.js');
+});
+
+test('ignore excludes files', () => {
+  const files = makeFiles(['src/a.js', 'src/a.test.js', 'src/b.js']);
+  const cfg = { ...DEFAULT_CONFIG, ignore: ['**/*.test.js'] };
+  const result = filterFiles(files, cfg);
+  const rels = result.map(f => f.rel);
+  assert.ok(!rels.includes('src/a.test.js'));
+  assert.ok(rels.includes('src/a.js'));
+});
+
+// ── manifestChanged ──────────────────────────────────────────────
+
+console.log('\nmanifestChanged:');
+
+test('null old manifest means changed', () => {
+  assert.strictEqual(manifestChanged(null, { 'a.js': { mtimeMs: 1, size: 100 } }), true);
+});
+
+test('identical manifests are not changed', () => {
+  const m = { 'a.js': { mtimeMs: 1, size: 100 } };
+  assert.strictEqual(manifestChanged(m, { ...m }), false);
+});
+
+test('different mtime means changed', () => {
+  const old = { 'a.js': { mtimeMs: 1, size: 100 } };
+  const nw = { 'a.js': { mtimeMs: 2, size: 100 } };
+  assert.strictEqual(manifestChanged(old, nw), true);
+});
+
+test('new file means changed', () => {
+  const old = { 'a.js': { mtimeMs: 1, size: 100 } };
+  const nw = { 'a.js': { mtimeMs: 1, size: 100 }, 'b.js': { mtimeMs: 2, size: 50 } };
+  assert.strictEqual(manifestChanged(old, nw), true);
+});
+
+// ── parseArgs ────────────────────────────────────────────────────
+
+console.log('\nparseArgs:');
+
+test('parses --key value pairs', () => {
+  const args = parseArgs(['node', 'script', '--path', '/tmp', '--interval', '30']);
+  assert.strictEqual(args.path, '/tmp');
+  assert.strictEqual(args.interval, '30');
+});
+
+test('parses boolean flags', () => {
+  const args = parseArgs(['node', 'script', '--verbose']);
+  assert.strictEqual(args.verbose, true);
+});
+
+test('empty args returns empty object', () => {
+  const args = parseArgs(['node', 'script']);
+  assert.deepStrictEqual(args, {});
+});
+
+// ── walkDir ──────────────────────────────────────────────────────
+
+console.log('\nwalkDir:');
+
+test('discovers files recursively', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-walk-'));
+  try {
+    fs.mkdirSync(path.join(tmpDir, 'sub'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'a.txt'), 'a');
+    fs.writeFileSync(path.join(tmpDir, 'sub', 'b.txt'), 'b');
+    const files = walkDir(tmpDir, tmpDir);
+    const rels = files.map(f => f.rel).sort();
+    assert.deepStrictEqual(rels, ['a.txt', 'sub/b.txt']);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test('skips .git and node_modules', () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'guard-walk-'));
+  try {
+    fs.mkdirSync(path.join(tmpDir, '.git'), { recursive: true });
+    fs.mkdirSync(path.join(tmpDir, 'node_modules'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.git', 'HEAD'), 'ref');
+    fs.writeFileSync(path.join(tmpDir, 'node_modules', 'x.js'), 'x');
+    fs.writeFileSync(path.join(tmpDir, 'real.js'), 'y');
+    const files = walkDir(tmpDir, tmpDir);
+    assert.strictEqual(files.length, 1);
+    assert.strictEqual(files[0].rel, 'real.js');
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+});
+
+// ── Summary ──────────────────────────────────────────────────────
+
+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/recovery.md

@@ -13,8 +13,7 @@ Replace `<path>` / `<file>` with real paths. Run from repository root. **Review
 ### Single file / 单文件
 
 ```powershell
-# Preserve current file state via temp index (does not touch staging area)
-# 通过临时索引保留当前文件（不影响暂存区）
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
 $guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
 $env:GIT_INDEX_FILE = $guardIdx
 git read-tree HEAD
@@ -23,14 +22,15 @@ $tree = git write-tree
 $env:GIT_INDEX_FILE = $null
 Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
 $commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore"
-git update-ref refs/guard/pre-restore $commit
-Write-Host "Pre-restore backup: $($commit.Substring(0,7))"
+git update-ref "refs/guard/pre-restore/$ts" $commit
+git update-ref refs/guard/pre-restore $commit   # alias to latest
+Write-Host "Pre-restore backup: refs/guard/pre-restore/$ts ($($commit.Substring(0,7)))"
 ```
 
 ### Entire project / 整个项目
 
 ```powershell
-# Same as above but with git add -A
+$ts = Get-Date -Format 'yyyyMMdd_HHmmss'
 $guardIdx = Join-Path (git rev-parse --git-dir) "guard-pre-restore-index"
 $env:GIT_INDEX_FILE = $guardIdx
 git read-tree HEAD
@@ -39,8 +39,9 @@ $tree = git write-tree
 $env:GIT_INDEX_FILE = $null
 Remove-Item $guardIdx -Force -ErrorAction SilentlyContinue
 $commit = git commit-tree $tree -p HEAD -m "guard: preserve current before restore"
-git update-ref refs/guard/pre-restore $commit
-Write-Host "Pre-restore backup: $($commit.Substring(0,7))"
+git update-ref "refs/guard/pre-restore/$ts" $commit
+git update-ref refs/guard/pre-restore $commit   # alias to latest
+Write-Host "Pre-restore backup: refs/guard/pre-restore/$ts ($($commit.Substring(0,7)))"
 ```
 
 ### Non-Git fallback (shadow copy) / 非 Git 备选方案
@@ -53,21 +54,40 @@ Copy-Item "<file>" "$dir/<filename>"
 Write-Host "Pre-restore shadow copy: $dir"
 ```
 
+### List all pre-restore snapshots / 列出所有恢复前快照
+
+```bash
+git for-each-ref refs/guard/pre-restore/ --sort=-creatordate \
+  --format="%(refname:short) %(creatordate:short) %(objectname:short)"
+```
+
 ### Undo a restore (recover pre-restore state) / 撤销恢复（回到恢复前的状态）
 
 ```bash
-# Restore single file to pre-restore state
-# 将单个文件恢复到恢复前的状态
+# Undo using a specific timestamped snapshot
+# 使用特定时间戳快照撤销恢复
+git restore --source=refs/guard/pre-restore/<yyyyMMdd_HHmmss> -- <file>
+
+# Undo using the latest pre-restore snapshot (alias)
+# 使用最近一次的恢复前快照撤销
 git restore --source=refs/guard/pre-restore -- <file>
 
-# Restore entire project to pre-restore state
-# 将整个项目恢复到恢复前的状态
-git restore --source=refs/guard/pre-restore -- .
+# Restore entire project / 恢复整个项目
+git restore --source=refs/guard/pre-restore/<yyyyMMdd_HHmmss> -- .
 
 # From shadow copy / 从影子拷贝恢复
 Copy-Item ".cursor-guard-backup/pre-restore-<ts>/<file>" "<original-path>"
 ```
 
+### Clean up old pre-restore refs / 清理旧的恢复前快照
+
+```bash
+# Delete all pre-restore refs (keep only the latest alias)
+# 删除所有时间戳快照（仅保留 latest alias）
+git for-each-ref refs/guard/pre-restore/ --format="%(refname)" |
+  xargs -n1 git update-ref -d
+```
+
 ---
 
 ## Inspect current state