claude-code-hookkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Austin Amelone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# claude-code-hookkit
+
+[![npm version](https://img.shields.io/npm/v/claude-code-hookkit.svg)](https://www.npmjs.com/package/claude-code-hookkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**husky for Claude Code** — install, manage, test, and share hooks with a single command.
+
+Go from zero to production-grade Claude Code hooks in under 60 seconds:
+
+```bash
+npx claude-code-hookkit init && npx claude-code-hookkit add security-pack
+```
+
+---
+
+## What Are Claude Code Hooks?
+
+Claude Code hooks are shell commands triggered by Claude Code events (PreToolUse, PostToolUse, SessionStart, Stop). They run automatically and can:
+
+- **Block** dangerous operations before they execute (exit code 2)
+- **Observe** and log what Claude does (exit code 0, advisory)
+- **Provide feedback** after actions complete
+
+Hooks are configured in `~/.claude/settings.json` under the `hooks` key. `claude-code-hookkit` manages that configuration for you — non-destructively, with backups.
+
+---
+
+## Quick Start
+
+```bash
+# Initialize hook directory and seed settings.json
+npx claude-code-hookkit init
+
+# Install the security pack (sensitive-path-guard + exit-code-enforcer)
+npx claude-code-hookkit add security-pack
+
+# See what's installed
+npx claude-code-hookkit list
+
+# Verify everything is healthy
+npx claude-code-hookkit doctor
+```
+
+---
+
+## Command Reference
+
+### `claude-code-hookkit init`
+
+Scaffold the hook directory and seed `settings.json`.
+
+```bash
+claude-code-hookkit init                    # project scope (default)
+claude-code-hookkit init --scope user       # user-level settings (~/.claude/settings.json)
+claude-code-hookkit init --dry-run          # preview without writing
+```
+
+### `claude-code-hookkit add <name>`
+
+Install a hook or pack from the bundled registry.
+
+```bash
+claude-code-hookkit add sensitive-path-guard          # single hook
+claude-code-hookkit add security-pack                 # install entire pack
+claude-code-hookkit add cost-tracker --scope user     # user-level install
+claude-code-hookkit add post-edit-lint --dry-run      # preview changes
+```
+
+### `claude-code-hookkit remove <name>`
+
+Remove an installed hook (script + settings.json entry).
+
+```bash
+claude-code-hookkit remove sensitive-path-guard
+claude-code-hookkit remove post-edit-lint --scope user
+claude-code-hookkit remove web-budget-gate --dry-run
+```
+
+### `claude-code-hookkit list`
+
+List all available hooks with installed status, event type, and pack.
+
+```bash
+claude-code-hookkit list
+claude-code-hookkit list --scope user
+```
+
+### `claude-code-hookkit test <hook>`
+
+Test a hook with its bundled fixture data. Validates exit code and output.
+
+```bash
+claude-code-hookkit test sensitive-path-guard         # test single hook
+claude-code-hookkit test --all                        # test all installed hooks
+```
+
+### `claude-code-hookkit create <name>`
+
+Scaffold a custom hook from a template.
+
+```bash
+claude-code-hookkit create my-guard --event PreToolUse --matcher Bash
+claude-code-hookkit create session-logger --event SessionStart
+claude-code-hookkit create cleanup --event Stop
+```
+
+Generates a working shell script with proper shebang, stdin JSON parsing, and a test fixture skeleton.
+
+### `claude-code-hookkit doctor`
+
+Validate installation health: script existence, permissions, settings.json validity, conflicting hooks.
+
+```bash
+claude-code-hookkit doctor
+claude-code-hookkit doctor --scope user
+```
+
+### `claude-code-hookkit restore`
+
+Revert settings.json to the last backup (created automatically before every write).
+
+```bash
+claude-code-hookkit restore
+claude-code-hookkit restore --scope user
+```
+
+### `claude-code-hookkit info <hook>`
+
+Show full details for a hook: description, event, matcher, pack, and example input JSON.
+
+```bash
+claude-code-hookkit info sensitive-path-guard
+claude-code-hookkit info web-budget-gate
+```
+
+---
+
+## Hook Registry
+
+All 7 bundled hooks ship with the package — no network required.
+
+| Hook | Description | Event | Matcher | Pack |
+|------|-------------|-------|---------|------|
+| `sensitive-path-guard` | Blocks writes to .env, credentials, private keys | PreToolUse | Edit\|Write | security-pack |
+| `exit-code-enforcer` | Blocks known-dangerous shell commands (rm -rf /, fork bombs, etc.) | PreToolUse | Bash | security-pack |
+| `post-edit-lint` | Runs linter on files after Claude edits them | PostToolUse | Write\|Edit | quality-pack |
+| `ts-check` | Runs TypeScript type checking after code changes | PostToolUse | Write\|Edit | quality-pack |
+| `web-budget-gate` | Limits web search/fetch calls per session to control costs | PreToolUse | WebSearch\|WebFetch | cost-pack |
+| `cost-tracker` | Tracks tool usage costs per session | PostToolUse | — | cost-pack |
+| `error-advisor` | Provides contextual fix suggestions when commands fail | PostToolUse | Bash | error-pack |
+
+---
+
+## Packs
+
+Install related hooks together in one command.
+
+### `security-pack`
+
+Essential security hooks. Blocks writes to sensitive files and dangerous shell commands.
+
+```bash
+claude-code-hookkit add security-pack
+```
+
+Includes: `sensitive-path-guard`, `exit-code-enforcer`
+
+### `quality-pack`
+
+Code quality hooks that run automatically after Claude edits files.
+
+```bash
+claude-code-hookkit add quality-pack
+```
+
+Includes: `post-edit-lint`, `ts-check`
+
+### `cost-pack`
+
+Cost control hooks. Limit web calls per session and track tool usage.
+
+```bash
+claude-code-hookkit add cost-pack
+```
+
+Includes: `web-budget-gate`, `cost-tracker`
+
+### `error-pack`
+
+Error recovery. When a Bash command fails, this hook analyzes the output and suggests contextual fixes.
+
+```bash
+claude-code-hookkit add error-pack
+```
+
+Includes: `error-advisor`
+
+---
+
+## How Hooks Work
+
+Claude Code evaluates hooks from your `settings.json`. Example entry added by `claude-code-hookkit add`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "/path/to/.claude/hooks/sensitive-path-guard.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Exit codes:**
+- `0` — allow the operation (or advisory-only PostToolUse hook)
+- `2` — block the operation (Claude Code spec; exit 1 does not block)
+
+**Input format:** Claude Code passes JSON via stdin. Hooks read it with `INPUT=$(cat)` and parse fields with `grep`/`sed` (no `jq` required — POSIX-compatible).
+
+---
+
+## Creating Custom Hooks
+
+Scaffold a hook with the right structure:
+
+```bash
+claude-code-hookkit create my-guard --event PreToolUse --matcher Bash
+```
+
+This creates:
+- `.claude/hooks/my-guard.sh` — working hook script
+- `.claude/hooks/fixtures/my-guard/allow-example.json` — test fixture skeleton
+
+The generated script handles stdin JSON parsing, includes commented examples, and uses the correct exit codes. Edit the pattern-matching logic and add your fixture test cases, then run:
+
+```bash
+claude-code-hookkit test my-guard
+```
+
+### Hook Template Pattern
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+
+# Extract what you need from tool JSON
+VALUE=$(printf '%s' "$INPUT" | grep -o '"field"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"//; s/"//')
+
+# Your logic here
+if [[ "$VALUE" == "bad-value" ]]; then
+  printf 'BLOCKED: reason\n' >&2
+  exit 2
+fi
+
+exit 0
+```
+
+### Fixture Format
+
+```json
+{
+  "description": "What this fixture tests",
+  "input": { "tool_input": { "file_path": ".env" } },
+  "expectedExitCode": 2
+}
+```
+
+---
+
+## Settings Scope
+
+All commands support `--scope`:
+
+| Scope | Settings File | Hook Directory |
+|-------|---------------|----------------|
+| `project` (default) | `.claude/settings.json` | `.claude/hooks/` |
+| `user` | `~/.claude/settings.json` | `~/.claude/hooks/` |
+| `local` | `.claude/settings.local.json` | `.claude/hooks/` |
+
+`add` and `init` always perform a deep merge — your existing settings are never overwritten.
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Add your hook to `registry/hooks/` with inline comments
+3. Add metadata to `registry/registry.json`
+4. Add test fixtures to `registry/hooks/fixtures/<hook-name>/`
+5. Run `npm test` — all fixtures must pass
+6. Submit a PR with a description of what the hook does and why it's useful
+
+Hooks must be:
+- POSIX-compatible (macOS bash 3.2 + Linux bash 5.x)
+- No external dependencies (no `jq`, no `python`, no `node`)
+- Exit code 2 to block, exit code 0 to allow
+- Include at least one allow fixture and one block fixture
+
+---
+
+## License
+
+MIT — Copyright (c) 2026 Austin Amelone

package/dist/add-O4OSFQ76.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import {
+  log
+} from "./chunk-2BZZUQQ3.js";
+import {
+  applyMerge
+} from "./chunk-LRXKKJDU.js";
+import "./chunk-QKT647BI.js";
+import {
+  getHook,
+  getPack
+} from "./chunk-XLX5K6TZ.js";
+import {
+  getHooksDir,
+  getSettingsPath
+} from "./chunk-PEDGREZY.js";
+
+// src/commands/add.ts
+import { copyFile, chmod, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+function getDefaultSourceHooksDir() {
+  const __filename = fileURLToPath(import.meta.url);
+  let dir = dirname(__filename);
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "registry", "hooks");
+    if (existsSync(candidate)) return candidate;
+    const parent = resolve(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join(dirname(__filename), "..", "..", "registry", "hooks");
+}
+async function _addAt(opts) {
+  const { settingsPath, hooksDir, hookName, dryRun = false } = opts;
+  const sourceHooksDir = opts.sourceHooksDir ?? getDefaultSourceHooksDir();
+  const hook = getHook(hookName);
+  if (!hook) {
+    log.error(`Unknown hook: "${hookName}". Run "claude-code-hookkit list" to see available hooks.`);
+    return;
+  }
+  const srcPath = join(sourceHooksDir, hook.scriptFile);
+  const destPath = join(hooksDir, hook.scriptFile);
+  if (dryRun) {
+    log.dryRun(`Would copy: ${srcPath} -> ${destPath}`);
+    log.dryRun(`Would chmod +x: ${destPath}`);
+    log.dryRun(`Would add ${hook.event}${hook.matcher ? ` [${hook.matcher}]` : ""} hook to settings.json`);
+    return;
+  }
+  await mkdir(hooksDir, { recursive: true });
+  const result = await applyMerge({
+    settingsPath,
+    newHooks: [
+      {
+        event: hook.event,
+        matcher: hook.matcher,
+        hook: { type: "command", command: destPath }
+      }
+    ],
+    dryRun: false
+  });
+  if (result.added.length > 0) {
+    await copyFile(srcPath, destPath);
+    await chmod(destPath, 493);
+  }
+  if (result.added.length > 0) {
+    log.success(`Installed hook: ${hook.name}`);
+    log.dim(`  Script: ${destPath}`);
+    if (hook.pack) {
+      log.dim(`  Pack: ${hook.pack}`);
+    }
+    log.dim(`  Event: ${hook.event}${hook.matcher ? ` [matcher: ${hook.matcher}]` : ""}`);
+  } else if (result.skipped.length > 0) {
+    log.warn(`Hook "${hook.name}" is already installed (skipped).`);
+  }
+}
+async function _addPackAt(opts) {
+  const { settingsPath, hooksDir, packName, dryRun = false } = opts;
+  const sourceHooksDir = opts.sourceHooksDir ?? getDefaultSourceHooksDir();
+  const pack = getPack(packName);
+  if (!pack) {
+    log.error(`Unknown hook or pack: "${packName}". Run "claude-code-hookkit list" to see available options.`);
+    return;
+  }
+  log.info(`Installing ${packName} (${pack.hooks.length} hooks)...`);
+  const installed = [];
+  const skipped = [];
+  for (const hookName of pack.hooks) {
+    const hook = getHook(hookName);
+    if (!hook) {
+      log.warn(`Pack "${packName}" references unknown hook "${hookName}" \u2014 skipping.`);
+      continue;
+    }
+    if (dryRun) {
+      const srcPath = join(sourceHooksDir, hook.scriptFile);
+      const destPath = join(hooksDir, hook.scriptFile);
+      log.dryRun(`Would install hook: ${hookName}`);
+      log.dryRun(`  ${srcPath} -> ${destPath}`);
+      installed.push(hookName);
+      continue;
+    }
+    await _addAt({ settingsPath, hooksDir, sourceHooksDir, hookName, dryRun });
+    installed.push(hookName);
+  }
+  if (!dryRun) {
+    log.success(`Installed ${packName} (${installed.length} hooks): ${installed.join(", ")}`);
+  }
+}
+async function addCommand(opts) {
+  const validScopes = ["user", "project", "local"];
+  const scope = validScopes.includes(opts.scope) ? opts.scope : "project";
+  const settingsPath = getSettingsPath(scope);
+  const hooksDir = getHooksDir(scope);
+  if (getPack(opts.hookName)) {
+    await _addPackAt({
+      settingsPath,
+      hooksDir,
+      packName: opts.hookName,
+      dryRun: opts.dryRun
+    });
+    return;
+  }
+  if (getHook(opts.hookName)) {
+    await _addAt({
+      settingsPath,
+      hooksDir,
+      hookName: opts.hookName,
+      dryRun: opts.dryRun
+    });
+    return;
+  }
+  log.error(`Unknown hook or pack: "${opts.hookName}". Run "claude-code-hookkit list" to see available options.`);
+}
+export {
+  _addAt,
+  _addPackAt,
+  addCommand
+};

package/dist/chunk-2BZZUQQ3.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+// src/utils/logger.ts
+import pc from "picocolors";
+var log = {
+  /** Standard informational message */
+  info(msg) {
+    console.log(msg);
+  },
+  /** Success message in green */
+  success(msg) {
+    console.log(pc.green(msg));
+  },
+  /** Warning message in yellow */
+  warn(msg) {
+    console.warn(pc.yellow(msg));
+  },
+  /** Error message in red (to stderr) */
+  error(msg) {
+    console.error(pc.red(msg));
+  },
+  /** Dimmed/secondary text */
+  dim(msg) {
+    console.log(pc.dim(msg));
+  },
+  /** Dry-run prefixed message in yellow */
+  dryRun(msg) {
+    console.log(pc.yellow("[DRY RUN]") + " " + msg);
+  }
+};
+
+export {
+  log
+};

package/dist/chunk-LRXKKJDU.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import {
+  createBackup
+} from "./chunk-QKT647BI.js";
+
+// src/config/manager.ts
+import { readFile, writeFile } from "fs/promises";
+
+// src/config/merger.ts
+function isDuplicate(groups, matcher, command) {
+  return groups.some((group) => {
+    const matcherMatches = group.matcher === matcher;
+    const commandMatches = group.hooks.some((h) => h.command === command);
+    return matcherMatches && commandMatches;
+  });
+}
+function mergeHooks(input) {
+  const settings = structuredClone(input.existing);
+  const added = [];
+  const skipped = [];
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+  for (const { event, matcher, hook } of input.newHooks) {
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = [];
+    }
+    const existingGroups = settings.hooks[event];
+    if (isDuplicate(existingGroups, matcher, hook.command)) {
+      skipped.push({
+        event,
+        matcher,
+        command: hook.command,
+        reason: "Already exists (same event + matcher + command)"
+      });
+      continue;
+    }
+    const newGroup = {
+      ...matcher !== void 0 ? { matcher } : {},
+      hooks: [{ type: hook.type, command: hook.command }]
+    };
+    existingGroups.push(newGroup);
+    added.push({ event, matcher, command: hook.command });
+  }
+  return { settings, added, skipped };
+}
+
+// src/config/manager.ts
+function detectIndent(raw) {
+  const lines = raw.split("\n");
+  for (const line of lines.slice(1)) {
+    if (line.startsWith("	")) return "	";
+    const match = line.match(/^( +)/);
+    if (match) return match[1].length;
+  }
+  return 2;
+}
+async function readSettings(path) {
+  try {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      return {};
+    }
+    throw err;
+  }
+}
+async function writeSettings(path, settings, originalRaw) {
+  const indent = originalRaw ? detectIndent(originalRaw) : 2;
+  const output = JSON.stringify(settings, null, indent) + "\n";
+  await writeFile(path, output, "utf8");
+}
+async function applyMerge(opts) {
+  const { settingsPath, newHooks, dryRun = false } = opts;
+  let originalRaw;
+  let existing;
+  try {
+    originalRaw = await readFile(settingsPath, "utf8");
+    existing = JSON.parse(originalRaw);
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      existing = {};
+      originalRaw = void 0;
+    } else {
+      throw err;
+    }
+  }
+  const result = mergeHooks({ existing, newHooks });
+  if (!dryRun) {
+    await createBackup(settingsPath);
+    await writeSettings(settingsPath, result.settings, originalRaw);
+  }
+  return result;
+}
+
+export {
+  readSettings,
+  writeSettings,
+  applyMerge
+};

package/dist/chunk-PEDGREZY.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+// src/config/locator.ts
+import { homedir } from "os";
+import { join, resolve, dirname } from "path";
+import { existsSync } from "fs";
+function findProjectRoot() {
+  const home = homedir();
+  let dir = resolve(process.cwd());
+  while (true) {
+    if (existsSync(join(dir, ".git"))) {
+      return dir;
+    }
+    if (dir !== home && existsSync(join(dir, ".claude"))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+function getSettingsPath(scope) {
+  switch (scope) {
+    case "user":
+      return join(homedir(), ".claude", "settings.json");
+    case "project":
+      return resolve(findProjectRoot(), ".claude", "settings.json");
+    case "local":
+      return resolve(findProjectRoot(), ".claude", "settings.local.json");
+  }
+}
+function getHooksDir(scope) {
+  switch (scope) {
+    case "user":
+      return join(homedir(), ".claude", "hooks");
+    case "project":
+    case "local":
+      return resolve(findProjectRoot(), ".claude", "hooks");
+  }
+}
+
+export {
+  getSettingsPath,
+  getHooksDir
+};

package/dist/chunk-QKT647BI.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+// src/config/backup.ts
+import { copyFile, access } from "fs/promises";
+import { constants } from "fs";
+async function createBackup(settingsPath) {
+  const backupPath = settingsPath + ".backup";
+  try {
+    await access(settingsPath, constants.F_OK);
+    await copyFile(settingsPath, backupPath);
+    return backupPath;
+  } catch {
+    return "";
+  }
+}
+async function restoreBackup(settingsPath) {
+  const backupPath = settingsPath + ".backup";
+  try {
+    await access(backupPath, constants.F_OK);
+    await copyFile(backupPath, settingsPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  createBackup,
+  restoreBackup
+};