@devrik-tools/claude-gates 0.7.2 → 0.9.0

package/cli/evidence.mjs

@@ -0,0 +1,78 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 120000;
+const OUTPUT_TAIL_LINES = 20;
+
+function tail(text) {
+  return String(text ?? '')
+    .split(/\r?\n/)
+    .filter((line) => line.length > 0)
+    .slice(-OUTPUT_TAIL_LINES)
+    .join('\n');
+}
+
+export function verifyCommand(
+  command,
+  { cwd, expect, timeoutMs = DEFAULT_TIMEOUT_MS } = {},
+) {
+  const result = spawnSync(command, {
+    cwd,
+    shell: true,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+  });
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+  const exitCode = result.error ? null : result.status;
+  const failure = commandFailure(result, exitCode, output, expect);
+  return {
+    kind: 'command',
+    command,
+    expect: expect ?? null,
+    exitCode,
+    outputTail: tail(output),
+    verified: failure === null,
+    verifiedAt: new Date().toISOString(),
+    failure,
+  };
+}
+
+function commandFailure(result, exitCode, output, expect) {
+  if (result.error) return `could not run: ${result.error.message}`;
+  if (exitCode !== 0) return `exit code ${exitCode}`;
+  if (expect && !output.includes(expect))
+    return `output does not contain "${expect}"`;
+  return null;
+}
+
+export function verifyPath(path, { cwd, contains } = {}) {
+  const absolute = isAbsolute(path) ? path : join(cwd, path);
+  const exists = existsSync(absolute);
+  let containsFound = true;
+  if (exists && contains) {
+    try {
+      containsFound =
+        statSync(absolute).isFile() &&
+        readFileSync(absolute, 'utf8').includes(contains);
+    } catch {
+      containsFound = false;
+    }
+  }
+  const failure = pathFailure(path, exists, containsFound, contains);
+  return {
+    kind: 'path',
+    path,
+    contains: contains ?? null,
+    exists,
+    verified: failure === null,
+    verifiedAt: new Date().toISOString(),
+    failure,
+  };
+}
+
+function pathFailure(path, exists, containsFound, contains) {
+  if (!exists) return `"${path}" does not exist`;
+  if (!containsFound) return `"${path}" does not contain "${contains}"`;
+  return null;
+}

package/cli/hooks-manifest.mjs

@@ -0,0 +1,89 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { matcherFor } from '../plugins/gates/hooks/lib/hook-io.mjs';
+import { JSON_INDENT, REPOSITORY_ROOT } from './constants.mjs';
+import { allGates } from './registry.mjs';
+
+const DEFAULT_TIMEOUT_SECONDS = 30;
+const MATCHED_EVENTS = new Set(['PreToolUse', 'PostToolUse']);
+const PLUGIN_ROOT_VARIABLE = '${CLAUDE_PLUGIN_ROOT}';
+
+export function hooksJsonPathFor(pluginName) {
+  return join(REPOSITORY_ROOT, 'plugins', pluginName, 'hooks', 'hooks.json');
+}
+
+function hookEntry(script, timeoutSeconds, tools, event) {
+  const entry = {
+    hooks: [
+      {
+        type: 'command',
+        command: `node "${PLUGIN_ROOT_VARIABLE}/hooks/${script}"`,
+        timeout: timeoutSeconds,
+      },
+    ],
+  };
+  if (MATCHED_EVENTS.has(event)) entry.matcher = matcherFor(tools);
+  return MATCHED_EVENTS.has(event)
+    ? { matcher: entry.matcher, hooks: entry.hooks }
+    : entry;
+}
+
+export function buildHooksManifest(registry, pluginName) {
+  const hooks = {};
+  const pluginGates = allGates(registry).filter(
+    (gate) => gate.plugin === pluginName,
+  );
+  for (const gate of pluginGates) {
+    const timeoutSeconds = gate.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+    const scripts = [
+      { event: gate.event, script: gate.script, tools: gate.tools },
+      ...(gate.extraScripts ?? []).map((extra) => ({
+        event: extra.event,
+        script: extra.script,
+        tools: extra.tools ?? gate.tools,
+      })),
+    ];
+    for (const { event, script, tools } of scripts) {
+      hooks[event] ??= [];
+      hooks[event].push(hookEntry(script, timeoutSeconds, tools, event));
+    }
+  }
+  return { hooks };
+}
+
+export function pluginNamesIn(registry) {
+  return [...new Set(allGates(registry).map((gate) => gate.plugin))];
+}
+
+function readManifestJson(pluginName) {
+  try {
+    return JSON.stringify(
+      JSON.parse(readFileSync(hooksJsonPathFor(pluginName), 'utf8')),
+    );
+  } catch {
+    return null;
+  }
+}
+
+export function hooksManifestDrift(registry) {
+  const drifted = [];
+  for (const pluginName of pluginNamesIn(registry)) {
+    const expected = JSON.stringify(buildHooksManifest(registry, pluginName));
+    if (readManifestJson(pluginName) !== expected) drifted.push(pluginName);
+  }
+  return drifted;
+}
+
+export function writeHooksManifests(registry) {
+  const written = [];
+  for (const pluginName of pluginNamesIn(registry)) {
+    const path = hooksJsonPathFor(pluginName);
+    writeFileSync(
+      path,
+      `${JSON.stringify(buildHooksManifest(registry, pluginName), null, JSON_INDENT)}\n`,
+      'utf8',
+    );
+    written.push(path);
+  }
+  return written;
+}

package/cli/index.mjs

@@ -6,15 +6,26 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command } from 'commander';
+import { SCOPES, configPathFor } from './config.mjs';
 import {
   EXIT_CODE,
   LIST_SEPARATOR,
   REGISTRY_PATH,
   REPOSITORY_ROOT,
 } from './constants.mjs';
+import { diagnose, renderDiagnosis } from './doctor.mjs';
+import { hooksManifestDrift, writeHooksManifests } from './hooks-manifest.mjs';
+import { runLog } from './log.mjs';
 import { loadRegistry, validateRegistry } from './registry.mjs';
 import { runSmoke, OUTCOMES } from './smoke.mjs';
 import { registerTaskCommand } from './task.mjs';
+import {
+  defaultScopeFor,
+  renderStatus,
+  resolveTargets,
+  statusRows,
+  toggleGates,
+} from './toggle.mjs';
 
 const packageManifest = JSON.parse(
   readFileSync(join(REPOSITORY_ROOT, 'package.json'), 'utf8'),
@@ -33,13 +44,68 @@ function splitList(value) {
 }
 
 function registryCheck() {
-  const problems = validateRegistry(
-    JSON.parse(readFileSync(REGISTRY_PATH, 'utf8')),
-  );
+  const candidate = JSON.parse(readFileSync(REGISTRY_PATH, 'utf8'));
+  const problems = validateRegistry(candidate);
   if (problems.length > 0) {
     fail(`registry.json is invalid:\n- ${problems.join('\n- ')}`);
   }
-  process.stdout.write('registry.json OK\n');
+  const drifted = hooksManifestDrift(candidate);
+  if (drifted.length > 0) {
+    fail(
+      `hooks.json is out of date for plugin(s): ${drifted.join(', ')}. ` +
+        'Run `claude-gates registry --sync-hooks`.',
+    );
+  }
+  process.stdout.write('registry.json OK, hooks.json in sync\n');
+}
+
+function registrySyncHooks() {
+  const written = writeHooksManifests(loadRegistry());
+  process.stdout.write(`Wrote:\n  ${written.join('\n  ')}\n`);
+}
+
+function scopeFromOptions(options) {
+  if (options.project && options.global)
+    fail('Pick one of --project, --global');
+  if (options.project) return SCOPES.PROJECT;
+  if (options.global) return SCOPES.GLOBAL;
+  return defaultScopeFor(process.cwd());
+}
+
+function describeToggle(result, enabled) {
+  const verb = enabled ? 'Enabled' : 'Disabled';
+  const state = enabled ? 'on' : 'off';
+  const changed =
+    result.changed.length > 0 ? `: ${result.changed.join(', ')}` : '';
+  const unchanged =
+    result.unchanged > 0 ? ` (${result.unchanged} already ${state})` : '';
+  return `${verb} ${result.changed.length} gate(s) in ${result.path}${changed}${unchanged}\n`;
+}
+
+function toggle(ids, options, enabled) {
+  const registry = loadRegistry();
+  const scope = scopeFromOptions(options);
+  const path = configPathFor(scope);
+  let result;
+  try {
+    result = toggleGates(
+      path,
+      registry,
+      resolveTargets(registry, ids),
+      enabled,
+    );
+  } catch (error) {
+    return fail(error.message);
+  }
+  process.stdout.write(describeToggle(result, enabled));
+}
+
+function status() {
+  const rows = statusRows(loadRegistry());
+  const source =
+    rows.find((row) => row.source !== 'default')?.source ?? 'default';
+  const label = `Effective gates (layer: ${source}, cwd ${process.cwd()})`;
+  process.stdout.write(`${renderStatus(rows, label)}\n`);
 }
 
 function registryList() {
@@ -125,6 +191,10 @@ program
     'keep any previously installed plugin version instead of removing it first',
   )
   .option('--dry-run', 'show the selection without writing')
+  .option(
+    '--force',
+    'apply changes to gates already in the file without asking (default: keep them)',
+  )
   .action(async (options) => {
     const { runInit } = await import('./init.mjs');
     await runInit(options);
@@ -133,12 +203,60 @@ program
 program
   .command('registry')
   .description('Inspect registry.json.')
-  .option('--check', 'validate the registry')
+  .option('--check', 'validate the registry and hooks.json sync')
   .option('--list', 'print families and gates')
+  .option('--sync-hooks', 'regenerate each plugin hooks.json from the registry')
   .action((options) => {
     if (options.check) return registryCheck();
     if (options.list) return registryList();
-    return fail('registry needs --check or --list');
+    if (options.syncHooks) return registrySyncHooks();
+    return fail('registry needs --check, --list or --sync-hooks');
+  });
+
+program
+  .command('enable <ids...>')
+  .description('Turn gates on: gate ids, config keys, family ids, or "all".')
+  .option('--project', 'edit this project config')
+  .option('--global', 'edit the global config')
+  .action((ids, options) => toggle(ids, options, true));
+
+program
+  .command('disable <ids...>')
+  .description('Turn gates off: gate ids, config keys, family ids, or "all".')
+  .option('--project', 'edit this project config')
+  .option('--global', 'edit the global config')
+  .action((ids, options) => toggle(ids, options, false));
+
+program
+  .command('status')
+  .description(
+    'Show which gates are on for this directory and where that comes from.',
+  )
+  .action(() => status());
+
+program
+  .command('log')
+  .description(
+    'Show the decisions gates recorded for this project (.ai/gates-log.jsonl).',
+  )
+  .option('--tail <n>', 'how many of the latest entries to show (default 30)')
+  .option('--all', 'show every entry')
+  .option('--gate <id>', 'only this gate id or config key')
+  .option('--deny', 'only denials')
+  .option('--decision <kind>', 'deny | warn | block | config')
+  .option('--since <iso>', 'only entries after this ISO timestamp')
+  .option('--json', 'print JSON')
+  .action((options) => runLog(options));
+
+program
+  .command('doctor')
+  .description(
+    'Check that Claude Code runs this package version of the plugins.',
+  )
+  .action(() => {
+    const report = diagnose();
+    process.stdout.write(renderDiagnosis(report));
+    if (report.problems.length > 0) process.exit(EXIT_CODE.FAILURE);
   });
 
 program

package/cli/init.mjs

@@ -11,12 +11,17 @@ import {
 } from './config.mjs';
 import { EXIT_CODE } from './constants.mjs';
 import { installPlugin, pluginInstallCommands } from './install.mjs';
-import { materializeGates } from './materialize.mjs';
+import {
+  materializeGates,
+  plannedChanges,
+  revertChanges,
+} from './materialize.mjs';
 import { loadRegistry, allGates } from './registry.mjs';
 import {
   MODES,
   resolveSelection,
   adoptionOf,
+  namedGatesFor,
   summarize,
 } from './selection.mjs';
 
@@ -69,6 +74,7 @@ export function normalizeOptions(options = {}) {
     dryRun: Boolean(options.dryRun),
     install: options.install,
     removePrevious: options.removePrevious,
+    force: Boolean(options.force),
   };
 }
 
@@ -183,6 +189,58 @@ async function askRemovePrevious(io) {
   );
 }
 
+function stateLabel(value) {
+  if (value === 'default') return 'default';
+  return value ? 'on' : 'off';
+}
+
+function describeChange(change) {
+  return `${change.configKey}: ${stateLabel(change.from)} → ${stateLabel(change.to)}`;
+}
+
+async function askChanges(io, changes) {
+  const approved = bail(
+    await io.multiselect({
+      message:
+        'These gates are already in the file and would change. Keep checked the ones to apply:',
+      options: changes.map((change) => ({
+        value: change.configKey,
+        label: describeChange(change),
+      })),
+      initialValues: changes.map((change) => change.configKey),
+      required: false,
+    }),
+  );
+  return new Set(approved);
+}
+
+/** Existing gates only change when the user confirms (or passes --force); never silently. */
+async function settleChanges({ io, flags, interactive, existingGates, gates }) {
+  const changes = plannedChanges(existingGates, gates);
+  if (changes.length === 0) return { gates, kept: [] };
+  if (flags.force) return { gates, kept: [] };
+  if (interactive) {
+    const approved = await askChanges(io, changes);
+    const kept = changes.filter((change) => !approved.has(change.configKey));
+    return {
+      gates: revertChanges(
+        gates,
+        existingGates,
+        kept.map((change) => change.configKey),
+      ),
+      kept,
+    };
+  }
+  return {
+    gates: revertChanges(
+      gates,
+      existingGates,
+      changes.map((change) => change.configKey),
+    ),
+    kept: changes,
+  };
+}
+
 async function confirmWrite(io, fileExists) {
   const confirmed = bail(
     await io.confirm({
@@ -246,6 +304,22 @@ async function installGatesAfterWrite({
   return { path, config: merged, written: true, installed: result.installed };
 }
 
+function enabledOfEntry(entry, fallback) {
+  if (typeof entry === 'boolean') return entry;
+  if (entry && typeof entry === 'object') return entry.enabled !== false;
+  return fallback;
+}
+
+function adoptionOfEntries(registry, gateEntries) {
+  const map = {};
+  for (const gate of allGates(registry))
+    map[gate.configKey] = enabledOfEntry(
+      gateEntries[gate.configKey],
+      gate.default,
+    );
+  return adoptionOf(map);
+}
+
 export async function runInit(
   options,
   { cwd = process.cwd(), io = prompts } = {},
@@ -273,13 +347,33 @@ export async function runInit(
     process.exit(EXIT_CODE.FAILURE);
   }
 
+  const existingGates = existing.data.gates ?? {};
+  const settled = await settleChanges({
+    io,
+    flags,
+    interactive,
+    existingGates,
+    gates: materializeGates(
+      registry,
+      gates,
+      existingGates,
+      mode,
+      namedGatesFor(registry, mode, picks),
+    ),
+  });
   const merged = mergeConfig(existing.data, {
-    adopted: adoptionOf(gates),
-    gates: materializeGates(registry, gates, existing.data.gates ?? {}, mode),
+    adopted: adoptionOfEntries(registry, settled.gates),
+    gates: settled.gates,
     gateVersion: registry.gateVersion,
   });
 
   io.note(renderSummary(registry, gates), `Selection (${scope}) → ${path}`);
+  if (settled.kept.length > 0) {
+    io.log.warn(
+      `Kept as they were (not confirmed): ${settled.kept.map(describeChange).join('; ')}. ` +
+        'Use `claude-gates enable|disable <gate>` or re-run with --force to apply.',
+    );
+  }
 
   if (flags.dryRun) {
     io.outro('Dry run: nothing written.');

package/cli/log.mjs

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { logPathFor } from '../plugins/gates/hooks/lib/gate-log.mjs';
+import { findProjectRoot } from './config.mjs';
+
+const DEFAULT_TAIL = 30;
+const TIMESTAMP_LENGTH = 'YYYY-MM-DD HH:MM:SS'.length;
+const DECISION_COLUMN_WIDTH = 6;
+
+export function readLogEntries(cwd) {
+  const path = logPathFor(findProjectRoot(cwd));
+  if (!existsSync(path)) return { path, entries: [] };
+  const entries = readFileSync(path, 'utf8')
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+  return { path, entries };
+}
+
+export function filterEntries(entries, { gate, decision, since } = {}) {
+  const sinceTime = since ? Date.parse(since) : Number.NaN;
+  return entries.filter((entry) => {
+    if (gate && entry.gate !== gate && entry.configKey !== gate) return false;
+    if (decision && entry.decision !== decision) return false;
+    if (!Number.isNaN(sinceTime) && Date.parse(entry.ts) < sinceTime)
+      return false;
+    return true;
+  });
+}
+
+export function renderEntry(entry) {
+  const stamp = String(entry.ts ?? '')
+    .replace('T', ' ')
+    .slice(0, TIMESTAMP_LENGTH);
+  const decision = String(entry.decision ?? '').padEnd(DECISION_COLUMN_WIDTH);
+  const tool = entry.tool ? ` ${entry.tool}` : '';
+  return `${stamp}  ${decision} ${entry.gate}${tool}\n    ${entry.summary ?? ''}\n    → ${entry.reason ?? ''}`;
+}
+
+export function runLog(
+  options,
+  { cwd = process.cwd(), out = process.stdout } = {},
+) {
+  const { path, entries } = readLogEntries(cwd);
+  const filtered = filterEntries(entries, {
+    gate: options.gate,
+    decision: options.deny ? 'deny' : options.decision,
+    since: options.since,
+  });
+  const tail = Number(options.tail) > 0 ? Number(options.tail) : DEFAULT_TAIL;
+  const shown = options.all ? filtered : filtered.slice(-tail);
+  if (options.json) {
+    out.write(`${JSON.stringify(shown, null, 2)}\n`);
+    return;
+  }
+  if (shown.length === 0) {
+    out.write(`No gate decisions recorded (${path}).\n`);
+    return;
+  }
+  out.write(`${shown.map(renderEntry).join('\n')}\n`);
+  out.write(
+    `\n${shown.length} of ${filtered.length} decision(s) shown from ${path}\n`,
+  );
+}

package/cli/materialize.mjs

@@ -24,7 +24,7 @@ function pluginHooksDirectory(pluginName) {
  * 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) {
+export function defaultParametersOf(gate) {
   try {
     const out = execFileSync(
       process.execPath,
@@ -68,11 +68,17 @@ function existingParametersOf(existingEntry) {
  * mode. `mergeConfig` still does the key-by-key merge against the rest of the file
  * (unrelated top-level keys, gates the new registry dropped).
  */
+function namedByMode(registry, mode) {
+  if (mode === MODES.DEFAULTS) return new Set();
+  return new Set(allGates(registry).map((gate) => gate.configKey));
+}
+
 export function materializeGates(
   registry,
   enabledMap,
   existingGates = {},
   mode = MODES.DEFAULTS,
+  named = namedByMode(registry, mode),
 ) {
   const gates = {};
   for (const gate of allGates(registry)) {
@@ -81,7 +87,7 @@ export function materializeGates(
       gate.configKey,
     );
 
-    if (hasExisting && mode === MODES.DEFAULTS) {
+    if (hasExisting && !named.has(gate.configKey)) {
       gates[gate.configKey] = existingGates[gate.configKey];
       continue;
     }
@@ -101,3 +107,31 @@ export function materializeGates(
   }
   return gates;
 }
+
+function enabledStateOf(entry) {
+  if (typeof entry === 'boolean') return entry;
+  if (entry && typeof entry === 'object') {
+    return entry.enabled === undefined ? 'default' : entry.enabled !== false;
+  }
+  return 'default';
+}
+
+/** Gates whose `enabled` this run would flip relative to what the file already has. */
+export function plannedChanges(existingGates, materializedGates) {
+  const changes = [];
+  for (const [configKey, next] of Object.entries(materializedGates)) {
+    if (!Object.prototype.hasOwnProperty.call(existingGates, configKey))
+      continue;
+    const from = enabledStateOf(existingGates[configKey]);
+    const to = enabledStateOf(next);
+    if (from !== to) changes.push({ configKey, from, to });
+  }
+  return changes;
+}
+
+export function revertChanges(materializedGates, existingGates, configKeys) {
+  const reverted = { ...materializedGates };
+  for (const configKey of configKeys)
+    reverted[configKey] = existingGates[configKey];
+  return reverted;
+}

package/cli/registry.mjs

@@ -20,6 +20,8 @@ export const TOOL_GROUPS = [
   'delegation',
   'execution',
   'question',
+  'research',
+  'monitor',
 ];
 
 /** The kinds of value a gate param can take, so the CLI can describe and validate it. */
@@ -55,8 +57,17 @@ const gateSchema = z.object({
     .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(),
+  timeoutSeconds: z.number().int().positive().optional(),
+  extraScripts: z
+    .array(
+      z.object({
+        event: z.enum(HOOK_EVENTS),
+        script: z.string().regex(SCRIPT_PATTERN),
+        tools: z.array(z.enum(TOOL_GROUPS)).optional(),
+      }),
+    )
+    .optional(),
 });
 
 const familySchema = z.object({

package/cli/selection.mjs

@@ -81,3 +81,21 @@ export function summarize(registry, gatesMap) {
     };
   });
 }
+
+/** Config keys a run explicitly decided about: only these may change an existing entry. */
+export function namedGatesFor(registry, mode, picks = {}) {
+  const gates = allGates(registry);
+  const keysOf = (predicate) =>
+    new Set(gates.filter(predicate).map((gate) => gate.configKey));
+  if (mode === MODES.ALL || mode === MODES.NONE) return keysOf(() => true);
+  if (mode === MODES.DEFAULTS) return new Set();
+  if (mode === MODES.FAMILIES) {
+    const chosen = new Set(picks.families ?? []);
+    return keysOf((gate) => chosen.has(gate.family));
+  }
+  if (mode === MODES.GRANULAR) {
+    const chosen = new Set(picks.gates ?? []);
+    return keysOf((gate) => chosen.has(gate.id));
+  }
+  throw new Error(`Unknown selection mode: ${mode}`);
+}