@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/cli/install.mjs

@@ -1,80 +1,150 @@
-// Installs the gates plugin into Claude Code from the selection `init` just wrote.
-// Additive by design: `claude plugin install` merges the plugin's hooks alongside whatever
-// the user already has — it never rewrites their settings. If the `claude` binary is not
-// reachable, this degrades to printing the manual command, and `init` still succeeds.
-
-import { execFileSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { SCOPES } from './config.mjs';
-import { MARKETPLACE_PATH, REPOSITORY_ROOT } from './constants.mjs';
-
-const CLAUDE_BIN = 'claude';
-
-// Config scope decides where the plugin is installed: a project selection stays local to
-// this project (its .claude/settings.json); a global selection installs for every project.
-const PLUGIN_SCOPE = Object.freeze({
-  [SCOPES.PROJECT]: 'project',
-  [SCOPES.GLOBAL]: 'user',
-});
-
-function marketplaceAndPlugin() {
-  const manifest = JSON.parse(readFileSync(MARKETPLACE_PATH, 'utf8'));
-  const [plugin] = manifest.plugins;
-  return { marketplace: manifest.name, plugin: plugin.name };
-}
-
-/** The `claude plugin install …` line, read from the manifest, never hard-coded. */
-export function pluginInstallCommand() {
-  const { marketplace, plugin } = marketplaceAndPlugin();
-  return `claude plugin install ${plugin}@${marketplace}`;
-}
-
-function claude(commandArguments) {
-  return execFileSync(CLAUDE_BIN, commandArguments, {
-    encoding: 'utf8',
-    stdio: 'pipe',
-  });
-}
-
-/**
- * Registers the marketplace (idempotent: a second add just reports it already exists, which
- * is not fatal) and installs the plugin at the scope matching the config choice.
- * Returns { installed, scope } on success, or { installed:false, reason } to fall back to
- * the printed command.
- */
-export function installPlugin(configScope, { cwd = process.cwd() } = {}) {
-  const { marketplace, plugin } = marketplaceAndPlugin();
-  const scope = PLUGIN_SCOPE[configScope] ?? 'user';
-
-  try {
-    try {
-      claude([
-        'plugin',
-        'marketplace',
-        'add',
-        REPOSITORY_ROOT,
-        '--scope',
-        'user',
-      ]);
-    } catch {
-      // Already registered, or the marketplace add is a no-op — install can still proceed.
-    }
-    claude([
-      'plugin',
-      'install',
-      `${plugin}@${marketplace}`,
-      '--yes',
-      '--scope',
-      scope,
-    ]);
-    return { installed: true, scope };
-  } catch (error) {
-    const reason =
-      error?.code === 'ENOENT'
-        ? 'the `claude` command was not found on PATH'
-        : (error?.stderr || error?.message || String(error))
-            .trim()
-            .split('\n')[0];
-    return { installed: false, reason, cwd };
-  }
-}
+// Installs the gates plugin into Claude Code from the selection `init` just wrote.
+// Additive by design: `claude plugin install` merges the plugin's hooks alongside whatever
+// the user already has — it never rewrites their settings. If the `claude` binary is not
+// reachable, this degrades to printing the manual command, and `init` still succeeds.
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { SCOPES } from './config.mjs';
+import { MARKETPLACE_PATH, REPOSITORY_ROOT } from './constants.mjs';
+
+const CLAUDE_BIN = 'claude';
+
+// Config scope decides where the plugin is installed: a project selection stays local to
+// this project (its .claude/settings.json); a global selection installs for every project.
+const PLUGIN_SCOPE = Object.freeze({
+  [SCOPES.PROJECT]: 'project',
+  [SCOPES.GLOBAL]: 'user',
+});
+
+function marketplaceManifest() {
+  return JSON.parse(readFileSync(MARKETPLACE_PATH, 'utf8').replace(/^/, ''));
+}
+
+/**
+ * The name Claude Code actually registered THIS directory's marketplace under. It is usually
+ * the manifest's `name`, but not always: if the user added the same directory earlier under a
+ * different name (e.g. `devrik`), Claude Code keeps that original registration name, and
+ * `plugin marketplace add` is a no-op that does not rename it. Installing as `plugin@<name>`
+ * then fails with "not found in marketplace <name>". So we ask Claude Code which registered
+ * marketplace points at our REPOSITORY_ROOT and use that name; we fall back to the manifest
+ * name when the listing is unavailable (e.g. no `claude` binary, or a parsing change).
+ */
+function registeredMarketplaceName(runClaude, fallbackName) {
+  try {
+    const listing = runClaude(['plugin', 'marketplace', 'list']);
+    // Each marketplace block prints a name line then a `Source: … (<path>)` line. Find the
+    // block whose source path is our repo root and return its name.
+    const root = REPOSITORY_ROOT.replace(/[\\/]+$/, '');
+    const lines = listing.split(/\r?\n/);
+    let currentName = null;
+    for (const line of lines) {
+      const nameMatch = line.match(/^\s*(?:❯\s*)?([A-Za-z0-9_-]+)\s*$/);
+      if (nameMatch) currentName = nameMatch[1];
+      const sourceMatch = line.match(/Source:.*\(([^)]+)\)/);
+      if (sourceMatch && currentName) {
+        const sourcePath = sourceMatch[1].replace(/[\\/]+$/, '');
+        if (sourcePath.toLowerCase() === root.toLowerCase()) return currentName;
+      }
+    }
+  } catch {
+    // Listing unavailable — fall back to the manifest name below.
+  }
+  return fallbackName;
+}
+
+/** Every plugin the manifest declares, paired with the marketplace's registered name. */
+function marketplaceAndPlugins(runClaude = realClaude) {
+  const manifest = marketplaceManifest();
+  const marketplace = registeredMarketplaceName(runClaude, manifest.name);
+  return manifest.plugins.map((plugin) => ({
+    marketplace,
+    plugin: plugin.name,
+  }));
+}
+
+/** The `claude plugin install …` lines, one per plugin the manifest declares. */
+export function pluginInstallCommands() {
+  return marketplaceAndPlugins().map(
+    ({ marketplace, plugin }) => `claude plugin install ${plugin}@${marketplace}`,
+  );
+}
+
+/** Back-compat single-line form: the first plugin's install command. */
+export function pluginInstallCommand() {
+  return pluginInstallCommands()[0];
+}
+
+function realClaude(commandArguments) {
+  return execFileSync(CLAUDE_BIN, commandArguments, {
+    encoding: 'utf8',
+    stdio: 'pipe',
+  });
+}
+
+function reasonFor(error) {
+  return error?.code === 'ENOENT'
+    ? 'the `claude` command was not found on PATH'
+    : (error?.stderr || error?.message || String(error)).trim().split('\n')[0];
+}
+
+/**
+ * Registers the marketplace (idempotent: a second add just reports it already exists, which
+ * is not fatal) once, then installs EVERY plugin the manifest declares at the scope matching
+ * the config choice. A project that adopts claude-gates gets all of its plugins (gates,
+ * tasks, …), not just the first — a single failed install does not stop the rest from being
+ * attempted, so one broken plugin never silently blocks another that would have worked.
+ *
+ * Returns { installed, scope, results } where `installed` is true only if every plugin
+ * installed; `results` is a per-plugin { plugin, installed, reason? } list so a caller can
+ * report exactly which ones need the manual command.
+ *
+ * `runClaude` is an injectable seam (defaults to the real `claude` binary) so tests can
+ * exercise the multi-plugin partial-failure logic without actually invoking the CLI and
+ * installing plugins on the machine running the test.
+ */
+export function installPlugin(
+  configScope,
+  { cwd = process.cwd(), runClaude = realClaude } = {},
+) {
+  const scope = PLUGIN_SCOPE[configScope] ?? 'user';
+
+  try {
+    runClaude(['plugin', 'marketplace', 'add', REPOSITORY_ROOT, '--scope', 'user']);
+  } catch {
+    // Already registered, or the marketplace add is a no-op — install can still proceed.
+  }
+
+  // Resolve the registered marketplace name AFTER the add, so a fresh registration is seen and
+  // a pre-existing one (under any name) is matched by its source path. Doing it here, not at
+  // module top, means the name reflects the live registration this run just ensured.
+  const targets = marketplaceAndPlugins(runClaude);
+
+  const results = targets.map(({ marketplace, plugin }) => {
+    try {
+      runClaude([
+        'plugin',
+        'install',
+        `${plugin}@${marketplace}`,
+        '--yes',
+        '--scope',
+        scope,
+      ]);
+      return { plugin, installed: true };
+    } catch (error) {
+      return { plugin, installed: false, reason: reasonFor(error) };
+    }
+  });
+
+  const installed = results.every((result) => result.installed);
+  if (installed) return { installed: true, scope, results };
+
+  const failed = results.filter((result) => !result.installed);
+  return {
+    installed: false,
+    scope,
+    results,
+    reason: failed.map((result) => `${result.plugin}: ${result.reason}`).join('; '),
+    cwd,
+  };
+}

package/cli/materialize.mjs

@@ -1,51 +1,102 @@
-// 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';
-
-const DUMP_ENV = 'CLAUDE_GATES_DUMP_DEFAULTS';
-const PLUGIN_HOOKS_DIR = join(REPOSITORY_ROOT, 'plugins', 'gates', 'hooks');
-
-/**
- * Runs one gate in defaults-dump mode and returns its built-in params. The registry only
- * lists gates that exist on disk (enforced by a test), so this always resolves; a genuine
- * runtime failure yields {} rather than aborting the whole init.
- */
-function defaultParametersOf(gate) {
-  try {
-    const out = execFileSync(
-      process.execPath,
-      [join(PLUGIN_HOOKS_DIR, gate.script)],
-      { encoding: 'utf8', env: { ...process.env, [DUMP_ENV]: '1' } },
-    );
-    return JSON.parse(out).defaultParams ?? {};
-  } catch {
-    return {};
-  }
-}
-
-/**
- * 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.
- */
-export function materializeGates(registry, enabledMap) {
-  const gates = {};
-  for (const gate of allGates(registry)) {
-    const enabled = enabledMap[gate.configKey] === true;
-    const hasParameters = Array.isArray(gate.params) && gate.params.length > 0;
-    if (!hasParameters) {
-      gates[gate.configKey] = enabled;
-      continue;
-    }
-    gates[gate.configKey] = { enabled, ...defaultParametersOf(gate) };
-  }
-  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 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;
+}

package/cli/registry.mjs

@@ -1,127 +1,136 @@
-// 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),
-  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;
-}
-
-export function allGates(registry) {
-  return registry.families.flatMap((family) =>
-    family.gates.map((gate) => ({ ...gate, family: family.id })),
-  );
-}
+// 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,
+    })),
+  );
+}