@goodfoot/claude-code-hooks 1.0.1

package/types/scaffold.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Scaffold module for generating new Claude Code hook projects.
+ *
+ * Generates a complete TypeScript project structure with:
+ * - package.json with dependencies and scripts
+ * - tsconfig.json with ESM/Node20 configuration
+ * - biome.json for linting/formatting
+ * - Hook template files for each requested hook type
+ * - Vitest test files for each hook
+ * - vitest.config.ts for test configuration
+ * @module
+ * @example
+ * ```bash
+ * npx @goodfoot/claude-code-hooks --scaffold ./my-hooks --hooks Stop,SubagentStop -o dist/hooks.json
+ * ```
+ */
+/**
+ * Options for scaffolding a new hook project.
+ */
+export interface ScaffoldOptions {
+  /** Directory path where the project will be created. */
+  directory: string;
+  /** Array of hook event names to generate (e.g., ['Stop', 'SubagentStop']). */
+  hooks: string[];
+  /** Relative path for hooks.json output in the build script. */
+  outputPath: string;
+}
+/**
+ * Scaffolds a new Claude Code hook project.
+ *
+ * Creates the complete project structure including:
+ * - package.json, tsconfig.json, biome.json, vitest.config.ts
+ * - src/ directory with hook implementations
+ * - test/ directory with vitest tests
+ * @param options - Scaffold configuration options
+ * @throws Exits with code 1 if directory exists or hook names are invalid
+ * @example
+ * ```typescript
+ * scaffoldProject({
+ *   directory: './my-hooks',
+ *   hooks: ['Stop', 'SubagentStop'],
+ *   outputPath: 'dist/hooks.json'
+ * });
+ * ```
+ */
+export declare function scaffoldProject(options: ScaffoldOptions): void;

package/types/tool-helpers.d.ts

@@ -0,0 +1,336 @@
+/**
+ * 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
+ */
+import type { PreToolUseInput, PostToolUseInput, PostToolUseFailureInput, PermissionRequestInput } from './inputs.js';
+import type {
+  WriteToolInput,
+  EditToolInput,
+  MultiEditToolInput,
+  ReadToolInput,
+  BashToolInput,
+  GlobToolInput,
+  GrepToolInput,
+  FileModifyingToolInput,
+  FileModifyingToolName
+} from './tool-inputs.js';
+/**
+ * Union of all hook input types that include tool_input.
+ */
+export type ToolUseInput = PreToolUseInput | PostToolUseInput | PostToolUseFailureInput | PermissionRequestInput;
+/**
+ * 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 declare function isWriteTool<T extends ToolUseInput>(
+  input: T
+): input is T & {
+  tool_name: 'Write';
+  tool_input: WriteToolInput;
+};
+/**
+ * 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 declare function isEditTool<T extends ToolUseInput>(
+  input: T
+): input is T & {
+  tool_name: 'Edit';
+  tool_input: EditToolInput;
+};
+/**
+ * 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 declare function isMultiEditTool<T extends ToolUseInput>(
+  input: T
+): input is T & {
+  tool_name: 'MultiEdit';
+  tool_input: MultiEditToolInput;
+};
+/**
+ * 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 declare function isFileModifyingTool<T extends ToolUseInput>(
+  input: T
+): input is T & {
+  tool_name: FileModifyingToolName;
+  tool_input: FileModifyingToolInput;
+};
+/**
+ * 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 declare function isReadTool<T extends ToolUseInput>(
+  input: T
+): input is T & {
+  tool_name: 'Read';
+  tool_input: ReadToolInput;
+};
+/**
+ * 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 declare function isBashTool<T extends ToolUseInput>(
+  input: T
+): input is T & {
+  tool_name: 'Bash';
+  tool_input: BashToolInput;
+};
+/**
+ * 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 declare function isGlobTool<T extends ToolUseInput>(
+  input: T
+): input is T & {
+  tool_name: 'Glob';
+  tool_input: GlobToolInput;
+};
+/**
+ * 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 declare function isGrepTool<T extends ToolUseInput>(
+  input: T
+): input is T & {
+  tool_name: 'Grep';
+  tool_input: GrepToolInput;
+};
+/**
+ * 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 declare function getFilePath(input: ToolUseInput): string | 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 declare function isJsTsFile(filePath: string): boolean;
+/**
+ * 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 declare function isTsFile(filePath: string): boolean;
+/**
+ * Result of checking content for a pattern.
+ */
+export interface PatternCheckResult {
+  /** True if the pattern was found in any content. */
+  found: boolean;
+  /** True if the pattern is being added (not present in old content, present in new). */
+  isAddition: boolean;
+  /** All matches found across all content (deduplicated). */
+  matches: string[];
+  /** Per-edit details for MultiEdit operations. */
+  details?: Array<{
+    /** Index of the edit (for MultiEdit) or 0 for Write/Edit. */
+    index: number;
+    /** True if found in this edit. */
+    found: boolean;
+    /** True if this edit adds the pattern. */
+    isAddition: boolean;
+    /** Matches in this edit. */
+    matches: string[];
+  }>;
+}
+/**
+ * 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 declare function checkContentForPattern(input: PreToolUseInput, pattern: RegExp): PatternCheckResult | null;
+/**
+ * Context passed to the forEachContent callback.
+ */
+export interface ContentContext {
+  /** The new content being written or replacing old content. */
+  newContent: string;
+  /** The old content being replaced (null for Write). */
+  oldContent: string | null;
+  /** Index of the edit (0 for Write/Edit, index for MultiEdit). */
+  index: number;
+  /** True if this is a Write operation (not Edit/MultiEdit). */
+  isWrite: boolean;
+}
+/**
+ * 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 declare function forEachContent(input: PreToolUseInput, callback: (ctx: ContentContext) => boolean): boolean;

package/types/tool-inputs.d.ts

@@ -0,0 +1,228 @@
+/**
+ * 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
+ */
+/**
+ * Input structure for the Write tool.
+ *
+ * The Write tool creates or overwrites files with the specified content.
+ * @example
+ * ```typescript
+ * // Example tool input
+ * {
+ *   file_path: '/workspace/src/index.ts',
+ *   content: 'export const hello = "world";'
+ * }
+ * ```
+ */
+export interface WriteToolInput {
+  /** Absolute path to the file to write. */
+  file_path: string;
+  /** The content to write to the file. */
+  content: string;
+}
+/**
+ * Input structure for the Edit tool.
+ *
+ * The Edit tool performs search-and-replace operations on files.
+ * @example
+ * ```typescript
+ * // Example tool input
+ * {
+ *   file_path: '/workspace/src/index.ts',
+ *   old_string: 'const x = 1;',
+ *   new_string: 'const x = 2;',
+ *   replace_all: false
+ * }
+ * ```
+ */
+export interface EditToolInput {
+  /** Absolute path to the file to edit. */
+  file_path: string;
+  /** The text to search for (must be unique in the file unless replace_all is true). */
+  old_string: string;
+  /** The text to replace old_string with. */
+  new_string: string;
+  /** If true, replace all occurrences. If false, old_string must be unique. */
+  replace_all?: boolean;
+}
+/**
+ * A single edit entry within a MultiEdit operation.
+ */
+export interface MultiEditEntry {
+  /** The text to search for. */
+  old_string: string;
+  /** The text to replace old_string with. */
+  new_string: string;
+}
+/**
+ * Input structure for the MultiEdit tool.
+ *
+ * The MultiEdit tool performs multiple search-and-replace operations on a single file.
+ * All edits are applied atomically.
+ * @example
+ * ```typescript
+ * // Example tool input
+ * {
+ *   file_path: '/workspace/src/index.ts',
+ *   edits: [
+ *     { old_string: 'const x = 1;', new_string: 'const x = 2;' },
+ *     { old_string: 'const y = 1;', new_string: 'const y = 2;' }
+ *   ]
+ * }
+ * ```
+ */
+export interface MultiEditToolInput {
+  /** Absolute path to the file to edit. */
+  file_path: string;
+  /** Array of edit operations to apply. */
+  edits: MultiEditEntry[];
+}
+/**
+ * Input structure for the Read tool.
+ *
+ * The Read tool reads file contents, optionally with offset and limit.
+ * @example
+ * ```typescript
+ * // Example tool input
+ * {
+ *   file_path: '/workspace/src/index.ts',
+ *   offset: 0,
+ *   limit: 100
+ * }
+ * ```
+ */
+export interface ReadToolInput {
+  /** Absolute path to the file to read. */
+  file_path: string;
+  /** Line offset to start reading from. */
+  offset?: number;
+  /** Maximum number of lines to read. */
+  limit?: number;
+}
+/**
+ * Input structure for the Bash tool.
+ *
+ * The Bash tool executes shell commands.
+ * @example
+ * ```typescript
+ * // Example tool input
+ * {
+ *   command: 'npm install',
+ *   timeout: 60000,
+ *   description: 'Install dependencies'
+ * }
+ * ```
+ */
+export interface BashToolInput {
+  /** The command to execute. */
+  command: string;
+  /** Optional timeout in milliseconds. */
+  timeout?: number;
+  /** Optional description of what the command does. */
+  description?: string;
+}
+/**
+ * Input structure for the Glob tool.
+ *
+ * The Glob tool finds files matching a glob pattern.
+ * @example
+ * ```typescript
+ * // Example tool input
+ * {
+ *   pattern: '**\/*.ts',
+ *   path: '/workspace/src'
+ * }
+ * ```
+ */
+export interface GlobToolInput {
+  /** Glob pattern to match files against. */
+  pattern: string;
+  /** Directory to search in (defaults to cwd). */
+  path?: string;
+}
+/**
+ * Input structure for the Grep tool.
+ *
+ * The Grep tool searches file contents using regex patterns.
+ * @example
+ * ```typescript
+ * // Example tool input
+ * {
+ *   pattern: 'function\\s+\\w+',
+ *   path: '/workspace/src',
+ *   glob: '*.ts'
+ * }
+ * ```
+ */
+export interface GrepToolInput {
+  /** Regular expression pattern to search for. */
+  pattern: string;
+  /** Directory to search in (defaults to cwd). */
+  path?: string;
+  /** Glob pattern to filter files. */
+  glob?: string;
+}
+/**
+ * Union of all file-modifying tool inputs.
+ *
+ * Use this type when you need to handle Write, Edit, or MultiEdit generically.
+ */
+export type FileModifyingToolInput = WriteToolInput | EditToolInput | MultiEditToolInput;
+/**
+ * Tool names for file-modifying tools.
+ *
+ * Use this type when you need to reference the tool name in type guards.
+ */
+export type FileModifyingToolName = 'Write' | 'Edit' | 'MultiEdit';
+/**
+ * Union of all known tool inputs.
+ *
+ * This includes all tool inputs that have well-defined type structures.
+ */
+export type KnownToolInput =
+  | WriteToolInput
+  | EditToolInput
+  | MultiEditToolInput
+  | ReadToolInput
+  | BashToolInput
+  | GlobToolInput
+  | GrepToolInput;
+/**
+ * Tool names for all known tools with typed inputs.
+ */
+export type KnownToolName = 'Write' | 'Edit' | 'MultiEdit' | 'Read' | 'Bash' | 'Glob' | 'Grep';
+/**
+ * Type mapping from tool name to tool input type.
+ *
+ * Used by typed factory overloads to provide automatic typing.
+ * @example
+ * ```typescript
+ * type WriteInput = ToolInputMap['Write']; // WriteToolInput
+ * ```
+ */
+export interface ToolInputMap {
+  Write: WriteToolInput;
+  Edit: EditToolInput;
+  MultiEdit: MultiEditToolInput;
+  Read: ReadToolInput;
+  Bash: BashToolInput;
+  Glob: GlobToolInput;
+  Grep: GrepToolInput;
+}