@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/plugins/gates/hooks/lib/config.mjs

@@ -1,165 +1,172 @@
-// Runtime gate configuration for the hooks. Self-contained: Node built-ins only, no npm,
-// so it works when the plugin is installed on its own.
-//
-// This is the READER the gates use at runtime. The CLI (`cli/config.mjs`) is the WRITER;
-// the two never import each other. Both agree on the file: `<project root>/.ai/config.json`,
-// with `~/.claude/claude-gates/config.json` as the global fallback.
-//
-// ── Two things a project controls per gate ──────────────────────────────────────────
-//   1. enabled — is the gate on? A gate absent from config keeps the registry default.
-//   2. params  — how the gate behaves: its whitelist, its patterns, its watched paths.
-//      A param the project declares REPLACES the gate's built-in default wholesale (it
-//      does not merge). The gate ships its defaults in its own source so the user can
-//      read them and know exactly what to override.
-//
-// ── Config shape a project may write ────────────────────────────────────────────────
-//   "gates": {
-//     "blockDestructiveShellCommands": true,                  // shorthand: enabled only
-//     "blockWritesToProtectedPaths": { "enabled": true, "protectedPaths": ["...","..."] }
-//   }
-// A bare boolean is the enabled-only shorthand the CLI writes today; an object carries
-// enabled plus any params. Both are accepted so an old plain config keeps working.
-
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-
-const CLAUDE_USER_DIRECTORY = '.claude';
-const GLOBAL_STATE_DIRECTORY = 'claude-gates';
-const PROJECT_STATE_DIRECTORY = '.ai';
-const CONFIG_FILE = 'config.json';
-// Markers that identify a project root while climbing. Both `.git` AND `.ai/` count — the
-// same set the CLI uses — so a repo-less project (no git yet) still gets its project config
-// read. Anchoring on `.git` alone silently dropped the project layer in such repos.
-const PROJECT_ROOT_MARKERS = ['.git', PROJECT_STATE_DIRECTORY];
-
-function readJsonOrNull(path) {
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    // A corrupt project config must not silently disable protection: treat it as absent,
-    // which falls through to the global config and then to the registry defaults.
-    return null;
-  }
-}
-
-/** Climbs to the nearest project root (a dir holding `.git` or `.ai/`); null when none. */
-function projectRootOf(startDirectory) {
-  let current = startDirectory;
-  while (true) {
-    if (
-      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
-    ) {
-      return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-function projectConfigPath(startDirectory) {
-  const root = projectRootOf(startDirectory);
-  if (!root) return null;
-  return join(root, PROJECT_STATE_DIRECTORY, CONFIG_FILE);
-}
-
-function globalConfigPath(home) {
-  return join(home, CLAUDE_USER_DIRECTORY, GLOBAL_STATE_DIRECTORY, CONFIG_FILE);
-}
-
-/**
- * The `gates` object from the first config that exists: project first, then global.
- * A project config that exists but lacks a `gates` key still wins (an empty object) —
- * declaring a config is a deliberate act, and falling through to global would silently
- * re-enable what the project meant to turn off.
- */
-function gatesLayerFor(startDirectory, home) {
-  const projectPath = projectConfigPath(startDirectory);
-  const projectData = projectPath ? readJsonOrNull(projectPath) : null;
-  if (projectData) return projectData.gates ?? {};
-
-  const globalData = readJsonOrNull(globalConfigPath(home));
-  if (globalData) return globalData.gates ?? {};
-
-  return null; // nothing declared anywhere: gates fall back to registry defaults
-}
-
-/** Normalizes a gate's config entry (bool shorthand or object) to a plain object. */
-function gateEntryOf(gatesLayer, configKey) {
-  if (!gatesLayer) return null;
-  const entry = gatesLayer[configKey];
-  if (entry === undefined) return null;
-  if (typeof entry === 'boolean') return { enabled: entry };
-  if (entry && typeof entry === 'object') return entry;
-  return null; // malformed (string/number/null): ignore, fall back to default
-}
-
-/**
- * Reads the gates layer once per dispatcher invocation and hands back a lookup the
- * dispatcher and gates share. Reading once matters: N gates in the same tool call must
- * not each re-read and re-parse the file.
- *
- * @param {string} startDirectory usually process.cwd()
- * @returns {{ isEnabled(configKey, registryDefault): boolean,
- *             paramsFor(configKey): object }}
- */
-export function loadGateConfig(startDirectory, { home = homedir() } = {}) {
-  const gatesLayer = gatesLayerFor(startDirectory, home);
-
-  return {
-    /**
-     * A gate runs unless a config explicitly turns it off. `enabled` absent means "use
-     * the registry default"; only an explicit `false` disables. When no config exists
-     * anywhere, the registry default decides.
-     */
-    isEnabled(configKey, registryDefault) {
-      const entry = gateEntryOf(gatesLayer, configKey);
-      if (!entry || entry.enabled === undefined) return registryDefault;
-      return entry.enabled !== false;
-    },
-
-    /**
-     * The project's params for a gate (everything except `enabled`), or an empty object
-     * when none are declared. The gate merges these over its own built-in defaults —
-     * a declared param replaces the corresponding default wholesale.
-     */
-    paramsFor(configKey) {
-      const entry = gateEntryOf(gatesLayer, configKey);
-      if (!entry) return {};
-      const parameters = { ...entry };
-      delete parameters.enabled;
-      return parameters;
-    },
-  };
-}
-
-/**
- * Whether a gate should run, standalone. `registryDefault` decides when the project (and
- * global) config is silent about this gate; only an explicit `enabled: false` turns a gate
- * off. Used by `runGate` at each gate's start.
- */
-export function isGateEnabled(
-  configKey,
-  registryDefault,
-  startDirectory,
-  { home = homedir() } = {},
-) {
-  return loadGateConfig(startDirectory, { home }).isEnabled(
-    configKey,
-    registryDefault,
-  );
-}
-
-/**
- * A single gate's project params (its whitelist/patterns), standalone. Returns {} when
- * nothing is declared, so the gate falls back to its own built-in defaults.
- */
-export function gateParameters(
-  configKey,
-  startDirectory,
-  { home = homedir() } = {},
-) {
-  return loadGateConfig(startDirectory, { home }).paramsFor(configKey);
-}
+// Runtime gate configuration for the hooks. Self-contained: Node built-ins only, no npm,
+// so it works when the plugin is installed on its own.
+//
+// This is the READER the gates use at runtime. The CLI (`cli/config.mjs`) is the WRITER;
+// the two never import each other. Both agree on the file: `<project root>/.ai/config.json`,
+// with `~/.claude/claude-gates/config.json` as the global fallback.
+//
+// ── Two things a project controls per gate ──────────────────────────────────────────
+//   1. enabled — is the gate on? A gate absent from config keeps the registry default.
+//   2. params  — how the gate behaves: its whitelist, its patterns, its watched paths.
+//      A param the project declares REPLACES the gate's built-in default wholesale (it
+//      does not merge). The gate ships its defaults in its own source so the user can
+//      read them and know exactly what to override.
+//
+// ── Config shape a project may write ────────────────────────────────────────────────
+//   "gates": {
+//     "blockDestructiveShellCommands": true,                  // shorthand: enabled only
+//     "blockWritesToProtectedPaths": { "enabled": true, "protectedPaths": ["...","..."] }
+//   }
+// A bare boolean is the enabled-only shorthand the CLI writes today; an object carries
+// enabled plus any params. Both are accepted so an old plain config keeps working.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+const CLAUDE_USER_DIRECTORY = '.claude';
+const GLOBAL_STATE_DIRECTORY = 'claude-gates';
+const PROJECT_STATE_DIRECTORY = '.ai';
+const CONFIG_FILE = 'config.json';
+// Markers that identify a project root while climbing. Both `.git` AND `.ai/` count — the
+// same set the CLI uses — so a repo-less project (no git yet) still gets its project config
+// read. Anchoring on `.git` alone silently dropped the project layer in such repos.
+const PROJECT_ROOT_MARKERS = ['.git', PROJECT_STATE_DIRECTORY];
+
+function readJsonOrNull(path) {
+  if (!existsSync(path)) return null;
+  try {
+    // Strip a UTF-8 BOM () before parsing. `readFileSync(path,'utf8')` does NOT remove
+    // it, and JSON.parse throws on a leading BOM — so a config saved by a Windows editor or by
+    // PowerShell 5.1's `Set-Content -Encoding utf8` (which prepends a BOM) would be read as
+    // unparseable, treated as absent, and SILENTLY DROP every gate disable in it. That is the
+    // opposite of safe: it re-enables protections the project turned off, and (worse for the
+    // symmetric case) means a project can't be trusted to have been read at all. Removing the
+    // BOM makes the common Windows round-trip parse correctly.
+    return JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+  } catch {
+    // A genuinely corrupt project config must not silently disable protection: treat it as
+    // absent, which falls through to the global config and then to the registry defaults.
+    return null;
+  }
+}
+
+/** Climbs to the nearest project root (a dir holding `.git` or `.ai/`); null when none. */
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function projectConfigPath(startDirectory) {
+  const root = projectRootOf(startDirectory);
+  if (!root) return null;
+  return join(root, PROJECT_STATE_DIRECTORY, CONFIG_FILE);
+}
+
+function globalConfigPath(home) {
+  return join(home, CLAUDE_USER_DIRECTORY, GLOBAL_STATE_DIRECTORY, CONFIG_FILE);
+}
+
+/**
+ * The `gates` object from the first config that exists: project first, then global.
+ * A project config that exists but lacks a `gates` key still wins (an empty object) —
+ * declaring a config is a deliberate act, and falling through to global would silently
+ * re-enable what the project meant to turn off.
+ */
+function gatesLayerFor(startDirectory, home) {
+  const projectPath = projectConfigPath(startDirectory);
+  const projectData = projectPath ? readJsonOrNull(projectPath) : null;
+  if (projectData) return projectData.gates ?? {};
+
+  const globalData = readJsonOrNull(globalConfigPath(home));
+  if (globalData) return globalData.gates ?? {};
+
+  return null; // nothing declared anywhere: gates fall back to registry defaults
+}
+
+/** Normalizes a gate's config entry (bool shorthand or object) to a plain object. */
+function gateEntryOf(gatesLayer, configKey) {
+  if (!gatesLayer) return null;
+  const entry = gatesLayer[configKey];
+  if (entry === undefined) return null;
+  if (typeof entry === 'boolean') return { enabled: entry };
+  if (entry && typeof entry === 'object') return entry;
+  return null; // malformed (string/number/null): ignore, fall back to default
+}
+
+/**
+ * Reads the gates layer once per dispatcher invocation and hands back a lookup the
+ * dispatcher and gates share. Reading once matters: N gates in the same tool call must
+ * not each re-read and re-parse the file.
+ *
+ * @param {string} startDirectory usually process.cwd()
+ * @returns {{ isEnabled(configKey, registryDefault): boolean,
+ *             paramsFor(configKey): object }}
+ */
+export function loadGateConfig(startDirectory, { home = homedir() } = {}) {
+  const gatesLayer = gatesLayerFor(startDirectory, home);
+
+  return {
+    /**
+     * A gate runs unless a config explicitly turns it off. `enabled` absent means "use
+     * the registry default"; only an explicit `false` disables. When no config exists
+     * anywhere, the registry default decides.
+     */
+    isEnabled(configKey, registryDefault) {
+      const entry = gateEntryOf(gatesLayer, configKey);
+      if (!entry || entry.enabled === undefined) return registryDefault;
+      return entry.enabled !== false;
+    },
+
+    /**
+     * The project's params for a gate (everything except `enabled`), or an empty object
+     * when none are declared. The gate merges these over its own built-in defaults —
+     * a declared param replaces the corresponding default wholesale.
+     */
+    paramsFor(configKey) {
+      const entry = gateEntryOf(gatesLayer, configKey);
+      if (!entry) return {};
+      const parameters = { ...entry };
+      delete parameters.enabled;
+      return parameters;
+    },
+  };
+}
+
+/**
+ * Whether a gate should run, standalone. `registryDefault` decides when the project (and
+ * global) config is silent about this gate; only an explicit `enabled: false` turns a gate
+ * off. Used by `runGate` at each gate's start.
+ */
+export function isGateEnabled(
+  configKey,
+  registryDefault,
+  startDirectory,
+  { home = homedir() } = {},
+) {
+  return loadGateConfig(startDirectory, { home }).isEnabled(
+    configKey,
+    registryDefault,
+  );
+}
+
+/**
+ * A single gate's project params (its whitelist/patterns), standalone. Returns {} when
+ * nothing is declared, so the gate falls back to its own built-in defaults.
+ */
+export function gateParameters(
+  configKey,
+  startDirectory,
+  { home = homedir() } = {},
+) {
+  return loadGateConfig(startDirectory, { home }).paramsFor(configKey);
+}

package/plugins/gates/hooks/lib/hook-io-config.edge.test.mjs

@@ -0,0 +1,189 @@
+// Edge audit for the common scaffolding (hook-io.mjs, config.mjs) that every gate shares.
+// Uses a minimal real gate built on runGate() so behavior is exercised end to end rather
+// than by reading source and guessing.
+//
+// Findings:
+//   1. Config precedence: a project config that EXISTS but omits a given gate key falls
+//      through to the REGISTRY DEFAULT passed by the gate (not to the global config) --
+//      confirmed by gatesLayerFor's early return the moment projectData is truthy
+//      (config.mjs line 80-81: `if (projectData) return projectData.gates ?? {};`). A
+//      global config with the key enabled is never consulted once a project config file
+//      exists at all, even if it says nothing about this particular gate.
+//   2. A corrupted project config.json does NOT silently disable protection: readJsonOrNull
+//      returns null on parse failure, gatesLayerFor then falls through to the global config
+//      layer, and if that too is corrupt/absent, isGateEnabled falls back to the gate's own
+//      registryDefault. Verified with a gate whose registryDefault is `true` (deny-by-default)
+//      to prove corruption doesn't fail open when the default is protective.
+//   3. toolNameOf/runGate coalescing (payload.tool_name ?? payload.name ?? '' -> '' on
+//      unparseable JSON) is exercised directly here against the shared helpers, independent
+//      of any specific gate's matcher set.
+
+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, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// A minimal probe gate: denies unconditionally whenever it runs and is enabled, with a
+// registryDefault of true (protective/deny-by-default), so we can distinguish "ran and
+// allowed via toolName mismatch" from "did not run because disabled".
+const PROBE_GATE_SOURCE = `
+import { runGate, deny } from ${JSON.stringify(pathToFileURL(join(HERE, 'hook-io.mjs')).href)};
+runGate(
+  { id: 'probe-gate', configKey: 'probeGate', enabledByDefault: true },
+  ({ toolName }) => {
+    deny('probe-gate', 'toolName=' + JSON.stringify(toolName));
+  },
+);
+`;
+
+function writeProbeGate(directory) {
+  const gatePath = join(directory, 'probe-gate.mjs');
+  writeFileSync(gatePath, PROBE_GATE_SOURCE);
+  return gatePath;
+}
+
+function runProbe(gatePath, rawInput, project) {
+  const out = execFileSync(process.execPath, [gatePath], {
+    input: rawInput,
+    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('toolNameOf/runGate: unparseable JSON payload coalesces toolName to empty string, not null', () => {
+  const scratch = mkdtempSync(join(tmpdir(), 'hookio-edge-'));
+  const project = mkdtempSync(join(tmpdir(), 'hookio-proj-'));
+  mkdirSync(join(project, '.git'));
+  const gatePath = writeProbeGate(scratch);
+  // registryDefault=true means the probe gate is ON with no config at all; it always denies
+  // when it runs, and the deny message embeds the resolved toolName so we can inspect it.
+  const result = runProbe(gatePath, 'not json at all {{{', project);
+  assert.ok(isDeny(result));
+  assert.match(
+    result.hookSpecificOutput.permissionDecisionReason,
+    /toolName=""/,
+    'confirms toolNameOf(...) ?? \'\' resolves corrupt payloads to the empty string, ' +
+      'the exact value that fails to match any TOOL_GROUPS Set',
+  );
+});
+
+test('config precedence: project config exists but omits the gate key -> registryDefault wins, NOT global config', () => {
+  const project = mkdtempSync(join(tmpdir(), 'hookio-proj-'));
+  mkdirSync(join(project, '.git'));
+  mkdirSync(join(project, '.ai'));
+  // Project config exists, and declares gates, but never mentions 'probeGate'.
+  writeFileSync(
+    join(project, '.ai', 'config.json'),
+    JSON.stringify({ gates: { someOtherGate: true } }),
+  );
+  // Global config (same HOME as project, since HOME=project below) explicitly disables it.
+  // If precedence were "most specific explicit setting wins", global's false should apply.
+  // If precedence is "project file existing short-circuits global entirely", the probe's
+  // own registryDefault (true) should apply instead, ignoring global.
+  const home = project; // isolate HOME to a dir we control, distinct from project root marker use
+  mkdirSync(join(home, '.claude', 'claude-gates'), { recursive: true });
+  writeFileSync(
+    join(home, '.claude', 'claude-gates', 'config.json'),
+    JSON.stringify({ gates: { probeGate: false } }),
+  );
+  const scratch = mkdtempSync(join(tmpdir(), 'hookio-edge-'));
+  const gatePath = writeProbeGate(scratch);
+  const out = execFileSync(process.execPath, [gatePath], {
+    input: JSON.stringify({ tool_name: 'Write', tool_input: {} }),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+  });
+  const result = out.trim() ? JSON.parse(out.trim()) : null;
+  assert.ok(
+    isDeny(result),
+    'PASA(confirmed): project config existing makes gatesLayerFor return early with {} ' +
+      'for gates it does not mention, so registryDefault (true/deny) wins over the global ' +
+      'config saying false -- global is never consulted once ANY project config.json exists',
+  );
+});
+
+test('config precedence: NO project config at all -> global config value is honored', () => {
+  const project = mkdtempSync(join(tmpdir(), 'hookio-proj-'));
+  mkdirSync(join(project, '.git'));
+  // No .ai/config.json in the project at all.
+  const home = mkdtempSync(join(tmpdir(), 'hookio-home-'));
+  mkdirSync(join(home, '.claude', 'claude-gates'), { recursive: true });
+  writeFileSync(
+    join(home, '.claude', 'claude-gates', 'config.json'),
+    JSON.stringify({ gates: { probeGate: false } }),
+  );
+  const scratch = mkdtempSync(join(tmpdir(), 'hookio-edge-'));
+  const gatePath = writeProbeGate(scratch);
+  const out = execFileSync(process.execPath, [gatePath], {
+    input: JSON.stringify({ tool_name: 'Write', tool_input: {} }),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+  });
+  const result = out.trim() ? JSON.parse(out.trim()) : null;
+  assert.equal(
+    result,
+    null,
+    'control: with no project config file present at all, global config IS consulted and ' +
+      'its false correctly disables the gate -- confirms the precedence bug above is ' +
+      'specifically "project file exists" short-circuiting, not "global never works"',
+  );
+});
+
+test('corrupted project config.json does not silently disable a protective (default-on) gate', () => {
+  const project = mkdtempSync(join(tmpdir(), 'hookio-proj-'));
+  mkdirSync(join(project, '.git'));
+  mkdirSync(join(project, '.ai'));
+  writeFileSync(join(project, '.ai', 'config.json'), '{ this is not valid json ][');
+  const home = mkdtempSync(join(tmpdir(), 'hookio-home-'));
+  const scratch = mkdtempSync(join(tmpdir(), 'hookio-edge-'));
+  const gatePath = writeProbeGate(scratch);
+  const out = execFileSync(process.execPath, [gatePath], {
+    input: JSON.stringify({ tool_name: 'Write', tool_input: {} }),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+  });
+  const result = out.trim() ? JSON.parse(out.trim()) : null;
+  assert.ok(
+    isDeny(result),
+    'FALLA(ok): corrupt project config treated as absent -> falls through to global (none) ' +
+      '-> registryDefault (true) -> still protected, matching config.mjs\'s documented intent',
+  );
+});
+
+test('corrupted GLOBAL config.json (no project config) does not silently disable a protective gate', () => {
+  const project = mkdtempSync(join(tmpdir(), 'hookio-proj-'));
+  mkdirSync(join(project, '.git'));
+  const home = mkdtempSync(join(tmpdir(), 'hookio-home-'));
+  mkdirSync(join(home, '.claude', 'claude-gates'), { recursive: true });
+  writeFileSync(
+    join(home, '.claude', 'claude-gates', 'config.json'),
+    '{ not valid json at all',
+  );
+  const scratch = mkdtempSync(join(tmpdir(), 'hookio-edge-'));
+  const gatePath = writeProbeGate(scratch);
+  const out = execFileSync(process.execPath, [gatePath], {
+    input: JSON.stringify({ tool_name: 'Write', tool_input: {} }),
+    encoding: 'utf8',
+    cwd: project,
+    env: { ...process.env, HOME: home, USERPROFILE: home },
+  });
+  const result = out.trim() ? JSON.parse(out.trim()) : null;
+  assert.ok(
+    isDeny(result),
+    'FALLA(ok): corrupt global config also treated as absent -> registryDefault wins',
+  );
+});