@goodfoot/claude-code-hooks 1.0.1

package/dist/outputs.js

@@ -0,0 +1,282 @@
+/**
+ * Output types and builders for Claude Code hooks.
+ *
+ * Provides type-safe output builder functions for all 12 hook types. Each builder
+ * accepts options that match the wire format expected by Claude Code, with types
+ * derived from the Claude Agent SDK's `SyncHookJSONOutput` type.
+ * @see https://code.claude.com/docs/en/hooks
+ * @module
+ */
+// ============================================================================
+// Exit Code Constants
+// ============================================================================
+/**
+ * Exit codes used by Claude Code hooks.
+ *
+ * | Exit Code | Name | When Used | Claude Code Behavior |
+ * |-----------|------|-----------|---------------------|
+ * | 0 | Success | Handler returns normally | Continue, parse stdout as JSON |
+ * | 1 | Error | Invalid input, non-blocking error | Non-blocking, stderr to user only |
+ * | 2 | Block | Handler throws OR `stopReason` set | Blocking, stderr shown to Claude |
+ */
+export const EXIT_CODES = {
+  /** Handler completed successfully. Claude Code parses stdout as JSON. */
+  SUCCESS: 0,
+  /** Non-blocking error occurred (e.g., invalid input). stderr shown to user only. */
+  ERROR: 1,
+  /** Handler threw exception OR blocking action requested. stderr shown to Claude. */
+  BLOCK: 2
+};
+// ============================================================================
+// Output Builder Factories
+// ============================================================================
+/**
+ * Factory for hooks that have hookSpecificOutput with a hookEventName discriminator.
+ * @param hookType - The hook type name used as the _type discriminator
+ * @returns A builder function that creates the output object
+ * @internal
+ */
+function createHookSpecificOutputBuilder(hookType) {
+  return (options = {}) => {
+    const { hookSpecificOutput, ...rest } = options;
+    const stdout =
+      hookSpecificOutput !== undefined
+        ? { ...rest, hookSpecificOutput: { hookEventName: hookType, ...hookSpecificOutput } }
+        : rest;
+    return { _type: hookType, stdout };
+  };
+}
+/**
+ * Factory for hooks that only use CommonOptions (simple passthrough).
+ * @param hookType - The hook type name used as the _type discriminator
+ * @returns A builder function that creates the output object
+ * @internal
+ */
+function createSimpleOutputBuilder(hookType) {
+  return (options = {}) => ({
+    _type: hookType,
+    stdout: options
+  });
+}
+/**
+ * Factory for hooks that use decision-based options (Stop, SubagentStop).
+ * @param hookType - The hook type name used as the _type discriminator
+ * @returns A builder function that creates the output object
+ * @internal
+ */
+function createDecisionOutputBuilder(hookType) {
+  return (options = {}) => ({
+    _type: hookType,
+    stdout: options
+  });
+}
+/**
+ * Creates an output for PreToolUse hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PreToolUseOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Allow tool execution
+ * preToolUseOutput({
+ *   hookSpecificOutput: { permissionDecision: 'allow' }
+ * });
+ *
+ * // Deny with reason
+ * preToolUseOutput({
+ *   hookSpecificOutput: {
+ *     permissionDecision: 'deny',
+ *     permissionDecisionReason: 'Dangerous command detected'
+ *   }
+ * });
+ *
+ * // Allow with modified input
+ * preToolUseOutput({
+ *   hookSpecificOutput: {
+ *     permissionDecision: 'allow',
+ *     updatedInput: { command: 'ls -la' }
+ *   }
+ * });
+ * ```
+ */
+export const preToolUseOutput = /* @__PURE__ */ createHookSpecificOutputBuilder('PreToolUse');
+/**
+ * Creates an output for PostToolUse hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PostToolUseOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Add context after a file read
+ * postToolUseOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'File contains sensitive data'
+ *   }
+ * });
+ * ```
+ */
+export const postToolUseOutput = /* @__PURE__ */ createHookSpecificOutputBuilder('PostToolUse');
+/**
+ * Creates an output for PostToolUseFailure hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PostToolUseFailureOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * postToolUseFailureOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Try using a different approach'
+ *   }
+ * });
+ * ```
+ */
+export const postToolUseFailureOutput = /* @__PURE__ */ createHookSpecificOutputBuilder('PostToolUseFailure');
+/**
+ * Creates an output for UserPromptSubmit hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A UserPromptSubmitOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * userPromptSubmitOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'This project uses TypeScript strict mode'
+ *   }
+ * });
+ * ```
+ */
+export const userPromptSubmitOutput = /* @__PURE__ */ createHookSpecificOutputBuilder('UserPromptSubmit');
+/**
+ * Creates an output for SessionStart hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SessionStartOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * sessionStartOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: JSON.stringify({ project: 'my-project' })
+ *   }
+ * });
+ * ```
+ */
+export const sessionStartOutput = /* @__PURE__ */ createHookSpecificOutputBuilder('SessionStart');
+/**
+ * Creates an output for SessionEnd hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SessionEndOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * sessionEndOutput({});
+ * ```
+ */
+export const sessionEndOutput = /* @__PURE__ */ createSimpleOutputBuilder('SessionEnd');
+/**
+ * Creates an output for Stop hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A StopOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Allow the stop
+ * stopOutput({ decision: 'approve' });
+ *
+ * // Block with reason
+ * stopOutput({
+ *   decision: 'block',
+ *   reason: 'There are uncommitted changes'
+ * });
+ * ```
+ */
+export const stopOutput = /* @__PURE__ */ createDecisionOutputBuilder('Stop');
+/**
+ * Creates an output for SubagentStart hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SubagentStartOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * subagentStartOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Focus on finding patterns'
+ *   }
+ * });
+ * ```
+ */
+export const subagentStartOutput = /* @__PURE__ */ createHookSpecificOutputBuilder('SubagentStart');
+/**
+ * Creates an output for SubagentStop hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A SubagentStopOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Block with reason
+ * subagentStopOutput({
+ *   decision: 'block',
+ *   reason: 'Task not complete'
+ * });
+ * ```
+ */
+export const subagentStopOutput = /* @__PURE__ */ createDecisionOutputBuilder('SubagentStop');
+/**
+ * Creates an output for Notification hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A NotificationOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Add context about the notification
+ * notificationOutput({
+ *   hookSpecificOutput: {
+ *     additionalContext: 'Notification forwarded to Slack #alerts channel'
+ *   }
+ * });
+ *
+ * // Suppress the notification
+ * notificationOutput({ suppressOutput: true });
+ * ```
+ */
+export const notificationOutput = /* @__PURE__ */ createHookSpecificOutputBuilder('Notification');
+/**
+ * Creates an output for PreCompact hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PreCompactOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * preCompactOutput({
+ *   systemMessage: 'Remember: strict mode is enabled'
+ * });
+ * ```
+ */
+export const preCompactOutput = /* @__PURE__ */ createSimpleOutputBuilder('PreCompact');
+/**
+ * Creates an output for PermissionRequest hooks.
+ * @param options - Configuration options for the hook output
+ * @returns A PermissionRequestOutput object ready for the runtime
+ * @example
+ * ```typescript
+ * // Auto-approve
+ * permissionRequestOutput({
+ *   hookSpecificOutput: {
+ *     decision: { behavior: 'allow' }
+ *   }
+ * });
+ *
+ * // Auto-approve with modified input
+ * permissionRequestOutput({
+ *   hookSpecificOutput: {
+ *     decision: {
+ *       behavior: 'allow',
+ *       updatedInput: { file_path: '/safe/path' }
+ *     }
+ *   }
+ * });
+ *
+ * // Auto-deny
+ * permissionRequestOutput({
+ *   hookSpecificOutput: {
+ *     decision: {
+ *       behavior: 'deny',
+ *       message: 'Not allowed',
+ *       interrupt: true
+ *     }
+ *   }
+ * });
+ *
+ * // Fall through to normal prompt
+ * permissionRequestOutput({});
+ * ```
+ */
+export const permissionRequestOutput = /* @__PURE__ */ createHookSpecificOutputBuilder('PermissionRequest');

package/dist/runtime.js

@@ -0,0 +1,222 @@
+/**
+ * Runtime module for Claude Code hooks.
+ *
+ * Handles stdin/stdout/exit code semantics for compiled hook execution.
+ * This module is the core orchestrator that:
+ * - Reads JSON from stdin (wire format with snake_case properties)
+ * - Invokes the hook handler
+ * - Writes output to stdout
+ * - Manages exit codes
+ * @module
+ * @example
+ * ```typescript
+ * // In a compiled hook file
+ * import { execute } from '@goodfoot/claude-code-hooks/runtime';
+ * import myHook from './my-hook.js';
+ *
+ * execute(myHook);
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ */
+import { persistEnvVar, persistEnvVars } from './env.js';
+import { logger } from './logger.js';
+import { EXIT_CODES } from './outputs.js';
+// ============================================================================
+// Stdin/Stdout Handling
+// ============================================================================
+/**
+ * Reads all data from stdin.
+ * @returns Promise resolving to the complete stdin content
+ */
+async function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    // Set encoding first to ensure data events receive strings
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => {
+      chunks.push(chunk);
+    });
+    process.stdin.on('end', () => {
+      resolve(chunks.join(''));
+    });
+    process.stdin.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+/**
+ * Parses stdin JSON input.
+ * @param stdinContent - Raw stdin content
+ * @returns Parsed input (wire format with snake_case properties)
+ * @throws Error if JSON is malformed
+ */
+function parseStdinInput(stdinContent) {
+  // Parse JSON - input uses wire format (snake_case) directly
+  const rawInput = JSON.parse(stdinContent);
+  return rawInput;
+}
+/**
+ * Writes hook output to stdout.
+ *
+ * Output uses camelCase keys per Claude Code hook specification.
+ * @param output - The hook output to write
+ * @see https://code.claude.com/docs/en/hooks#hook-output-structure
+ */
+function writeStdout(output) {
+  // Output uses camelCase - no transformation needed
+  process.stdout.write(JSON.stringify(output));
+}
+// ============================================================================
+// Error Handling
+// ============================================================================
+/**
+ * Creates an error output for malformed stdin JSON.
+ * @param error - The parse error
+ * @returns HookOutput with empty stdout
+ */
+function createMalformedInputOutput(error) {
+  logger.error(`Invalid JSON input: ${error instanceof Error ? error.message : String(error)}`);
+  return { stdout: {} };
+}
+/**
+ * Writes handler error stacktrace to stderr and exits with code 2.
+ *
+ * When a hook handler throws an exception:
+ * - Stacktrace (with sourcemaps if available) is output to stderr
+ * - Process exits with code 2 (BLOCK)
+ * - No JSON is output to stdout
+ * @param error - The error thrown by the handler
+ */
+function handleHandlerError(error) {
+  // Write stack trace to stderr (sourcemaps are applied automatically by Node.js)
+  if (error instanceof Error) {
+    process.stderr.write(`${error.stack ?? error.message}\n`);
+  } else {
+    process.stderr.write(`${String(error)}\n`);
+  }
+  // Log to file if configured
+  logger.error(`Hook handler error: ${error instanceof Error ? error.message : String(error)}`);
+  // Clear logger context and close
+  logger.clearContext();
+  logger.close();
+  // Exit with code 2 (BLOCK) - no JSON output
+  process.exit(EXIT_CODES.BLOCK);
+}
+/**
+ * Converts a SpecificHookOutput to HookOutput for wire format.
+ *
+ * SpecificHookOutput types have: { _type, exitCode, stdout, stderr? }
+ * HookOutput has: { exitCode, stdout, stderr? }
+ *
+ * Since output builders now produce wire-format directly, this function
+ * simply strips the `_type` discriminator field.
+ * @param specificOutput - The specific output from a hook handler
+ * @returns HookOutput ready for serialization
+ * @see https://code.claude.com/docs/en/hooks#hook-output-structure
+ * @example
+ * ```typescript
+ * const specificOutput = preToolUseOutput({ hookSpecificOutput: { permissionDecision: 'allow' } });
+ * const hookOutput = convertToHookOutput(specificOutput);
+ * // hookOutput: { exitCode: 0, stdout: { hookSpecificOutput: { ... } } }
+ * ```
+ */
+export function convertToHookOutput(specificOutput) {
+  return { stdout: specificOutput.stdout };
+}
+// ============================================================================
+// Execute Function
+// ============================================================================
+/**
+ * Executes a hook handler with full runtime orchestration.
+ *
+ * This is the main entry point that compiled hooks use. When a compiled hook
+ * runs as a CLI:
+ *
+ * 1. Reads all stdin
+ * 2. Parses JSON (wire format with snake_case properties)
+ * 3. Sets up logger context (hookType, input)
+ * 4. Calls handler with input and context (logger)
+ * 5. Handles any errors, logs them
+ * 6. Writes JSON to stdout
+ * 7. Closes logger
+ * 8. Exits with appropriate code
+ * @param hookFn - The hook function to execute (from hook factory)
+ * @example
+ * ```typescript
+ * // In compiled hook file
+ * import { execute } from '@goodfoot/claude-code-hooks/runtime';
+ * import { preToolUseHook, preToolUseOutput } from '@goodfoot/claude-code-hooks';
+ *
+ * const myHook = preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   logger.info('Processing Bash command');
+ *   return preToolUseOutput({ allow: true });
+ * });
+ *
+ * execute(myHook);
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ */
+export async function execute(hookFn) {
+  let output;
+  try {
+    // Check for log file configuration conflicts
+    // CLAUDE_CODE_HOOKS_CLI_LOG_FILE is injected by the CLI --log parameter
+    // CLAUDE_CODE_HOOKS_LOG_FILE is the user's environment variable
+    const cliLogFile = process.env['CLAUDE_CODE_HOOKS_CLI_LOG_FILE'];
+    const envLogFile = process.env['CLAUDE_CODE_HOOKS_LOG_FILE'];
+    if (cliLogFile !== undefined && envLogFile !== undefined && cliLogFile !== envLogFile) {
+      // Write error to stderr and exit with error code
+      process.stderr.write(
+        `Log file configuration conflict: CLI --log="${cliLogFile}" vs CLAUDE_CODE_HOOKS_LOG_FILE="${envLogFile}". ` +
+          'Use only one method to configure hook logging.\n'
+      );
+      process.exit(EXIT_CODES.ERROR);
+    }
+    // If CLI log file is set, configure the logger
+    if (cliLogFile !== undefined) {
+      logger.setLogFile(cliLogFile);
+    }
+    // Read and parse stdin
+    let stdinContent;
+    try {
+      stdinContent = await readStdin();
+    } catch (error) {
+      logger.logError(error, 'Failed to read stdin');
+      output = createMalformedInputOutput(error);
+      return;
+    }
+    // Parse and transform input
+    let input;
+    try {
+      input = parseStdinInput(stdinContent);
+    } catch (error) {
+      logger.logError(error, 'Failed to parse stdin JSON');
+      output = createMalformedInputOutput(error);
+      return;
+    }
+    // Set logger context
+    const hookEventName = hookFn.hookEventName;
+    logger.setContext(hookEventName, input);
+    // Build context - SessionStart hooks get extended context with persistEnvVar
+    const context = hookEventName === 'SessionStart' ? { logger, persistEnvVar, persistEnvVars } : { logger };
+    // Execute handler
+    try {
+      const specificOutput = await hookFn(input, context);
+      output = convertToHookOutput(specificOutput);
+    } catch (error) {
+      // Handler threw - output stacktrace to stderr and exit with code 2
+      // This call never returns (process.exit)
+      handleHandlerError(error);
+    }
+  } finally {
+    // Write output if we have it
+    if (output !== undefined) {
+      writeStdout(output.stdout);
+    }
+    // Clear logger context
+    logger.clearContext();
+    logger.close();
+    // Exit with success (handler errors exit via handleHandlerError with code 2)
+    process.exit(EXIT_CODES.SUCCESS);
+  }
+}