fix(hooks): address coderabbit review — use lstatSync for symlink paths

CodeRabbit major on PR #1898: fs.statSync follows symlinks, so a dangling
protected symlink (e.g. .eslintrc.js pointing at a missing target) would
throw ENOENT and be treated as absent — letting an agent "replace" the
symlink and bypass the protection.

Swap statSync for lstatSync. lstat reports the link node itself regardless
of whether its target exists, so protected entries that happen to be
symlinks stay blocked. ENOENT handling is unchanged: only a genuinely
missing path (no link, no file, no directory) counts as absent.

Add a regression test that creates a dangling symlink at .eslintrc.js and
verifies the hook still blocks Write. Skips cleanly on platforms/sandboxes
that disallow symlink creation (EPERM/EACCES).

scripts/hooks/config-protection.js

@@ -7,12 +7,13 @@
  * the actual code. This hook steers the agent back to fixing the source.
  *
  * Exit codes:
- *   0 = allow (not a config file)
+ *   0 = allow (not a config file, or first-time creation of one)
- *   2 = block (config file modification attempted)
+ *   2 = block (existing config file modification attempted)
  */
 
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 
 const MAX_STDIN = 1024 * 1024;
@@ -58,7 +59,7 @@ const PROTECTED_FILES = new Set([
   '.stylelintrc.yml',
   '.markdownlint.json',
   '.markdownlint.yaml',
-  '.markdownlintrc',
+  '.markdownlintrc'
 ]);
 
 function parseInput(inputOrRaw) {
@@ -94,13 +95,41 @@ function run(inputOrRaw, options = {}) {
 
   const basename = path.basename(filePath);
   if (PROTECTED_FILES.has(basename)) {
+    // Allow first-time creation — there's no existing config to weaken.
+    // The hook's purpose is blocking modifications; writing a brand-new
+    // config file in a project that has none is a legitimate bootstrap
+    // path (e.g. scaffolding ESLint into a fresh repo).
+    //
+    // Fail closed on any stat error other than ENOENT. Use lstatSync so a
+    // symlink at the protected path is treated as present even if its target
+    // is missing — a dangling symlink at e.g. .eslintrc.js still represents
+    // an existing config entry that an agent should not silently replace.
+    // fs.existsSync would swallow EACCES/EPERM as false; lstatSync exposes
+    // the error code so we can treat only genuine "path not found" (ENOENT)
+    // as absent.
+    let exists = true;
+    try {
+      fs.lstatSync(filePath);
+      // lstat succeeded — something (file, dir, or symlink) exists here.
+    } catch (err) {
+      if (err && err.code === 'ENOENT') {
+        exists = false;
+      }
+      // Any other error (EACCES, EPERM, ELOOP, etc.) leaves exists=true
+      // so the guard is never silently weakened.
+    }
+
+    if (!exists) {
+      return { exitCode: 0 };
+    }
+
     return {
       exitCode: 2,
       stderr:
         `BLOCKED: Modifying ${basename} is not allowed. ` +
         'Fix the source code to satisfy linter/formatter rules instead of ' +
         'weakening the config. If this is a legitimate config change, ' +
-        'disable the config-protection hook temporarily.',
+        'disable the config-protection hook temporarily.'
     };
   }
 
@@ -125,7 +154,7 @@ process.stdin.on('data', chunk => {
 process.stdin.on('end', () => {
   const result = run(raw, {
     truncated,
-    maxStdin: Number(process.env.ECC_HOOK_INPUT_MAX_BYTES) || MAX_STDIN,
+    maxStdin: Number(process.env.ECC_HOOK_INPUT_MAX_BYTES) || MAX_STDIN
   });
 
   if (result.stderr) {

tests/hooks/config-protection.test.js

@@ -4,6 +4,7 @@
 
 const assert = require('assert');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
@@ -70,85 +71,249 @@ function runTests() {
   let passed = 0;
   let failed = 0;
 
-  if (test('blocks protected config file edits through run-with-flags', () => {
+  if (
-    const input = {
+    test('blocks protected config file edits through run-with-flags', () => {
-      tool_name: 'Write',
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
-      tool_input: {
+      try {
-        file_path: '.eslintrc.js',
+        const absPath = path.join(tmpDir, '.eslintrc.js');
-        content: 'module.exports = {};'
+        fs.writeFileSync(absPath, 'module.exports = {};');
+
+        const input = {
+          tool_name: 'Write',
+          tool_input: {
+            file_path: absPath,
+            content: 'module.exports = {};'
+          }
+        };
+
+        const result = runHook(input);
+        assert.strictEqual(result.code, 2, 'Expected protected config edit to be blocked');
+        assert.strictEqual(result.stdout, '', 'Blocked hook should not echo raw input');
+        assert.ok(result.stderr.includes('BLOCKED: Modifying .eslintrc.js is not allowed.'), `Expected block message, got: ${result.stderr}`);
+      } finally {
+        try {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        } catch {
+          // best-effort cleanup
+        }
       }
-    };
+    })
+  )
+    passed++;
+  else failed++;
 
-    const result = runHook(input);
+  if (
-    assert.strictEqual(result.code, 2, 'Expected protected config edit to be blocked');
+    test('passes through safe file edits unchanged', () => {
-    assert.strictEqual(result.stdout, '', 'Blocked hook should not echo raw input');
+      const input = {
-    assert.ok(result.stderr.includes('BLOCKED: Modifying .eslintrc.js is not allowed.'), `Expected block message, got: ${result.stderr}`);
+        tool_name: 'Write',
-  })) passed++; else failed++;
+        tool_input: {
+          file_path: 'src/index.js',
+          content: 'console.log("ok");'
+        }
+      };
 
-  if (test('passes through safe file edits unchanged', () => {
+      const rawInput = JSON.stringify(input);
-    const input = {
+      const result = runHook(input);
-      tool_name: 'Write',
+      assert.strictEqual(result.code, 0, 'Expected safe file edit to pass');
-      tool_input: {
+      assert.strictEqual(result.stdout, rawInput, 'Expected exact raw JSON passthrough');
-        file_path: 'src/index.js',
+      assert.strictEqual(result.stderr, '', 'Expected no stderr for safe edits');
-        content: 'console.log("ok");'
+    })
-      }
+  )
-    };
+    passed++;
-
+  else failed++;
-    const rawInput = JSON.stringify(input);
-    const result = runHook(input);
-    assert.strictEqual(result.code, 0, 'Expected safe file edit to pass');
-    assert.strictEqual(result.stdout, rawInput, 'Expected exact raw JSON passthrough');
-    assert.strictEqual(result.stderr, '', 'Expected no stderr for safe edits');
-  })) passed++; else failed++;
-
-  if (test('blocks truncated protected config payloads instead of failing open', () => {
-    const rawInput = JSON.stringify({
-      tool_name: 'Write',
-      tool_input: {
-        file_path: '.eslintrc.js',
-        content: 'x'.repeat(1024 * 1024 + 2048)
-      }
-    });
-
-    const result = runHook(rawInput);
-    assert.strictEqual(result.code, 2, 'Expected truncated protected payload to be blocked');
-    assert.strictEqual(result.stdout, '', 'Blocked truncated payload should not echo raw input');
-    assert.ok(result.stderr.includes('Hook input exceeded 1048576 bytes'), `Expected size warning, got: ${result.stderr}`);
-    assert.ok(result.stderr.includes('truncated payload'), `Expected truncated payload warning, got: ${result.stderr}`);
-  })) passed++; else failed++;
-
-  if (test('legacy hooks do not echo raw input when they fail without stdout', () => {
-    const pluginRoot = path.join(__dirname, '..', `tmp-runner-plugin-${Date.now()}`);
-    const scriptDir = path.join(pluginRoot, 'scripts', 'hooks');
-    const scriptPath = path.join(scriptDir, 'legacy-block.js');
-
-    try {
-      fs.mkdirSync(scriptDir, { recursive: true });
-      fs.writeFileSync(
-        scriptPath,
-        '#!/usr/bin/env node\nprocess.stderr.write("blocked by legacy hook\\n");\nprocess.exit(2);\n'
-      );
 
+  if (
+    test('blocks truncated protected config payloads instead of failing open', () => {
       const rawInput = JSON.stringify({
         tool_name: 'Write',
         tool_input: {
           file_path: '.eslintrc.js',
-          content: 'module.exports = {};'
+          content: 'x'.repeat(1024 * 1024 + 2048)
         }
       });
 
-      const result = runCustomHook(pluginRoot, 'pre:legacy-block', 'scripts/hooks/legacy-block.js', rawInput);
+      const result = runHook(rawInput);
-      assert.strictEqual(result.code, 2, 'Expected failing legacy hook exit code to propagate');
+      assert.strictEqual(result.code, 2, 'Expected truncated protected payload to be blocked');
-      assert.strictEqual(result.stdout, '', 'Expected failing legacy hook to avoid raw passthrough');
+      assert.strictEqual(result.stdout, '', 'Blocked truncated payload should not echo raw input');
-      assert.ok(result.stderr.includes('blocked by legacy hook'), `Expected legacy hook stderr, got: ${result.stderr}`);
+      assert.ok(result.stderr.includes('Hook input exceeded 1048576 bytes'), `Expected size warning, got: ${result.stderr}`);
-    } finally {
+      assert.ok(result.stderr.includes('truncated payload'), `Expected truncated payload warning, got: ${result.stderr}`);
+    })
+  )
+    passed++;
+  else failed++;
+
+  if (
+    test('allows first-time creation of a protected config file', () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
       try {
-        fs.rmSync(pluginRoot, { recursive: true, force: true });
+        const absPath = path.join(tmpDir, 'eslint.config.mjs');
-      } catch {
+        const input = {
-        // best-effort cleanup
+          tool_name: 'Write',
+          tool_input: {
+            file_path: absPath,
+            content: 'export default [];'
+          }
+        };
+
+        const rawInput = JSON.stringify(input);
+        const result = runHook(input);
+        assert.strictEqual(result.code, 0, `Expected exit 0 for first-time creation, got ${result.code}; stderr: ${result.stderr}`);
+        assert.strictEqual(result.stdout, rawInput, 'Expected raw passthrough when creation is allowed');
+        assert.strictEqual(result.stderr, '', `Expected no stderr for first-time creation, got: ${result.stderr}`);
+      } finally {
+        try {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        } catch {
+          // best-effort cleanup
+        }
       }
-    }
+    })
-  })) passed++; else failed++;
+  )
+    passed++;
+  else failed++;
+
+  if (
+    test('allows first-time creation when the parent directory does not exist yet', () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
+      try {
+        // Path under a non-existent subdirectory — statSync returns ENOENT
+        // on the final segment, which should be treated as "does not exist"
+        // and allow the write. (Agent or CLI is expected to create parents
+        // during the Write itself; this hook does not need to.)
+        const absPath = path.join(tmpDir, 'no-such-parent', '.prettierrc');
+        const input = {
+          tool_name: 'Write',
+          tool_input: {
+            file_path: absPath,
+            content: '{}'
+          }
+        };
+
+        const rawInput = JSON.stringify(input);
+        const result = runHook(input);
+        assert.strictEqual(result.code, 0, `Expected exit 0 for ENOENT path, got ${result.code}; stderr: ${result.stderr}`);
+        assert.strictEqual(result.stdout, rawInput, 'Expected raw passthrough when path does not exist');
+      } finally {
+        try {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        } catch {
+          // best-effort cleanup
+        }
+      }
+    })
+  )
+    passed++;
+  else failed++;
+
+  if (
+    test('blocks protected paths that exist as a dangling symlink', () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
+      try {
+        const missingTarget = path.join(tmpDir, 'nowhere.js');
+        const linkPath = path.join(tmpDir, '.eslintrc.js');
+        try {
+          fs.symlinkSync(missingTarget, linkPath);
+        } catch (err) {
+          // Windows without Developer Mode or certain sandboxes disallow
+          // symlinks. Skip cleanly rather than fail the suite.
+          if (err.code === 'EPERM' || err.code === 'EACCES') {
+            console.log('    (skipped: symlink creation not permitted here)');
+            return;
+          }
+          throw err;
+        }
+
+        const input = {
+          tool_name: 'Write',
+          tool_input: {
+            file_path: linkPath,
+            content: 'module.exports = {};'
+          }
+        };
+
+        const result = runHook(input);
+        assert.strictEqual(result.code, 2, `Expected exit 2 for dangling symlink, got ${result.code}; stderr: ${result.stderr}`);
+        assert.strictEqual(result.stdout, '', 'Blocked hook should not echo raw input');
+        assert.ok(
+          result.stderr.includes('BLOCKED: Modifying .eslintrc.js is not allowed.'),
+          `Expected block message, got: ${result.stderr}`
+        );
+      } finally {
+        try {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        } catch {
+          // best-effort cleanup
+        }
+      }
+    })
+  )
+    passed++;
+  else failed++;
+
+  if (
+    test('still blocks writes to an existing protected config file', () => {
+      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
+      try {
+        const absPath = path.join(tmpDir, '.eslintrc.js');
+        fs.writeFileSync(absPath, 'module.exports = { rules: {} };');
+
+        const input = {
+          tool_name: 'Edit',
+          tool_input: {
+            file_path: absPath,
+            content: 'module.exports = { rules: { "no-console": "off" } };'
+          }
+        };
+
+        const result = runHook(input);
+        assert.strictEqual(result.code, 2, 'Expected exit 2 when modifying an existing protected config');
+        assert.strictEqual(result.stdout, '', 'Blocked hook should not echo raw input');
+        assert.ok(result.stderr.includes('BLOCKED: Modifying .eslintrc.js is not allowed.'), `Expected block message, got: ${result.stderr}`);
+      } finally {
+        try {
+          fs.rmSync(tmpDir, { recursive: true, force: true });
+        } catch {
+          // best-effort cleanup
+        }
+      }
+    })
+  )
+    passed++;
+  else failed++;
+
+  if (
+    test('legacy hooks do not echo raw input when they fail without stdout', () => {
+      const pluginRoot = path.join(__dirname, '..', `tmp-runner-plugin-${Date.now()}`);
+      const scriptDir = path.join(pluginRoot, 'scripts', 'hooks');
+      const scriptPath = path.join(scriptDir, 'legacy-block.js');
+
+      try {
+        fs.mkdirSync(scriptDir, { recursive: true });
+        fs.writeFileSync(scriptPath, '#!/usr/bin/env node\nprocess.stderr.write("blocked by legacy hook\\n");\nprocess.exit(2);\n');
+
+        const rawInput = JSON.stringify({
+          tool_name: 'Write',
+          tool_input: {
+            file_path: '.eslintrc.js',
+            content: 'module.exports = {};'
+          }
+        });
+
+        const result = runCustomHook(pluginRoot, 'pre:legacy-block', 'scripts/hooks/legacy-block.js', rawInput);
+        assert.strictEqual(result.code, 2, 'Expected failing legacy hook exit code to propagate');
+        assert.strictEqual(result.stdout, '', 'Expected failing legacy hook to avoid raw passthrough');
+        assert.ok(result.stderr.includes('blocked by legacy hook'), `Expected legacy hook stderr, got: ${result.stderr}`);
+      } finally {
+        try {
+          fs.rmSync(pluginRoot, { recursive: true, force: true });
+        } catch {
+          // best-effort cleanup
+        }
+      }
+    })
+  )
+    passed++;
+  else failed++;
 
   console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
   process.exit(failed > 0 ? 1 : 0);