@goodfoot/claude-code-hooks 1.0.1

package/types/cli.d.ts

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for compiling Claude Code hooks using esbuild.
+ *
+ * Compiles TypeScript hooks to standalone ESM modules and generates hooks.json
+ * with correct command paths and matcher configurations.
+ * @example
+ * ```bash
+ * # Compile hooks and generate hooks.json
+ * claude-code-hooks -i "hooks/**\/*.ts" -o "./dist/hooks.json"
+ *
+ * # With runtime logging (equivalent to CLAUDE_CODE_HOOKS_LOG_FILE)
+ * claude-code-hooks -i "hooks/**\/*.ts" -o "./dist/hooks.json" --log /tmp/hooks.log
+ * ```
+ * @module
+ */
+import type { HookEventName } from './inputs.js';
+import { HOOK_FACTORY_TO_EVENT } from './constants.js';
+/**
+ * Hook context determines how paths are resolved in hooks.json.
+ *
+ * - `plugin`: Uses `$CLAUDE_PLUGIN_ROOT` for plugin hooks
+ * - `agent`: Uses `"$CLAUDE_PROJECT_DIR"` for agent hooks (.claude/hooks/)
+ */
+type HookContext = 'plugin' | 'agent';
+/**
+ * Command-line arguments parsed from process.argv.
+ */
+interface CliArgs {
+  /** Glob pattern for hook source files. */
+  input: string;
+  /** Path for hooks.json output file. */
+  output: string;
+  /** Optional log file path. */
+  log?: string;
+  /** Show help. */
+  help: boolean;
+  /** Show version. */
+  version: boolean;
+  /** Directory path for scaffolding a new hook project. */
+  scaffold?: string;
+  /** Comma-separated list of hook types to generate when scaffolding. */
+  hooks?: string;
+  /** Node executable path to use in command output (default: "node"). */
+  executable?: string;
+}
+/**
+ * Metadata extracted from a hook file via TypeScript AST analysis.
+ */
+interface HookMetadata {
+  /** The hook event type (PreToolUse, SessionStart, etc.). */
+  hookEventName: HookEventName;
+  /** Optional matcher pattern from hook config. */
+  matcher?: string;
+  /** Optional timeout in milliseconds from hook config. */
+  timeout?: number;
+}
+/**
+ * A compiled hook with its metadata and output path.
+ */
+interface CompiledHook {
+  /** Original source file path. */
+  sourcePath: string;
+  /** Compiled output file path. */
+  outputPath: string;
+  /** Output filename (e.g., "my-hook.abc123de.mjs"). */
+  outputFilename: string;
+  /** Extracted hook metadata. */
+  metadata: HookMetadata;
+}
+/**
+ * Individual hook configuration within a matcher group.
+ */
+interface HookConfig {
+  /** Hook type - always "command" for compiled hooks. */
+  type: 'command';
+  /** Absolute path to compiled hook executable. */
+  command: string;
+  /** Optional timeout in seconds. */
+  timeout?: number;
+}
+/**
+ * Matcher group entry within an event type.
+ */
+interface MatcherEntry {
+  /** Matcher pattern (tool name, regex, etc.). Optional for some event types. */
+  matcher?: string;
+  /** Array of hook configurations in this matcher group. */
+  hooks: HookConfig[];
+}
+/**
+ * The complete hooks.json structure expected by Claude Code.
+ *
+ * Format: { hooks: { EventType: [ { matcher?, hooks: [...] } ] } }
+ */
+interface HooksJson {
+  /** Object keyed by event type (PreToolUse, SessionStart, etc.). */
+  hooks: Partial<Record<HookEventName, MatcherEntry[]>>;
+  /** Generated file tracking metadata. */
+  __generated: {
+    /** Array of generated filenames. */
+    files: string[];
+    /** ISO timestamp of generation. */
+    timestamp: string;
+  };
+}
+/**
+ * Parses command-line arguments.
+ * @param argv - Process argv (usually process.argv.slice(2))
+ * @returns Parsed arguments
+ */
+declare function parseArgs(argv: string[]): CliArgs;
+/**
+ * Validates CLI arguments and returns error message if invalid.
+ * @param args - Parsed CLI arguments
+ * @returns Error message if invalid, undefined if valid
+ */
+declare function validateArgs(args: CliArgs): string | undefined;
+/**
+ * Extracts hook metadata from a TypeScript source file using AST analysis.
+ *
+ * Looks for default exports that call hook factory functions (preToolUseHook, etc.)
+ * and extracts the hook type, matcher, and timeout from the config object.
+ * @param sourcePath - Absolute path to the TypeScript source file
+ * @returns Extracted hook metadata or undefined if not a valid hook file
+ * @example
+ * ```typescript
+ * // For a file containing:
+ * // export default preToolUseHook({ matcher: 'Bash', timeout: 5000 }, handler);
+ *
+ * const metadata = analyzeHookFile('/path/to/hook.ts');
+ * // { hookEventName: 'PreToolUse', matcher: 'Bash', timeout: 5000 }
+ * ```
+ */
+declare function analyzeHookFile(sourcePath: string): HookMetadata | undefined;
+/**
+ * Discovers hook files matching the glob pattern.
+ * @param pattern - Glob pattern for hook files
+ * @param cwd - Current working directory for relative patterns
+ * @returns Array of absolute paths to hook files
+ */
+declare function discoverHookFiles(pattern: string, cwd: string): Promise<string[]>;
+/**
+ * Options for compiling a hook.
+ */
+interface CompileHookOptions {
+  /** Absolute path to source file. */
+  sourcePath: string;
+  /** Directory for compiled output. */
+  outputDir: string;
+  /** Optional log file path to inject into compiled hook. */
+  logFilePath?: string;
+}
+/**
+ * Compiles a TypeScript hook file to a self-contained ESM executable.
+ *
+ * Creates a wrapper that imports the hook and calls execute(), then bundles
+ * everything together including the runtime.
+ * @param options - Compilation options
+ * @returns Compiled output content as a string
+ */
+declare function compileHook(options: CompileHookOptions): Promise<string>;
+/**
+ * Generates a content hash (SHA-256, 8-char prefix) for a compiled hook.
+ * @param content - Compiled hook content
+ * @returns 8-character hex hash
+ */
+declare function generateContentHash(content: string): string;
+/**
+ * Groups compiled hooks by event type, then by matcher pattern.
+ * @param compiledHooks - Array of compiled hooks
+ * @returns Nested map: EventType -> Matcher -> Hooks
+ */
+declare function groupHooksByEventAndMatcher(
+  compiledHooks: CompiledHook[]
+): Map<HookEventName, Map<string | undefined, CompiledHook[]>>;
+/**
+ * Result of detecting the hook context, including the root directory.
+ */
+interface HookContextInfo {
+  /** Hook context type. */
+  context: HookContext;
+  /** Absolute path to the root directory (plugin root or project root). */
+  rootDir: string;
+}
+/**
+ * Auto-detects the hook context and root directory based on directory structure.
+ *
+ * Detection logic:
+ * - If output path contains `.claude/` directory segment → agent context, root is parent of .claude/
+ * - If `.claude-plugin/` directory exists within 3 levels up → plugin context, root is that directory
+ * - Default: plugin context with hooks.json parent directory as root
+ * @param outputPath - Absolute path to the hooks.json output file
+ * @returns Detected hook context and root directory
+ */
+declare function detectHookContext(outputPath: string): HookContextInfo;
+/**
+ * Generates a command path based on the hook context.
+ *
+ * Calculates the relative path from the root directory to the build directory.
+ * Prepends the node executable.
+ *
+ * - `plugin`: Uses `node $CLAUDE_PLUGIN_ROOT/hooks/build/filename`
+ * - `agent`: Uses `node "$CLAUDE_PROJECT_DIR"/.claude/hooks/build/filename`
+ * @param filename - The compiled hook filename
+ * @param buildDir - Absolute path to the build directory
+ * @param contextInfo - Hook context info including root directory
+ * @param executable - Node executable path (default: "node")
+ * @returns The command path string
+ */
+declare function generateCommandPath(
+  filename: string,
+  buildDir: string,
+  contextInfo: HookContextInfo,
+  executable?: string
+): string;
+/**
+ * Generates the hooks.json content in Claude Code's expected format.
+ *
+ * Format: { hooks: { EventType: [ { matcher?, hooks: [...] } ] } }
+ * @param compiledHooks - Array of compiled hooks
+ * @param buildDir - Absolute path to the build directory
+ * @param contextInfo - Hook context info for path resolution
+ * @param executable - Node executable path (default: "node")
+ * @returns The hooks.json structure
+ */
+declare function generateHooksJson(
+  compiledHooks: CompiledHook[],
+  buildDir: string,
+  contextInfo: HookContextInfo,
+  executable?: string
+): HooksJson;
+/**
+ * Reads an existing hooks.json file if it exists.
+ * @param outputPath - Path to the hooks.json file
+ * @returns Parsed HooksJson or undefined if file doesn't exist
+ */
+declare function readExistingHooksJson(outputPath: string): HooksJson | undefined;
+/**
+ * Removes previously generated hook files from disk.
+ * Only removes files that were tracked in __generated.files.
+ * @param existingHooksJson - The existing hooks.json content
+ * @param outputDir - Directory containing the generated files
+ */
+declare function removeOldGeneratedFiles(existingHooksJson: HooksJson, outputDir: string): void;
+/**
+ * Extracts hooks from an existing hooks.json that were NOT generated by this package.
+ * Identifies generated hooks by checking if their command path matches the generated file pattern.
+ * @param existingHooksJson - The existing hooks.json content
+ * @returns Object containing preserved hooks (keyed by event type)
+ */
+declare function extractPreservedHooks(existingHooksJson: HooksJson): Partial<Record<HookEventName, MatcherEntry[]>>;
+/**
+ * Merges preserved hooks with newly generated hooks.
+ * Preserved hooks are added first, then new hooks are appended.
+ * @param newHooksJson - The newly generated hooks.json content
+ * @param preservedHooks - Hooks to preserve from the existing hooks.json
+ * @returns Merged HooksJson
+ */
+declare function mergeHooksJson(
+  newHooksJson: HooksJson,
+  preservedHooks: Partial<Record<HookEventName, MatcherEntry[]>>
+): HooksJson;
+export {
+  parseArgs,
+  validateArgs,
+  analyzeHookFile,
+  discoverHookFiles,
+  compileHook,
+  generateContentHash,
+  detectHookContext,
+  generateCommandPath,
+  generateHooksJson,
+  groupHooksByEventAndMatcher,
+  readExistingHooksJson,
+  removeOldGeneratedFiles,
+  extractPreservedHooks,
+  mergeHooksJson,
+  HOOK_FACTORY_TO_EVENT
+};
+export type { CliArgs, HookMetadata, CompiledHook, HookConfig, MatcherEntry, HooksJson };

package/types/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared constants for the CLI and scaffold modules.
+ * @module
+ */
+import type { HookEventName } from './inputs.js';
+/**
+ * Maps hook factory function names to their event names.
+ */
+export declare const HOOK_FACTORY_TO_EVENT: Record<string, HookEventName>;

package/types/env.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Environment variable utilities for Claude Code hooks.
+ *
+ * Provides typed access to Claude Code's environment variables and utilities
+ * for persisting environment variables in SessionStart hooks.
+ *
+ * ## Environment Variables
+ *
+ * Claude Code sets these environment variables when running hooks:
+ *
+ * | Variable | Description | Available In |
+ * |----------|-------------|--------------|
+ * | `CLAUDE_PROJECT_DIR` | Absolute path to project root | All hooks |
+ * | `CLAUDE_ENV_FILE` | Path to file for persisting env vars | SessionStart only |
+ * | `CLAUDE_CODE_REMOTE` | `"true"` if running remotely | All hooks |
+ * @module
+ * @example
+ * ```typescript
+ * import { getProjectDir, persistEnvVar, isRemoteEnvironment } from '@goodfoot/claude-code-hooks';
+ *
+ * // Get project directory
+ * const projectDir = getProjectDir();
+ *
+ * // Check if running remotely
+ * if (isRemoteEnvironment()) {
+ *   // Handle remote-specific logic
+ * }
+ *
+ * // In SessionStart hook: persist environment variables
+ * persistEnvVar('NODE_ENV', 'production');
+ * persistEnvVar('API_KEY', 'secret-key');
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#hook-execution-details
+ */
+/**
+ * Claude Code environment variable names.
+ *
+ * These are the environment variables that Claude Code sets when running hooks.
+ */
+export declare const CLAUDE_ENV_VARS: {
+  /**
+   * Absolute path to the project root directory where Claude Code was started.
+   * Available in all hooks.
+   */
+  readonly PROJECT_DIR: 'CLAUDE_PROJECT_DIR';
+  /**
+   * Path to a file where SessionStart hooks can persist environment variables.
+   * Variables written to this file will be available in all subsequent bash commands.
+   * Only available in SessionStart hooks.
+   */
+  readonly ENV_FILE: 'CLAUDE_ENV_FILE';
+  /**
+   * Set to "true" when running in a remote (web) environment.
+   * Not set or empty when running in local CLI environment.
+   */
+  readonly REMOTE: 'CLAUDE_CODE_REMOTE';
+};
+/**
+ * Gets the Claude Code project directory.
+ *
+ * This is the absolute path to the project root where Claude Code was started.
+ * The value comes from the `CLAUDE_PROJECT_DIR` environment variable.
+ * @returns The project directory path, or undefined if not set
+ * @example
+ * ```typescript
+ * const projectDir = getProjectDir();
+ * if (projectDir) {
+ *   const configPath = `${projectDir}/.claude/config.json`;
+ * }
+ * ```
+ */
+export declare function getProjectDir(): string | undefined;
+/**
+ * Gets the Claude Code env file path for persisting environment variables.
+ *
+ * This is only available in SessionStart hooks. The path points to a file
+ * where you can write shell export statements to persist environment variables
+ * for all subsequent bash commands in the session.
+ * @returns The env file path, or undefined if not set (not a SessionStart hook)
+ * @example
+ * ```typescript
+ * const envFile = getEnvFilePath();
+ * if (envFile) {
+ *   // We're in a SessionStart hook and can persist env vars
+ *   persistEnvVar('MY_VAR', 'my-value');
+ * }
+ * ```
+ */
+export declare function getEnvFilePath(): string | undefined;
+/**
+ * Checks if the hook is running in a remote (web) environment.
+ *
+ * Remote environments may have different capabilities or restrictions
+ * compared to local CLI environments.
+ * @returns true if running remotely, false if running locally
+ * @example
+ * ```typescript
+ * if (isRemoteEnvironment()) {
+ *   // Use web-compatible approaches
+ * } else {
+ *   // Can use local CLI features
+ * }
+ * ```
+ */
+export declare function isRemoteEnvironment(): boolean;
+/**
+ * Persists an environment variable for use in subsequent bash commands.
+ *
+ * This function writes a shell export statement to the `CLAUDE_ENV_FILE`,
+ * which Claude Code sources before running bash commands. This allows
+ * SessionStart hooks to configure the environment for the entire session.
+ *
+ * **Important**: This function only works in SessionStart hooks where
+ * `CLAUDE_ENV_FILE` is set. In other hooks, it will throw an error.
+ * @param name - The environment variable name
+ * @param value - The environment variable value (will be shell-escaped)
+ * @throws Error if CLAUDE_ENV_FILE is not set (not in a SessionStart hook)
+ * @example
+ * ```typescript
+ * import { sessionStartHook, sessionStartOutput, persistEnvVar } from '@goodfoot/claude-code-hooks';
+ *
+ * export default sessionStartHook({}, async (input) => {
+ *   // Persist environment variables for the session
+ *   persistEnvVar('NODE_ENV', 'production');
+ *   persistEnvVar('API_KEY', process.env.MY_API_KEY ?? 'default');
+ *   persistEnvVar('PATH', `${process.env.PATH}:./node_modules/.bin`);
+ *
+ *   return sessionStartOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#persisting-environment-variables
+ */
+export declare function persistEnvVar(name: string, value: string): void;
+/**
+ * Persists multiple environment variables at once.
+ *
+ * This is a convenience wrapper around `persistEnvVar` for setting
+ * multiple variables in a single call.
+ * @param vars - Object mapping variable names to values
+ * @throws Error if CLAUDE_ENV_FILE is not set (not in a SessionStart hook)
+ * @example
+ * ```typescript
+ * persistEnvVars({
+ *   NODE_ENV: 'production',
+ *   API_KEY: 'secret',
+ *   DEBUG: 'false'
+ * });
+ * ```
+ */
+export declare function persistEnvVars(vars: Record<string, string>): void;