thor-interactive 0.1.0.pre.1

data/examples/README.md

@@ -0,0 +1,144 @@
+# Thor Interactive Examples
+
+## Sample Application
+
+The `sample_app.rb` demonstrates both normal Thor CLI usage and interactive REPL mode.
+
+### Normal CLI Usage
+
+```bash
+# Run individual commands
+ruby sample_app.rb hello World
+ruby sample_app.rb count
+ruby sample_app.rb add "Buy groceries"
+ruby sample_app.rb list
+ruby sample_app.rb status
+ruby sample_app.rb help
+```
+
+### Interactive REPL Mode
+
+```bash
+# Start interactive mode
+ruby sample_app.rb interactive
+```
+
+Once in interactive mode:
+
+```
+sample> hello Alice
+Hello Alice!
+
+sample> count
+Count: 1
+
+sample> count  
+Count: 2
+
+sample> add "First item"
+Added 'First item'. Total items: 1
+
+sample> add "Second item"  
+Added 'Second item'. Total items: 2
+
+sample> list
+Items:
+  1. First item
+  2. Second item
+
+sample> status
+Application Status:
+  Counter: 2
+  Items in list: 2
+  Memory usage: 15234 KB
+
+sample> This is unrecognized text
+Echo: This is unrecognized text
+
+sample> help
+Available commands:
+  hello                Say hello to NAME
+  count                Show and increment counter (demonstrates state persistence)
+  add                  Add item to list (demonstrates state persistence)
+  list                 Show all items
+  clear                Clear all items
+  echo                 Echo the text back (used as default handler)
+  status               Show application status
+  interactive          Start an interactive REPL for this application
+
+Special commands:
+  help [COMMAND]       Show help for command
+  exit/quit/q          Exit the REPL
+
+sample> exit
+Goodbye!
+```
+
+## Key Features Demonstrated
+
+### 1. State Persistence
+- The `@@counter` and `@@items` class variables maintain their state between commands in interactive mode
+- In normal CLI mode, each command starts fresh
+
+### 2. Auto-completion
+- Tab completion works for command names
+- Try typing `h<TAB>` or `a<TAB>` to see completions
+
+### 3. Default Handler
+- Text that doesn't match a command gets sent to the `echo` command
+- This is configurable via the `default_handler` option
+
+### 4. Built-in Help
+- `help` shows all available commands
+- `help COMMAND` shows help for a specific command
+
+### 5. History
+- Up/down arrows navigate command history
+- History is persistent across sessions
+
+### 6. Graceful Exit
+- Ctrl+C interrupts current operation
+- Ctrl+D or `exit`/`quit`/`q` exits the REPL
+
+## Integration Patterns
+
+### Minimal Integration
+```ruby
+class MyApp < Thor
+  include Thor::Interactive::Command
+  
+  # Your existing Thor commands...
+  desc "hello NAME", "Say hello"
+  def hello(name)
+    puts "Hello #{name}!"
+  end
+end
+
+# Now available: ruby myapp.rb interactive
+```
+
+### Custom Configuration
+```ruby
+class MyApp < Thor
+  include Thor::Interactive::Command
+  
+  configure_interactive(
+    prompt: "myapp> ",
+    default_handler: proc do |input, thor_instance|
+      # Handle unrecognized input
+      thor_instance.invoke(:search, [input])
+    end
+  )
+  
+  # Your commands...
+end
+```
+
+### Programmatic Usage
+```ruby
+# Instead of using the mixin, start programmatically
+Thor::Interactive.start(MyApp, 
+  prompt: "custom> ",
+  default_handler: proc { |input, instance| puts "Got: #{input}" }
+)
+```

data/examples/demo_session.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demo script showing the difference between CLI and interactive modes
+
+require_relative "../lib/thor/interactive"
+require_relative "sample_app"
+
+puts "=== Thor Interactive Demo ==="
+puts
+puts "1. CLI Mode (each command runs fresh):"
+puts "   $ ruby sample_app.rb count"
+puts "   $ ruby sample_app.rb count"
+puts
+
+system("ruby sample_app.rb count")
+system("ruby sample_app.rb count")
+
+puts "\n   Notice: Both show 'Count: 1' because state resets"
+puts
+
+puts "2. Interactive Mode (state persists):"
+puts "   To see interactive mode, run:"
+puts "   $ ruby sample_app.rb interactive"
+puts
+puts "   Then try these commands in sequence:"
+puts "   sample> count"
+puts "   sample> count" 
+puts "   sample> add \"first item\""
+puts "   sample> add \"second item\""
+puts "   sample> list"
+puts "   sample> status"
+puts "   sample> help"
+puts "   sample> This text goes to default handler"
+puts "   sample> exit"
+puts
+puts "=== Key Differences ==="
+puts
+puts "CLI Mode:"
+puts "- Fresh Thor instance each command"
+puts "- No state persistence"
+puts "- Standard Thor behavior"
+puts
+puts "Interactive Mode:"
+puts "- Single persistent Thor instance"
+puts "- State maintained between commands"
+puts "- Auto-completion with TAB"
+puts "- Command history with arrow keys"
+puts "- Default handler for unrecognized input"
+puts "- Built-in help system"
+puts
+puts "=== Features Implemented ==="
+puts
+puts "✓ Generic design - works with any Thor application"
+puts "✓ State persistence through single Thor instance"
+puts "✓ Auto-completion for command names"
+puts "✓ Configurable default handlers"
+puts "✓ Command history with persistent storage"
+puts "✓ Both CLI and interactive modes supported"
+puts "✓ Proper error handling and signal management"
+puts "✓ Help system integration"
+puts "✓ Comprehensive test suite"
+puts
+puts "Ready for your Claude Code-like RAG application!"

data/examples/nested_example.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/thor/interactive"
+
+# Example app that allows nested interactive sessions
+class NestedApp < Thor
+  include Thor::Interactive::Command
+
+  configure_interactive(
+    prompt: "nested> ",
+    allow_nested: true,  # Allow nested interactive sessions
+    nested_prompt_format: "[L%d] %s"  # Custom format for nested prompts
+  )
+
+  desc "hello NAME", "Say hello"
+  def hello(name)
+    puts "Hello #{name}!"
+  end
+
+  desc "demo", "Show nesting demo info"
+  def demo
+    level = ENV['THOR_INTERACTIVE_LEVEL']
+    puts "Current nesting level: #{level || 'not in interactive mode'}"
+    puts "Try running 'interactive' to see nested sessions!"
+  end
+
+  desc "status", "Show session status"
+  def status
+    if ENV['THOR_INTERACTIVE_SESSION']
+      level = ENV['THOR_INTERACTIVE_LEVEL'].to_i
+      puts "In interactive session - Level #{level}"
+    else
+      puts "Not in interactive session"
+    end
+  end
+end
+
+# Example app that prevents nested sessions (default behavior)
+class SafeApp < Thor
+  include Thor::Interactive::Command
+
+  configure_interactive(
+    prompt: "safe> ",
+    allow_nested: false  # This is the default, but being explicit
+  )
+
+  desc "hello NAME", "Say hello"
+  def hello(name)
+    puts "Hello #{name}!"
+  end
+
+  desc "demo", "Show nesting prevention"
+  def demo
+    puts "This app prevents nested sessions."
+    puts "Try running 'interactive' to see the protection!"
+  end
+end
+
+if __FILE__ == $0
+  puts "=== Nested Interactive Sessions Demo ==="
+  puts
+  puts "1. NestedApp - allows nested sessions:"
+  puts "   ruby nested_example.rb nested"
+  puts 
+  puts "2. SafeApp - prevents nested sessions:"
+  puts "   ruby nested_example.rb safe"
+  puts
+  
+  case ARGV[0]
+  when "nested"
+    ARGV.shift
+    NestedApp.start(ARGV)
+  when "safe" 
+    ARGV.shift
+    SafeApp.start(ARGV)
+  else
+    puts "Usage: ruby nested_example.rb [nested|safe] [command]"
+  end
+end

data/examples/sample_app.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../lib/thor/interactive"
+
+# Example Thor application that demonstrates both normal CLI usage
+# and interactive REPL mode
+class SampleApp < Thor
+  include Thor::Interactive::Command
+
+  # Configure interactive mode
+  configure_interactive(
+    prompt: "sample> ",
+    allow_nested: false,  # Prevent nested interactive sessions by default
+    default_handler: proc do |input, thor_instance|
+      # Send unrecognized input to the 'echo' command
+      thor_instance.invoke(:echo, [input])
+    end
+  )
+
+  # Class variable to demonstrate state persistence in interactive mode
+  class_variable_set(:@@counter, 0)
+  class_variable_set(:@@items, [])
+
+  desc "hello NAME", "Say hello to NAME"
+  def hello(name)
+    puts "Hello #{name}!"
+  end
+
+  desc "count", "Show and increment counter (demonstrates state persistence)"
+  def count
+    @@counter += 1
+    puts "Count: #{@@counter}"
+  end
+
+  desc "add ITEM", "Add item to list (demonstrates state persistence)"
+  def add(item)
+    @@items << item
+    puts "Added '#{item}'. Total items: #{@@items.length}"
+  end
+
+  desc "list", "Show all items"
+  def list
+    if @@items.empty?
+      puts "No items in the list"
+    else
+      puts "Items:"
+      @@items.each_with_index do |item, index|
+        puts "  #{index + 1}. #{item}"
+      end
+    end
+  end
+
+  desc "clear", "Clear all items"
+  def clear
+    @@items.clear
+    puts "List cleared"
+  end
+
+  desc "echo TEXT", "Echo the text back (used as default handler)"
+  def echo(*words)
+    text = words.join(" ")
+    puts "Echo: #{text}"
+  end
+
+  desc "status", "Show application status"
+  def status
+    puts "Application Status:"
+    puts "  Counter: #{@@counter}"
+    puts "  Items in list: #{@@items.length}"
+    puts "  Memory usage: #{`ps -o rss= -p #{Process.pid}`.strip} KB" rescue "Unknown"
+  end
+end
+
+# This allows the file to work both ways:
+# 1. Normal Thor CLI: ruby sample_app.rb hello World
+# 2. Interactive mode: ruby sample_app.rb interactive
+if __FILE__ == $0
+  SampleApp.start(ARGV)
+end

data/examples/test_interactive.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test script to verify interactive functionality
+# This simulates what would happen in interactive mode
+
+require_relative "../lib/thor/interactive"
+
+class TestApp < Thor
+  include Thor::Interactive::Command
+
+  configure_interactive(
+    prompt: "test> ",
+    default_handler: proc do |input, instance|
+      puts "Default handler got: #{input}"
+    end
+  )
+
+  class_variable_set(:@@counter, 0)
+
+  desc "count", "Increment and show counter"
+  def count
+    @@counter += 1
+    puts "Count: #{@@counter}"
+  end
+
+  desc "hello NAME", "Say hello"
+  def hello(name)
+    puts "Hello #{name}!"
+  end
+end
+
+# Test normal CLI mode
+puts "=== Testing Normal CLI Mode ==="
+puts "Running: hello Alice"
+TestApp.start(["hello", "Alice"])
+puts "\nRunning: count (twice - should both be 1)"
+TestApp.start(["count"])
+TestApp.start(["count"])
+
+puts "\n=== Testing Interactive Shell Creation ==="
+shell = Thor::Interactive::Shell.new(TestApp)
+puts "Shell created successfully with Thor class: #{shell.thor_class}"
+puts "Shell has persistent Thor instance: #{shell.thor_instance.class}"
+
+puts "\n=== Testing Command Recognition ==="
+# Test if commands are recognized
+test_commands = %w[hello count help exit]
+test_commands.each do |cmd|
+  recognized = shell.send(:thor_command?, cmd)
+  puts "Command '#{cmd}': #{recognized ? 'recognized' : 'not recognized'}"
+end
+
+puts "\n=== Testing Completion ==="
+completions = shell.send(:complete_commands, "h")
+puts "Completions for 'h': #{completions}"
+
+puts "\n=== Interactive mode ready! ==="
+puts "To test interactively, run: ruby examples/sample_app.rb interactive"
+puts "Then try commands like:"
+puts "  count (multiple times to see state persistence)"
+puts "  add item1"
+puts "  add item2" 
+puts "  list"
+puts "  hello Alice"
+puts "  help"
+puts "  exit"

data/lib/thor/interactive/command.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "shell"
+
+class Thor
+  module Interactive
+    # Mixin to add an interactive command to Thor applications
+    module Command
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.class_eval do
+          desc "interactive", "Start an interactive REPL for this application"
+          option :prompt, type: :string, desc: "Custom prompt for the REPL"
+          option :history_file, type: :string, desc: "Custom history file location"
+          
+          def interactive
+            # Check for nested sessions unless explicitly allowed
+            if ENV['THOR_INTERACTIVE_SESSION'] && !self.class.interactive_options[:allow_nested]
+              puts "Already in an interactive session."
+              puts "To allow nested sessions, configure with: configure_interactive(allow_nested: true)"
+              return
+            end
+            
+            opts = self.class.interactive_options.dup
+            opts[:prompt] = options[:prompt] || options["prompt"] if options[:prompt] || options["prompt"]
+            opts[:history_file] = options[:history_file] || options["history_file"] if options[:history_file] || options["history_file"]
+            
+            Thor::Interactive::Shell.new(self.class, opts).start
+          end
+        end
+      end
+
+      module ClassMethods
+        def interactive_options
+          @interactive_options ||= { allow_nested: false }
+        end
+
+        def configure_interactive(**options)
+          interactive_options.merge!(options)
+        end
+      end
+    end
+  end
+end

data/lib/thor/interactive/shell.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "reline"
+require "shellwords"
+require "thor"
+
+class Thor
+  module Interactive
+    class Shell
+      DEFAULT_PROMPT = "> "
+      DEFAULT_HISTORY_FILE = "~/.thor_interactive_history"
+      EXIT_COMMANDS = %w[exit quit q].freeze
+
+      attr_reader :thor_class, :thor_instance, :prompt
+
+      def initialize(thor_class, options = {})
+        @thor_class = thor_class
+        @thor_instance = thor_class.new
+        
+        # Merge class-level interactive options if available
+        merged_options = {}
+        if thor_class.respond_to?(:interactive_options)
+          merged_options.merge!(thor_class.interactive_options)
+        end
+        merged_options.merge!(options)
+        
+        @merged_options = merged_options
+        @default_handler = merged_options[:default_handler]
+        @prompt = merged_options[:prompt] || DEFAULT_PROMPT
+        @history_file = File.expand_path(merged_options[:history_file] || DEFAULT_HISTORY_FILE)
+        
+        setup_completion
+        load_history
+      end
+
+      def start
+        # Track that we're in an interactive session
+        was_in_session = ENV['THOR_INTERACTIVE_SESSION']
+        nesting_level = ENV['THOR_INTERACTIVE_LEVEL'].to_i
+        
+        ENV['THOR_INTERACTIVE_SESSION'] = 'true'
+        ENV['THOR_INTERACTIVE_LEVEL'] = (nesting_level + 1).to_s
+        
+        # Adjust prompt for nested sessions if configured
+        display_prompt = @prompt
+        if nesting_level > 0 && @merged_options[:nested_prompt_format]
+          display_prompt = @merged_options[:nested_prompt_format] % [nesting_level + 1, @prompt]
+        elsif nesting_level > 0
+          display_prompt = "(#{nesting_level + 1}) #{@prompt}"
+        end
+        
+        show_welcome(nesting_level)
+        
+        loop do
+          line = Reline.readline(display_prompt, true)
+          break if should_exit?(line)
+          
+          next if line.nil? || line.strip.empty?
+          
+          process_input(line.strip)
+        rescue Interrupt
+          puts "\n(Interrupted - press Ctrl+D or type 'exit' to quit)"
+        rescue => e
+          puts "Error: #{e.message}"
+          puts e.backtrace.first(3) if ENV["DEBUG"]
+        end
+        
+        save_history
+        puts nesting_level > 0 ? "Exiting nested session..." : "Goodbye!"
+        
+      ensure
+        # Restore previous session state
+        if was_in_session
+          ENV['THOR_INTERACTIVE_SESSION'] = 'true'
+          ENV['THOR_INTERACTIVE_LEVEL'] = nesting_level.to_s
+        else
+          ENV.delete('THOR_INTERACTIVE_SESSION')
+          ENV.delete('THOR_INTERACTIVE_LEVEL')
+        end
+      end
+
+      private
+
+      def setup_completion
+        Reline.completion_proc = proc do |text, preposing|
+          complete_input(text, preposing)
+        end
+      end
+
+      def complete_input(text, preposing)
+        # If we're at the start of the line, complete command names
+        if preposing.strip.empty?
+          complete_commands(text)
+        else
+          # Try to complete command options or let it fall back to file completion
+          complete_command_options(text, preposing)
+        end
+      end
+
+      def complete_commands(text)
+        return [] if text.nil?
+        
+        command_names = @thor_class.tasks.keys + EXIT_COMMANDS + ["help"]
+        command_names.select { |cmd| cmd.start_with?(text) }.sort
+      end
+
+      def complete_command_options(text, preposing)
+        # Basic implementation - can be enhanced later
+        # For now, just return empty array to let Reline handle file completion
+        []
+      end
+
+      def process_input(input)
+        # Handle completely empty input
+        return if input.nil? || input.strip.empty?
+
+        args = parse_input(input)
+        return if args.empty?
+
+        command = args.shift
+
+        if thor_command?(command)
+          invoke_thor_command(command, args)
+        elsif @default_handler
+          @default_handler.call(input, @thor_instance)
+        else
+          puts "Unknown command: '#{command}'. Type 'help' for available commands."
+        end
+      end
+
+      def parse_input(input)
+        Shellwords.split(input)
+      rescue ArgumentError => e
+        puts "Error parsing input: #{e.message}"
+        []
+      end
+
+      def thor_command?(command)
+        @thor_class.tasks.key?(command) || 
+        @thor_class.subcommand_classes.key?(command) ||
+        command == "help"
+      end
+
+      def invoke_thor_command(command, args)
+        # Use the persistent instance to maintain state
+        if command == "help"
+          show_help(args.first)
+        else
+          # For simple commands, call directly for state persistence
+          # For complex options/subcommands, this is a basic implementation
+          if @thor_instance.respond_to?(command)
+            @thor_instance.send(command, *args)
+          else
+            @thor_instance.invoke(command, args)
+          end
+        end
+      rescue Thor::Error => e
+        puts "Thor Error: #{e.message}"
+      rescue ArgumentError => e
+        puts "Thor Error: #{e.message}"
+        puts "Try: help #{command}" if thor_command?(command)
+      rescue StandardError => e
+        puts "Error: #{e.message}"
+      end
+
+      def show_help(command = nil)
+        if command && @thor_class.tasks.key?(command)
+          @thor_class.command_help(Thor::Base.shell.new, command)
+        else
+          puts "Available commands:"
+          @thor_class.tasks.each do |name, task|
+            puts "  #{name.ljust(20)} #{task.description}"
+          end
+          puts
+          puts "Special commands:"
+          puts "  help [COMMAND]       Show help for command"
+          puts "  exit/quit/q          Exit the REPL"
+          puts
+        end
+      end
+
+      def should_exit?(line)
+        return true if line.nil? # Ctrl+D
+        
+        stripped = line.strip.downcase
+        EXIT_COMMANDS.include?(stripped)
+      end
+
+      def show_welcome(nesting_level = 0)
+        if nesting_level > 0
+          puts "#{@thor_class.name} Interactive Shell (nested level #{nesting_level + 1})"
+          puts "Type 'exit' to return to previous level, or 'help' for commands"
+        else
+          puts "#{@thor_class.name} Interactive Shell"
+          puts "Type 'help' for available commands, 'exit' to quit"
+        end
+        puts
+      end
+
+      def load_history
+        return unless File.exist?(@history_file)
+        
+        File.readlines(@history_file, chomp: true).each do |line|
+          Reline::HISTORY << line
+        end
+      rescue => e
+        # Ignore history loading errors
+      end
+
+      def save_history
+        return unless Reline::HISTORY.size > 0
+        
+        File.write(@history_file, Reline::HISTORY.to_a.join("\n"))
+      rescue => e
+        # Ignore history saving errors  
+      end
+    end
+  end
+end