@goodfoot/claude-code-hooks 1.0.1

package/dist/constants.js

@@ -0,0 +1,21 @@
+/**
+ * Shared constants for the CLI and scaffold modules.
+ * @module
+ */
+/**
+ * Maps hook factory function names to their event names.
+ */
+export const HOOK_FACTORY_TO_EVENT = {
+  preToolUseHook: 'PreToolUse',
+  postToolUseHook: 'PostToolUse',
+  postToolUseFailureHook: 'PostToolUseFailure',
+  notificationHook: 'Notification',
+  userPromptSubmitHook: 'UserPromptSubmit',
+  sessionStartHook: 'SessionStart',
+  sessionEndHook: 'SessionEnd',
+  stopHook: 'Stop',
+  subagentStartHook: 'SubagentStart',
+  subagentStopHook: 'SubagentStop',
+  preCompactHook: 'PreCompact',
+  permissionRequestHook: 'PermissionRequest'
+};

package/dist/env.js

@@ -0,0 +1,188 @@
+/**
+ * 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
+ */
+import * as fs from 'node:fs';
+/**
+ * Claude Code environment variable names.
+ *
+ * These are the environment variables that Claude Code sets when running hooks.
+ */
+export const CLAUDE_ENV_VARS = {
+  /**
+   * Absolute path to the project root directory where Claude Code was started.
+   * Available in all hooks.
+   */
+  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.
+   */
+  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.
+   */
+  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 function getProjectDir() {
+  return process.env[CLAUDE_ENV_VARS.PROJECT_DIR];
+}
+/**
+ * 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 function getEnvFilePath() {
+  return process.env[CLAUDE_ENV_VARS.ENV_FILE];
+}
+/**
+ * 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 function isRemoteEnvironment() {
+  return process.env[CLAUDE_ENV_VARS.REMOTE] === 'true';
+}
+/**
+ * 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 function persistEnvVar(name, value) {
+  const envFile = getEnvFilePath();
+  if (envFile === undefined) {
+    throw new Error(
+      'persistEnvVar can only be used in SessionStart hooks. ' + 'CLAUDE_ENV_FILE environment variable is not set.'
+    );
+  }
+  // Shell-escape the value to handle special characters
+  const escapedValue = escapeShellValue(value);
+  // Write the export statement
+  const exportStatement = `export ${name}=${escapedValue}\n`;
+  fs.appendFileSync(envFile, exportStatement, 'utf-8');
+}
+/**
+ * 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 function persistEnvVars(vars) {
+  for (const [name, value] of Object.entries(vars)) {
+    persistEnvVar(name, value);
+  }
+}
+/**
+ * Escapes a value for safe use in a shell export statement.
+ *
+ * Uses single quotes and escapes any embedded single quotes.
+ * This prevents shell injection and handles special characters.
+ * @param value - The value to escape
+ * @returns The shell-escaped value (with quotes)
+ * @internal
+ */
+function escapeShellValue(value) {
+  // Use single quotes and escape any embedded single quotes
+  // 'value' -> 'val'\''ue' for values containing single quotes
+  const escaped = value.replace(/'/g, "'\\''");
+  return `'${escaped}'`;
+}

package/dist/hooks.js

@@ -0,0 +1,391 @@
+/**
+ * Hook factory functions for Claude Code hooks.
+ *
+ * Provides typed factory functions for all 12 hook types that handle:
+ * - Input type narrowing based on hook event type
+ * - Output type enforcement via return types
+ * - Error wrapping with automatic logging
+ * - Logger context injection
+ *
+ * Each factory accepts a HookConfig with optional matcher and timeout settings,
+ * and returns a function that the runtime invokes when the hook file executes.
+ * @module
+ * @example
+ * ```typescript
+ * import { preToolUseHook, preToolUseOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * export default preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   logger.info('Processing Bash command');
+ *   return preToolUseOutput({ allow: true });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ */
+// ============================================================================
+// Generic Factory
+// ============================================================================
+/**
+ * Creates a hook factory function for a specific hook type.
+ *
+ * This is the internal implementation used by all typed factories.
+ * It wraps the handler with error catching and logging.
+ * @param hookEventName - The hook event name
+ * @param config - Hook configuration
+ * @param handler - The handler function to wrap
+ * @returns A wrapped hook function
+ * @internal
+ */
+function createHookFunction(hookEventName, config, handler) {
+  const hookFn = async (input, context) => {
+    // Delegate error handling to the runtime - just execute the handler
+    // The runtime will catch errors, log them, and return appropriate output
+    return await handler(input, context);
+  };
+  // Attach metadata for runtime inspection
+  hookFn.hookEventName = hookEventName;
+  hookFn.matcher = config.matcher;
+  hookFn.timeout = config.timeout;
+  return hookFn;
+}
+/** @inheritdoc */
+export function preToolUseHook(config, handler) {
+  return createHookFunction('PreToolUse', config, handler);
+}
+/** @inheritdoc */
+export function postToolUseHook(config, handler) {
+  return createHookFunction('PostToolUse', config, handler);
+}
+/** @inheritdoc */
+export function postToolUseFailureHook(config, handler) {
+  return createHookFunction('PostToolUseFailure', config, handler);
+}
+// ============================================================================
+// Notification Hook Factory
+// ============================================================================
+/**
+ * Creates a Notification hook handler.
+ *
+ * Notification hooks fire when Claude Code sends a notification, allowing you to:
+ * - Forward notifications to external systems
+ * - Log important events
+ * - Trigger custom alerting
+ *
+ * **Matcher**: Matches against `notification_type`
+ * @param config - Hook configuration with optional matcher and timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { notificationHook, notificationOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Forward notifications to Slack
+ * export default notificationHook({}, async (input, { logger }) => {
+ *   logger.info('Notification received', {
+ *     type: input.notification_type,
+ *     title: input.title
+ *   });
+ *
+ *   await sendSlackMessage(input.title ?? 'Notification', input.message);
+ *
+ *   return notificationOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#notification
+ */
+export function notificationHook(config, handler) {
+  return createHookFunction('Notification', config, handler);
+}
+// ============================================================================
+// UserPromptSubmit Hook Factory
+// ============================================================================
+/**
+ * Creates a UserPromptSubmit hook handler.
+ *
+ * UserPromptSubmit hooks fire when a user submits a prompt, allowing you to:
+ * - Add additional context or instructions
+ * - Log user interactions
+ * - Validate or transform prompts
+ *
+ * **Matcher**: No matcher support - fires on all prompt submissions
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { userPromptSubmitHook, userPromptSubmitOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Add project context to every prompt
+ * export default userPromptSubmitHook({}, async (input, { logger }) => {
+ *   logger.debug('User prompt submitted', { promptLength: input.prompt.length });
+ *
+ *   const projectContext = await getProjectContext();
+ *
+ *   return userPromptSubmitOutput({
+ *     additionalContext: projectContext
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#userpromptsubmit
+ */
+export function userPromptSubmitHook(config, handler) {
+  return createHookFunction('UserPromptSubmit', config, handler);
+}
+// ============================================================================
+// SessionStart Hook Factory
+// ============================================================================
+/**
+ * Creates a SessionStart hook handler.
+ *
+ * SessionStart hooks fire when a Claude Code session starts or restarts,
+ * allowing you to:
+ * - Initialize session state
+ * - Inject context or instructions
+ * - Persist environment variables for subsequent bash commands
+ * - Set up logging or monitoring
+ *
+ * **Matcher**: Matches against `source` ('startup', 'resume', 'clear', 'compact')
+ *
+ * **Context**: SessionStart hooks receive an extended context with `persistEnvVar`
+ * and `persistEnvVars` functions for setting environment variables.
+ * @param config - Hook configuration with optional matcher and timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { sessionStartHook, sessionStartOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Persist environment variables for the session
+ * export default sessionStartHook({ matcher: 'startup' }, async (input, { logger, persistEnvVar }) => {
+ *   logger.info('New session started', {
+ *     sessionId: input.session_id,
+ *     cwd: input.cwd
+ *   });
+ *
+ *   // Set environment variables for all subsequent bash commands
+ *   persistEnvVar('NODE_ENV', 'development');
+ *   persistEnvVar('DEBUG', 'true');
+ *
+ *   return sessionStartOutput({});
+ * });
+ * ```
+ * @example
+ * ```typescript
+ * // Set multiple environment variables at once
+ * export default sessionStartHook({}, async (input, { persistEnvVars }) => {
+ *   persistEnvVars({
+ *     NODE_ENV: 'production',
+ *     API_KEY: 'secret',
+ *     DEBUG: 'false'
+ *   });
+ *
+ *   return sessionStartOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#sessionstart
+ */
+export function sessionStartHook(config, handler) {
+  return createHookFunction('SessionStart', config, handler);
+}
+// ============================================================================
+// SessionEnd Hook Factory
+// ============================================================================
+/**
+ * Creates a SessionEnd hook handler.
+ *
+ * SessionEnd hooks fire when a Claude Code session ends, allowing you to:
+ * - Clean up session resources
+ * - Log session metrics
+ * - Persist session state
+ *
+ * **Matcher**: Matches against `reason` (the exit reason string)
+ * @param config - Hook configuration with optional matcher and timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { sessionEndHook, sessionEndOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Log session end and clean up
+ * export default sessionEndHook({}, async (input, { logger }) => {
+ *   logger.info('Session ended', {
+ *     sessionId: input.session_id,
+ *     reason: input.reason
+ *   });
+ *
+ *   await cleanupSessionResources(input.session_id);
+ *
+ *   return sessionEndOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#sessionend
+ */
+export function sessionEndHook(config, handler) {
+  return createHookFunction('SessionEnd', config, handler);
+}
+// ============================================================================
+// Stop Hook Factory
+// ============================================================================
+/**
+ * Creates a Stop hook handler.
+ *
+ * Stop hooks fire when Claude Code is about to stop, allowing you to:
+ * - Block the stop and require additional action
+ * - Confirm the user wants to stop
+ * - Clean up resources before stopping
+ *
+ * **Matcher**: No matcher support - fires on all stop events
+ * @param config - Hook configuration with optional timeout (matcher is ignored)
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { stopHook, stopOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Block stop if there are pending changes
+ * export default stopHook({}, async (input, { logger }) => {
+ *   const pendingChanges = await checkPendingChanges();
+ *
+ *   if (pendingChanges.length > 0) {
+ *     logger.warn('Blocking stop due to pending changes', {
+ *       count: pendingChanges.length
+ *     });
+ *
+ *     return stopOutput({
+ *       decision: 'block',
+ *       reason: `There are ${pendingChanges.length} uncommitted changes`,
+ *       systemMessage: 'Please commit or discard changes before stopping'
+ *     });
+ *   }
+ *
+ *   logger.info('Approving stop');
+ *   return stopOutput({ decision: 'approve' });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#stop
+ */
+export function stopHook(config, handler) {
+  return createHookFunction('Stop', config, handler);
+}
+// ============================================================================
+// SubagentStart Hook Factory
+// ============================================================================
+/**
+ * Creates a SubagentStart hook handler.
+ *
+ * SubagentStart hooks fire when a subagent (Task tool) starts, allowing you to:
+ * - Inject context for the subagent
+ * - Log subagent invocations
+ * - Configure subagent behavior
+ *
+ * **Matcher**: Matches against `agent_type` (e.g., 'explore', 'codebase-analysis')
+ * @param config - Hook configuration with optional matcher and timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { subagentStartHook, subagentStartOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Add context for explore subagents
+ * export default subagentStartHook({ matcher: 'explore' }, async (input, { logger }) => {
+ *   logger.info('Explore subagent starting', {
+ *     agentId: input.agent_id,
+ *     agentType: input.agent_type
+ *   });
+ *
+ *   return subagentStartOutput({
+ *     additionalContext: 'Focus on finding patterns and conventions'
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#subagentstart
+ */
+export function subagentStartHook(config, handler) {
+  return createHookFunction('SubagentStart', config, handler);
+}
+// ============================================================================
+// SubagentStop Hook Factory
+// ============================================================================
+/**
+ * Creates a SubagentStop hook handler.
+ *
+ * SubagentStop hooks fire when a subagent completes or stops, allowing you to:
+ * - Block the subagent from stopping
+ * - Process subagent results
+ * - Clean up subagent resources
+ * - Log subagent completion
+ *
+ * **Matcher**: Matches against `agent_type` (e.g., 'explore', 'codebase-analysis')
+ * @param config - Hook configuration with optional matcher and timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { subagentStopHook, subagentStopOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Block explore subagents if task incomplete
+ * export default subagentStopHook({ matcher: 'explore' }, async (input, { logger }) => {
+ *   logger.info('Subagent stopping', {
+ *     agentId: input.agent_id,
+ *     agentType: input.agent_type
+ *   });
+ *
+ *   // Block if transcript shows incomplete work
+ *   return subagentStopOutput({
+ *     decision: 'block',
+ *     reason: 'Please verify exploration is complete'
+ *   });
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#subagentstop
+ */
+export function subagentStopHook(config, handler) {
+  return createHookFunction('SubagentStop', config, handler);
+}
+// ============================================================================
+// PreCompact Hook Factory
+// ============================================================================
+/**
+ * Creates a PreCompact hook handler.
+ *
+ * PreCompact hooks fire before context compaction occurs, allowing you to:
+ * - Preserve important information before compaction
+ * - Log compaction events
+ * - Modify custom instructions for the compacted context
+ *
+ * **Matcher**: Matches against `trigger` ('manual', 'auto')
+ * @param config - Hook configuration with optional matcher and timeout
+ * @param handler - The handler function to execute
+ * @returns A hook function that can be exported as the default export
+ * @example
+ * ```typescript
+ * import { preCompactHook, preCompactOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * // Log compaction events and preserve context
+ * export default preCompactHook({}, async (input, { logger }) => {
+ *   logger.info('Context compaction triggered', {
+ *     trigger: input.trigger,
+ *     hasCustomInstructions: input.custom_instructions !== null
+ *   });
+ *
+ *   return preCompactOutput({
+ *     systemMessage: 'Remember: strict mode is enabled'
+ *   });
+ * });
+ * ```
+ * @example
+ * ```typescript
+ * // Only handle manual compaction
+ * export default preCompactHook({ matcher: 'manual' }, async (input, { logger }) => {
+ *   logger.info('Manual compaction requested');
+ *   return preCompactOutput({});
+ * });
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#precompact
+ */
+export function preCompactHook(config, handler) {
+  return createHookFunction('PreCompact', config, handler);
+}
+/** @inheritdoc */
+export function permissionRequestHook(config, handler) {
+  return createHookFunction('PermissionRequest', config, handler);
+}

package/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * Type-safe Claude Code hooks library.
+ *
+ * Provides typed input/output handling, output builders, and logging system
+ * for building Claude Code hooks with full type safety.
+ * @module
+ */
+// Hook event names constant
+export { HOOK_EVENT_NAMES } from './inputs.js';
+// Output builder functions
+export {
+  // Exit codes
+  EXIT_CODES,
+  // All 12 output builder functions
+  preToolUseOutput,
+  postToolUseOutput,
+  postToolUseFailureOutput,
+  userPromptSubmitOutput,
+  sessionStartOutput,
+  sessionEndOutput,
+  stopOutput,
+  subagentStartOutput,
+  subagentStopOutput,
+  notificationOutput,
+  preCompactOutput,
+  permissionRequestOutput
+} from './outputs.js';
+// Logger exports
+export { LOG_LEVELS, Logger, logger } from './logger.js';
+// Hook factory functions - all 12 hook types
+export {
+  preToolUseHook,
+  postToolUseHook,
+  postToolUseFailureHook,
+  notificationHook,
+  userPromptSubmitHook,
+  sessionStartHook,
+  sessionEndHook,
+  stopHook,
+  subagentStartHook,
+  subagentStopHook,
+  preCompactHook,
+  permissionRequestHook
+} from './hooks.js';
+// Runtime exports - execute function
+export {
+  // Main execute function for compiled hooks
+  execute
+} from './runtime.js';
+// Environment variable utilities
+export {
+  // Environment variable name constants
+  CLAUDE_ENV_VARS,
+  // Getters
+  getProjectDir,
+  getEnvFilePath,
+  isRemoteEnvironment
+} from './env.js';
+// Tool helper functions - Type guards and utilities
+export {
+  // Type guards
+  isWriteTool,
+  isEditTool,
+  isMultiEditTool,
+  isFileModifyingTool,
+  isReadTool,
+  isBashTool,
+  isGlobTool,
+  isGrepTool,
+  // File path utilities
+  getFilePath,
+  isJsTsFile,
+  isTsFile,
+  // Content inspection
+  checkContentForPattern,
+  forEachContent
+} from './tool-helpers.js';