@devrik-tools/claude-gates 0.3.1 → 0.6.0

package/cli/materialize.mjs

@@ -1,102 +1,103 @@
-// Materializes each gate's default params into the config that `init` writes, so every
-// configurable value (a whitelist, a pattern list, a threshold) lands in the user's
-// .ai/config.json ready to edit. The values come from the gates themselves — each gate,
-// run with CLAUDE_GATES_DUMP_DEFAULTS set, prints its own defaults — so there is a single
-// source of truth (the gate) and nothing is duplicated in the registry.
-
-import { execFileSync } from 'node:child_process';
-import { join } from 'node:path';
-import { REPOSITORY_ROOT } from './constants.mjs';
-import { allGates } from './registry.mjs';
-import { MODES } from './selection.mjs';
-
-const DUMP_ENV = 'CLAUDE_GATES_DUMP_DEFAULTS';
-
-/** A gate's `hooks/` directory: each plugin (registry's per-family `plugin`) owns its own. */
-function pluginHooksDir(pluginName) {
-  return join(REPOSITORY_ROOT, 'plugins', pluginName, 'hooks');
-}
-
-/**
- * Runs one gate in defaults-dump mode and returns its built-in params. Not every gate
- * supports the defaults-dump protocol (only the `gates` plugin's PreToolUse gates do, via
- * runGate in hook-io.mjs); a script that does not recognize the env var, does not exist, or
- * errors for any other reason yields {} rather than aborting the whole init — the same
- * fallback already relied on before multi-plugin support.
- */
-function defaultParametersOf(gate) {
-  try {
-    const out = execFileSync(
-      process.execPath,
-      [join(pluginHooksDir(gate.plugin), gate.script)],
-      { encoding: 'utf8', env: { ...process.env, [DUMP_ENV]: '1' } },
-    );
-    return JSON.parse(out).defaultParams ?? {};
-  } catch {
-    return {};
-  }
-}
-
-/** The existing entry's params, stripped of `enabled` — {} for a boolean or missing entry. */
-function existingParamsOf(existingEntry) {
-  if (!existingEntry || typeof existingEntry !== 'object') return {};
-  const { enabled: _enabled, ...params } = existingEntry;
-  return params;
-}
-
-/**
- * Turns the flat `{ configKey: enabled }` selection into the config's gates map. A gate
- * that declares params (per the registry) becomes `{ enabled, ...defaults }` so its knobs
- * are visible and editable; a gate with no params stays a plain boolean, keeping the file
- * compact. Only gates with params are spawned, so paramless selections cost nothing.
- *
- * `existingGates` (the project's current config, if any) and `mode` (the selection mode
- * this run used) together decide how much of an already-present gate survives:
- *
- *   - mode === DEFAULTS: a "fill the gaps" sweep, not a directed choice. A gate already in
- *     `existingGates` is carried over VERBATIM (enabled + every param) — materializing
- *     defaults must never be what resets a disablement or a custom pattern list the user
- *     deliberately set.
- *   - any other mode (ALL / FAMILIES / GRANULAR): the user named this gate (directly, or
- *     via its family) this run, so `enabled` follows the new selection — that is the whole
- *     point of picking it. Its PARAMS still survive from the existing entry, since there is
- *     no per-run way to pass new param values through `init`'s flags today; only `enabled`
- *     is something this run actually decided.
- *
- * A gate absent from `existingGates` always gets a freshly computed value regardless of
- * mode. `mergeConfig` still does the key-by-key merge against the rest of the file
- * (unrelated top-level keys, gates the new registry dropped).
- */
-export function materializeGates(
-  registry,
-  enabledMap,
-  existingGates = {},
-  mode = MODES.DEFAULTS,
-) {
-  const gates = {};
-  for (const gate of allGates(registry)) {
-    const hasExisting = Object.prototype.hasOwnProperty.call(
-      existingGates,
-      gate.configKey,
-    );
-
-    if (hasExisting && mode === MODES.DEFAULTS) {
-      gates[gate.configKey] = existingGates[gate.configKey];
-      continue;
-    }
-
-    const enabled = enabledMap[gate.configKey] === true;
-    const hasParameters = Array.isArray(gate.params) && gate.params.length > 0;
-    if (!hasParameters) {
-      gates[gate.configKey] = enabled;
-      continue;
-    }
-
-    const defaults = defaultParametersOf(gate);
-    const params = hasExisting
-      ? { ...defaults, ...existingParamsOf(existingGates[gate.configKey]) }
-      : defaults;
-    gates[gate.configKey] = { enabled, ...params };
-  }
-  return gates;
-}
+// Materializes each gate's default params into the config that `init` writes, so every
+// configurable value (a whitelist, a pattern list, a threshold) lands in the user's
+// .ai/config.json ready to edit. The values come from the gates themselves — each gate,
+// run with CLAUDE_GATES_DUMP_DEFAULTS set, prints its own defaults — so there is a single
+// source of truth (the gate) and nothing is duplicated in the registry.
+
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { REPOSITORY_ROOT } from './constants.mjs';
+import { allGates } from './registry.mjs';
+import { MODES } from './selection.mjs';
+
+const DUMP_ENV = 'CLAUDE_GATES_DUMP_DEFAULTS';
+
+/** A gate's `hooks/` directory: each plugin (registry's per-family `plugin`) owns its own. */
+function pluginHooksDirectory(pluginName) {
+  return join(REPOSITORY_ROOT, 'plugins', pluginName, 'hooks');
+}
+
+/**
+ * Runs one gate in defaults-dump mode and returns its built-in params. Not every gate
+ * supports the defaults-dump protocol (only the `gates` plugin's PreToolUse gates do, via
+ * runGate in hook-io.mjs); a script that does not recognize the env var, does not exist, or
+ * errors for any other reason yields {} rather than aborting the whole init — the same
+ * fallback already relied on before multi-plugin support.
+ */
+function defaultParametersOf(gate) {
+  try {
+    const out = execFileSync(
+      process.execPath,
+      [join(pluginHooksDirectory(gate.plugin), gate.script)],
+      { encoding: 'utf8', env: { ...process.env, [DUMP_ENV]: '1' } },
+    );
+    return JSON.parse(out).defaultParams ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/** The existing entry's params, stripped of `enabled` — {} for a boolean or missing entry. */
+function existingParametersOf(existingEntry) {
+  if (!existingEntry || typeof existingEntry !== 'object') return {};
+  const parameters = { ...existingEntry };
+  delete parameters.enabled;
+  return parameters;
+}
+
+/**
+ * Turns the flat `{ configKey: enabled }` selection into the config's gates map. A gate
+ * that declares params (per the registry) becomes `{ enabled, ...defaults }` so its knobs
+ * are visible and editable; a gate with no params stays a plain boolean, keeping the file
+ * compact. Only gates with params are spawned, so paramless selections cost nothing.
+ *
+ * `existingGates` (the project's current config, if any) and `mode` (the selection mode
+ * this run used) together decide how much of an already-present gate survives:
+ *
+ *   - mode === DEFAULTS: a "fill the gaps" sweep, not a directed choice. A gate already in
+ *     `existingGates` is carried over VERBATIM (enabled + every param) — materializing
+ *     defaults must never be what resets a disablement or a custom pattern list the user
+ *     deliberately set.
+ *   - any other mode (ALL / FAMILIES / GRANULAR): the user named this gate (directly, or
+ *     via its family) this run, so `enabled` follows the new selection — that is the whole
+ *     point of picking it. Its PARAMS still survive from the existing entry, since there is
+ *     no per-run way to pass new param values through `init`'s flags today; only `enabled`
+ *     is something this run actually decided.
+ *
+ * A gate absent from `existingGates` always gets a freshly computed value regardless of
+ * mode. `mergeConfig` still does the key-by-key merge against the rest of the file
+ * (unrelated top-level keys, gates the new registry dropped).
+ */
+export function materializeGates(
+  registry,
+  enabledMap,
+  existingGates = {},
+  mode = MODES.DEFAULTS,
+) {
+  const gates = {};
+  for (const gate of allGates(registry)) {
+    const hasExisting = Object.prototype.hasOwnProperty.call(
+      existingGates,
+      gate.configKey,
+    );
+
+    if (hasExisting && mode === MODES.DEFAULTS) {
+      gates[gate.configKey] = existingGates[gate.configKey];
+      continue;
+    }
+
+    const enabled = enabledMap[gate.configKey] === true;
+    const hasParameters = Array.isArray(gate.params) && gate.params.length > 0;
+    if (!hasParameters) {
+      gates[gate.configKey] = enabled;
+      continue;
+    }
+
+    const defaults = defaultParametersOf(gate);
+    const parameters = hasExisting
+      ? { ...defaults, ...existingParametersOf(existingGates[gate.configKey]) }
+      : defaults;
+    gates[gate.configKey] = { enabled, ...parameters };
+  }
+  return gates;
+}

package/cli/registry.mjs

@@ -1,136 +1,139 @@
-// Loads and validates registry.json — the catalog that menus, config and hooks derive from.
-// Validation is a zod schema so the shape is declared once and errors are uniform.
-// Fails loudly on a corrupt catalog: a menu built on invalid data would write a
-// configuration that no gate recognizes.
-
-import { readFileSync } from 'node:fs';
-import { z } from 'zod';
-import { REGISTRY_PATH } from './constants.mjs';
-
-export const HOOK_EVENTS = [
-  'PreToolUse',
-  'SessionStart',
-  'PostToolUse',
-  'Stop',
-  'UserPromptSubmit',
-];
-export const TOOL_GROUPS = [
-  'write',
-  'shell',
-  'delegation',
-  'execution',
-  'question',
-];
-
-/** The kinds of value a gate param can take, so the CLI can describe and validate it. */
-export const PARAM_TYPES = ['string', 'number', 'boolean', 'string[]'];
-
-const ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-const CONFIG_KEY_PATTERN = /^[a-z][A-Za-z0-9]*$/;
-const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
-// A gate's script is a path relative to the plugin's hooks/ directory: `gates/x.mjs`
-// (a PreToolUse gate) or `x.mjs` (a session hook). Never absolute, never climbing out.
-const SCRIPT_PATTERN = /^(?!\/|[A-Za-z]:|\.\.\/)[\w./-]+\.mjs$/;
-
-/**
- * A configurable param a project may override. The registry declares that the param
- * EXISTS and its type; the default VALUE lives in the gate's own source, so the user
- * reads it there and knows exactly what a project override replaces.
- */
-const parameterSchema = z.object({
-  name: z.string().regex(CONFIG_KEY_PATTERN, 'param name must be camelCase'),
-  type: z.enum(PARAM_TYPES),
-  description: z.string().min(1),
-});
-
-const gateSchema = z.object({
-  id: z.string().regex(ID_PATTERN, 'gate id must be kebab-case'),
-  configKey: z
-    .string()
-    .regex(CONFIG_KEY_PATTERN, 'configKey must be camelCase'),
-  default: z.boolean(),
-  event: z.enum(HOOK_EVENTS),
-  tools: z.array(z.enum(TOOL_GROUPS)),
-  script: z
-    .string()
-    .regex(SCRIPT_PATTERN, 'script must be an .mjs path relative to hooks/'),
-  description: z.string().min(1),
-  // Optional: a gate with no configurable params omits it.
-  params: z.array(parameterSchema).optional(),
-});
-
-const familySchema = z.object({
-  id: z.string().regex(ID_PATTERN, 'family id must be kebab-case'),
-  name: z.string().min(1),
-  description: z.string().min(1),
-  // Which plugin's hooks/ directory the family's gate scripts resolve against. Optional so
-  // existing families need no change: absent means the original 'gates' plugin.
-  plugin: z.string().regex(ID_PATTERN, 'plugin id must be kebab-case').optional(),
-  gates: z.array(gateSchema).min(1),
-});
-
-function duplicatesIn(items) {
-  const seen = new Set();
-  const duplicates = new Set();
-  for (const item of items) {
-    if (seen.has(item)) duplicates.add(item);
-    seen.add(item);
-  }
-  return [...duplicates];
-}
-
-/** Uniqueness across families is not expressible per-field, so it is a second pass. */
-function duplicateProblems(candidate) {
-  const families = Array.isArray(candidate?.families) ? candidate.families : [];
-  const gates = families.flatMap((family) =>
-    Array.isArray(family?.gates) ? family.gates : [],
-  );
-  return [
-    ...duplicatesIn(families.map((family) => family?.id)).map(
-      (id) => `duplicate family id: ${id}`,
-    ),
-    ...duplicatesIn(gates.map((gate) => gate?.id)).map(
-      (id) => `duplicate gate id: ${id}`,
-    ),
-    ...duplicatesIn(gates.map((gate) => gate?.configKey)).map(
-      (key) => `duplicate configKey: ${key}`,
-    ),
-  ];
-}
-
-export const registrySchema = z.object({
-  gateVersion: z.string().regex(VERSION_PATTERN, 'gateVersion must be x.y.z'),
-  families: z.array(familySchema).min(1),
-});
-
-/** Returns a list of human-readable problems; empty when the registry is valid. */
-export function validateRegistry(candidate) {
-  const result = registrySchema.safeParse(candidate);
-  const schemaProblems = result.success
-    ? []
-    : result.error.issues.map(
-        (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
-      );
-  return [...schemaProblems, ...duplicateProblems(candidate)];
-}
-
-export function loadRegistry(path = REGISTRY_PATH) {
-  const candidate = JSON.parse(readFileSync(path, 'utf8'));
-  const problems = validateRegistry(candidate);
-  if (problems.length > 0) {
-    throw new Error(`registry.json is invalid:\n- ${problems.join('\n- ')}`);
-  }
-  return candidate;
-}
-
-const DEFAULT_PLUGIN = 'gates';
-
-export function allGates(registry) {
-  return registry.families.flatMap((family) =>
-    family.gates.map((gate) => ({
-      ...gate,
-      family: family.id,
-      plugin: family.plugin ?? DEFAULT_PLUGIN,
-    })),
-  );
-}
+// Loads and validates registry.json — the catalog that menus, config and hooks derive from.
+// Validation is a zod schema so the shape is declared once and errors are uniform.
+// Fails loudly on a corrupt catalog: a menu built on invalid data would write a
+// configuration that no gate recognizes.
+
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { REGISTRY_PATH } from './constants.mjs';
+
+export const HOOK_EVENTS = [
+  'PreToolUse',
+  'SessionStart',
+  'PostToolUse',
+  'Stop',
+  'UserPromptSubmit',
+];
+export const TOOL_GROUPS = [
+  'write',
+  'shell',
+  'delegation',
+  'execution',
+  'question',
+];
+
+/** The kinds of value a gate param can take, so the CLI can describe and validate it. */
+export const PARAM_TYPES = ['string', 'number', 'boolean', 'string[]'];
+
+const ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const CONFIG_KEY_PATTERN = /^[a-z][A-Za-z0-9]*$/;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+// A gate's script is a path relative to the plugin's hooks/ directory: `gates/x.mjs`
+// (a PreToolUse gate) or `x.mjs` (a session hook). Never absolute, never climbing out.
+const SCRIPT_PATTERN = /^(?!\/|[A-Za-z]:|\.\.\/)[\w./-]+\.mjs$/;
+
+/**
+ * A configurable param a project may override. The registry declares that the param
+ * EXISTS and its type; the default VALUE lives in the gate's own source, so the user
+ * reads it there and knows exactly what a project override replaces.
+ */
+const parameterSchema = z.object({
+  name: z.string().regex(CONFIG_KEY_PATTERN, 'param name must be camelCase'),
+  type: z.enum(PARAM_TYPES),
+  description: z.string().min(1),
+});
+
+const gateSchema = z.object({
+  id: z.string().regex(ID_PATTERN, 'gate id must be kebab-case'),
+  configKey: z
+    .string()
+    .regex(CONFIG_KEY_PATTERN, 'configKey must be camelCase'),
+  default: z.boolean(),
+  event: z.enum(HOOK_EVENTS),
+  tools: z.array(z.enum(TOOL_GROUPS)),
+  script: z
+    .string()
+    .regex(SCRIPT_PATTERN, 'script must be an .mjs path relative to hooks/'),
+  description: z.string().min(1),
+  // Optional: a gate with no configurable params omits it.
+  params: z.array(parameterSchema).optional(),
+});
+
+const familySchema = z.object({
+  id: z.string().regex(ID_PATTERN, 'family id must be kebab-case'),
+  name: z.string().min(1),
+  description: z.string().min(1),
+  // Which plugin's hooks/ directory the family's gate scripts resolve against. Optional so
+  // existing families need no change: absent means the original 'gates' plugin.
+  plugin: z
+    .string()
+    .regex(ID_PATTERN, 'plugin id must be kebab-case')
+    .optional(),
+  gates: z.array(gateSchema).min(1),
+});
+
+function duplicatesIn(items) {
+  const seen = new Set();
+  const duplicates = new Set();
+  for (const item of items) {
+    if (seen.has(item)) duplicates.add(item);
+    seen.add(item);
+  }
+  return [...duplicates];
+}
+
+/** Uniqueness across families is not expressible per-field, so it is a second pass. */
+function duplicateProblems(candidate) {
+  const families = Array.isArray(candidate?.families) ? candidate.families : [];
+  const gates = families.flatMap((family) =>
+    Array.isArray(family?.gates) ? family.gates : [],
+  );
+  return [
+    ...duplicatesIn(families.map((family) => family?.id)).map(
+      (id) => `duplicate family id: ${id}`,
+    ),
+    ...duplicatesIn(gates.map((gate) => gate?.id)).map(
+      (id) => `duplicate gate id: ${id}`,
+    ),
+    ...duplicatesIn(gates.map((gate) => gate?.configKey)).map(
+      (key) => `duplicate configKey: ${key}`,
+    ),
+  ];
+}
+
+export const registrySchema = z.object({
+  gateVersion: z.string().regex(VERSION_PATTERN, 'gateVersion must be x.y.z'),
+  families: z.array(familySchema).min(1),
+});
+
+/** Returns a list of human-readable problems; empty when the registry is valid. */
+export function validateRegistry(candidate) {
+  const result = registrySchema.safeParse(candidate);
+  const schemaProblems = result.success
+    ? []
+    : result.error.issues.map(
+        (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
+      );
+  return [...schemaProblems, ...duplicateProblems(candidate)];
+}
+
+export function loadRegistry(path = REGISTRY_PATH) {
+  const candidate = JSON.parse(readFileSync(path, 'utf8'));
+  const problems = validateRegistry(candidate);
+  if (problems.length > 0) {
+    throw new Error(`registry.json is invalid:\n- ${problems.join('\n- ')}`);
+  }
+  return candidate;
+}
+
+const DEFAULT_PLUGIN = 'gates';
+
+export function allGates(registry) {
+  return registry.families.flatMap((family) =>
+    family.gates.map((gate) => ({
+      ...gate,
+      family: family.id,
+      plugin: family.plugin ?? DEFAULT_PLUGIN,
+    })),
+  );
+}