claude_hooks 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eb1adbb7a091ea436fa56940baf40407eb2d0f148760d7f1c470d4577794744
-  data.tar.gz: cf79657245bd18e98ba407d49d49b4fe539fd7feb4be4daa46c4cee00e5ea1a7
+  metadata.gz: 05073a7e1f50d4391f4afddff10e781bf70c1c1a5ec15b4d8c5cf7959827ca53
+  data.tar.gz: a477cb849efb154ac3452150030bde9a4219c82887afae7b3fded7d9d01b482c
 SHA512:
-  metadata.gz: c0303fbf858d8869ff0a326ce5031193f684cd6ca76d1fce9657b52439f1a789b06cbdcdf161663478b65e35455f5d9e756bd595eeb1e065d47be6e8936782e1
-  data.tar.gz: 8a134f14432693883b43576f7c66b9e9e68acd4f0c97e10be1ad91893a2e8f1d25cc30445d41afd087a923272105e32bb0df110f4834d3930c275d4afc263181
+  metadata.gz: ca053e3783d088baebefa2ffed240a63f624e053dfbaa10e1513191b20428f152414d281a782e2a76ba24490b9d25033271c75c47f85e89785aec7570bcc92ff
+  data.tar.gz: 54baf322b8031460dfcf92998c86950dd84f25b67d6b3e78270f5951dce81d169b7d355a1e6498c31fd33442572943c93795bce1fbbcb359b32ceecb145af2d6

data/README.md

@@ -19,6 +19,7 @@ Here's how to create a simple hook:
 1. **Create a simple hook script**
 ```ruby
 #!/usr/bin/env ruby
+require 'json'
 require 'claude_hooks'
 
 # Inherit from the right hook type class to get access to helper methods
@@ -72,23 +73,31 @@ That's it! Your hook will now add context to every user prompt. 🎉
 
 ## 📦 Installation
 
-Add to your Gemfile (you can add a Gemfile in your `.claude` directory if needed):
+Install it globally (simpler):
+
+```bash
+$ gem install claude_hooks
+```
+
+**Note:** Claude Code itself will still use the system-installed gem, not the bundled version unless you use `bundle exec` to run it in your `.claude/settings.json`.
+
+Or add it to your Gemfile (you can add a Gemfile in your `.claude` directory if needed):
+
 
 ```ruby
+# .claude/Gemfile
+source 'https://rubygems.org'
 gem 'claude_hooks'
 ```
 
-And then execute:
+And then run:
 
 ```bash
 $ bundle install
 ```
 
-Or install it globally:
-
-```bash
-$ gem install claude_hooks
-```
+> [!WARNING]
+> If you use a Gemfile, you need to use `bundle exec` to run your hooks in your `.claude/settings.json`.
 
 ### 🔧 Configuration
 
@@ -225,6 +234,14 @@ end
   - [🚨 Advices](#-advices)
   - [⚠️ Troubleshooting](#️-troubleshooting)
     - [Make your entrypoint scripts executable](#make-your-entrypoint-scripts-executable)
+  - [🧪 CLI Debugging](#-cli-debugging)
+    - [Basic Usage](#basic-usage)
+    - [Customization with Blocks](#customization-with-blocks)
+    - [Testing Methods](#testing-methods)
+      - [1. Test with STDIN (default)](#1-test-with-stdin-default)
+      - [2. Test with default sample data instead of STDIN](#2-test-with-default-sample-data-instead-of-stdin)
+      - [3. Test with Sample Data + Customization](#3-test-with-sample-data--customization)
+    - [Example Hook with CLI Testing](#example-hook-with-cli-testing)
   - [🐛 Debugging](#-debugging)
     - [Test an individual entrypoint](#test-an-individual-entrypoint)
 
@@ -579,6 +596,14 @@ log <<~TEXT
 TEXT
 ```
 
+You can also use the logger from an entrypoint script:
+```ruby
+require 'claude_hooks'
+
+logger = ClaudeHooks::Logger.new("TEST-SESSION-01", 'entrypoint')
+logger.log "Simple message"
+```
+
 #### Log File Location
 Logs are written to session-specific files in the configured log directory:
 - **Defaults to**: `~/.claude/logs/hooks/session-{session_id}.log`
@@ -737,7 +762,7 @@ exit 0
 For the operation to stop for a UserPromptSubmit hook, you would return structured JSON data followed by `exit 1`:
 
 ```ruby
-$stderr.puts JSON.generate({
+STDERR.puts JSON.generate({
   continue: false,
   stopReason: "JSON parsing error: #{e.message}",
   suppressOutput: false
@@ -746,13 +771,13 @@ exit 1
 ```
 
 > [!WARNING]
-> Don't forget to use `$stderr.puts` to output the JSON to STDERR.
+> Don't forget to use `STDERR.puts` to output the JSON to STDERR.
 
 
 ## 🚨 Advices
 
 1. **Logging**: Use `log()` method instead of `puts` to avoid interfering with JSON output
-2. **Error Handling**: Hooks should handle their own errors and use the `log` method for debugging. For errors, don't forget to exit with the right exit code (1, 2) and output the JSON indicating the error to STDERR using `$stderr.puts`.
+2. **Error Handling**: Hooks should handle their own errors and use the `log` method for debugging. For errors, don't forget to exit with the right exit code (1, 2) and output the JSON indicating the error to STDERR using `STDERR.puts`.
 3. **Output Format**: Always return `output_data` or `nil` from your `call` method
 4. **Path Management**: Use `path_for()` for all file operations relative to the Claude base directory
 
@@ -767,6 +792,108 @@ chmod +x ~/.claude/hooks/entrypoints/user_prompt_submit.rb
 ```
 
 
+## 🧪 CLI Debugging
+
+The `ClaudeHooks::CLI` module provides utilities to simplify testing hooks in isolation. Instead of writing repetitive JSON parsing and error handling code, you can use the CLI test runner.
+
+### Basic Usage
+
+Replace the traditional testing boilerplate:
+
+```ruby
+# Old way (15+ lines of repetitive code)
+if __FILE__ == $0
+  begin
+    require 'json'
+    input_data = JSON.parse(STDIN.read)
+    hook = MyHook.new(input_data)
+    result = hook.call
+    puts JSON.generate(result)
+  rescue StandardError => e
+    STDERR.puts "Error: #{e.message}"
+    puts JSON.generate({
+      continue: false,
+      stopReason: "Error: #{e.message}",
+      suppressOutput: false
+    })
+    exit 1
+  end
+end
+```
+
+With the simple CLI test runner:
+
+```ruby
+# New way (1 line!)
+if __FILE__ == $0
+  ClaudeHooks::CLI.test_runner(MyHook)
+end
+```
+
+### Customization with Blocks
+
+You can customize the input data for testing using blocks:
+
+```ruby
+if __FILE__ == $0
+  ClaudeHooks::CLI.test_runner(MyHook) do |input_data|
+    input_data['debug_mode'] = true
+    input_data['custom_field'] = 'test_value'
+    input_data['user_name'] = 'TestUser'
+  end
+end
+```
+
+### Testing Methods
+
+#### 1. Test with STDIN (default)
+```ruby
+ClaudeHooks::CLI.test_runner(MyHook)
+# Usage: echo '{"session_id":"test","prompt":"Hello"}' | ruby my_hook.rb
+```
+
+#### 2. Test with default sample data instead of STDIN
+```ruby
+ClaudeHooks::CLI.run_with_sample_data(MyHook, { 'prompt' => 'test prompt' })
+# Provides default values, no STDIN needed
+```
+
+#### 3. Test with Sample Data + Customization
+```ruby
+ClaudeHooks::CLI.run_with_sample_data(MyHook) do |input_data|
+  input_data['prompt'] = 'Custom test prompt'
+  input_data['debug'] = true
+end
+```
+
+### Example Hook with CLI Testing
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'claude_hooks'
+
+class MyTestHook < ClaudeHooks::UserPromptSubmit
+  def call
+    log "Debug mode: #{input_data['debug_mode']}"
+    log "Processing: #{prompt}"
+
+    if input_data['debug_mode']
+      log "All input keys: #{input_data.keys.join(', ')}"
+    end
+
+    output_data
+  end
+end
+
+# Test runner with customization
+if __FILE__ == $0
+  ClaudeHooks::CLI.test_runner(MyTestHook) do |input_data|
+    input_data['debug_mode'] = true
+  end
+end
+```
+
 ## 🐛 Debugging
 
 ### Test an individual entrypoint

data/example_dotclaude/hooks/entrypoints/user_prompt_submit.rb

@@ -22,16 +22,7 @@ begin
   # Output final merged result to Claude Code
   puts JSON.generate(hook_output)
 
-  exit 0
-rescue JSON::ParserError => e
-  STDERR.puts "Error parsing JSON: #{e.message}"
-
-  puts JSON.generate({
-    continue: false,
-    stopReason: "Hook JSON parsing error: #{e.message}",
-    suppressOutput: false
-  })
-  exit 1
+  exit 0 # Don't forget to exit with the right exit code (0, 1, 2)
 rescue StandardError => e
   STDERR.puts "Error in UserPromptSubmit hook: #{e.message} #{e.backtrace.join("\n")}"
 

data/example_dotclaude/hooks/handlers/user_prompt_submit/append_rules.rb

@@ -39,28 +39,7 @@ end
 
 # If this file is run directly (for testing), call the hook script
 if __FILE__ == $0
-  begin
-    require 'json'
-
-    input_data = JSON.parse(STDIN.read)
-    hook = AppendRules.new(input_data)
-    hook.call
-    puts hook.stringify_output
-  rescue JSON::ParserError => e
-    STDERR.puts "Error parsing JSON: #{e.message}"
-    puts JSON.generate({
-      continue: false,
-      stopReason: "JSON parsing error in AppendRules: #{e.message}",
-      suppressOutput: false
-    })
-    exit 0
-  rescue StandardError => e
-    STDERR.puts "Error in AppendRules hook: #{e.message}, #{e.backtrace.join("\n")}"
-    puts JSON.generate({
-      continue: false,
-      stopReason: "AppendRules execution error: #{e.message}",
-      suppressOutput: false
-    })
-    exit 0
+  ClaudeHooks::CLI.test_runner(AppendRules) do |input_data|
+    input_data['session_id'] = 'session-id-override-01'
   end
 end

data/example_dotclaude/hooks/handlers/user_prompt_submit/log_user_prompt.rb

@@ -33,18 +33,5 @@ end
 
 # If this file is run directly (for testing), call the hook
 if __FILE__ == $0
-  begin
-    require 'json'
-
-    hook = LogUserPrompt.new(JSON.parse(STDIN.read))
-    hook.call
-  rescue StandardError => e
-    STDERR.puts "Error in LogUserPrompt hook: #{e.message}, #{e.backtrace.join("\n")}"
-    puts JSON.generate({
-      continue: false,
-      stopReason: "LogUserPrompt execution error: #{e.message}",
-      suppressOutput: false
-    })
-    exit 0
-  end
+  ClaudeHooks::CLI.test_runner(LogUserPrompt)
 end

data/lib/claude_hooks/base.rb

@@ -26,7 +26,7 @@ module ClaudeHooks
 
     attr_reader :config, :input_data, :output_data, :logger
     def initialize(input_data = {})
-      @config = Configuration.config
+      @config = Configuration
       @input_data = input_data
       @output_data = {
         'continue' => true,
@@ -108,11 +108,11 @@ module ClaudeHooks
     # === CONFIG AND UTILITY METHODS ===
 
     def base_dir
-      Configuration.base_dir
+      config.base_dir
     end
 
     def path_for(relative_path)
-      Configuration.path_for(relative_path)
+      config.path_for(relative_path)
     end
 
     # Supports both single messages and blocks for multiline logging

data/lib/claude_hooks/cli.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ClaudeHooks
+  # CLI utility for testing hook handlers in isolation
+  # This module provides a standardized way to run hooks directly from the command line
+  # for testing and debugging purposes.
+  module CLI
+    class << self
+      # Run a hook class directly from command line
+      # Usage: 
+      #   ClaudeHooks::CLI.run_hook(YourHookClass)
+      #   ClaudeHooks::CLI.run_hook(YourHookClass, custom_input_data)
+      #   
+      #   # With customization block:
+      #   ClaudeHooks::CLI.run_hook(YourHookClass) do |input_data|
+      #     input_data['debug_mode'] = true
+      #   end
+      def run_hook(hook_class, input_data = nil, &block)
+        # If no input data provided, read from STDIN
+        input_data ||= read_stdin_input
+        
+        # Apply customization block if provided
+        if block_given?
+          yield(input_data)
+        end
+        
+        # Create and execute the hook
+        hook = hook_class.new(input_data)
+        result = hook.call
+        
+        # Output the result as JSON (same format as production hooks)
+        puts JSON.generate(result) if result
+        
+        result
+      rescue StandardError => e
+        handle_error(e, hook_class)
+      end
+
+      # Create a test runner block for a hook class
+      # This generates the common if __FILE__ == $0 block content
+      # 
+      # Usage: 
+      #   ClaudeHooks::CLI.test_runner(YourHookClass)
+      #   
+      #   # With customization block:
+      #   ClaudeHooks::CLI.test_runner(YourHookClass) do |input_data|
+      #     input_data['custom_field'] = 'test_value'
+      #     input_data['user_name'] = 'TestUser'
+      #   end
+      def test_runner(hook_class, &block)
+        input_data = read_stdin_input
+        
+        # Apply customization block if provided
+        if block_given?
+          yield(input_data)
+        end
+        
+        run_hook(hook_class, input_data)
+      end
+
+      # Run hook with sample data (useful for development)
+      # Usage:
+      #   ClaudeHooks::CLI.run_with_sample_data(YourHookClass)
+      #   ClaudeHooks::CLI.run_with_sample_data(YourHookClass, { 'prompt' => 'test prompt' })
+      #   
+      #   # With customization block:
+      #   ClaudeHooks::CLI.run_with_sample_data(YourHookClass) do |input_data|
+      #     input_data['prompt'] = 'Custom test prompt'
+      #     input_data['debug'] = true
+      #   end
+      def run_with_sample_data(hook_class, sample_data = {}, &block)
+        default_sample = {
+          'session_id' => 'test-session',
+          'transcript_path' => '/tmp/test_transcript.md',
+          'cwd' => Dir.pwd,
+          'hook_event_name' => hook_class.hook_type
+        }
+
+        # Merge with hook-specific sample data
+        merged_data = default_sample.merge(sample_data)
+        
+        # Apply customization block if provided
+        if block_given?
+          yield(merged_data)
+        end
+        
+        run_hook(hook_class, merged_data)
+      end
+
+      private
+
+      def read_stdin_input
+        stdin_content = STDIN.read.strip
+        return {} if stdin_content.empty?
+        
+        JSON.parse(stdin_content)
+      rescue JSON::ParserError => e
+        raise "Invalid JSON input: #{e.message}"
+      end
+
+      def handle_error(error, hook_class)
+        STDERR.puts "Error in #{hook_class.name} hook: #{error.message}"
+        STDERR.puts error.backtrace.join("\n") if error.backtrace
+
+        # Output error response in Claude Code format
+        error_response = {
+          continue: false,
+          stopReason: "#{hook_class.name} execution error: #{error.message}",
+          suppressOutput: false
+        }
+
+        puts JSON.generate(error_response)
+        exit 1
+      end
+    end
+  end
+end

data/lib/claude_hooks/configuration.rb

@@ -63,7 +63,8 @@ module ClaudeHooks
       def method_missing(method_name, *args, &block)
         # Convert method name to ENV key format (e.g., my_custom_setting -> MY_CUSTOM_SETTING)
         env_key = method_name.to_s.upcase
-        config_key = method_name.to_s
+        # Convert snake_case method name to camelCase for config file lookup
+        config_key = snake_case_to_camel_case(method_name.to_s)
 
         value = get_config_value(env_key, config_key)
         return value unless value.nil?
@@ -74,13 +75,19 @@ module ClaudeHooks
       def respond_to_missing?(method_name, include_private = false)
         # Check if we have a config value for this method
         env_key = method_name.to_s.upcase
-        config_key = method_name.to_s
+        config_key = snake_case_to_camel_case(method_name.to_s)
         
         !get_config_value(env_key, config_key).nil? || super
       end
 
       private
 
+      def snake_case_to_camel_case(snake_str)
+        # Convert snake_case to camelCase (e.g., user_name -> userName)
+        parts = snake_str.split('_')
+        parts.first + parts[1..-1].map(&:capitalize).join
+      end
+
       def config_file_path
         @config_file_path ||= path_for('config/config.json')
       end

data/lib/claude_hooks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeHooks
-  VERSION = "0.1.1"
-end
+  VERSION = "0.1.2"
+end

data/lib/claude_hooks.rb

@@ -4,6 +4,7 @@ require_relative "claude_hooks/version"
 require_relative "claude_hooks/configuration"
 require_relative "claude_hooks/logger"
 require_relative "claude_hooks/base"
+require_relative "claude_hooks/cli"
 require_relative "claude_hooks/user_prompt_submit"
 require_relative "claude_hooks/pre_tool_use"
 require_relative "claude_hooks/post_tool_use"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_hooks
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Gabriel Dehan
@@ -67,13 +67,12 @@ files:
 - claude_hooks.gemspec
 - example_dotclaude/commands/.gitkeep
 - example_dotclaude/hooks/entrypoints/user_prompt_submit.rb
-- example_dotclaude/hooks/entrypoints/user_prompt_submit/append_rules.rb
-- example_dotclaude/hooks/entrypoints/user_prompt_submit/log_user_prompt.rb
 - example_dotclaude/hooks/handlers/user_prompt_submit/append_rules.rb
 - example_dotclaude/hooks/handlers/user_prompt_submit/log_user_prompt.rb
 - example_dotclaude/settings.json
 - lib/claude_hooks.rb
 - lib/claude_hooks/base.rb
+- lib/claude_hooks/cli.rb
 - lib/claude_hooks/configuration.rb
 - lib/claude_hooks/logger.rb
 - lib/claude_hooks/notification.rb

data/example_dotclaude/hooks/entrypoints/user_prompt_submit/append_rules.rb

@@ -1,66 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'claude_hooks'
-
-# Hook script that appends rules to user prompt
-class AppendRules < ClaudeHooks::UserPromptSubmit
-
-  def call
-    log "Executing AppendRules hook"
-
-    # Read the rule content
-    rule_content = read_rule_content
-
-    if rule_content
-      add_additional_context!(rule_content)
-      log "Successfully added rule content as additional context (#{rule_content.length} characters)"
-    else
-      log "No rule content found", level: :warn
-    end
-
-    output_data
-  end
-
-  private
-
-  def read_rule_content
-    rule_file_path = path_for('rules/post-user-prompt.rule.md')
-
-    if File.exist?(rule_file_path)
-      content = File.read(rule_file_path).strip
-      return content unless content.empty?
-    end
-
-    log "Rule file not found or empty at: #{rule_file_path}", level: :warn
-    log "Base directory: #{base_dir}"
-    nil
-  end
-end
-
-# If this file is run directly (for testing), call the hook script
-if __FILE__ == $0
-  begin
-    require 'json'
-
-    input_data = JSON.parse(STDIN.read)
-    hook = AppendRules.new(input_data)
-    hook.call
-    puts hook.stringify_output
-  rescue JSON::ParserError => e
-    STDERR.puts "Error parsing JSON: #{e.message}"
-    puts JSON.generate({
-      continue: false,
-      stopReason: "JSON parsing error in AppendRules: #{e.message}",
-      suppressOutput: false
-    })
-    exit 0
-  rescue StandardError => e
-    STDERR.puts "Error in AppendRules hook: #{e.message}, #{e.backtrace.join("\n")}"
-    puts JSON.generate({
-      continue: false,
-      stopReason: "AppendRules execution error: #{e.message}",
-      suppressOutput: false
-    })
-    exit 0
-  end
-end

data/example_dotclaude/hooks/entrypoints/user_prompt_submit/log_user_prompt.rb

@@ -1,50 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'fileutils'
-require 'claude_hooks'
-
-# Example hook module that logs user prompts to a file
-class LogUserPrompt < ClaudeHooks::UserPromptSubmit
-
-  def call
-    log "Executing LogUserPrompt hook"
-
-    # Log the prompt to a file (just as an example)
-    log_file_path = path_for('logs/user_prompts.log')
-    ensure_log_directory_exists
-
-    timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S')
-
-    log <<~TEXT
-      Prompt: #{current_prompt}
-      Logged user prompt to #{log_file_path}
-    TEXT
-
-    nil
-  end
-
-  private
-
-  def ensure_log_directory_exists
-    log_dir = path_for('logs')
-    FileUtils.mkdir_p(log_dir) unless Dir.exist?(log_dir)
-  end
-end
-
-# If this file is run directly (for testing), call the hook
-if __FILE__ == $0
-  begin
-    require 'json'
-
-    hook = LogUserPrompt.new(JSON.parse(STDIN.read))
-    hook.call
-  rescue StandardError => e
-    STDERR.puts "Error in LogUserPrompt hook: #{e.message}, #{e.backtrace.join("\n")}"
-    puts JSON.generate({
-      continue: false,
-      stopReason: "LogUserPrompt execution error: #{e.message}",
-      suppressOutput: false
-    })
-    exit 0
-  end
-end