@devrik-tools/claude-gates 0.1.2 → 0.2.0

package/cli/__tests__/version-consistency.test.mjs

@@ -0,0 +1,44 @@
+// Version coherence guard. This exists because of a real incident: the npm package was
+// bumped to 0.1.3 and published, but plugin.json / marketplace.json stayed at 0.1.0. Claude
+// Code versions a plugin by its plugin.json/marketplace version, so a machine that already
+// had 0.1.0 cached NEVER updated the code on reinstall — it ran the old, pre-migration gates
+// while the freshly written config.json said 0.1.3. The gates looked "enabled but broken".
+//
+// The rule this enforces: the npm package version, both plugin.json versions, and every
+// marketplace.json plugin entry must be the SAME string. Bump them together, every release.
+
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+function readJson(relativePath) {
+  return JSON.parse(readFileSync(join(ROOT, relativePath), 'utf8').replace(/^/, ''));
+}
+
+test('npm, both plugin.json, and every marketplace entry share one version', () => {
+  const versions = {
+    'package.json': readJson('package.json').version,
+    'plugins/gates/.claude-plugin/plugin.json': readJson(
+      'plugins/gates/.claude-plugin/plugin.json',
+    ).version,
+    'plugins/tasks/.claude-plugin/plugin.json': readJson(
+      'plugins/tasks/.claude-plugin/plugin.json',
+    ).version,
+  };
+  for (const plugin of readJson('.claude-plugin/marketplace.json').plugins) {
+    versions[`marketplace.json:${plugin.name}`] = plugin.version;
+  }
+
+  const distinct = [...new Set(Object.values(versions))];
+  assert.equal(
+    distinct.length,
+    1,
+    `all versions must match; found ${JSON.stringify(versions)}. ` +
+      'A plugin.json/marketplace version behind the npm version means Claude Code keeps ' +
+      'serving the OLD cached plugin code on reinstall. Bump them together.',
+  );
+});

package/cli/config.mjs

@@ -1,113 +1,124 @@
-// 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');
-}
+// 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}`);
+}
+
+// A leading UTF-8 BOM (EF BB BF, decoded as U+FEFF) is not stripped by readFileSync('utf8'),
+// and JSON.parse rejects a string that starts with it. Without stripping it, a config saved
+// by a BOM-adding editor or `PowerShell Set-Content -Encoding utf8` would read back as
+// `corrupt: true` — a valid, user-edited config (with its gate overrides) mistaken for
+// unreadable. init.mjs bails loudly on `corrupt`, but a caller relying on `data` alone (as
+// `mergeConfig` does) would otherwise merge onto `{}` and silently drop every existing gate
+// override the user made. This is the same failure mode fixed in the gates' own config.mjs.
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+export function readConfig(path) {
+  if (!existsSync(path)) return { exists: false, data: {}, corrupt: false };
+  try {
+    return {
+      exists: true,
+      data: JSON.parse(stripBom(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/index.mjs

@@ -1,97 +1,100 @@
-#!/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));
+#!/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';
+import { registerTaskCommand } from './task.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');
+  });
+
+registerTaskCommand(program);
+
+program.parseAsync(process.argv).catch((error) => fail(error.message));