@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/gates/hooks/gates/recurrence-lock/recurrence-lock.edge.test.mjs

@@ -0,0 +1,102 @@
+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 newProject({ config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'recurrence-lock-edge-'));
+  mkdirSync(join(project, '.git'));
+  mkdirSync(join(project, '.ai'), { recursive: true });
+  if (config) {
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  return project;
+}
+
+function runGateIn(project, payload) {
+  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 exec() {
+  return { tool_name: 'Bash', tool_input: { command: 'echo hi' } };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+// EDGE CASE (BUG): mcp__ide__executeCode is part of TOOL_GROUPS.execution (lib/hook-io.mjs
+// line 37-46) and this gate checks TOOL_GROUPS.execution.includes(toolName), so this should
+// actually be covered. Verify it is (defensive check — not assumed).
+test('OK: mcp__ide__executeCode is covered because it is in TOOL_GROUPS.execution', () => {
+  const project = newProject();
+  writeFileSync(
+    join(project, '.ai', 'reincidencias.json'),
+    JSON.stringify({ classes: [{ class: 'x', occurrences: [1, 2], status: 'open' }] }),
+  );
+  assert.ok(isDeny(runGateIn(project, { tool_name: 'mcp__ide__executeCode', tool_input: {} })));
+});
+
+// FIXED (was BUG): status is now trimmed before lowercasing, so a padded/capitalized status
+// like "Closed " (trailing space) is correctly recognized as closed and no longer sticks the
+// lock on a legitimately-resolved recurrence. A genuine typo like "closd" must still NOT be
+// recognized (no typo-tolerance) and stays open-blocking, as expected.
+test('FIXED: a status of "Closed " (capitalized, trailing space) is trimmed and recognized as closed, unblocking the recurrence', () => {
+  const project = newProject();
+  writeFileSync(
+    join(project, '.ai', 'reincidencias.json'),
+    JSON.stringify({ classes: [{ class: 'x', occurrences: [1, 2], status: 'Closed ' }] }),
+  );
+  assert.equal(runGateIn(project, exec()), null, 'a padded/capitalized "Closed " status must be trimmed and recognized as closed, allowing the tool call through');
+});
+
+test('OK: a genuine typo status like "closd" is NOT recognized as closed and stays open-blocking (no typo-tolerance)', () => {
+  const project = newProject();
+  writeFileSync(
+    join(project, '.ai', 'reincidencias.json'),
+    JSON.stringify({ classes: [{ class: 'x', occurrences: [1, 2], status: 'closd' }] }),
+  );
+  assert.ok(isDeny(runGateIn(project, exec())), 'a typo status must not be silently treated as closed');
+});
+
+// FIXED (was BUG): occurrences are now deduplicated (by id/hash, or by value for bare
+// scalars) before counting against the threshold. `occurrences: [1, 1]` is the same
+// occurrence logged twice (e.g. by a race or a bug in the writer) and must no longer count
+// as two distinct occurrences.
+test('FIXED: duplicate identical entries in occurrences[] are deduplicated before counting, so [1, 1] does not reach a threshold of 2', () => {
+  const project = newProject();
+  writeFileSync(
+    join(project, '.ai', 'reincidencias.json'),
+    JSON.stringify({ classes: [{ class: 'dup', occurrences: [1, 1], status: 'open' }] }),
+  );
+  assert.equal(runGateIn(project, exec()), null, 'duplicate occurrence entries must be deduplicated before comparing against thresholdAppearances');
+});
+
+// OK: genuinely distinct occurrences (even with the same shape) must still count normally —
+// dedup must not under-count real, distinct recurrences.
+test('OK: distinct occurrence entries (identified by id) still count toward the threshold normally', () => {
+  const project = newProject();
+  writeFileSync(
+    join(project, '.ai', 'reincidencias.json'),
+    JSON.stringify({
+      classes: [
+        {
+          class: 'distinct',
+          occurrences: [{ id: 'a' }, { id: 'b' }],
+          status: 'open',
+        },
+      ],
+    }),
+  );
+  assert.ok(isDeny(runGateIn(project, exec())), 'two genuinely distinct occurrences (different ids) must still trip the threshold');
+});

package/plugins/gates/hooks/gates/reuse-before-build/edge.edge.test.mjs

@@ -0,0 +1,94 @@
+// Edge-case probes for reuse-before-build. Previously: (1) TOOL_FOLDERS matching was a
+// bare substring test on the normalized path, so a legitimate folder like
+// "src/mytools/thing.mjs" was misclassified as a tool build (false positive) because
+// it contains the substring "tools/"; (2) checkDelegation read the prompt only from
+// toolInput.prompt/description, so a delegation using another field name (e.g. `task`)
+// was invisible; (3) an MCP-style write tool name (not in the old TOOL_GROUPS.write
+// Set) bypassed the gate entirely. All three are now fixed: isExecutableToolPath
+// compares whole path SEGMENTS (not substrings), delegationPromptOf() reads
+// task/instructions/message/input too, and toolInGroups() classifies any mcp__* tool
+// by its action segment so an unrecognized MCP write name is still caught.
+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(), 'reuse-before-build-edge-'));
+  mkdirSync(join(project, '.git'));
+  mkdirSync(join(project, '.ai'));
+  const effectiveConfig = config ?? {
+    gates: { requireReuseCheckBeforeBuilding: true },
+  };
+  writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(effectiveConfig));
+  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 isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+test('FIXED: a legitimate "mytools/" folder is no longer misclassified as a tool build', () => {
+  const payload = {
+    tool_name: 'Write',
+    tool_input: { file_path: 'src/mytools/thing.mjs', content: 'export function thing(){}' },
+  };
+  assert.equal(
+    isDeny(runGate(payload)),
+    false,
+    'isExecutableToolPath must compare whole path segments, not substrings: "mytools" ' +
+      'is not the segment "tools"',
+  );
+});
+
+test('FIXED: a real "tools/" folder is still caught (control for the segment fix)', () => {
+  const payload = {
+    tool_name: 'Write',
+    tool_input: { file_path: 'tools/thing.mjs', content: 'export function thing(){}' },
+  };
+  assert.ok(
+    isDeny(runGate(payload)),
+    'a genuine tools/ segment must still trigger the gate',
+  );
+});
+
+test('FIXED: an MCP-style write tool name is no longer invisible to the gate', () => {
+  const payload = {
+    tool_name: 'mcp__filesystem__write_file',
+    tool_input: { file_path: 'scripts/new-tool.mjs', content: 'export function parse(){}' },
+  };
+  assert.ok(
+    isDeny(runGate(payload)),
+    'toolInGroups must classify an MCP write tool by its action segment (write_file)',
+  );
+});
+
+test('FIXED: a delegation prompt carried in `task` (not prompt/description) is now checked', () => {
+  const payload = {
+    tool_name: 'Agent',
+    tool_input: { task: 'Please write a new script that parses CSV files.' },
+  };
+  assert.ok(
+    isDeny(runGate(payload)),
+    'delegationPromptOf must read the `task` field',
+  );
+});
+
+test('OK: the equivalent Write-tool payload IS caught (control)', () => {
+  const payload = {
+    tool_name: 'Write',
+    tool_input: { file_path: 'scripts/new-tool.mjs', content: 'export function parse(){}' },
+  };
+  assert.ok(isDeny(runGate(payload)), 'control failed');
+});

package/plugins/gates/hooks/gates/reuse-before-build/index.mjs

@@ -1,150 +1,159 @@
-// reuse-before-build — do not reinvent the wheel. Before building a new script, gate,
-// verifier or generic helper, consult the per-project tool map: a record of what already
-// solves a given need, local first, cloud second. This gate is the deterministic half —
-// it consults the map and objects when a build is starting without evidence of a check.
-// It never reaches the network: the cloud search (npm, marketplaces) is done by the
-// assistant or the `claude-gates tool-map` CLI, so the hook stays self-contained.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   toolMapFile   path to the per-project tool map, relative to the project root.
-//                 Default .ai/tool-map.json.
-//
-// ── How it decides (deterministic, no judgment) ─────────────────────────────────────
-// A write that creates an executable tool (by extension) inside a tools folder, or a
-// delegation prompt that asks to build one, must carry evidence that the wheel was
-// checked: either an audit phrase in the text, or the need already recorded in the tool
-// map. Absent both, the gate blocks with an actionable message — consult the map, then
-// (if truly absent) search local→cloud and record the result with the CLI.
-
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, extname, join } from 'node:path';
-import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'reuse-before-build';
-const CONFIG_KEY = 'requireReuseCheckBeforeBuilding';
-
-const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
-const DELEGATION_TOOLS = new Set(TOOL_GROUPS.delegation);
-
-const DEFAULT_TOOL_MAP_FILE = join('.ai', 'tool-map.json');
-const EXECUTABLE_EXTENSIONS = new Set([
-  '.js',
-  '.mjs',
-  '.cjs',
-  '.ts',
-  '.py',
-  '.sh',
-  '.ps1',
-]);
-const TOOL_FOLDERS = ['scripts/', 'hooks/', 'tools/', 'gates/'];
-// A map word must be this long to count as a real signal (skip "the", "csv" is 3 but rare).
-const MIN_SIGNIFICANT_WORD_LENGTH = 4;
-
-// A verb of creation next to a tool noun. Deliberately narrow: "write a report" or
-// "create a folder" do not match because the noun is not one of these.
-const BUILD_INTENT_PATTERN =
-  /\b(write|create|build|implement|add)\s+(a |the )?(new )?(script|verifier|gate|hook|linter|checker|tool)\b/i;
-// Evidence the wheel was already checked: any phrase stating the audit result.
-const AUDIT_DONE_PATTERN =
-  /(already exists|no existing tool|there is no plugin|audited|checked whether|nothing does this|justification:)/i;
-
-function projectRootOf(startDirectory) {
-  let current = startDirectory;
-  while (true) {
-    if (existsSync(join(current, '.git'))) return current;
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-/**
- * Whether the tool map already records a need matching the given text. The map is a JSON
- * blob; a cheap lowercased contains-check over the significant words of the build target
- * is enough — the gate does not parse the map's shape, so the CLI is free to evolve it.
- * A word of 4+ chars found in the map counts as "this need is already tracked".
- */
-function needRecordedInMap(startDirectory, toolMapFile, targetText) {
-  const root = projectRootOf(startDirectory);
-  if (!root) return false;
-  const path = join(root, toolMapFile);
-  if (!existsSync(path)) return false;
-  let map;
-  try {
-    map = readFileSync(path, 'utf8').toLowerCase();
-  } catch {
-    return false;
-  }
-  const words = targetText
-    .toLowerCase()
-    .split(/[^a-z0-9]+/)
-    .filter((word) => word.length >= MIN_SIGNIFICANT_WORD_LENGTH);
-  return words.some((word) => map.includes(word));
-}
-
-function isExecutableToolPath(filePath) {
-  const inToolFolder = TOOL_FOLDERS.some((folder) =>
-    filePath.replace(/\\/g, '/').includes(folder),
-  );
-  return (
-    inToolFolder && EXECUTABLE_EXTENSIONS.has(extname(filePath).toLowerCase())
-  );
-}
-
-const DENY_MESSAGE =
-  'Do not reinvent the wheel. Before building this, consult the project tool map and ' +
-  'confirm nothing already covers it, auditing in this order: (1) LOCAL — the repo and ' +
-  'installed deps (search by name and usage, read the manifest); (2) CONTEXT7 — resolve ' +
-  'the candidate library and read its docs to confirm whether it truly covers the need; ' +
-  '(3) WEB — search npm and plugin marketplaces for a maintained package. If it is ' +
-  'genuinely absent, record the finding (e.g. `claude-gates tool-map add`) and state the ' +
-  'audit in the text, so the exploration is not repeated next time.';
-
-/** A build is allowed when its text declares an audit or the need is already in the map. */
-function buildIsCleared(text, cwd, toolMapFile) {
-  return (
-    AUDIT_DONE_PATTERN.test(text) || needRecordedInMap(cwd, toolMapFile, text)
-  );
-}
-
-/** Delegation: block a build-a-tool prompt that is not cleared. */
-function checkDelegation(toolInput, cwd, toolMapFile) {
-  const prompt = String(toolInput.prompt ?? toolInput.description ?? '');
-  if (!BUILD_INTENT_PATTERN.test(prompt)) return;
-  if (buildIsCleared(prompt, cwd, toolMapFile)) return;
-  deny(GATE_ID, DENY_MESSAGE);
-}
-
-/** Write: block a new executable tool that is not cleared by its content or the map. */
-function checkWrite(toolInput, cwd, toolMapFile) {
-  const rawPath = String(
-    toolInput.file_path ?? toolInput.target_file ?? toolInput.path ?? '',
-  );
-  const filePath = rawPath.replace(/\\/g, '/');
-  if (!isExecutableToolPath(filePath)) return;
-  // Editing an EXISTING file is not building a new tool — only creation triggers the audit.
-  // A file already on disk is an edit, so it is allowed (lets the gates maintain themselves).
-  if (rawPath && existsSync(rawPath)) return;
-  const content = String(toolInput.content ?? toolInput.CodeContent ?? '');
-  if (AUDIT_DONE_PATTERN.test(content)) return;
-  if (needRecordedInMap(cwd, toolMapFile, filePath)) return;
-  deny(GATE_ID, DENY_MESSAGE);
-}
-
-runGate(
-  {
-    id: GATE_ID,
-    configKey: CONFIG_KEY,
-    enabledByDefault: false,
-    defaultParams: { toolMapFile: DEFAULT_TOOL_MAP_FILE },
-  },
-  ({ toolName, toolInput, parameters }) => {
-    const toolMapFile = parameters.toolMapFile ?? DEFAULT_TOOL_MAP_FILE;
-    const cwd = process.cwd();
-    if (DELEGATION_TOOLS.has(toolName)) {
-      checkDelegation(toolInput, cwd, toolMapFile);
-    } else if (WRITE_TOOLS.has(toolName)) {
-      checkWrite(toolInput, cwd, toolMapFile);
-    }
-  },
-);
+// reuse-before-build — do not reinvent the wheel. Before building a new script, gate,
+// verifier or generic helper, consult the per-project tool map: a record of what already
+// solves a given need, local first, cloud second. This gate is the deterministic half —
+// it consults the map and objects when a build is starting without evidence of a check.
+// It never reaches the network: the cloud search (npm, marketplaces) is done by the
+// assistant or the `claude-gates tool-map` CLI, so the hook stays self-contained.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   toolMapFile   path to the per-project tool map, relative to the project root.
+//                 Default .ai/tool-map.json.
+//
+// ── How it decides (deterministic, no judgment) ─────────────────────────────────────
+// A write that creates an executable tool (by extension) inside a tools folder, or a
+// delegation prompt that asks to build one, must carry evidence that the wheel was
+// checked: either an audit phrase in the text, or the need already recorded in the tool
+// map. Absent both, the gate blocks with an actionable message — consult the map, then
+// (if truly absent) search local→cloud and record the result with the CLI.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import {
+  runGate,
+  deny,
+  toolInGroups,
+  writtenContentOf,
+  writtenPathOf,
+  delegationPromptOf,
+} from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'reuse-before-build';
+const CONFIG_KEY = 'requireReuseCheckBeforeBuilding';
+
+const DEFAULT_TOOL_MAP_FILE = join('.ai', 'tool-map.json');
+const EXECUTABLE_EXTENSIONS = new Set([
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.py',
+  '.sh',
+  '.ps1',
+]);
+const TOOL_FOLDERS = ['scripts/', 'hooks/', 'tools/', 'gates/'];
+// A map word must be this long to count as a real signal (skip "the", "csv" is 3 but rare).
+const MIN_SIGNIFICANT_WORD_LENGTH = 4;
+
+// A verb of creation next to a tool noun. Deliberately narrow: "write a report" or
+// "create a folder" do not match because the noun is not one of these.
+const BUILD_INTENT_PATTERN =
+  /\b(write|create|build|implement|add)\s+(a |the )?(new )?(script|verifier|gate|hook|linter|checker|tool)\b/i;
+// Evidence the wheel was already checked: any phrase stating the audit result.
+const AUDIT_DONE_PATTERN =
+  /(already exists|no existing tool|there is no plugin|audited|checked whether|nothing does this|justification:)/i;
+
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (existsSync(join(current, '.git'))) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * Whether the tool map already records a need matching the given text. The map is a JSON
+ * blob; a cheap lowercased contains-check over the significant words of the build target
+ * is enough — the gate does not parse the map's shape, so the CLI is free to evolve it.
+ * A word of 4+ chars found in the map counts as "this need is already tracked".
+ */
+function needRecordedInMap(startDirectory, toolMapFile, targetText) {
+  const root = projectRootOf(startDirectory);
+  if (!root) return false;
+  const path = join(root, toolMapFile);
+  if (!existsSync(path)) return false;
+  let map;
+  try {
+    map = readFileSync(path, 'utf8').toLowerCase();
+  } catch {
+    return false;
+  }
+  const words = targetText
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((word) => word.length >= MIN_SIGNIFICANT_WORD_LENGTH);
+  return words.some((word) => map.includes(word));
+}
+
+/** Whether the path has a real path SEGMENT equal to one of the tool-folder names
+ * (e.g. `tools`), not merely a substring match -- `src/mytools/thing.mjs` contains the
+ * substring "tools/" but its actual segments are `src`, `mytools`, `thing.mjs`, none of
+ * which is `tools`. Splitting on the separator and comparing whole segments closes that
+ * false positive without allowing a matching false negative. */
+function isExecutableToolPath(filePath) {
+  const segments = filePath.replace(/\\/g, '/').split('/');
+  const toolFolderNames = TOOL_FOLDERS.map((folder) => folder.replace(/\/$/, ''));
+  const inToolFolder = segments.some((segment) =>
+    toolFolderNames.includes(segment),
+  );
+  return (
+    inToolFolder && EXECUTABLE_EXTENSIONS.has(extname(filePath).toLowerCase())
+  );
+}
+
+const DENY_MESSAGE =
+  'Do not reinvent the wheel. Before building this, consult the project tool map and ' +
+  'confirm nothing already covers it, auditing in this order: (1) LOCAL — the repo and ' +
+  'installed deps (search by name and usage, read the manifest); (2) CONTEXT7 — resolve ' +
+  'the candidate library and read its docs to confirm whether it truly covers the need; ' +
+  '(3) WEB — search npm and plugin marketplaces for a maintained package. If it is ' +
+  'genuinely absent, record the finding (e.g. `claude-gates tool-map add`) and state the ' +
+  'audit in the text, so the exploration is not repeated next time.';
+
+/** A build is allowed when its text declares an audit or the need is already in the map. */
+function buildIsCleared(text, cwd, toolMapFile) {
+  return (
+    AUDIT_DONE_PATTERN.test(text) || needRecordedInMap(cwd, toolMapFile, text)
+  );
+}
+
+/** Delegation: block a build-a-tool prompt that is not cleared. */
+function checkDelegation(toolInput, cwd, toolMapFile) {
+  const prompt = delegationPromptOf(toolInput);
+  if (!BUILD_INTENT_PATTERN.test(prompt)) return;
+  if (buildIsCleared(prompt, cwd, toolMapFile)) return;
+  deny(GATE_ID, DENY_MESSAGE);
+}
+
+/** Write: block a new executable tool that is not cleared by its content or the map. */
+function checkWrite(toolInput, cwd, toolMapFile) {
+  const rawPath = writtenPathOf(toolInput);
+  const filePath = rawPath.replace(/\\/g, '/');
+  if (!isExecutableToolPath(filePath)) return;
+  // Editing an EXISTING file is not building a new tool — only creation triggers the audit.
+  // A file already on disk is an edit, so it is allowed (lets the gates maintain themselves).
+  if (rawPath && existsSync(rawPath)) return;
+  const content = writtenContentOf(toolInput);
+  if (AUDIT_DONE_PATTERN.test(content)) return;
+  if (needRecordedInMap(cwd, toolMapFile, filePath)) return;
+  deny(GATE_ID, DENY_MESSAGE);
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: { toolMapFile: DEFAULT_TOOL_MAP_FILE },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const toolMapFile = parameters.toolMapFile ?? DEFAULT_TOOL_MAP_FILE;
+    const cwd = process.cwd();
+    if (toolInGroups(toolName, ['delegation'])) {
+      checkDelegation(toolInput, cwd, toolMapFile);
+    } else if (toolInGroups(toolName, ['write'])) {
+      checkWrite(toolInput, cwd, toolMapFile);
+    }
+  },
+);