@devrik-tools/claude-gates 0.4.0 → 0.7.0

package/plugins/gates/hooks/gates/staged-lint/index.mjs

@@ -0,0 +1,187 @@
+// staged-lint — denies a `git commit` when the files YOU staged fail lint. It never lints the
+// whole repo (that would block you on pre-existing debt in files you never touched); it lints
+// ONLY the staged files — what this commit actually introduces — so a clean commit is never
+// held hostage by someone else's old lint errors, and you can never add NEW lint debt through
+// your own change.
+//
+// justification: no existing gate covers this. lint-commit runs the project's lint script over
+// the WHOLE project and blocks if anything fails — too broad: a repo with pre-existing debt can
+// never commit. This gate scopes the check to the staged set, so it enforces "your change is
+// clean" without demanding "the whole repo is clean".
+//
+// ── How it works ─────────────────────────────────────────────────────────────────────
+// On a real `git commit`, it asks git for the staged files (`git diff --cached --name-only
+// --diff-filter=ACM`), keeps the ones with a lintable extension, and runs the project's lint
+// command over exactly those paths. Non-zero exit → deny with the lint output. No staged
+// lintable file, or no lint command declared → allow (nothing to enforce, never invented).
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   lintCommand      the command to run; the staged paths are appended as arguments. Default
+//                    null → autodetect eslint (`npx eslint`) when the project has an eslint
+//                    config, else allow (never invent a linter).
+//   lintExtensions   which staged file extensions are linted. Default js/mjs/cjs/ts/tsx/jsx.
+//   lintTimeoutMs    how long the lint run may take before it counts as a failure.
+//   escapeHatch      substring in the command that skips the check for one commit. Default
+//                    '[skip-lint]'.
+//
+// ── Fail-safe shape ──────────────────────────────────────────────────────────────────
+// Not a commit: allow (silent). No staged lintable files, or no linter: allow. The lint run
+// cannot spawn: deny (a commit gate that cannot evaluate must not silently permit). Lint exits
+// non-zero: deny with the tail of its output. Lint exits zero: allow.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { runGate, deny, toolInGroups } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'staged-lint';
+const CONFIG_KEY = 'blockCommitWithStagedLintErrors';
+
+const SHELL_GROUPS = ['shell'];
+const DEFAULT_LINT_TIMEOUT_MS = 60000;
+const OUTPUT_TAIL_LINES = 20;
+const DEFAULT_ESCAPE_HATCH = '[skip-lint]';
+const DEFAULT_LINT_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'];
+const ESLINT_CONFIG_FILES = [
+  'eslint.config.mjs',
+  'eslint.config.js',
+  'eslint.config.cjs',
+  '.eslintrc',
+  '.eslintrc.js',
+  '.eslintrc.cjs',
+  '.eslintrc.json',
+  '.eslintrc.yml',
+  '.eslintrc.yaml',
+];
+
+// Same git-global-option normalization lint-commit and no-coauthor use, so
+// `git -C /repo -c x=y commit` reduces to `git commit` before the pattern runs.
+const GIT_OPTION_WITH_VALUE = String.raw`(?:-[Cc]|--git-dir|--work-tree|--namespace|--exec-path|--config-env)(?:\s+|=)\S+`;
+const GIT_FLAG_OPTION = String.raw`--(?:paginate|no-pager|bare|no-optional-locks)|-p`;
+const GIT_GLOBAL_OPTION_PATTERN = new RegExp(
+  String.raw`\bgit\s+(?:${GIT_OPTION_WITH_VALUE}|${GIT_FLAG_OPTION})\s+`,
+  'i',
+);
+const GIT_COMMIT_PATTERN = /\bgit\s+commit\b/i;
+
+function normalizeGitOptions(command) {
+  let previous;
+  let normalized = command;
+  do {
+    previous = normalized;
+    normalized = normalized.replace(GIT_GLOBAL_OPTION_PATTERN, 'git ');
+  } while (normalized !== previous);
+  return normalized;
+}
+
+function isGitCommit(command) {
+  return GIT_COMMIT_PATTERN.test(normalizeGitOptions(command));
+}
+
+function commandTextFrom(toolInput) {
+  return String(toolInput.CommandLine ?? toolInput.command ?? '');
+}
+
+/** The staged files added/copied/modified (not deleted), with an extension in scope. */
+function stagedFilesToLint(cwd, lintExtensions) {
+  const result = spawnSync(
+    'git',
+    ['diff', '--cached', '--name-only', '--diff-filter=ACM'],
+    { cwd, encoding: 'utf8' },
+  );
+  if (result.status !== 0 || !result.stdout) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .filter((file) => lintExtensions.includes(extname(file).toLowerCase()));
+}
+
+/** The lint command to run, or null when none can be determined (never invented). */
+function resolveLintCommand(cwd, lintCommandOverride) {
+  if (lintCommandOverride) return lintCommandOverride;
+  const hasEslint = ESLINT_CONFIG_FILES.some((name) =>
+    existsSync(join(cwd, name)),
+  );
+  return hasEslint ? 'npx eslint' : null;
+}
+
+function tailLines(text, count) {
+  const lines = String(text)
+    .split(/\r?\n/)
+    .filter((line) => line.length > 0);
+  return lines.slice(-count).join('\n');
+}
+
+/** The lint command with the staged paths appended (quoted), so ONLY they are linted. */
+function lintCommandForFiles(lintCommand, files) {
+  const quotedPaths = files.map((file) => `"${file}"`).join(' ');
+  return `${lintCommand} ${quotedPaths}`;
+}
+
+/** Runs the lint command over the staged files; returns the spawnSync result. */
+function runLintOverStaged(lintCommand, files, cwd, timeoutMs) {
+  return spawnSync(lintCommandForFiles(lintCommand, files), {
+    cwd,
+    shell: true,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+  });
+}
+
+/** Denies when the lint run could not spawn or reported failures; otherwise returns. */
+function denyIfLintFailed(result, lintCommand, escapeHatch) {
+  if (result.error) {
+    deny(
+      GATE_ID,
+      `Could not run the lint command ("${lintCommand}") over the staged files: ` +
+        `${result.error.message}. Fix the lint setup or set lintCommand/` +
+        `${CONFIG_KEY} in .ai/config.json.`,
+    );
+  }
+  if (result.status !== 0) {
+    const combinedOutput =
+      `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+    const outputTail = tailLines(combinedOutput, OUTPUT_TAIL_LINES);
+    deny(
+      GATE_ID,
+      `The files you staged fail lint — commit blocked until your own changes are clean ` +
+        `(the rest of the repo is not checked). Fix them, or add "${escapeHatch}" to the ` +
+        `commit command for a deliberate exception:\n${outputTail}`,
+    );
+  }
+}
+
+runGate(
+  {
+    id: GATE_ID,
+    configKey: CONFIG_KEY,
+    enabledByDefault: false,
+    defaultParams: {
+      lintCommand: null,
+      lintExtensions: DEFAULT_LINT_EXTENSIONS,
+      lintTimeoutMs: DEFAULT_LINT_TIMEOUT_MS,
+      escapeHatch: DEFAULT_ESCAPE_HATCH,
+    },
+  },
+  ({ toolName, toolInput, parameters }) => {
+    if (!toolInGroups(toolName, SHELL_GROUPS)) return;
+
+    const command = commandTextFrom(toolInput);
+    if (!isGitCommit(command)) return;
+
+    const escapeHatch = parameters.escapeHatch ?? DEFAULT_ESCAPE_HATCH;
+    if (escapeHatch && command.includes(escapeHatch)) return;
+
+    const cwd = process.cwd();
+    const stagedFiles = stagedFilesToLint(cwd, parameters.lintExtensions);
+    if (stagedFiles.length === 0) return; // nothing you staged is in scope: nothing to enforce
+
+    const lintCommand = resolveLintCommand(cwd, parameters.lintCommand);
+    if (!lintCommand) return; // no linter declared/detected: never invent one
+
+    const timeoutMs = parameters.lintTimeoutMs ?? DEFAULT_LINT_TIMEOUT_MS;
+    const result = runLintOverStaged(lintCommand, stagedFiles, cwd, timeoutMs);
+    denyIfLintFailed(result, lintCommand, escapeHatch);
+  },
+);

package/plugins/gates/hooks/gates/stop-pending/index.mjs

@@ -1,164 +1,169 @@
-// stop-pending — the hook that obliges the assistant not to leave pending tasks behind.
-// On the Stop event, if the project's task store (`.ai/tasks/active.json`) has ACTIVE
-// tasks (status open/in_forge — see allowStopWithBlockedTasks for `blocked`), this BLOCKS
-// the stop and lists them with how to close each: `task close --evidence` or `task
-// abandon`.
-//
-// justification: no existing tool covers this. The tasks plugin (register-requests.mjs,
-// session-tasks.mjs) reminds and recites; nothing in this repo stops the agent from ending
-// a turn while a task is still open — that requires a Stop hook that can BLOCK, which only
-// this event shape supports.
-//
-// ── Stop hook event shape (Claude Code) ──────────────────────────────────────────────
-// stdin carries JSON: { session_id, stop_hook_active, ... }. To block the stop (make the
-// agent continue instead of ending the turn), print {"decision":"block","reason":"..."}
-// and exit 0 — `reason` is shown to the model so it knows what to do next. To allow the
-// stop, print nothing (or {}) and exit 0.
-//
-// ── stop_hook_active loop-guard (mandatory) ──────────────────────────────────────────
-// If a Stop hook already blocked once in this cycle, Claude Code re-invokes Stop hooks
-// with stop_hook_active=true. Blocking AGAIN here would never let the turn end — an
-// infinite loop. So: whenever stop_hook_active === true, this gate unconditionally allows
-// the stop, even if pending tasks remain. That trades "always caught" for "never hangs the
-// session" — a single missed reminder is recoverable, a frozen session is not.
-//
-// ── Why this re-reads active.json directly instead of importing task-store.mjs ──────
-// The task store lives in a DIFFERENT plugin (plugins/tasks/hooks/lib/task-store.mjs).
-// Importing across plugin boundaries makes each plugin's installability depend on the
-// other being present at a specific relative path — exactly the coupling every other gate
-// in this repo avoids by being self-contained (Node built-ins only). This gate instead
-// re-reads the on-disk JSON shape directly: `{ tasks: [ { id, title, status, ... } ] }`
-// with status one of open/blocked/in_forge/done/abandoned (done/abandoned already live
-// only in history.json, never in active.json, by task-store's own close() contract — so
-// active.json is never filtered by status here beyond blocked/allowStopWithBlockedTasks).
-// A change to that shape would need updating in two places, but a cross-plugin import
-// would need the OTHER plugin installed at all, which is worse for a gate meant to work
-// standalone.
-//
-// ── What a project can configure (params) ───────────────────────────────────────────
-//   allowStopWithBlockedTasks   when true (default), a task with status 'blocked' (a
-//                               declared cause + a next condition) does NOT prevent stop —
-//                               only open/in_forge do. Set false to also block on 'blocked'.
-//
-// ── Fail-safe shape (mandatory for a Stop hook) ──────────────────────────────────────
-// Everything below is wrapped in try/catch. No plugin/tasks installed, no .ai/tasks/, a
-// corrupt active.json, or ANY unexpected error: allow the stop. A broken Stop hook must
-// never hang a session — that is worse than one missed reminder.
-
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { isGateEnabled, gateParameters } from '../../lib/config.mjs';
-import { readHookPayload } from '../../lib/hook-io.mjs';
-
-const GATE_ID = 'stop-pending';
-const CONFIG_KEY = 'blockStopWithPendingTasks';
-
-const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
-const ACTIVE_TASKS_FILE = join('.ai', 'tasks', 'active.json');
-const BLOCKING_STATUSES = new Set(['open', 'in_forge']);
-const BLOCKED_STATUS = 'blocked';
-
-function stripBom(text) {
-  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-}
-
-function projectRootOf(startDirectory) {
-  let current = startDirectory;
-  while (true) {
-    if (PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))) {
-      return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-/** Reads .ai/tasks/active.json's task list directly. [] on any absence/corruption. */
-function readActiveTasks(root) {
-  const path = join(root, ACTIVE_TASKS_FILE);
-  if (!existsSync(path)) return [];
-  try {
-    const parsed = JSON.parse(stripBom(readFileSync(path, 'utf8')));
-    return Array.isArray(parsed.tasks) ? parsed.tasks : [];
-  } catch {
-    return [];
-  }
-}
-
-function blockingTasksFrom(tasks, allowBlocked) {
-  return tasks.filter((task) => {
-    if (BLOCKING_STATUSES.has(task.status)) return true;
-    return !allowBlocked && task.status === BLOCKED_STATUS;
-  });
-}
-
-function describeTasks(tasks) {
-  return tasks
-    .map(
-      (task) =>
-        `  - [${task.status}] ${task.id}: ${task.title ?? '(untitled)'}` +
-        (task.status === BLOCKED_STATUS && task.blockedReason
-          ? ` (blocked: ${task.blockedReason})`
-          : ''),
-    )
-    .join('\n');
-}
-
-function block(reason) {
-  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
-  process.exit(0);
-}
-
-function allow() {
-  process.exit(0);
-}
-
-function main() {
-  try {
-    const rawPayload = readHookPayload();
-    if (rawPayload === null) return allow();
-
-    let payload;
-    try {
-      payload = JSON.parse(rawPayload);
-    } catch {
-      return allow(); // unparseable Stop payload: fail-safe, never hang the session
-    }
-
-    // Loop-guard: a Stop hook already blocked once this cycle. Never block again.
-    if (payload?.stop_hook_active === true) return allow();
-
-    const cwd = process.cwd();
-    // registryDefault MUST match this gate's `default` in registry.json (true). The gate
-    // does not read the registry — this literal IS its default when a project config is
-    // silent about the key. It was false while the registry said false; both moved to true
-    // so the pending-task reminder actually fires on a fresh install, not only when the
-    // user's config names the key explicitly.
-    if (!isGateEnabled(CONFIG_KEY, true, cwd)) return allow();
-
-    const root = projectRootOf(cwd);
-    if (!root) return allow(); // no project: nothing to check
-
-    const parameters = gateParameters(CONFIG_KEY, cwd);
-    const allowBlocked = parameters.allowStopWithBlockedTasks !== false; // default true
-
-    const tasks = readActiveTasks(root);
-    const blockingTasks = blockingTasksFrom(tasks, allowBlocked);
-    if (blockingTasks.length === 0) return allow();
-
-    return block(
-      `[${GATE_ID}] There are ${blockingTasks.length} pending task(s) still active for this ` +
-        `project:\n${describeTasks(blockingTasks)}\n` +
-        'Close each before ending the turn: `task close <id> --evidence "..."` when done, ' +
-        'or `task abandon <id> --reason "..."` when it will not be finished. A task left ' +
-        '`blocked` with a stated cause does not require closing unless ' +
-        'allowStopWithBlockedTasks is set to false.',
-    );
-  } catch {
-    // A broken Stop hook must never hang the session.
-    return allow();
-  }
-}
-
-main();
+// stop-pending — the hook that obliges the assistant not to leave pending tasks behind.
+// On the Stop event, if the project's task store (`.ai/tasks/active.json`) has ACTIVE
+// tasks (status open/in_forge — see allowStopWithBlockedTasks for `blocked`), this BLOCKS
+// the stop and lists them with how to close each: `task close --evidence` or `task
+// abandon`.
+//
+// justification: no existing tool covers this. The tasks plugin (register-requests.mjs,
+// session-tasks.mjs) reminds and recites; nothing in this repo stops the agent from ending
+// a turn while a task is still open — that requires a Stop hook that can BLOCK, which only
+// this event shape supports.
+//
+// ── Stop hook event shape (Claude Code) ──────────────────────────────────────────────
+// stdin carries JSON: { session_id, stop_hook_active, ... }. To block the stop (make the
+// agent continue instead of ending the turn), print {"decision":"block","reason":"..."}
+// and exit 0 — `reason` is shown to the model so it knows what to do next. To allow the
+// stop, print nothing (or {}) and exit 0.
+//
+// ── stop_hook_active loop-guard (mandatory) ──────────────────────────────────────────
+// If a Stop hook already blocked once in this cycle, Claude Code re-invokes Stop hooks
+// with stop_hook_active=true. Blocking AGAIN here would never let the turn end — an
+// infinite loop. So: whenever stop_hook_active === true, this gate unconditionally allows
+// the stop, even if pending tasks remain. That trades "always caught" for "never hangs the
+// session" — a single missed reminder is recoverable, a frozen session is not.
+//
+// ── Why this re-reads active.json directly instead of importing task-store.mjs ──────
+// The task store lives in a DIFFERENT plugin (plugins/tasks/hooks/lib/task-store.mjs).
+// Importing across plugin boundaries makes each plugin's installability depend on the
+// other being present at a specific relative path — exactly the coupling every other gate
+// in this repo avoids by being self-contained (Node built-ins only). This gate instead
+// re-reads the on-disk JSON shape directly: `{ tasks: [ { id, title, status, ... } ] }`
+// with status one of open/blocked/in_forge/done/abandoned (done/abandoned already live
+// only in history.json, never in active.json, by task-store's own close() contract — so
+// active.json is never filtered by status here beyond blocked/allowStopWithBlockedTasks).
+// A change to that shape would need updating in two places, but a cross-plugin import
+// would need the OTHER plugin installed at all, which is worse for a gate meant to work
+// standalone.
+//
+// ── What a project can configure (params) ───────────────────────────────────────────
+//   allowStopWithBlockedTasks   when true (default), a task with status 'blocked' (a
+//                               declared cause + a next condition) does NOT prevent stop —
+//                               only open/in_forge do. Set false to also block on 'blocked'.
+//
+// ── Fail-safe shape (mandatory for a Stop hook) ──────────────────────────────────────
+// Everything below is wrapped in try/catch. No plugin/tasks installed, no .ai/tasks/, a
+// corrupt active.json, or ANY unexpected error: allow the stop. A broken Stop hook must
+// never hang a session — that is worse than one missed reminder.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isGateEnabled, gateParameters } from '../../lib/config.mjs';
+import { readHookPayload } from '../../lib/hook-io.mjs';
+
+const GATE_ID = 'stop-pending';
+const CONFIG_KEY = 'blockStopWithPendingTasks';
+
+const PROJECT_ROOT_MARKERS = ['.git', '.ai'];
+const ACTIVE_TASKS_FILE = join('.ai', 'tasks', 'active.json');
+const BLOCKING_STATUSES = new Set(['open', 'in_forge']);
+const BLOCKED_STATUS = 'blocked';
+
+const BOM_CODE_POINT = 0xfeff;
+
+function stripBom(text) {
+  return text.charCodeAt(0) === BOM_CODE_POINT ? text.slice(1) : text;
+}
+
+function projectRootOf(startDirectory) {
+  let current = startDirectory;
+  while (true) {
+    if (
+      PROJECT_ROOT_MARKERS.some((marker) => existsSync(join(current, marker)))
+    ) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** Reads .ai/tasks/active.json's task list directly. [] on any absence/corruption. */
+function readActiveTasks(root) {
+  const path = join(root, ACTIVE_TASKS_FILE);
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(stripBom(readFileSync(path, 'utf8')));
+    return Array.isArray(parsed.tasks) ? parsed.tasks : [];
+  } catch {
+    return [];
+  }
+}
+
+function blockingTasksFrom(tasks, allowBlocked) {
+  return tasks.filter((task) => {
+    if (BLOCKING_STATUSES.has(task.status)) return true;
+    return !allowBlocked && task.status === BLOCKED_STATUS;
+  });
+}
+
+function describeTasks(tasks) {
+  return tasks
+    .map(
+      (task) =>
+        `  - [${task.status}] ${task.id}: ${task.title ?? '(untitled)'}${
+          task.status === BLOCKED_STATUS && task.blockedReason
+            ? ` (blocked: ${task.blockedReason})`
+            : ''
+        }`,
+    )
+    .join('\n');
+}
+
+function block(reason) {
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  process.exit(0);
+}
+
+function allow() {
+  process.exit(0);
+}
+
+function main() {
+  try {
+    const rawPayload = readHookPayload();
+    if (rawPayload === null) return allow();
+
+    let payload;
+    try {
+      payload = JSON.parse(rawPayload);
+    } catch {
+      return allow(); // unparseable Stop payload: fail-safe, never hang the session
+    }
+
+    // Loop-guard: a Stop hook already blocked once this cycle. Never block again.
+    if (payload?.stop_hook_active === true) return allow();
+
+    const cwd = process.cwd();
+    // registryDefault MUST match this gate's `default` in registry.json (true). The gate
+    // does not read the registry — this literal IS its default when a project config is
+    // silent about the key. It was false while the registry said false; both moved to true
+    // so the pending-task reminder actually fires on a fresh install, not only when the
+    // user's config names the key explicitly.
+    if (!isGateEnabled(CONFIG_KEY, true, cwd)) return allow();
+
+    const root = projectRootOf(cwd);
+    if (!root) return allow(); // no project: nothing to check
+
+    const parameters = gateParameters(CONFIG_KEY, cwd);
+    const allowBlocked = parameters.allowStopWithBlockedTasks !== false; // default true
+
+    const tasks = readActiveTasks(root);
+    const blockingTasks = blockingTasksFrom(tasks, allowBlocked);
+    if (blockingTasks.length === 0) return allow();
+
+    return block(
+      `[${GATE_ID}] There are ${blockingTasks.length} pending task(s) still active for this ` +
+        `project:\n${describeTasks(blockingTasks)}\n` +
+        'Close each before ending the turn: `task close <id> --evidence "..."` when done, ' +
+        'or `task abandon <id> --reason "..."` when it will not be finished. A task left ' +
+        '`blocked` with a stated cause does not require closing unless ' +
+        'allowStopWithBlockedTasks is set to false.',
+    );
+  } catch {
+    // A broken Stop hook must never hang the session.
+    return allow();
+  }
+}
+
+main();