@devrik-tools/claude-gates 0.1.0

package/plugins/gates/hooks/gates/root-cause-first/index.mjs

@@ -0,0 +1,50 @@
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'root-cause-first';
+const CONFIG_KEY = 'requireRootCauseBeforePatch';
+
+const DEFAULT_PATCH_MARKER_PATTERNS = ['//\\s*todo:?\\s*fix\\s+later\\s+patch'];
+
+function extractContent(toolName, toolInput) {
+  if (TOOL_GROUPS.delegation.includes(toolName)) {
+    return toolInput?.prompt;
+  }
+  return toolInput?.content ?? toolInput?.new_string;
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      patchMarkerPatterns: DEFAULT_PATCH_MARKER_PATTERNS,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    const isWrite = TOOL_GROUPS.write.includes(toolName);
+    const isDelegation = TOOL_GROUPS.delegation.includes(toolName);
+    if (!isWrite && !isDelegation) return;
+
+    const content = extractContent(toolName, toolInput);
+    if (typeof content !== 'string') return;
+
+    const patterns = parameters.patchMarkerPatterns.map(
+      (source) => new RegExp(source, 'i'),
+    );
+    const matched = patterns.find((pattern) => pattern.test(content));
+    if (!matched) return;
+
+    deny(
+      GATE_ID,
+      `Content matches a patch-without-diagnosis marker (${matched.source}). Identify and fix the root cause before patching; do not defer with a "fix later" marker.`,
+    );
+  },
+);
+
+// Simplified vs. the source guard (guard-root-cause-first.mjs): the original
+// used an auxiliary lib/embedded-content-detection.mjs module to tell real
+// file content apart from a quoted example inside markdown. That module does
+// not exist in this repo, so this gate matches directly against the new
+// content/prompt. Distinguishing markdown quotes from real code is future
+// work if false positives on quoted examples become a problem.

package/plugins/gates/hooks/gates/root-cause-first/test.mjs

@@ -0,0 +1,73 @@
+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(), 'root-cause-first-'));
+  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,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function write(content) {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: '/repo/src/x.js', content },
+  };
+}
+function delegate(prompt) {
+  return { tool_name: 'Agent', tool_input: { prompt } };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+const ENABLE = { config: { gates: { requireRootCauseBeforePatch: true } } };
+
+test('denies a patch-marker comment in a write', () => {
+  assert.ok(isDeny(runGate(write('// TODO fix later patch'), ENABLE)));
+});
+
+test('denies the same marker inside a delegation prompt', () => {
+  assert.ok(
+    isDeny(runGate(delegate('add a // TODO fix later patch comment'), ENABLE)),
+  );
+});
+
+test('allows innocuous content', () => {
+  assert.equal(runGate(write('const x = 1;'), ENABLE), null);
+});
+
+test('disabled by default (registry default is false)', () => {
+  assert.equal(runGate(write('// TODO fix later patch')), null);
+});
+
+test('project patchMarkerPatterns override replaces the built-in list', () => {
+  const config = {
+    gates: {
+      requireRootCauseBeforePatch: {
+        enabled: true,
+        patchMarkerPatterns: ['hack-me-later'],
+      },
+    },
+  };
+  assert.equal(runGate(write('// TODO fix later patch'), { config }), null);
+  assert.ok(isDeny(runGate(write('// hack-me-later'), { config })));
+});

package/plugins/gates/hooks/gates/root-whitelist/index.mjs

@@ -0,0 +1,111 @@
+// root-whitelist — denies creating a new file or folder at the project's ROOT unless it
+// is on the declared whitelist. Migrated from ~/.claude/hooks/guard-root-whitelist.mjs.
+// A root grows orphaned files silently: nothing else stops a stray file from landing next
+// to package.json. Only the top level of the project is governed — anything nested is
+// this gate's business only insofar as its first path segment is the new thing at the root.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   rootFilesWhitelist    root-level file names allowed to be created. Replaces the
+//                         built-in list wholesale.
+//   rootFoldersWhitelist  root-level folder names allowed to be created. 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. A dotfile/dotfolder (.gitignore, .claude) is always allowed —
+// dotfiles are a different, well-known convention this gate does not police.
+
+import { basename, normalize, sep } from 'node:path';
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'root-whitelist';
+const CONFIG_KEY = 'blockPathsOutsideRootWhitelist';
+
+const WRITE_TOOLS = new Set(TOOL_GROUPS.write);
+
+const DEFAULT_ROOT_FILES_WHITELIST = [
+  'AGENTS.md',
+  'CLAUDE.md',
+  'README.md',
+  'LICENSE',
+  'package.json',
+  'package-lock.json',
+  'tsconfig.json',
+  'eslint.config.mjs',
+  'eslint.config.js',
+  'eslint.config.cjs',
+  '.prettierrc',
+  '.prettierrc.json',
+  '.prettierignore',
+  '.eslintignore',
+  'cspell.json',
+  '.cspell.json',
+  '.gitignore',
+  '.env',
+  '.env.example',
+];
+
+const DEFAULT_ROOT_FOLDERS_WHITELIST = [
+  'src',
+  'tests',
+  'docs',
+  'scripts',
+  'plugins',
+];
+
+/** 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 ??
+      '',
+  );
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: true,
+    defaultParams: {
+      rootFilesWhitelist: DEFAULT_ROOT_FILES_WHITELIST,
+      rootFoldersWhitelist: DEFAULT_ROOT_FOLDERS_WHITELIST,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!WRITE_TOOLS.has(toolName)) return;
+
+    const target = writeTargetFrom(toolInput);
+    if (!target) return;
+
+    const normalized = normalize(target);
+    const projectRoot = process.cwd() + sep;
+
+    // The whitelist describes the project's ROOT. A file outside the project (session
+    // scratchpad, system temp, another repo) is not at its root, and this rule does not
+    // govern it: letting it through is correct, not an exception.
+    if (!normalized.startsWith(projectRoot)) return;
+
+    const relativePath = normalized.slice(projectRoot.length);
+    const filesWhitelist = new Set(parameters.rootFilesWhitelist ?? []);
+    const foldersWhitelist = new Set(parameters.rootFoldersWhitelist ?? []);
+
+    if (!relativePath.includes(sep)) {
+      const fileName = basename(relativePath);
+      if (fileName.startsWith('.') || filesWhitelist.has(fileName)) return;
+      deny(
+        GATE_ID,
+        `'${fileName}' at the project root is not on the whitelist (${[...filesWhitelist].join(', ')}).`,
+      );
+      return;
+    }
+
+    const topDirectory = relativePath.split(sep)[0];
+    if (topDirectory.startsWith('.') || foldersWhitelist.has(topDirectory))
+      return;
+    deny(
+      GATE_ID,
+      `Folder '${topDirectory}' at the project root is not on the whitelist (${[...foldersWhitelist].join(', ')}).`,
+    );
+  },
+);

package/plugins/gates/hooks/gates/root-whitelist/test.mjs

@@ -0,0 +1,80 @@
+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');
+
+// Creates a fresh temp project (with .git so it is recognized as a root, and an optional
+// .ai/config.json) and returns its path plus a `run` function that executes the gate with
+// that project as cwd, building the write target relative to it. This keeps the file path
+// the gate inspects and the cwd it resolves against always in sync.
+function project({ config } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'root-whitelist-'));
+  mkdirSync(join(root, '.git'));
+  if (config) {
+    mkdirSync(join(root, '.ai'));
+    writeFileSync(join(root, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  return {
+    root,
+    run(payload) {
+      const out = execFileSync(process.execPath, [GATE], {
+        input: JSON.stringify(payload),
+        encoding: 'utf8',
+        cwd: root,
+        // Isolate from the user's real global config: point homedir() at the temp
+        // project so the global-config fallback finds nothing (registry default).
+        env: { ...process.env, HOME: root, USERPROFILE: root },
+      });
+      return out.trim() ? JSON.parse(out.trim()) : null;
+    },
+  };
+}
+
+function write(root, relativePath) {
+  return {
+    tool_name: 'Write',
+    tool_input: { file_path: join(root, relativePath) },
+  };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+test('denies an orphan root file and an undeclared root folder', () => {
+  const { root, run } = project();
+  assert.ok(isDeny(run(write(root, 'random-orphan.txt'))));
+  assert.ok(isDeny(run(write(root, join('random-folder', 'a.js')))));
+});
+
+test('allows a whitelisted root file, a whitelisted folder and a dotfile', () => {
+  const { root, run } = project();
+  assert.equal(run(write(root, 'package.json')), null);
+  assert.equal(run(write(root, join('src', 'index.js'))), null);
+  assert.equal(run(write(root, '.env')), null);
+});
+
+test('disabled by config: the gate does not run', () => {
+  const config = { gates: { blockPathsOutsideRootWhitelist: false } };
+  const { root, run } = project({ config });
+  assert.equal(run(write(root, 'random-orphan.txt')), null);
+});
+
+test('project rootFoldersWhitelist replaces the built-in list', () => {
+  const config = {
+    gates: {
+      blockPathsOutsideRootWhitelist: {
+        enabled: true,
+        rootFoldersWhitelist: ['app'],
+      },
+    },
+  };
+  const { root, run } = project({ config });
+  // 'src' no longer whitelisted under the override
+  assert.ok(isDeny(run(write(root, join('src', 'index.js')))));
+  assert.equal(run(write(root, join('app', 'index.js'))), null);
+});

package/plugins/gates/hooks/gates/rule-skill-autodiscovery/index.mjs

@@ -0,0 +1,99 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { runGate, deny, TOOL_GROUPS } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'rule-skill-autodiscovery';
+const CONFIG_KEY = 'autodiscoverRulesAndSkills';
+
+const DEFAULT_RULES_DIR = 'rules';
+const DEFAULT_GATE_FILE_NAMES = [
+  'gate.mjs',
+  'rules.mjs',
+  'check.mjs',
+  'verify.mjs',
+];
+
+function isGateFile(fileName, gateFileNames) {
+  return gateFileNames.includes(fileName) || fileName.endsWith('.gate.mjs');
+}
+
+function findScriptsIn(scriptsDirectory, gateFileNames) {
+  if (!existsSync(scriptsDirectory)) return [];
+  let entries;
+  try {
+    entries = readdirSync(scriptsDirectory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile())
+    .filter((entry) => /\.(mjs|js)$/.test(entry.name))
+    .filter((entry) => isGateFile(entry.name, gateFileNames))
+    .map((entry) => join(scriptsDirectory, entry.name));
+}
+
+function discoverScripts(projectRoot, rulesDirectoryName, gateFileNames) {
+  const scripts = [
+    ...findScriptsIn(join(projectRoot, rulesDirectoryName), gateFileNames),
+  ];
+
+  const skillsRoot = join(projectRoot, '.claude', 'skills');
+  if (existsSync(skillsRoot)) {
+    let skillDirectories;
+    try {
+      skillDirectories = readdirSync(skillsRoot, {
+        withFileTypes: true,
+      }).filter((entry) => entry.isDirectory());
+    } catch {
+      skillDirectories = [];
+    }
+    for (const skillDirectory of skillDirectories) {
+      scripts.push(
+        ...findScriptsIn(join(skillsRoot, skillDirectory.name), gateFileNames),
+      );
+    }
+  }
+
+  return scripts;
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      rulesDir: DEFAULT_RULES_DIR,
+      gateFileNames: DEFAULT_GATE_FILE_NAMES,
+    },
+  },
+  ({ toolName, parameters }) => {
+    const isExecution = TOOL_GROUPS.execution.includes(toolName);
+    const isDelegation = TOOL_GROUPS.delegation.includes(toolName);
+    if (!isExecution && !isDelegation) return;
+
+    const projectRoot = process.cwd();
+    const scripts = discoverScripts(
+      projectRoot,
+      parameters.rulesDir,
+      parameters.gateFileNames,
+    );
+    if (scripts.length === 0) return;
+
+    for (const script of scripts) {
+      try {
+        execFileSync(process.execPath, [script], {
+          stdio: 'ignore',
+          timeout: 5000,
+        });
+      } catch {
+        deny(
+          GATE_ID,
+          `Sub-gate failed: ${relative(projectRoot, script)}. Fix it before continuing.`,
+        );
+        return;
+      }
+    }
+  },
+);

package/plugins/gates/hooks/gates/rule-skill-autodiscovery/test.mjs

@@ -0,0 +1,78 @@
+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 runGateIn(project, payload) {
+  const out = execFileSync(process.execPath, [GATE], {
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    cwd: project,
+    // Isolate from the user's real global config: point homedir() at the temp
+    // project so the global-config fallback finds nothing (registry default).
+    env: { ...process.env, HOME: project, USERPROFILE: project },
+  });
+  return out.trim() ? JSON.parse(out.trim()) : null;
+}
+
+function newProject({ config } = {}) {
+  const project = mkdtempSync(join(tmpdir(), 'rule-skill-autodiscovery-'));
+  mkdirSync(join(project, '.git'));
+  if (config) {
+    mkdirSync(join(project, '.ai'));
+    writeFileSync(join(project, '.ai', 'config.json'), JSON.stringify(config));
+  }
+  return project;
+}
+
+function exec() {
+  return { tool_name: 'Bash', tool_input: { command: 'echo hi' } };
+}
+function isDeny(result) {
+  return result?.hookSpecificOutput?.permissionDecision === 'deny';
+}
+
+const ENABLE = { gates: { ['autodiscoverRulesAndSkills']: true } };
+
+test('denies when a discovered rule script fails', () => {
+  const project = newProject({ config: ENABLE });
+  mkdirSync(join(project, 'rules'));
+  writeFileSync(join(project, 'rules', 'gate.mjs'), 'process.exit(1);');
+  assert.ok(isDeny(runGateIn(project, exec())));
+});
+
+test('allows when discovered rule scripts succeed', () => {
+  const project = newProject({ config: ENABLE });
+  mkdirSync(join(project, 'rules'));
+  writeFileSync(join(project, 'rules', 'gate.mjs'), 'process.exit(0);');
+  assert.equal(runGateIn(project, exec()), null);
+});
+
+test('discovers gate files inside .claude/skills subfolders', () => {
+  const project = newProject({ config: ENABLE });
+  mkdirSync(join(project, '.claude', 'skills', 'my-skill'), {
+    recursive: true,
+  });
+  writeFileSync(
+    join(project, '.claude', 'skills', 'my-skill', 'check.mjs'),
+    'process.exit(1);',
+  );
+  assert.ok(isDeny(runGateIn(project, exec())));
+});
+
+test('degrades to allow when no rules dir or skills dir exists', () => {
+  const project = newProject({ config: ENABLE });
+  assert.equal(runGateIn(project, exec()), null);
+});
+
+test('disabled by default (registry default is false)', () => {
+  const project = newProject();
+  mkdirSync(join(project, 'rules'));
+  writeFileSync(join(project, 'rules', 'gate.mjs'), 'process.exit(1);');
+  assert.equal(runGateIn(project, exec()), null);
+});