@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/gates/hooks/gates/protected-paths/index.mjs

@@ -1,147 +1,144 @@
-// protected-paths — denies writes and mutating shell commands that target a path
-// containing one of the project's protected fragments (.env, lockfiles, the harness
-// itself). Migrated from ~/.claude/hooks/guard-protected-paths.mjs: that guard protected
-// hardcoded "code directories" (src, tests) to force delegation through a Leader role.
-// This gate keeps only the path-protection mechanism — sensitive files no write should
-// ever touch — and drops the Leader-role/delegation policy, which is a different concern.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   protectedPaths     path fragments (case-insensitive) that no write or mutating
-//                       command may target. Replaces the built-in list wholesale.
-//   mutatingCommands    shell command names treated as mutating, so a merely-reading
-//                       command that mentions a protected path (echo, cat, grep) is
-//                       never denied. Replaces the built-in list wholesale.
-// The defaults live here, in the source, so a project reads them and knows exactly what
-// its override replaces.
-
-import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'protected-paths';
-const CONFIG_KEY = 'blockWritesToProtectedPaths';
-
-const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
-const SHELL_TOOLS = new Set(TOOL_GROUPS.shell);
-
-const DEFAULT_PROTECTED_PATHS = [
-  '.env',
-  'package-lock.json',
-  'yarn.lock',
-  'pnpm-lock.yaml',
-  'hooks/',
-];
-
-const DEFAULT_MUTATING_COMMANDS = [
-  'touch',
-  'rm',
-  'cp',
-  'mv',
-  'sed\\s+-i',
-  'tee',
-  'install',
-  'chmod',
-  'chown',
-  'truncate',
-];
-
-function escapeRegExp(fragment) {
-  return fragment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/** The path a write tool targets, across the field names different tools use. */
-function writeTargetFrom(toolInput) {
-  return String(
-    toolInput.TargetFile ??
-      toolInput.target_file ??
-      toolInput.file_path ??
-      toolInput.path ??
-      '',
-  );
-}
-
-function isProtectedPath(path, protectedPaths) {
-  const normalized = path.toLowerCase();
-  return protectedPaths.some((fragment) =>
-    normalized.includes(fragment.toLowerCase()),
-  );
-}
-
-function buildCommandPatterns(protectedPaths, mutatingCommands) {
-  const pathAlternation = protectedPaths.map(escapeRegExp).join('|');
-  const mutatingAlternation = mutatingCommands.join('|');
-  const wordBoundary = String.raw`\b`;
-  const redirectPrefix = String.raw`>>?\s*\S*`;
-  return {
-    mutatingCommand: new RegExp(
-      `${wordBoundary}(${mutatingAlternation})${wordBoundary}`,
-      'i',
-    ),
-    protectedTarget: new RegExp(`(${pathAlternation})`, 'i'),
-    redirectToProtected: new RegExp(
-      `${redirectPrefix}(${pathAlternation})`,
-      'i',
-    ),
-  };
-}
-
-/** The write-tool branch: deny when the target path matches a protected fragment. */
-function checkWrite(toolInput, protectedPaths) {
-  const target = writeTargetFrom(toolInput);
-  if (target && isProtectedPath(target, protectedPaths)) {
-    deny(
-      GATE_ID,
-      `Writing to '${target}' is not allowed: it matches a protected path (${protectedPaths.join(', ')}).`,
-    );
-  }
-}
-
-/** The shell-tool branch: deny a mutating command whose target matches a protected path. */
-function checkShellCommand(toolInput, protectedPaths, mutatingCommands) {
-  const command = String(toolInput.CommandLine ?? toolInput.command ?? '');
-  if (!command.trim()) return;
-
-  const { mutatingCommand, protectedTarget, redirectToProtected } =
-    buildCommandPatterns(protectedPaths, mutatingCommands);
-
-  const targetsProtected =
-    redirectToProtected.test(command) ||
-    (mutatingCommand.test(command) && protectedTarget.test(command));
-
-  if (targetsProtected) {
-    deny(
-      GATE_ID,
-      `This command targets a protected path (${protectedPaths.join(', ')}) with a mutating operation. ` +
-        'Reading (echo/cat/grep) is fine; modifying it is not.',
-    );
-  }
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      protectedPaths: DEFAULT_PROTECTED_PATHS,
-      mutatingCommands: DEFAULT_MUTATING_COMMANDS,
-    },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    const isWrite = WRITE_TOOLS.has(toolName);
-    const isShell = SHELL_TOOLS.has(toolName);
-    if (!isWrite && !isShell) return;
-
-    const protectedPaths = parameters.protectedPaths ?? [];
-    if (protectedPaths.length === 0) return;
-
-    if (isWrite) {
-      checkWrite(toolInput, protectedPaths);
-      return;
-    }
-
-    checkShellCommand(
-      toolInput,
-      protectedPaths,
-      parameters.mutatingCommands ?? [],
-    );
-  },
-);
+// protected-paths — denies writes and mutating shell commands that target a path
+// containing one of the project's protected fragments (.env, lockfiles, the harness
+// itself). Migrated from ~/.claude/hooks/guard-protected-paths.mjs: that guard protected
+// hardcoded "code directories" (src, tests) to force delegation through a Leader role.
+// This gate keeps only the path-protection mechanism — sensitive files no write should
+// ever touch — and drops the Leader-role/delegation policy, which is a different concern.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   protectedPaths     path fragments (case-insensitive) that no write or mutating
+//                       command may target. Replaces the built-in list wholesale.
+//   mutatingCommands    shell command names treated as mutating, so a merely-reading
+//                       command that mentions a protected path (echo, cat, grep) is
+//                       never denied. Replaces the built-in list wholesale.
+// The defaults live here, in the source, so a project reads them and knows exactly what
+// its override replaces.
+
+import { runGate, deny, toolInGroups, writtenPathOf } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'protected-paths';
+const CONFIG_KEY = 'blockWritesToProtectedPaths';
+
+const DEFAULT_PROTECTED_PATHS = [
+  '.env',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'hooks/',
+];
+
+const DEFAULT_MUTATING_COMMANDS = [
+  'touch',
+  'rm',
+  'cp',
+  'mv',
+  'sed\\s+-i',
+  'tee',
+  'install',
+  'chmod',
+  'chown',
+  'truncate',
+];
+
+function escapeRegExp(fragment) {
+  return fragment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Windows delivers absolute paths with backslashes ('C:\repo\hooks\gates\x.mjs'), but a
+// protected fragment like 'hooks/' is written with a forward slash. Normalizing the
+// separator before comparing means the fragment matches regardless of which OS produced
+// the path, without weakening the existing case-insensitive comparison.
+function toForwardSlashes(path) {
+  return path.replace(/\\/g, '/');
+}
+
+function isProtectedPath(path, protectedPaths) {
+  const normalized = toForwardSlashes(path).toLowerCase();
+  return protectedPaths.some((fragment) =>
+    normalized.includes(fragment.toLowerCase()),
+  );
+}
+
+function buildCommandPatterns(protectedPaths, mutatingCommands) {
+  const pathAlternation = protectedPaths.map(escapeRegExp).join('|');
+  const mutatingAlternation = mutatingCommands.join('|');
+  const wordBoundary = String.raw`\b`;
+  const redirectPrefix = String.raw`>>?\s*\S*`;
+  return {
+    mutatingCommand: new RegExp(
+      `${wordBoundary}(${mutatingAlternation})${wordBoundary}`,
+      'i',
+    ),
+    protectedTarget: new RegExp(`(${pathAlternation})`, 'i'),
+    redirectToProtected: new RegExp(
+      `${redirectPrefix}(${pathAlternation})`,
+      'i',
+    ),
+  };
+}
+
+/** The write-tool branch: deny when the target path matches a protected fragment. */
+function checkWrite(toolInput, protectedPaths) {
+  const target = writtenPathOf(toolInput);
+  if (target && isProtectedPath(target, protectedPaths)) {
+    deny(
+      GATE_ID,
+      `Writing to '${target}' is not allowed: it matches a protected path (${protectedPaths.join(', ')}).`,
+    );
+  }
+}
+
+/** The shell-tool branch: deny a mutating command whose target matches a protected path. */
+function checkShellCommand(toolInput, protectedPaths, mutatingCommands) {
+  const rawCommand = String(toolInput.CommandLine ?? toolInput.command ?? '');
+  if (!rawCommand.trim()) return;
+  // Same separator normalization as the write branch: a command embedding a Windows
+  // path ('rm C:\repo\hooks\gates\evil.mjs') must still match a 'hooks/' fragment.
+  const command = toForwardSlashes(rawCommand);
+
+  const { mutatingCommand, protectedTarget, redirectToProtected } =
+    buildCommandPatterns(protectedPaths, mutatingCommands);
+
+  const targetsProtected =
+    redirectToProtected.test(command) ||
+    (mutatingCommand.test(command) && protectedTarget.test(command));
+
+  if (targetsProtected) {
+    deny(
+      GATE_ID,
+      `This command targets a protected path (${protectedPaths.join(', ')}) with a mutating operation. ` +
+        'Reading (echo/cat/grep) is fine; modifying it is not.',
+    );
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      protectedPaths: DEFAULT_PROTECTED_PATHS,
+      mutatingCommands: DEFAULT_MUTATING_COMMANDS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const isWrite = toolInGroups(toolName, ['write']);
+    const isShell = toolInGroups(toolName, ['shell']);
+    if (!isWrite && !isShell) return;
+
+    const protectedPaths = parameters.protectedPaths ?? [];
+    if (protectedPaths.length === 0) return;
+
+    if (isWrite) {
+      checkWrite(toolInput, protectedPaths);
+      return;
+    }
+
+    checkShellCommand(
+      toolInput,
+      protectedPaths,
+      parameters.mutatingCommands ?? [],
+    );
+  },
+);

package/plugins/gates/hooks/gates/protected-paths/protected-paths.edge.test.mjs

@@ -0,0 +1,126 @@
+// Edge-case audit for protected-paths: bypasses and false positives.
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const GATE = join(dirname(fileURLToPath(import.meta.url)), 'index.mjs');
+
+function runGate(payload, { config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'protected-paths-edge-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function write(filePath) {
+  return { tool_name: 'Write', tool_input: { file_path: filePath } };
+}
+function edit(filePath) {
+  return { tool_name: 'Edit', tool_input: { file_path: filePath } };
+}
+function bash(command) {
+  return { tool_name: 'Bash', tool_input: { command } };
+}
+function mcpTool(name, input) {
+  return { tool_name: name, tool_input: input };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+// ── FIXED: toolInGroups classifies an MCP tool by its action segment, so an MCP write
+// tool is now recognized regardless of its exact name.
+test('FIXED: mcp filesystem write_file targeting .env is now recognized as a write tool', () => {
+  const result = runGate(
+    mcpTool('mcp__filesystem__write_file', { path: '/repo/.env', content: 'X=1' }),
+  );
+  assert.ok(isDeny(result));
+});
+
+test('FIXED: mcp filesystem edit_file targeting package-lock.json is now recognized', () => {
+  const result = runGate(
+    mcpTool('mcp__filesystem__edit_file', {
+      file_path: '/repo/package-lock.json',
+      diff: '...',
+    }),
+  );
+  assert.ok(isDeny(result));
+});
+
+// ── FIXED: an mcp shell-equivalent tool with a mutating command against .env is now
+// recognized too, via toolInGroups' shell signal.
+test('FIXED: mcp shell-equivalent tool removing .env is now recognized as a shell tool', () => {
+  const result = runGate(mcpTool('mcp__shell__run', { command: 'rm .env' }));
+  assert.ok(isDeny(result));
+});
+
+// ── BUG candidate: chained command where the mutating verb and the protected path are
+// split across a chain, e.g. `echo hi && rm .env` — mutatingCommand.test and
+// protectedTarget.test both run against the FULL command string independently (not
+// requiring adjacency), so this should still be caught. Confirm.
+test('OK: mutating command chained after a harmless one is still caught', () => {
+  assert.ok(isDeny(runGate(bash('echo hi && rm .env'))));
+});
+
+// ── BUG candidate: redirect-to-protected pattern `>>?\s*\S*(protected)` requires the
+// protected fragment to appear immediately after the redirect target token (no space
+// before it beyond \s*, and \S* is greedy so it consumes up to whitespace). A redirect
+// with a relative path prefix like `echo x > ./.env` should still match since '.env' is
+// a substring inside './.env'. Confirm.
+test('OK: redirect to a protected path via a relative ./ prefix is still caught', () => {
+  assert.ok(isDeny(runGate(bash('echo "X=1" > ./.env'))));
+});
+
+// ── BUG: the redirect pattern anchors on `>>?\s*\S*(protected)` — but it does not
+// require a mutating command AT ALL; a bare redirect from an allowed "reading" command
+// like `cat foo > .env` is denied correctly. But what about protected-path matches
+// inside an UNQUOTED argument to a non-mutating, non-redirecting command that merely
+// happens to reference the filename without any real risk, e.g. `node --check .env`?
+// mutatingCommand list doesn't include 'node', and there's no redirect, so
+// targetsProtected is false — correctly allowed. Confirm to make sure the "read/lint a
+// protected path" case is not a false positive.
+test('OK: a non-mutating command that only references a protected filename is allowed', () => {
+  assert.equal(runGate(bash('node --check .env')), null);
+});
+
+// ── BUG: case sensitivity / path separator on Windows. protectedTarget building lower-
+// cases the path fragment comparison for isProtectedPath (writes) via .toLowerCase(), but
+// for the SHELL branch, buildCommandPatterns compiles patterns with the 'i' flag, so case
+// should be handled there too. Confirm mixed-case doesn't bypass either branch.
+test('OK: mixed-case protected path does not bypass either the write or shell branch', () => {
+  assert.ok(isDeny(runGate(write('/repo/.ENV'))));
+  assert.ok(isDeny(runGate(bash('rm .ENV'))));
+});
+
+// ── FIXED: the write and shell branches normalize backslashes to forward slashes before
+// comparing, so a Windows-style absolute path under hooks\ now matches the 'hooks/'
+// protected fragment.
+test('FIXED: windows backslash path under hooks\\ now matches the "hooks/" protected fragment', () => {
+  const result = runGate(write('C:\\repo\\hooks\\gates\\evil.mjs'));
+  assert.ok(isDeny(result));
+});
+
+// ── BUG: sed -i is in mutatingCommands as the two-token regex source `sed\\s+-i` joined
+// into one big alternation with \b...\b around the WHOLE alternation, not each term. This
+// means the outer \b applies to the first alternative's boundary only for single-word
+// terms; for the multi-word 'sed\\s+-i' term, \b anchors immediately before 's' and after
+// the LAST alternative in the group, not after 'sed\s+-i' locally — but since it's inside
+// one non-capturing pattern (`\b(a|b|sed\s+-i|c)\b`), the trailing \b applies right after
+// whatever alternative matched, i.e. after "-i", which IS a word boundary. Confirm sed -i
+// against a protected path is still caught (not a bug) before moving on.
+test('OK: sed -i against a protected path is still caught', () => {
+  assert.ok(isDeny(runGate(bash('sed -i "s/a/b/" .env'))));
+});

package/plugins/gates/hooks/gates/recurrence-lock/index.mjs

@@ -1,64 +1,89 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'recurrence-lock';
-const CONFIG_KEY = 'blockRegisteredRecurrences';
-
-// The source guard (guard-reincidence-lock.mjs) reads pending recurrences
-// from a full tracking module (../scripts/memory/recurrences.mjs) with
-// close/decide/pending subcommands. That infrastructure belongs to another
-// project and does not exist here. This gate only reads a plain state file
-// at .ai/reincidencias.json if present, with the shape:
-//   { classes: [{ class, occurrences: [...], status }] }
-// If neither the module nor the file exists, it allows silently — there is
-// nothing to enforce without a recurrence record.
-function loadOpenRecurrences(projectRoot, thresholdAppearances) {
-  const filePath = join(projectRoot, '.ai', 'reincidencias.json');
-  if (!existsSync(filePath)) return [];
-
-  let parsed;
-  try {
-    parsed = JSON.parse(readFileSync(filePath, 'utf8'));
-  } catch {
-    return [];
-  }
-
-  const classes = Array.isArray(parsed?.classes) ? parsed.classes : [];
-  return classes.filter((entry) => {
-    const occurrenceCount = Array.isArray(entry?.occurrences)
-      ? entry.occurrences.length
-      : 0;
-    const status = String(entry?.status ?? '').toLowerCase();
-    const isClosed = status === 'closed' || status === 'cerrada';
-    return occurrenceCount >= thresholdAppearances && !isClosed;
-  });
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: true,
-    defaultParams: {
-      thresholdAppearances: 2,
-    },
-  },
-  ({ toolName, parameters }) => {
-    const isExecution = TOOL_GROUPS.execution.includes(toolName);
-    const isDelegation = TOOL_GROUPS.delegation.includes(toolName);
-    if (!isExecution && !isDelegation) return;
-
-    const openRecurrences = loadOpenRecurrences(
-      process.cwd(),
-      parameters.thresholdAppearances,
-    );
-    if (openRecurrences.length === 0) return;
-
-    const names = openRecurrences.map((entry) => entry.class).join(', ');
-    deny(
-      GATE_ID,
-      `Registered recurring issue classes are still open and at/above threshold: ${names}. Resolve or close them before proceeding.`,
-    );
-  },
-);
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'recurrence-lock';
+const CONFIG_KEY = 'blockRegisteredRecurrences';
+
+/**
+ * De-duplicates occurrences before counting them against the threshold. An occurrence is
+ * identified by its `id`/`hash` field when present (the intended identity for a logged
+ * occurrence); a bare-scalar entry (number/string, as in the plain fixture shape used by
+ * tests) is deduplicated by its own value instead, since it carries no other identity.
+ * Without this, the same occurrence logged twice (a race or a bug in the writer) inflates
+ * the count and trips the lock as if two distinct occurrences had happened.
+ */
+function dedupOccurrences(occurrences) {
+  const seen = new Set();
+  const deduped = [];
+  for (const occurrence of occurrences) {
+    const identity =
+      occurrence && typeof occurrence === 'object'
+        ? String(occurrence.id ?? occurrence.hash ?? JSON.stringify(occurrence))
+        : String(occurrence);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    deduped.push(occurrence);
+  }
+  return deduped;
+}
+
+// The source guard (guard-reincidence-lock.mjs) reads pending recurrences
+// from a full tracking module (../scripts/memory/recurrences.mjs) with
+// close/decide/pending subcommands. That infrastructure belongs to another
+// project and does not exist here. This gate only reads a plain state file
+// at .ai/reincidencias.json if present, with the shape:
+//   { classes: [{ class, occurrences: [...], status }] }
+// If neither the module nor the file exists, it allows silently — there is
+// nothing to enforce without a recurrence record.
+function loadOpenRecurrences(projectRoot, thresholdAppearances) {
+  const filePath = join(projectRoot, '.ai', 'reincidencias.json');
+  if (!existsSync(filePath)) return [];
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return [];
+  }
+
+  const classes = Array.isArray(parsed?.classes) ? parsed.classes : [];
+  return classes.filter((entry) => {
+    const occurrences = Array.isArray(entry?.occurrences)
+      ? dedupOccurrences(entry.occurrences)
+      : [];
+    const occurrenceCount = occurrences.length;
+    // Trim before lowercasing so a padded status ("Closed ", "cerrada\n") is recognized —
+    // a status compared without trimming left a validly-closed (but padded) recurrence
+    // stuck as still-open, blocking unrelated work indefinitely.
+    const status = String(entry?.status ?? '').trim().toLowerCase();
+    const isClosed = status === 'closed' || status === 'cerrada';
+    return occurrenceCount >= thresholdAppearances && !isClosed;
+  });
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      thresholdAppearances: 2,
+    },
+  },
+  ({ toolName, parameters }) => {
+    if (!toolInGroups(toolName, ['execution', 'delegation'])) return;
+
+    const openRecurrences = loadOpenRecurrences(
+      process.cwd(),
+      parameters.thresholdAppearances,
+    );
+    if (openRecurrences.length === 0) return;
+
+    const names = openRecurrences.map((entry) => entry.class).join(', ');
+    deny(
+      GATE_ID,
+      `Registered recurring issue classes are still open and at/above threshold: ${names}. Resolve or close them before proceeding.`,
+    );
+  },
+);