feat: Enhanced Picocli Integration with Clean CommandContext API

[gnodet]

🚀 Enhanced Picocli Integration for Excellent User Experience

This PR introduces a comprehensive enhancement to JLine's Picocli integration, focusing on providing an excellent user experience while maintaining a clean, simple API.

📋 Overview

Builds upon the existing picocli-shell-jline3 foundation to provide:

• Clean CommandContext API - Framework-agnostic execution context without Gogo-specific dependencies
• Automatic Context Injection - Multiple injection patterns (constructor, field, method parameter)
• Rich Interactive Features - Enhanced completion, styled help, progress indicators
• Simple Configuration - Fluent builder pattern for easy setup

✨ Key Features

🎯 Clean API Design

• CommandContext Interface - Unified execution context for all command frameworks
• No Framework Dependencies - Removed session() method and other framework-specific concerns
• Builder Pattern - Fluent configuration for registry setup
• Automatic Discovery - Package scanning for @command annotated classes

🔧 Advanced Context Injection

// Constructor injection
public MyCommand(CommandContext context) { ... }

// Field injection
private CommandContext context; // Automatically injected

// Method parameter injection
public Integer call(CommandContext context) { ... }

🎨 Rich User Experience

• Enhanced Completion - File path completion, enum completion, rich styling
• Smart Help Generation - Styled help with examples, parameter types, default values
• Progress Indicators - Built-in support for progress bars and status messages
• Interactive Prompts - Support for interactive parameter prompting

⚙️ Flexible Configuration

PicocliConfiguration config = PicocliConfiguration.fullFeatured()
    .enableInteractivePrompts(true)
    .enableProgressIndicators(true)
    .enableEnhancedCompletion(true);

🏗️ Architecture

Core Components

• CommandContext - Clean execution context interface
• PicocliCommandRegistry - Main registry with automatic context injection
• ContextInjectingExecutionStrategy - Handles method parameter injection
• EnhancedPicocliCompleter - Rich completion with file and enum support
• PicocliConfiguration - Comprehensive configuration options

Integration Points

• Compatible with existing JLine widgets (TailTip, AutoSuggestion)
• Works with SystemRegistry for multi-framework command support
• Converts to/from PosixCommands.Context for compatibility

📝 Usage Examples

Simple Setup

CommandContext context = CommandContext.builder()
    .terminal(terminal)
    .currentDir(workDir)
    .build();

PicocliCommandRegistry registry = new PicocliCommandRegistry(context)
    .register(new MyCommand())
    .register(AnotherCommand.class);

Advanced Setup

PicocliCommandRegistry registry = PicocliCommandRegistry.builder(context)
    .register(new GreetCommand())
    .register(FileCommand.class)
    .scanPackages("com.example.commands")
    .build();

SystemRegistry systemRegistry = new SystemRegistryImpl(parser, terminal, workDir, configPath);
systemRegistry.setCommandRegistries(registry, builtins);

Rich Command Example

@Command(name = "deploy", description = "Deploy application")
public class DeployCommand implements Callable<Integer> {
    @Option(names = "--env") String environment;
    
    public Integer call(CommandContext ctx) {
        // Rich terminal access
        ctx.out().println(coloredText("Deploying to " + environment));
        
        // Progress indication
        if (ctx.isTty()) {
            showProgressBar(ctx.terminal());
        }
        
        return 0;
    }
}

🧪 Testing

Comprehensive test suite covering:

• ✅ Basic command registration and execution
• ✅ Context injection (all patterns)
• ✅ Builder pattern functionality
• ✅ Command info and option generation
• ✅ Error handling and validation

📊 Comparison with Basic Integration

Feature	Basic picocli-shell-jline3	Enhanced Integration
Context Access	Manual passing	Automatic injection
Completion	Basic	Rich + File + Enum
Help	Plain text	Styled + Examples
Registration	Manual setup	Fluent builder
Error Handling	Basic	Comprehensive
Configuration	Hardcoded	Flexible config
Testing	None	Full test suite

🔄 Backward Compatibility

• Fully compatible with existing JLine systems
• Can be used alongside other CommandRegistry implementations
• CommandContext converts to/from PosixCommands.Context
• No breaking changes to existing APIs

📁 Files Added/Modified

New Core API

• console/src/main/java/org/jline/console/CommandContext.java
• console/src/main/java/org/jline/console/DefaultCommandContext.java

Enhanced Picocli Integration

• console/src/main/java/org/jline/console/picocli/PicocliCommandRegistry.java
• console/src/main/java/org/jline/console/picocli/ContextInjectingExecutionStrategy.java
• console/src/main/java/org/jline/console/picocli/PicocliCmdDescGenerator.java
• console/src/main/java/org/jline/console/picocli/PicocliOptDescGenerator.java
• console/src/main/java/org/jline/console/picocli/EnhancedPicocliCompleter.java
• console/src/main/java/org/jline/console/picocli/PicocliConfiguration.java
• console/src/main/java/org/jline/console/picocli/package-info.java

Examples and Tests

• demo/src/main/java/org/jline/demo/examples/EnhancedPicocliExample.java
• console/src/test/java/org/jline/console/picocli/PicocliCommandRegistryTest.java

🎯 Benefits

1. Excellent User Experience - Rich completion, styled help, progress indicators
2. Clean API - Framework-agnostic design without unnecessary dependencies
3. Easy Integration - Fluent builder pattern and automatic context injection
4. Flexible Configuration - Customizable behavior for different use cases
5. Production Ready - Comprehensive testing and error handling
6. Extensible - Easy to add new features and customizations

🔮 Future Enhancements

• Integration with Spring Boot auto-configuration
• Support for custom completion providers
• Interactive parameter validation
• Command history and favorites
• Plugin architecture for extensions

This enhancement makes JLine's Picocli integration much more powerful and user-friendly while maintaining the clean, simple API design philosophy.

---

Pull Request opened by Augment Code with guidance from the PR author