thor-interactive 0.1.0.pre.5 → 0.1.0.pre.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7166b4156516b241939081e8c9fc67aba249ceae1be85b4693d4afdb7638b08d
-  data.tar.gz: 8c3f92ab064d86f27a028dd685037d8e205e452ae840a674c39025d21fd8acfb
+  metadata.gz: 79cee8c04a17409c31979f43c38dc2d03bd725e894fd4970970c0c5784a768ac
+  data.tar.gz: 91bb06f9ddefce2a5d150efc644aa10a77e3abe8099854dccade6e5770941339
 SHA512:
-  metadata.gz: 66f640e0df6d3f1699c6cd1e9612bd6f149da4a7716bcc66e49092a4dbe0f6e568eb98e97dc9e8eecc12548f8149eadbf01ab4149e0ab832d6a57fcf7c3237fe
-  data.tar.gz: a5993427b1e28efaa8849440ff0a16e724cb25dc746d0f49292bad78c2d1f364f5526e57d30e73361c236c1460c248ddb4eaf7c32ec370965622583982881232
+  metadata.gz: d6b99410867f9b4008f106dee56e87446b85e2473180369e211b66ea5b41cef2960e7da7848d399f7aeee47f3f28b0dc450bd1d623f2124ff75a1f7873506f3a
+  data.tar.gz: 1a8c863bb31996ee2378a26845c4793cd0260fbf067813aecf285fb3f9aeb9bd14001538e5613c12862a79b065285cf5642c75942585eac0244cb10365773169

data/README.md

@@ -1,38 +1,30 @@
-# Thor::Interactive
+<img src="/docs/assets/thor-interactive-wide.png" alt="thor-interactive" height="80px">
 
-Turn any Thor CLI into an interactive REPL with persistent state and auto-completion.
+Turn any Thor CLI into an interactive terminal application with persistent state, auto-completion, and a rich TUI powered by [ratatui_ruby](https://www.ratatui-ruby.dev/).
 
-Thor::Interactive automatically converts your existing Thor command-line applications into interactive REPLs, maintaining state between commands and providing auto-completion for commands and parameters. Perfect for applications that benefit from persistent sessions like RAG pipelines, database tools, or any CLI that maintains caches or connections.
+Thor::Interactive converts your existing Thor command-line applications into interactive sessions — a Claude Code-like terminal UI with multi-line input, a status bar, animated spinners, and theming. Perfect for RAG pipelines, database tools, or any CLI that benefits from persistent connections and cached state.
 
 ## Features
 
-- **Zero Configuration**: Works with any existing Thor application without modifications
+- **TUI Mode**: Rich terminal UI with multi-line input, status bar, spinner, tab completion overlay, and theming — powered by Rust via [ratatui_ruby](https://www.ratatui-ruby.dev/)
 - **State Persistence**: Maintains class variables and instance state between commands
-- **Auto-completion**: Tab completion for command names and basic parameter support
-- **Default Handlers**: Configurable fallback for non-command input
-- **Command History**: Persistent readline history with up/down arrow navigation
-- **Both Modes**: Supports both traditional CLI usage and interactive REPL mode
-- **Graceful Exit**: Proper handling of Ctrl+C interrupts and Ctrl+D/exit commands
+- **Auto-completion**: Tab completion for command names, options, and paths
+- **Default Handlers**: Configurable fallback for non-command input (great for natural language interfaces)
+- **Command History**: Persistent history with up/down arrow navigation
+- **Graceful Degradation**: Falls back to a Reline-based REPL if `ratatui_ruby` is not installed
 
-## Installation
+## Quick Start
+
+### Installation
 
 Add to your application's Gemfile:
 
 ```ruby
 gem 'thor-interactive'
+gem 'ratatui_ruby', '~> 1.4'  # Enables TUI mode
 ```
 
-Or install directly:
-
-```bash
-gem install thor-interactive
-```
-
-## Quick Start
-
-### Option 1: Add Interactive Command (Recommended)
-
-Add one line to your Thor class to get an `interactive` command:
+### Basic Usage
 
 ```ruby
 require 'thor'
@@ -41,462 +33,214 @@ require 'thor/interactive'
 class MyApp < Thor
   include Thor::Interactive::Command
 
-  # Your existing Thor commands work unchanged
+  configure_interactive(
+    ui_mode: :tui,
+    prompt: "myapp> "
+  )
+
   desc "hello NAME", "Say hello"
   def hello(name)
     puts "Hello #{name}!"
   end
+
+  desc "search QUERY", "Search for something"
+  def search(query)
+    puts "Searching for: #{query}"
+  end
 end
+
+MyApp.start(ARGV)
 ```
 
-Now your app supports both modes:
+Then `bundle install` and run:
 
 ```bash
 # Normal CLI usage (unchanged)
-ruby myapp.rb hello World
-
-# New interactive mode with slash commands
-ruby myapp.rb interactive
-myapp> /hello Alice
-Hello Alice!
-myapp> Natural language input goes to default handler
-myapp> exit
-```
-
-### Option 2: Programmatic Usage
+bundle exec ruby myapp.rb hello World
 
-Start an interactive shell programmatically:
+# Interactive TUI mode
+bundle exec ruby myapp.rb interactive
+```
 
-```ruby
-require 'thor/interactive'
+> **Note:** `bundle exec` ensures `ratatui_ruby` is loaded. Without it, you'll get the basic Reline REPL instead of the TUI.
 
-class MyApp < Thor
-  desc "hello NAME", "Say hello"
-  def hello(name)
-    puts "Hello #{name}!"
-  end
-end
+### Key Bindings
 
-# Start interactive shell
-Thor::Interactive.start(MyApp)
-```
+| Key | Action |
+|-----|--------|
+| Enter | Submit input |
+| Shift+Enter | Insert newline (Kitty protocol terminals) |
+| Ctrl+N | Toggle multi-line mode (fallback for older terminals) |
+| Ctrl+J | Always submit (even in multi-line mode) |
+| Tab | Auto-complete commands |
+| Ctrl+C | Clear input / double-tap to exit |
+| Ctrl+D | Exit |
+| Escape | Clear input / exit multi-line mode |
+| Up/Down | History navigation (single-line) or cursor movement (multi-line) |
 
-## State Persistence Example
+## State Persistence
 
-The key benefit is maintaining state between commands:
+The key benefit of interactive mode is maintaining state between commands. In normal CLI mode, each invocation starts fresh. In interactive mode, a single instance persists — so expensive connections, caches, and counters survive between commands:
 
 ```ruby
-class RAGApp < Thor
+class ProjectApp < Thor
   include Thor::Interactive::Command
 
-  # These persist between commands in interactive mode
-  class_variable_set(:@@llm_client, nil)
-  class_variable_set(:@@conversation_history, [])
+  @@db = nil
+  @@tasks = []
 
-  desc "ask TEXT", "Ask the LLM a question"
-  def ask(text)
-    # Initialize once, reuse across commands
-    @@llm_client ||= expensive_llm_initialization
+  configure_interactive(
+    ui_mode: :tui,
+    prompt: "project> "
+  )
 
-    response = @@llm_client.chat(text)
-    @@conversation_history << {input: text, output: response}
-    puts response
+  desc "connect HOST", "Connect to database"
+  def connect(host)
+    @@db = Database.new(host)  # Expensive — only done once
+    puts "Connected to #{host}"
   end
 
-  desc "history", "Show conversation history"
-  def history
-    @@conversation_history.each_with_index do |item, i|
-      puts "#{i+1}. Q: #{item[:input]}"
-      puts "   A: #{item[:output]}"
-    end
+  desc "add TASK", "Add a task"
+  def add(task)
+    @@tasks << {name: task, created_at: Time.now}
+    puts "Added: #{task} (#{@@tasks.size} total)"
   end
-end
-```
-
-In interactive mode:
-```bash
-ruby rag_app.rb interactive
-
-rag> /ask What is Ruby?
-# LLM initializes once  
-Ruby is a programming language...
-
-rag> /ask Tell me more
-# LLM client reused, conversation context maintained
-Based on our previous discussion about Ruby...
-
-rag> What's the difference between Ruby and Python?
-# Natural language goes directly to default handler (ask command)
-Ruby and Python differ in several ways...
-
-rag> /history  
-1. Q: What is Ruby?
-   A: Ruby is a programming language...
-2. Q: Tell me more
-   A: Based on our previous discussion about Ruby...
-3. Q: What's the difference between Ruby and Python?
-   A: Ruby and Python differ in several ways...
-```
-
-## Configuration
-
-Configure interactive behavior:
-
-```ruby
-class MyApp < Thor
-  include Thor::Interactive::Command
 
-  configure_interactive(
-    prompt: "myapp> ",                    # Custom prompt
-    allow_nested: false,                  # Prevent nested sessions (default)
-    nested_prompt_format: "[L%d] %s",    # Format for nested prompts (if allowed)
-    default_handler: proc do |input, thor_instance|
-      # Handle unrecognized input
-      # IMPORTANT: Use direct method calls, NOT invoke(), to avoid Thor's
-      # silent failure on repeated calls to the same method
-      thor_instance.search(input)  # ✅ Works repeatedly
-      # thor_instance.invoke(:search, [input])  # ❌ Fails after first call
+  desc "list", "Show all tasks"
+  def list
+    @@tasks.each_with_index do |t, i|
+      puts "#{i + 1}. #{t[:name]}"
     end
-  )
+  end
 
-  desc "search QUERY", "Search for something"
-  def search(query)
-    puts "Searching for: #{query}"
+  desc "status", "Show connection and task count"
+  def status
+    puts "Database: #{@@db ? 'connected' : 'not connected'}"
+    puts "Tasks: #{@@tasks.size}"
   end
 end
 ```
 
-Now unrecognized input gets sent to the search command:
-
 ```bash
-myapp> hello world
-Hello world!
-
-myapp> some random text
-Searching for: some random text
-```
+project> /connect localhost
+Connected to localhost
 
-### Nested Session Management
+project> /add "Design API"
+Added: Design API (1 total)
 
-By default, thor-interactive prevents nested interactive sessions to avoid confusion:
+project> /add "Write tests"
+Added: Write tests (2 total)
 
-```ruby
-class MyApp < Thor
-  include Thor::Interactive::Command
-
-  configure_interactive(
-    prompt: "myapp> ",
-    allow_nested: false  # Default behavior
-  )
-end
-```
-
-If you try to run `interactive` while already in an interactive session:
-
-```bash
-myapp> interactive
-Already in an interactive session.
-To allow nested sessions, configure with: configure_interactive(allow_nested: true)
+project> /status
+Database: connected    # Still connected — same instance!
+Tasks: 2
 ```
 
-#### Allowing Nested Sessions
+## Configuration
 
-For advanced use cases, you can enable nested sessions:
+### TUI Options
 
 ```ruby
-class AdvancedApp < Thor
-  include Thor::Interactive::Command
-
-  configure_interactive(
-    prompt: "advanced> ",
-    allow_nested: true,
-    nested_prompt_format: "[Level %d] %s"  # Optional custom format
-  )
-end
+configure_interactive(
+  ui_mode: :tui,
+  prompt: "myapp> ",
+  theme: :dark,                          # :default, :dark, :light, :minimal, or custom hash
+  status_bar: {
+    left: ->(instance) { " MyApp" },     # Left section
+    right: ->(instance) { " v1.0 " }     # Right section
+  },
+  spinner_messages: [                     # Custom spinner messages (optional)
+    "Thinking", "Brewing", "Crunching"
+  ]
+)
 ```
 
-With nested sessions enabled:
-
-```bash
-$ ruby advanced_app.rb interactive
-AdvancedApp Interactive Shell
-Type 'help' for available commands, 'exit' to quit
-
-advanced> interactive
-AdvancedApp Interactive Shell (nested level 2)
-Type 'exit' to return to previous level, or 'help' for commands
+### Custom Theme
 
-[Level 2] advanced> hello nested
-Hello nested!
-
-[Level 2] advanced> exit
-Exiting nested session...
-
-advanced> exit
-Goodbye!
+```ruby
+configure_interactive(
+  ui_mode: :tui,
+  theme: {
+    error_fg: :light_red,
+    input_border: :cyan,
+    status_bar_fg: :white,
+    status_bar_bg: :dark_gray
+  }
+)
 ```
 
-### ⚠️ Important: Default Handler Implementation
+See `Thor::Interactive::TUI::Theme::THEMES` for the full list of configurable color keys.
 
-**Always use direct method calls in default handlers, NOT `invoke()`:**
+### Default Handlers
 
-```ruby
-# ✅ CORRECT - Works for repeated calls
-configure_interactive(
-  default_handler: proc do |input, thor_instance|
-    thor_instance.ask(input)  # Direct method call
-  end
-)
+Route unrecognized input to a command automatically:
 
-# ❌ WRONG - Silent failure after first call  
+```ruby
 configure_interactive(
+  ui_mode: :tui,
+  prompt: "myapp> ",
   default_handler: proc do |input, thor_instance|
-    thor_instance.invoke(:ask, [input])  # Thor's invoke fails silently on repeat calls
+    thor_instance.search(input)
   end
 )
 ```
 
-**Why:** Thor's `invoke` method has internal deduplication that prevents repeated calls to the same method on the same instance. This causes silent failures in interactive mode where users expect to be able to repeat commands.
-
-## Advanced Usage
-
-### Custom Options
-
-Pass options to the interactive command:
-
 ```bash
-ruby myapp.rb interactive --prompt="custom> " --history-file=~/.my_history
-```
-
-### Multiple Applications
-
-Use the same gem with different Thor applications:
-
-```ruby
-# Database CLI
-class DBApp < Thor
-  include Thor::Interactive::Command
-  configure_interactive(prompt: "db> ")
-end
+myapp> /search thor interactive
+Searching for: thor interactive
 
-# API Testing CLI
-class APIApp < Thor
-  include Thor::Interactive::Command
-  configure_interactive(prompt: "api> ")
-end
+myapp> some random text
+Searching for: some random text    # No slash needed — default handler kicks in
 ```
 
-### Without Mixin
+**Important:** Always use direct method calls in default handlers, not `invoke()`. Thor's `invoke` has internal deduplication that silently prevents repeated calls to the same method.
 
-Use programmatically without including the module:
+### All Options
 
 ```ruby
-default_handler = proc do |input, instance|
-  puts "You said: #{input}"
-end
-
-Thor::Interactive.start(MyThorApp,
-  prompt: "custom> ",
-  default_handler: default_handler,
-  history_file: "~/.custom_history"
+configure_interactive(
+  ui_mode: :tui,                         # :tui for TUI mode (omit for basic REPL)
+  prompt: "myapp> ",                     # Custom prompt
+  theme: :dark,                          # TUI theme
+  status_bar: { left: ..., right: ... }, # TUI status bar sections
+  spinner_messages: [...],               # TUI spinner messages
+  history_file: "~/.myapp_history",      # Custom history file location
+  allow_nested: false,                   # Prevent nested sessions (default)
+  default_handler: proc { |input, i| },  # Handle non-command input
+  ctrl_c_behavior: :clear_prompt,        # :clear_prompt, :show_help, or :silent
+  double_ctrl_c_timeout: 0.5            # Seconds for double Ctrl+C exit
 )
 ```
 
-## Examples
+## Basic REPL Mode (without ratatui_ruby)
 
-See the `examples/` directory for complete working examples:
+If you don't need the TUI, or `ratatui_ruby` isn't available, thor-interactive provides a Reline-based REPL. Just omit `ui_mode: :tui`:
 
-- `sample_app.rb` - Demonstrates all features with a simple CLI
-- `test_interactive.rb` - Test script showing the API
+```ruby
+class MyApp < Thor
+  include Thor::Interactive::Command
 
-Run the example:
+  configure_interactive(prompt: "myapp> ")
 
-```bash
-cd examples
-ruby sample_app.rb interactive
+  desc "hello NAME", "Say hello"
+  def hello(name)
+    puts "Hello #{name}!"
+  end
+end
 ```
 
-## How It Works
-
-Thor::Interactive creates a persistent instance of your Thor class and invokes commands on that same instance, preserving any instance variables or class variables between commands. This is different from normal CLI usage where each command starts with a fresh instance.
+Or start programmatically:
 
-The shell provides:
-- Tab completion for command names
-- Readline history with persistent storage
-- Proper signal handling (Ctrl+C, Ctrl+D)
-- Help system integration
-- Configurable default handlers for non-commands
+```ruby
+Thor::Interactive.start(MyApp, prompt: "custom> ")
+```
 
 ## Development
 
-### Getting Started
-
-After checking out the repo:
-
 ```bash
 bundle install           # Install dependencies
-bundle exec rspec        # Run full test suite with coverage
+bundle exec rspec        # Run tests (446 examples)
 bundle exec rake build   # Build gem
-open coverage/index.html # View coverage report (after running tests)
-```
-
-### Testing
-
-The gem includes comprehensive tests organized into unit and integration test suites with **72%+ code coverage**:
-
-```bash
-# Run all tests
-bundle exec rspec
-
-# Run with detailed output
-bundle exec rspec --format documentation
-
-# View coverage report
-open coverage/index.html      # Detailed HTML coverage report
-
-# Run specific test suites
-bundle exec rspec spec/unit/           # Unit tests only
-bundle exec rspec spec/integration/    # Integration tests only
-
-# Run specific test files
-bundle exec rspec spec/unit/shell_spec.rb
-bundle exec rspec spec/integration/shell_integration_spec.rb
-```
-
-#### Test Structure
-
-```
-spec/
-├── spec_helper.rb              # Test configuration and shared setup
-├── support/
-│   ├── test_thor_apps.rb       # Test Thor applications (not packaged)
-│   └── capture_helpers.rb      # Test utilities for I/O capture
-├── unit/                       # Unit tests for individual components
-│   ├── shell_spec.rb           # Thor::Interactive::Shell tests
-│   ├── command_spec.rb         # Thor::Interactive::Command mixin tests
-│   └── completion_spec.rb      # Completion system tests
-└── integration/                # Integration tests for full workflows
-    └── shell_integration_spec.rb # End-to-end interactive shell tests
-```
-
-#### Test Applications
-
-Tests use dedicated Thor applications in `spec/support/test_thor_apps.rb`:
-
-- `SimpleTestApp` - Basic Thor app with simple commands
-- `StatefulTestApp` - App with state persistence and default handlers
-- `SubcommandTestApp` - App with Thor subcommands
-- `OptionsTestApp` - App with various Thor options and arguments
-
-These test apps are excluded from the packaged gem but provide comprehensive test coverage.
-
-### Example Applications
-
-The `examples/` directory contains working examples (these ARE packaged with the gem):
-
-#### Running the Sample Application
-
-```bash
-cd examples
-
-# Run in normal CLI mode
-ruby sample_app.rb help
-ruby sample_app.rb hello World
-ruby sample_app.rb count
-ruby sample_app.rb add "Test item"
-
-# Run in interactive mode
-ruby sample_app.rb interactive
-```
-
-#### Interactive Session Example
-
-```bash
-$ ruby sample_app.rb interactive
-SampleApp Interactive Shell
-Type 'help' for available commands, 'exit' to quit
-
-sample> hello Alice
-Hello Alice!
-
-sample> count
-Count: 1
-
-sample> count
-Count: 2    # Note: state persisted!
-
-sample> add "Buy groceries"
-Added: Buy groceries
-
-sample> add "Walk the dog"
-Added: Walk the dog
-
-sample> list
-1. Buy groceries
-2. Walk the dog
-
-sample> status
-Counter: 2, Items: 2
-
-sample> This is random text that doesn't match a command
-Echo: This is random text that doesn't match a command
-
-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 list maintain their values between commands
-2. **Auto-completion**: Try typing `h<TAB>` or `co<TAB>` to see command completion
-3. **Default Handler**: Text that doesn't match a command gets sent to the `echo` command
-4. **Command History**: Use up/down arrows to navigate previous commands
-5. **Error Handling**: Try invalid commands or missing arguments
-6. **Both Modes**: The same application works as traditional CLI and interactive REPL
-
-### Performance Testing
-
-For applications with expensive initialization (like LLM clients), you can measure the performance benefit:
-
-```bash
-# CLI mode - initializes fresh each time
-time ruby sample_app.rb count
-time ruby sample_app.rb count
-time ruby sample_app.rb count
-
-# Interactive mode - initializes once, reuses state
-ruby sample_app.rb interactive
-# Then run: count, count, count
-```
-
-### Debugging
-
-Enable debug mode to see backtraces on errors:
-
-```bash
-DEBUG=1 ruby sample_app.rb interactive
-```
-
-Or in your application:
-
-```ruby
-ENV["DEBUG"] = "1"
-Thor::Interactive.start(MyApp)
 ```
 
 ## Contributing