@devrik-tools/claude-gates 0.1.0

package/cli/__tests__/registry-gates-consistency.test.mjs

@@ -0,0 +1,44 @@
+// The registry and the gates on disk must agree: every PreToolUse gate the registry
+// declares has to have a script, and every gate folder on disk has to be declared. A
+// mismatch (a registry entry with no file, like the old `autocommit`, or an orphan folder)
+// is what made `init` spawn a non-existent gate — this test blocks it from returning.
+
+import assert from 'node:assert/strict';
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { loadRegistry, allGates } from '../registry.mjs';
+
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const GATES_DIR = join(REPO, 'plugins', 'gates', 'hooks', 'gates');
+
+const registry = loadRegistry();
+const preToolUseGates = allGates(registry).filter(
+  (gate) => gate.event === 'PreToolUse',
+);
+
+test('every PreToolUse gate in the registry has its script on disk', () => {
+  for (const gate of preToolUseGates) {
+    const scriptPath = join(REPO, 'plugins', 'gates', 'hooks', gate.script);
+    assert.ok(
+      existsSync(scriptPath),
+      `registry declares gate "${gate.id}" (script ${gate.script}) but the file is missing`,
+    );
+  }
+});
+
+test('every gate folder on disk is declared in the registry', () => {
+  const declaredScripts = new Set(preToolUseGates.map((gate) => gate.script));
+  const folders = readdirSync(GATES_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+
+  for (const folder of folders) {
+    const expectedScript = `gates/${folder}/index.mjs`;
+    assert.ok(
+      declaredScripts.has(expectedScript),
+      `gate folder "${folder}" exists on disk but no registry entry points to ${expectedScript}`,
+    );
+  }
+});

package/cli/__tests__/selection.test.mjs

@@ -0,0 +1,200 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { loadRegistry, validateRegistry, allGates } from '../registry.mjs';
+import {
+  MODES,
+  resolveSelection,
+  adoptionOf,
+  summarize,
+} from '../selection.mjs';
+
+const registry = loadRegistry();
+const keys = allGates(registry).map((gate) => gate.configKey);
+
+test('the shipped registry is valid', () => {
+  assert.deepEqual(validateRegistry(registry), []);
+});
+
+test('validateRegistry catches duplicate configKey and unknown event', () => {
+  const broken = {
+    gateVersion: '1.0.0',
+    families: [
+      {
+        id: 'x',
+        name: 'X',
+        gates: [
+          {
+            id: 'a',
+            configKey: 'k',
+            default: true,
+            event: 'PreToolUse',
+            tools: [],
+            description: 'a',
+          },
+          {
+            id: 'b',
+            configKey: 'k',
+            default: true,
+            event: 'Nope',
+            tools: [],
+            description: 'b',
+          },
+        ],
+      },
+    ],
+  };
+  const problems = validateRegistry(broken);
+  assert.ok(problems.some((problem) => /duplicate configKey: k/.test(problem)));
+  assert.ok(problems.some((problem) => /gates\.1\.event/.test(problem)));
+});
+
+// A one-gate registry whose gate fields are overridable, so each test tweaks only the
+// field it checks. Every level carries its required description/name.
+function oneGateRegistry(gateOverrides) {
+  return {
+    gateVersion: '1.0.0',
+    families: [
+      {
+        id: 'x',
+        name: 'X',
+        description: 'family x',
+        gates: [
+          {
+            id: 'a',
+            configKey: 'k',
+            default: true,
+            event: 'PreToolUse',
+            tools: [],
+            script: 'gates/a.mjs',
+            description: 'gate a',
+            ...gateOverrides,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+const ABSOLUTE_SCRIPT = `${'/'}etc/evil.mjs`;
+
+test('validateRegistry requires a valid relative .mjs script per gate', () => {
+  const withoutScript = oneGateRegistry({});
+  delete withoutScript.families[0].gates[0].script;
+  assert.ok(validateRegistry(withoutScript).some((p) => /script/.test(p)));
+
+  assert.ok(
+    validateRegistry(oneGateRegistry({ script: ABSOLUTE_SCRIPT })).some((p) =>
+      /script/.test(p),
+    ),
+  );
+  assert.ok(
+    validateRegistry(oneGateRegistry({ script: '../escape.mjs' })).some((p) =>
+      /script/.test(p),
+    ),
+  );
+  assert.deepEqual(
+    validateRegistry(oneGateRegistry({ script: 'gates/ok.mjs' })),
+    [],
+  );
+});
+
+test('validateRegistry rejects a param that is not camelCase or has a bad type', () => {
+  assert.ok(
+    validateRegistry(
+      oneGateRegistry({
+        params: [{ name: 'Bad-Name', type: 'string', description: 'd' }],
+      }),
+    ).length > 0,
+  );
+  assert.ok(
+    validateRegistry(
+      oneGateRegistry({
+        params: [{ name: 'ok', type: 'regex', description: 'd' }],
+      }),
+    ).length > 0,
+  );
+  assert.deepEqual(
+    validateRegistry(
+      oneGateRegistry({
+        params: [{ name: 'ok', type: 'string[]', description: 'd' }],
+      }),
+    ),
+    [],
+  );
+});
+
+test('ALL enables every key; NONE disables every key; both cover all keys', () => {
+  const all = resolveSelection(registry, MODES.ALL);
+  const none = resolveSelection(registry, MODES.NONE);
+  assert.deepEqual(Object.keys(all).sort(), [...keys].sort());
+  assert.ok(Object.values(all).every((v) => v === true));
+  assert.ok(Object.values(none).every((v) => v === false));
+});
+
+test("DEFAULTS mirrors the registry's default flags", () => {
+  const map = resolveSelection(registry, MODES.DEFAULTS);
+  for (const gate of allGates(registry))
+    assert.equal(map[gate.configKey], gate.default, gate.id);
+});
+
+test('FAMILIES enables exactly the picked families', () => {
+  const map = resolveSelection(registry, MODES.FAMILIES, {
+    families: ['security'],
+  });
+  for (const gate of allGates(registry))
+    assert.equal(map[gate.configKey], gate.family === 'security', gate.id);
+});
+
+test('GRANULAR enables exactly the picked gates', () => {
+  const map = resolveSelection(registry, MODES.GRANULAR, {
+    gates: ['bash-commands', 'no-reconfirm'],
+  });
+  const enabled = Object.entries(map)
+    .filter(([, v]) => v)
+    .map(([k]) => k)
+    .sort();
+  assert.deepEqual(
+    enabled,
+    ['blockDestructiveShellCommands', 'requireNoReconfirmOfApproved'].sort(),
+  );
+});
+
+test('unknown ids fail loudly instead of being ignored', () => {
+  assert.throws(
+    () => resolveSelection(registry, MODES.FAMILIES, { families: ['nope'] }),
+    /Unknown family/,
+  );
+  assert.throws(
+    () => resolveSelection(registry, MODES.GRANULAR, { gates: ['nope'] }),
+    /Unknown gate/,
+  );
+  assert.throws(
+    () => resolveSelection(registry, 'weird'),
+    /Unknown selection mode/,
+  );
+});
+
+test('adoptionOf: true / false / partial', () => {
+  assert.equal(adoptionOf(resolveSelection(registry, MODES.ALL)), true);
+  assert.equal(adoptionOf(resolveSelection(registry, MODES.NONE)), false);
+  assert.equal(
+    adoptionOf(
+      resolveSelection(registry, MODES.FAMILIES, { families: ['security'] }),
+    ),
+    'partial',
+  );
+});
+
+test('summarize counts per family', () => {
+  const rows = summarize(
+    registry,
+    resolveSelection(registry, MODES.FAMILIES, { families: ['security'] }),
+  );
+  const security = rows.find((row) => row.family === 'security');
+  assert.equal(security.enabled.length, security.total);
+  assert.ok(
+    rows
+      .filter((row) => row.family !== 'security')
+      .every((row) => row.enabled.length === 0),
+  );
+});

package/cli/config.mjs

@@ -0,0 +1,113 @@
+// Where the selection is persisted and how it merges with what is already there.
+//
+// Scope "project": `<project root>/.ai/config.json` — the file the hooks read
+//   per project. Other keys the project already has (autoCommit, etc.) are kept.
+// Scope "global": `~/.claude/claude-gates/config.json` — the fallback the hooks
+//   use when a project has no answer of its own.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { findUpSync } from 'find-up';
+import {
+  CLAUDE_USER_DIRECTORY,
+  CONFIG_FILE,
+  GLOBAL_STATE_DIRECTORY,
+  HOME_DIRECTORY,
+  JSON_INDENT,
+  PROJECT_ROOT_MARKERS,
+  PROJECT_STATE_DIRECTORY,
+} from './constants.mjs';
+
+export const SCOPES = Object.freeze({ GLOBAL: 'global', PROJECT: 'project' });
+
+/**
+ * Climbs from `startDirectory` to the nearest project marker (`.git`/`.ai`).
+ * The home directory (and anything above it) is never a project root: a stray
+ * `~/.ai` would otherwise turn every folder under home into "the project" and the
+ * config would land in the wrong place silently. `.git` may be a file (worktrees),
+ * so the matcher checks existence, not type.
+ */
+export function findProjectRoot(
+  startDirectory,
+  { home = HOME_DIRECTORY } = {},
+) {
+  if (startDirectory === home) return startDirectory;
+  const markerDirectory = findUpSync(
+    (directory) => {
+      if (directory === home) return findUpSync.stop;
+      const hasMarker = PROJECT_ROOT_MARKERS.some((marker) =>
+        existsSync(join(directory, marker)),
+      );
+      return hasMarker ? directory : undefined;
+    },
+    { cwd: startDirectory, stopAt: home, type: 'directory' },
+  );
+  return markerDirectory ?? startDirectory;
+}
+
+export function configPathFor(
+  scope,
+  { cwd = process.cwd(), home = HOME_DIRECTORY } = {},
+) {
+  if (scope === SCOPES.GLOBAL)
+    return join(
+      home,
+      CLAUDE_USER_DIRECTORY,
+      GLOBAL_STATE_DIRECTORY,
+      CONFIG_FILE,
+    );
+  if (scope === SCOPES.PROJECT)
+    return join(
+      findProjectRoot(cwd, { home }),
+      PROJECT_STATE_DIRECTORY,
+      CONFIG_FILE,
+    );
+  throw new Error(`Unknown scope: ${scope}`);
+}
+
+export function readConfig(path) {
+  if (!existsSync(path)) return { exists: false, data: {}, corrupt: false };
+  try {
+    return {
+      exists: true,
+      data: JSON.parse(readFileSync(path, 'utf8')),
+      corrupt: false,
+    };
+  } catch {
+    return { exists: true, data: {}, corrupt: true };
+  }
+}
+
+/**
+ * Merges one gate's new value onto whatever the project already had, preserving the user's
+ * edits. A gate with params arrives as `{ enabled, ...defaults }`; if the user already
+ * tuned those params, their values win and only `enabled` follows the new selection. A
+ * paramless gate is a plain boolean. This is what keeps a re-run of `init` additive: it
+ * never overwrites a whitelist or pattern list the user changed by hand.
+ */
+function mergeGate(existingValue, newValue) {
+  if (typeof newValue === 'boolean') return newValue;
+  if (existingValue && typeof existingValue === 'object') {
+    return { ...newValue, ...existingValue, enabled: newValue.enabled };
+  }
+  return newValue;
+}
+
+/**
+ * Merges the new selection into an existing config without touching unrelated keys. Gates
+ * are merged key by key: a gate absent from the new map keeps its old value (a registry
+ * that dropped a gate must not silently flip it), and a gate the user configured keeps its
+ * params (see mergeGate).
+ */
+export function mergeConfig(existing, { adopted, gates, gateVersion }) {
+  const mergedGates = { ...(existing.gates ?? {}) };
+  for (const [key, value] of Object.entries(gates)) {
+    mergedGates[key] = mergeGate(mergedGates[key], value);
+  }
+  return { ...existing, adopted, gateVersion, gates: mergedGates };
+}
+
+export function writeConfig(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(data, null, JSON_INDENT)}\n`, 'utf8');
+}

package/cli/constants.mjs

@@ -0,0 +1,36 @@
+// Every fixed value the CLI relies on, in one place. Nothing else in `cli/` may
+// carry a literal path segment, file name or exit code (enforced by eslint:
+// no-magic-numbers + no-restricted-syntax on path-like strings).
+
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CLI_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+
+export const REPOSITORY_ROOT = join(CLI_DIRECTORY, '..');
+export const REGISTRY_FILE = 'registry.json';
+export const REGISTRY_PATH = join(REPOSITORY_ROOT, REGISTRY_FILE);
+export const MARKETPLACE_PATH = join(
+  REPOSITORY_ROOT,
+  '.claude-plugin',
+  'marketplace.json',
+);
+
+/** Project-scope config lives next to the project's other `.ai/` state. */
+export const PROJECT_STATE_DIRECTORY = '.ai';
+export const CONFIG_FILE = 'config.json';
+/** Markers that identify a project root while climbing from the cwd. */
+export const PROJECT_ROOT_MARKERS = ['.git', PROJECT_STATE_DIRECTORY];
+
+/** Global-scope config lives under Claude Code's own user directory. */
+export const CLAUDE_USER_DIRECTORY = '.claude';
+export const GLOBAL_STATE_DIRECTORY = 'claude-gates';
+
+export const HOME_DIRECTORY = homedir();
+
+export const EXIT_CODE = Object.freeze({ SUCCESS: 0, FAILURE: 1 });
+
+export const JSON_INDENT = 2;
+
+export const LIST_SEPARATOR = ',';

package/cli/index.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Entry point (commander). Commands:
+//   init      interactive (or flag-driven) selection of gates, per project or globally
+//   registry  --check validates registry.json; --list prints the catalog
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import {
+  EXIT_CODE,
+  LIST_SEPARATOR,
+  REGISTRY_PATH,
+  REPOSITORY_ROOT,
+} from './constants.mjs';
+import { loadRegistry, validateRegistry } from './registry.mjs';
+
+const packageManifest = JSON.parse(
+  readFileSync(join(REPOSITORY_ROOT, 'package.json'), 'utf8'),
+);
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(EXIT_CODE.FAILURE);
+}
+
+function splitList(value) {
+  return value
+    .split(LIST_SEPARATOR)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function registryCheck() {
+  const problems = validateRegistry(
+    JSON.parse(readFileSync(REGISTRY_PATH, 'utf8')),
+  );
+  if (problems.length > 0) {
+    fail(`registry.json is invalid:\n- ${problems.join('\n- ')}`);
+  }
+  process.stdout.write('registry.json OK\n');
+}
+
+function registryList() {
+  const registry = loadRegistry();
+  for (const family of registry.families) {
+    process.stdout.write(`${family.name} (${family.id})\n`);
+    for (const gate of family.gates) {
+      const marker = gate.default ? '*' : ' ';
+      process.stdout.write(`  ${marker} ${gate.id}  ${gate.configKey}\n`);
+    }
+  }
+  process.stdout.write('\n* = recommended default\n');
+}
+
+const program = new Command()
+  .name(packageManifest.name)
+  .description(packageManifest.description)
+  .version(packageManifest.version);
+
+program
+  .command('init')
+  .description('Choose which gates to adopt and write the config.')
+  .option('--project', 'apply to this project (<root>/.ai/config.json)')
+  .option('--global', 'apply globally (~/.claude/claude-gates/config.json)')
+  .option('--defaults', 'enable the recommended defaults')
+  .option('--all', 'enable every gate')
+  .option('--none', "record a 'no' so you are not asked again")
+  .option(
+    '--families <ids>',
+    'enable whole families, comma-separated',
+    splitList,
+  )
+  .option(
+    '--gates <ids>',
+    'enable individual gates, comma-separated',
+    splitList,
+  )
+  .option('-y, --yes', 'never prompt; use flags and defaults')
+  .option('--no-install', 'write the config but do not install the plugin')
+  .option('--dry-run', 'show the selection without writing')
+  .action(async (options) => {
+    const { runInit } = await import('./init.mjs');
+    await runInit(options);
+  });
+
+program
+  .command('registry')
+  .description('Inspect registry.json.')
+  .option('--check', 'validate the registry')
+  .option('--list', 'print families and gates')
+  .action((options) => {
+    if (options.check) return registryCheck();
+    if (options.list) return registryList();
+    return fail('registry needs --check or --list');
+  });
+
+program.parseAsync(process.argv).catch((error) => fail(error.message));