@goodfoot/claude-code-hooks 1.0.1

package/dist/tool-helpers.js

@@ -0,0 +1,366 @@
+/**
+ * Type guards and helper functions for Claude Code tool inputs.
+ *
+ * Provides safe type narrowing for tool inputs and utility functions
+ * for common patterns like file path extraction and content inspection.
+ * @example
+ * ```typescript
+ * import {
+ *   preToolUseHook,
+ *   preToolUseOutput,
+ *   isWriteTool,
+ *   getFilePath,
+ *   isTsFile,
+ *   checkContentForPattern
+ * } from '@goodfoot/claude-code-hooks';
+ *
+ * export default preToolUseHook({ matcher: 'Write|Edit|MultiEdit' }, (input) => {
+ *   const filePath = getFilePath(input);
+ *   if (!filePath || !isTsFile(filePath)) return preToolUseOutput({});
+ *
+ *   const result = checkContentForPattern(input, /@ts-ignore/g);
+ *   if (result?.isAddition) {
+ *     return preToolUseOutput({
+ *       hookSpecificOutput: {
+ *         permissionDecision: 'deny',
+ *         permissionDecisionReason: `Cannot add: ${result.matches.join(', ')}`
+ *       }
+ *     });
+ *   }
+ *
+ *   return preToolUseOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ * @module
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard for Write tool inputs.
+ *
+ * Narrows the input type to include a typed WriteToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Write tool
+ * @example
+ * ```typescript
+ * if (isWriteTool(input)) {
+ *   // input.tool_input is now typed as WriteToolInput
+ *   console.log(input.tool_input.file_path);
+ *   console.log(input.tool_input.content);
+ * }
+ * ```
+ */
+export function isWriteTool(input) {
+  return input.tool_name === 'Write';
+}
+/**
+ * Type guard for Edit tool inputs.
+ *
+ * Narrows the input type to include a typed EditToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for an Edit tool
+ * @example
+ * ```typescript
+ * if (isEditTool(input)) {
+ *   console.log(input.tool_input.old_string);
+ *   console.log(input.tool_input.new_string);
+ * }
+ * ```
+ */
+export function isEditTool(input) {
+  return input.tool_name === 'Edit';
+}
+/**
+ * Type guard for MultiEdit tool inputs.
+ *
+ * Narrows the input type to include a typed MultiEditToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a MultiEdit tool
+ * @example
+ * ```typescript
+ * if (isMultiEditTool(input)) {
+ *   for (const edit of input.tool_input.edits) {
+ *     console.log(`${edit.old_string} -> ${edit.new_string}`);
+ *   }
+ * }
+ * ```
+ */
+export function isMultiEditTool(input) {
+  return input.tool_name === 'MultiEdit';
+}
+/**
+ * Type guard for any file-modifying tool (Write, Edit, or MultiEdit).
+ *
+ * Use this when you need to handle all file modifications generically.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Write, Edit, or MultiEdit tool
+ * @example
+ * ```typescript
+ * if (isFileModifyingTool(input)) {
+ *   const filePath = getFilePath(input); // Works for all three types
+ * }
+ * ```
+ */
+export function isFileModifyingTool(input) {
+  return input.tool_name === 'Write' || input.tool_name === 'Edit' || input.tool_name === 'MultiEdit';
+}
+/**
+ * Type guard for Read tool inputs.
+ *
+ * Narrows the input type to include a typed ReadToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Read tool
+ * @example
+ * ```typescript
+ * if (isReadTool(input)) {
+ *   console.log(input.tool_input.file_path);
+ *   console.log(input.tool_input.offset);
+ * }
+ * ```
+ */
+export function isReadTool(input) {
+  return input.tool_name === 'Read';
+}
+/**
+ * Type guard for Bash tool inputs.
+ *
+ * Narrows the input type to include a typed BashToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Bash tool
+ * @example
+ * ```typescript
+ * if (isBashTool(input)) {
+ *   console.log(input.tool_input.command);
+ *   console.log(input.tool_input.timeout);
+ * }
+ * ```
+ */
+export function isBashTool(input) {
+  return input.tool_name === 'Bash';
+}
+/**
+ * Type guard for Glob tool inputs.
+ *
+ * Narrows the input type to include a typed GlobToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Glob tool
+ * @example
+ * ```typescript
+ * if (isGlobTool(input)) {
+ *   console.log(input.tool_input.pattern);
+ *   console.log(input.tool_input.path);
+ * }
+ * ```
+ */
+export function isGlobTool(input) {
+  return input.tool_name === 'Glob';
+}
+/**
+ * Type guard for Grep tool inputs.
+ *
+ * Narrows the input type to include a typed GrepToolInput.
+ * @param input - The hook input to check
+ * @returns True if the input is for a Grep tool
+ * @example
+ * ```typescript
+ * if (isGrepTool(input)) {
+ *   console.log(input.tool_input.pattern);
+ *   console.log(input.tool_input.glob);
+ * }
+ * ```
+ */
+export function isGrepTool(input) {
+  return input.tool_name === 'Grep';
+}
+// ============================================================================
+// File Path Utilities
+// ============================================================================
+/**
+ * Extracts the file path from a tool input.
+ *
+ * Works with Write, Edit, MultiEdit, and Read tools.
+ * Returns null for other tools or if file_path is missing.
+ * @param input - The hook input to extract from
+ * @returns The file path, or null if not applicable
+ * @example
+ * ```typescript
+ * const filePath = getFilePath(input);
+ * if (filePath && isTsFile(filePath)) {
+ *   // Handle TypeScript file
+ * }
+ * ```
+ */
+export function getFilePath(input) {
+  const toolInput = input.tool_input;
+  if (toolInput && typeof toolInput === 'object' && 'file_path' in toolInput) {
+    const filePath = toolInput.file_path;
+    return typeof filePath === 'string' ? filePath : null;
+  }
+  return null;
+}
+/**
+ * Checks if a file path is a JavaScript or TypeScript file.
+ *
+ * Matches .js, .jsx, .ts, .tsx, .mjs, .mts, .cjs, .cts extensions.
+ * @param filePath - The file path to check
+ * @returns True if the file is JavaScript or TypeScript
+ * @example
+ * ```typescript
+ * if (isJsTsFile(filePath)) {
+ *   // Check for TypeScript-specific patterns
+ * }
+ * ```
+ */
+export function isJsTsFile(filePath) {
+  return /\.[cm]?[jt]sx?$/.test(filePath);
+}
+/**
+ * Checks if a file path is a TypeScript file.
+ *
+ * Matches .ts, .tsx, .mts, .cts extensions.
+ * @param filePath - The file path to check
+ * @returns True if the file is TypeScript
+ * @example
+ * ```typescript
+ * if (isTsFile(filePath)) {
+ *   // Enforce TypeScript-specific rules
+ * }
+ * ```
+ */
+export function isTsFile(filePath) {
+  return /\.[cm]?tsx?$/.test(filePath);
+}
+/**
+ * Checks if a pattern exists in the content being written or edited.
+ *
+ * For Write: checks the content being written
+ * For Edit: checks new_string (and old_string to detect additions)
+ * For MultiEdit: checks all edits and aggregates results
+ * @param input - The PreToolUse hook input
+ * @param pattern - The regex pattern to search for (global flag will be used)
+ * @returns Result object, or null if not a file-modifying tool
+ * @example
+ * ```typescript
+ * // Block @ts-ignore being added
+ * const result = checkContentForPattern(input, /@ts-ignore/g);
+ * if (result?.isAddition) {
+ *   return preToolUseOutput({
+ *     hookSpecificOutput: {
+ *       permissionDecision: 'deny',
+ *       permissionDecisionReason: `Cannot add: ${result.matches.join(', ')}`
+ *     }
+ *   });
+ * }
+ * ```
+ */
+export function checkContentForPattern(input, pattern) {
+  // Ensure pattern has global flag for matchAll
+  const globalPattern = pattern.global ? pattern : new RegExp(pattern.source, pattern.flags + 'g');
+  if (isWriteTool(input)) {
+    const matches = [...input.tool_input.content.matchAll(globalPattern)].map((m) => m[0]);
+    const uniqueMatches = [...new Set(matches)];
+    return {
+      found: uniqueMatches.length > 0,
+      isAddition: uniqueMatches.length > 0, // For Write, any match is an addition
+      matches: uniqueMatches
+    };
+  }
+  if (isEditTool(input)) {
+    const newMatches = [...input.tool_input.new_string.matchAll(globalPattern)].map((m) => m[0]);
+    const oldMatches = [...input.tool_input.old_string.matchAll(globalPattern)].map((m) => m[0]);
+    const uniqueNewMatches = [...new Set(newMatches)];
+    const uniqueOldMatches = new Set(oldMatches);
+    // Addition = found in new but not in old
+    const additions = uniqueNewMatches.filter((m) => !uniqueOldMatches.has(m));
+    return {
+      found: uniqueNewMatches.length > 0,
+      isAddition: additions.length > 0,
+      matches: uniqueNewMatches
+    };
+  }
+  if (isMultiEditTool(input)) {
+    const details = [];
+    const allMatches = new Set();
+    let anyFound = false;
+    let anyAddition = false;
+    for (let i = 0; i < input.tool_input.edits.length; i++) {
+      const edit = input.tool_input.edits[i];
+      const newMatches = [...edit.new_string.matchAll(globalPattern)].map((m) => m[0]);
+      const oldMatches = [...edit.old_string.matchAll(globalPattern)].map((m) => m[0]);
+      const uniqueNewMatches = [...new Set(newMatches)];
+      const uniqueOldMatches = new Set(oldMatches);
+      const additions = uniqueNewMatches.filter((m) => !uniqueOldMatches.has(m));
+      const found = uniqueNewMatches.length > 0;
+      const isAddition = additions.length > 0;
+      if (found) anyFound = true;
+      if (isAddition) anyAddition = true;
+      uniqueNewMatches.forEach((m) => allMatches.add(m));
+      details.push({
+        index: i,
+        found,
+        isAddition,
+        matches: uniqueNewMatches
+      });
+    }
+    return {
+      found: anyFound,
+      isAddition: anyAddition,
+      matches: [...allMatches],
+      details
+    };
+  }
+  return null;
+}
+/**
+ * Iterates over content in Write/Edit/MultiEdit operations.
+ *
+ * Provides a unified way to inspect content regardless of operation type.
+ * Return false from the callback to stop iteration early.
+ * @param input - The PreToolUse hook input
+ * @param callback - Function called for each content piece, return false to stop
+ * @returns True if all callbacks returned true, false if stopped early or not applicable
+ * @example
+ * ```typescript
+ * // Check all content for sensitive data
+ * const hasSensitive = !forEachContent(input, ({ newContent }) => {
+ *   if (/password|secret|api.?key/i.test(newContent)) {
+ *     return false; // Stop - found sensitive data
+ *   }
+ *   return true; // Continue
+ * });
+ * ```
+ */
+export function forEachContent(input, callback) {
+  if (isWriteTool(input)) {
+    return callback({
+      newContent: input.tool_input.content,
+      oldContent: null,
+      index: 0,
+      isWrite: true
+    });
+  }
+  if (isEditTool(input)) {
+    return callback({
+      newContent: input.tool_input.new_string,
+      oldContent: input.tool_input.old_string,
+      index: 0,
+      isWrite: false
+    });
+  }
+  if (isMultiEditTool(input)) {
+    for (let i = 0; i < input.tool_input.edits.length; i++) {
+      const edit = input.tool_input.edits[i];
+      const shouldContinue = callback({
+        newContent: edit.new_string,
+        oldContent: edit.old_string,
+        index: i,
+        isWrite: false
+      });
+      if (!shouldContinue) return false;
+    }
+    return true;
+  }
+  return false;
+}

package/dist/tool-inputs.js

@@ -0,0 +1,21 @@
+/**
+ * Type definitions for well-known Claude Code tool inputs.
+ *
+ * These types define the structure of `toolInput` for common Claude Code tools.
+ * Use them with type guards from `tool-helpers.ts` for safe type narrowing,
+ * or with typed hook factory overloads for automatic typing.
+ * @example
+ * ```typescript
+ * import { isWriteTool, getFilePath } from '@goodfoot/claude-code-hooks';
+ *
+ * preToolUseHook({ matcher: 'Write|Edit|MultiEdit' }, (input) => {
+ *   if (isWriteTool(input)) {
+ *     // input.tool_input is now typed as WriteToolInput
+ *     console.log(input.tool_input.file_path);
+ *   }
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ * @module
+ */
+export {};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@goodfoot/claude-code-hooks",
+  "version": "1.0.1",
+  "description": "Type-safe Claude Code hooks library with camelCase types and output builders",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "files": [
+    "dist",
+    "types"
+  ],
+  "scripts": {
+    "prettier": "prettier . --write --log-level warn",
+    "prettier:files": "prettier --write --log-level warn",
+    "eslint": "eslint --cache --fix ./src ./tests ./e2e",
+    "eslint:files": "eslint --cache --fix",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --build tsconfig.build.json",
+    "lint": "bash -c 'if [ $# -eq 0 ]; then yarn typecheck && yarn eslint && yarn prettier; else yarn typecheck && yarn eslint:files \"$@\" && yarn prettier:files \"$@\"; fi' --",
+    "test": "vitest run",
+    "test:types": "vitest run --typecheck",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "release": "bash ../../scripts/release-package.sh claude-code-hooks",
+    "release:dry-run": "bash ../../scripts/release-package.sh claude-code-hooks --dry-run"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./*": {
+      "import": "./src/*.ts",
+      "types": "./src/*.ts"
+    }
+  },
+  "bin": "./dist/cli.js",
+  "publishConfig": {
+    "bin": {
+      "claude-code-hooks": "./dist/cli.js"
+    },
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./types/index.d.ts"
+      },
+      "./*": {
+        "import": "./dist/*.js",
+        "types": "./types/*.d.ts"
+      }
+    }
+  },
+  "dependencies": {
+    "esbuild": "^0.24.0",
+    "glob": "^11.0.0",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.76",
+    "@types/node": "^24",
+    "eslint": "^9.36.0",
+    "eslint-plugin-jsdoc": "^50.0.0",
+    "prettier": "^3.6.2",
+    "tsx": "^4.20.3",
+    "vitest": "4.0.13"
+  }
+}