language-operator 0.1.81 → 0.1.82

data/.claude/skills/thor-cli-development/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: thor-cli-development
+description: Thor-based CLI development patterns for the aictl command-line interface
+---
+
+# Thor CLI Development Patterns
+
+## Purpose
+
+Provides consistent patterns for building the `aictl` CLI using Thor framework, including command structure, argument parsing, output formatting, and user experience patterns.
+
+## When to Use This Skill
+
+Automatically activates when:
+- Creating or modifying CLI commands in `lib/language_operator/cli/commands/`
+- Working with Thor command definitions
+- Implementing interactive wizards
+- Adding new subcommands to aictl
+- Working with command-line argument parsing and validation
+- Formatting CLI output (tables, progress, etc.)
+
+## Quick Start
+
+### New Command Checklist
+
+- [ ] Create command class in `lib/language_operator/cli/commands/`
+- [ ] Register command in `lib/language_operator/cli/main.rb`
+- [ ] Add comprehensive help text with examples
+- [ ] Implement input validation and error handling
+- [ ] Add progress indicators for long-running operations
+- [ ] Write RSpec tests in `spec/language_operator/cli/commands/`
+- [ ] Update shell completions if needed
+
+### Command Structure Checklist
+
+- [ ] Inherit from appropriate base class
+- [ ] Use descriptive `desc` and `long_desc`
+- [ ] Define options with types and defaults
+- [ ] Validate inputs early
+- [ ] Use consistent output formatting
+- [ ] Handle errors gracefully with helpful messages
+
+## Core Principles
+
+### 1. Thor Command Hierarchy
+
+```ruby
+# lib/language_operator/cli/main.rb
+module LanguageOperator::CLI
+  class Main < Thor
+    desc 'agent SUBCOMMAND ...ARGS', 'Manage agents'
+    subcommand 'agent', Commands::Agent
+    
+    desc 'model SUBCOMMAND ...ARGS', 'Manage language models'
+    subcommand 'model', Commands::Model
+  end
+end
+
+# Commands are organized by domain:
+# agent/    - Agent lifecycle management
+# model/    - Language model operations  
+# tool/     - Tool management
+# cluster/  - Kubernetes cluster operations
+```
+
+### 2. Command Class Pattern
+
+```ruby
+module LanguageOperator::CLI::Commands
+  class Agent < Thor
+    include CLI::Helpers::ClusterContext
+    include CLI::Helpers::ValidationHelper
+    
+    desc 'create NAME', 'Create a new agent'
+    long_desc <<~DESC
+      Create a new autonomous agent with the specified name.
+      
+      The agent will be deployed to the current Kubernetes cluster
+      and configured with the specified mode and schedule.
+      
+      Examples:
+        aictl agent create my-agent
+        aictl agent create scheduler --mode scheduled --schedule "0 */6 * * *"
+    DESC
+    option :mode, type: :string, default: 'autonomous',
+           desc: 'Agent execution mode (autonomous, scheduled, reactive)'
+    option :schedule, type: :string,
+           desc: 'Cron schedule for scheduled agents'
+    
+    def create(name)
+      # 1. Validate inputs
+      validate_agent_name!(name)
+      validate_cluster_connection!
+      
+      # 2. Interactive wizard if needed
+      wizard = Wizards::AgentWizard.new
+      config = wizard.run(name, options)
+      
+      # 3. Progress indication
+      spinner = TTY::Spinner.new("[:spinner] Creating agent...")
+      spinner.auto_spin
+      
+      # 4. Main operation
+      builder = Kubernetes::ResourceBuilder.new
+      manifest = builder.build_agent(config)
+      client = Kubernetes::Client.new
+      result = client.apply_resource(manifest)
+      
+      spinner.success
+      
+      # 5. Success output
+      say_status(:success, "Agent '#{name}' created", :green)
+      display_agent_info(result)
+      
+    rescue LanguageOperator::ValidationError => e
+      say_error("Validation failed: #{e.message}")
+      exit(1)
+    rescue LanguageOperator::NetworkError => e
+      say_error("Network error: #{e.message}")
+      exit(1)
+    end
+    
+    private
+    
+    def validate_agent_name!(name)
+      return if name.match?(/\A[a-z0-9-]+\z/)
+      raise ValidationError, "Invalid agent name: #{name}. Use lowercase letters, numbers, and hyphens."
+    end
+    
+    def display_agent_info(result)
+      table = TTY::Table.new(
+        header: ['Property', 'Value'],
+        rows: [
+          ['Name', result.metadata.name],
+          ['Mode', result.spec.mode],
+          ['Status', result.status&.phase || 'Creating']
+        ]
+      )
+      puts table.render(:ascii)
+    end
+  end
+end
+```
+
+### 3. Input Validation Patterns
+
+```ruby
+# Validate required arguments
+def create(name)
+  if name.nil? || name.empty?
+    say_error("Agent name is required")
+    invoke(:help, ['create'])
+    exit(1)
+  end
+  # ... rest of implementation
+end
+
+# Validate option combinations
+def deploy(name)
+  if options[:mode] == 'scheduled' && options[:schedule].nil?
+    say_error("Schedule is required for scheduled agents")
+    say("Example: aictl agent deploy #{name} --mode scheduled --schedule '0 */6 * * *'")
+    exit(1)
+  end
+end
+
+# Validate environment dependencies
+def status
+  validate_cluster_connection!
+  validate_agent_exists!(options[:agent])
+end
+```
+
+### 4. Output Formatting Standards
+
+```ruby
+# Success messages
+say_status(:success, "Operation completed", :green)
+
+# Error messages  
+say_error("Something went wrong: #{error.message}")
+
+# Info messages
+say_status(:info, "Checking cluster status...", :cyan)
+
+# Tables for structured data
+table = TTY::Table.new(
+  header: ['Name', 'Status', 'Mode'],
+  rows: agents.map { |a| [a.name, a.status, a.mode] }
+)
+puts table.render(:ascii, padding: [0, 1])
+
+# Progress indicators
+spinner = TTY::Spinner.new("[:spinner] Processing...")
+spinner.auto_spin
+# ... operation ...
+spinner.success("✓ Done!")
+```
+
+## Common Patterns
+
+### Pattern 1: Interactive Wizard
+
+```ruby
+module LanguageOperator::CLI::Wizards
+  class AgentWizard
+    include CLI::Helpers::UserPrompts
+    
+    def run(name, options = {})
+      say_header("Agent Creation Wizard")
+      
+      config = AgentConfig.new(name)
+      
+      # Mode selection
+      config.mode = options[:mode] || select_mode
+      
+      # Schedule if needed
+      if config.mode == 'scheduled'
+        config.schedule = options[:schedule] || prompt_for_schedule
+      end
+      
+      # Model selection
+      config.model = select_model
+      
+      # Confirmation
+      display_summary(config)
+      return config if yes?("Create agent with these settings?")
+      
+      say("Agent creation cancelled", :yellow)
+      exit(0)
+    end
+    
+    private
+    
+    def select_mode
+      prompt.select(
+        "Select execution mode:",
+        {
+          "Autonomous" => :autonomous,
+          "Scheduled" => :scheduled, 
+          "Reactive" => :reactive
+        }
+      )
+    end
+    
+    def prompt_for_schedule
+      prompt.ask(
+        "Enter cron schedule:",
+        default: "0 */6 * * *",
+        validate: ->(input) { CronParser.new(input).valid? }
+      )
+    end
+  end
+end
+```
+
+### Pattern 2: Error Handling with Context
+
+```ruby
+# Global error handler in base command
+module LanguageOperator::CLI
+  class BaseCommand < Thor
+    def self.exit_on_failure?
+      true
+    end
+    
+    private
+    
+    def say_error(message)
+      say("ERROR: #{message}", :red)
+    end
+    
+    def handle_kubernetes_error(error)
+      case error
+      when K8s::Error::NotFound
+        say_error("Resource not found. Check if the agent exists.")
+        say("Run 'aictl agent list' to see available agents.")
+      when K8s::Error::Unauthorized  
+        say_error("Access denied. Check your cluster permissions.")
+        say("Run 'aictl cluster status' to verify connection.")
+      else
+        say_error("Kubernetes error: #{error.message}")
+        say("Check cluster connectivity and try again.")
+      end
+    end
+  end
+end
+```
+
+### Pattern 3: Subcommand Registration
+
+```ruby
+# lib/language_operator/cli/main.rb
+module LanguageOperator::CLI
+  class Main < Thor
+    desc 'version', 'Show version information'
+    def version
+      say("aictl version #{LanguageOperator::VERSION}")
+    end
+    
+    desc 'status', 'Show cluster and agent status'
+    def status
+      Commands::Status.new.invoke(:all)
+    end
+    
+    # Subcommands
+    register(Commands::Agent, 'agent', 'agent SUBCOMMAND', 'Manage agents')
+    register(Commands::Model, 'model', 'model SUBCOMMAND', 'Manage models') 
+    register(Commands::Tool, 'tool', 'tool SUBCOMMAND', 'Manage tools')
+    register(Commands::Cluster, 'cluster', 'cluster SUBCOMMAND', 'Manage clusters')
+  end
+end
+```
+
+### Pattern 4: Configuration and Context
+
+```ruby
+module LanguageOperator::CLI::Helpers
+  module ClusterContext
+    def current_cluster
+      @current_cluster ||= begin
+        context = Kubernetes::Client.new.current_context
+        ClusterConfig.new(context)
+      end
+    end
+    
+    def validate_cluster_connection!
+      current_cluster.validate_connection!
+    rescue LanguageOperator::NetworkError => e
+      say_error("Cannot connect to cluster: #{e.message}")
+      say("Check your kubeconfig and cluster status.")
+      exit(1)
+    end
+    
+    def with_cluster_context(&block)
+      say_status(:info, "Using cluster: #{current_cluster.name}", :cyan)
+      yield(current_cluster)
+    end
+  end
+end
+```
+
+## Resource Files
+
+For detailed information, see:
+- [Command Templates](resources/command-templates.md) - Boilerplate for new commands
+- [Testing CLIs](resources/testing-patterns.md) - RSpec patterns for CLI testing
+- [User Experience](resources/ux-patterns.md) - Consistent user experience guidelines
+
+## Anti-Patterns to Avoid
+
+❌ **Missing help text** - Always provide `desc` and examples
+❌ **Silent failures** - Show clear error messages and exit codes
+❌ **Inconsistent output** - Use standardized formatting helpers
+❌ **No input validation** - Validate early and show helpful errors
+❌ **Long-running without feedback** - Use progress indicators
+❌ **Poor error recovery** - Provide actionable suggestions
+
+## Quick Reference
+
+| Command Element | Pattern |
+|----------------|---------|
+| Command definition | `desc 'name ARGS', 'Description'` |
+| Options | `option :name, type: :string, default: 'value'` |
+| Validation | `validate_something!(value)` |
+| Success output | `say_status(:success, message, :green)` |
+| Error output | `say_error(message)` |
+| Tables | `TTY::Table.new(header: [...], rows: [...])` |
+| Progress | `TTY::Spinner.new("[:spinner] Message...")` |
+| User input | `prompt.ask/select/yes?` |
+
+## Testing Patterns
+
+```ruby
+# spec/language_operator/cli/commands/agent_spec.rb
+RSpec.describe LanguageOperator::CLI::Commands::Agent do
+  subject(:command) { described_class.new }
+  
+  let(:kubernetes_client) { instance_double(LanguageOperator::Kubernetes::Client) }
+  
+  before do
+    allow(LanguageOperator::Kubernetes::Client).to receive(:new).and_return(kubernetes_client)
+    allow($stdout).to receive(:puts) # Suppress output during tests
+  end
+  
+  describe '#create' do
+    context 'with valid agent name' do
+      it 'creates the agent successfully' do
+        expect(kubernetes_client).to receive(:apply_resource).and_return(mock_agent)
+        
+        command.create('test-agent')
+        
+        expect($stdout).to have_received(:puts).with(/success/i)
+      end
+    end
+    
+    context 'with invalid agent name' do
+      it 'shows validation error and exits' do
+        expect { command.create('Invalid_Name') }.to raise_error(SystemExit)
+      end
+    end
+  end
+end
+```
+
+## Shell Completions
+
+```bash
+# completions/aictl.bash
+_aictl() {
+    local cur prev opts
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    
+    case "${prev}" in
+        aictl)
+            opts="agent model tool cluster status version help"
+            COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+            return 0
+            ;;
+        agent)
+            opts="create delete list inspect logs"
+            COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+            return 0
+            ;;
+    esac
+}
+
+complete -F _aictl aictl
+```

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- **BREAKING**: Renamed CLI binary from `aictl` to `langop`
+  - Binary renamed: `bin/aictl` → `bin/langop`
+  - Shell completions updated: `completions/aictl.*` → `completions/langop.*`
+  - All documentation updated to reference `langop`
+  - Migration required: Replace `aictl` with `langop` in scripts and automation
+
 ### Removed
 - **BREAKING**: Removed deprecated DSL v0 (workflow/step model)
   - Deleted `WorkflowDefinition` and `StepDefinition` classes

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    language-operator (0.1.80)
+    language-operator (0.1.82)
+      bcrypt (~> 3.1)
       faraday (~> 2.0)
       json-schema (~> 5.0)
       k8s-ruby (~> 0.17)
@@ -32,6 +33,7 @@ GEM
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
+    bcrypt (3.1.20)
     benchmark (0.5.0)
     bigdecimal (3.3.1)
     coderay (1.1.3)

data/completions/{_aictl → _langop}

@@ -1,8 +1,8 @@
-#compdef aictl
+#compdef langop
 
-# zsh completion for aictl
+# zsh completion for langop
 
-_aictl() {
+_langop() {
     local -a commands
     local curcontext="$curcontext" state line
     typeset -A opt_args
@@ -14,7 +14,7 @@ _aictl() {
         'persona:Manage agent personas'
         'tool:Manage MCP tools'
         'status:Show system status and overview'
-        'version:Show aictl and operator version'
+        'version:Show langop and operator version'
         'new:Generate a new tool or agent project'
         'serve:Start an MCP server for tools'
         'test:Test tool definitions'
@@ -29,34 +29,34 @@ _aictl() {
 
     case $state in
         command)
-            _describe 'aictl command' commands
+            _describe 'langop command' commands
             ;;
         args)
             case $line[1] in
                 cluster)
-                    _aictl_cluster
+                    _langop_cluster
                     ;;
                 use)
-                    _aictl_use
+                    _langop_use
                     ;;
                 agent)
-                    _aictl_agent
+                    _langop_agent
                     ;;
                 persona)
-                    _aictl_persona
+                    _langop_persona
                     ;;
                 tool)
-                    _aictl_tool
+                    _langop_tool
                     ;;
                 new)
-                    _aictl_new
+                    _langop_new
                     ;;
             esac
             ;;
     esac
 }
 
-_aictl_cluster() {
+_langop_cluster() {
     local -a subcommands
     subcommands=(
         'create:Create a new language cluster'
@@ -77,18 +77,18 @@ _aictl_cluster() {
         args)
             case $line[1] in
                 inspect|delete)
-                    _aictl_clusters
+                    _langop_clusters
                     ;;
             esac
             ;;
     esac
 }
 
-_aictl_use() {
-    _aictl_clusters
+_langop_use() {
+    _langop_clusters
 }
 
-_aictl_agent() {
+_langop_agent() {
     local -a subcommands
     subcommands=(
         'create:Create a new autonomous agent'
@@ -114,25 +114,25 @@ _aictl_agent() {
             case $line[1] in
                 create)
                     _arguments \
-                        '--cluster=[Override current cluster context]:cluster:_aictl_clusters' \
+                        '--cluster=[Override current cluster context]:cluster:_langop_clusters' \
                         '--create-cluster=[Create cluster inline]:name:' \
-                        '--persona=[Use specific persona]:persona:_aictl_personas' \
+                        '--persona=[Use specific persona]:persona:_langop_personas' \
                         '--dry-run[Preview without creating]'
                     ;;
                 list)
                     _arguments \
                         '--all-clusters[Show agents from all clusters]' \
-                        '--cluster=[Show agents from specific cluster]:cluster:_aictl_clusters'
+                        '--cluster=[Show agents from specific cluster]:cluster:_langop_clusters'
                     ;;
                 inspect|delete|logs|code|edit|pause|resume)
-                    _aictl_agents
+                    _langop_agents
                     ;;
             esac
             ;;
     esac
 }
 
-_aictl_persona() {
+_langop_persona() {
     local -a subcommands
     subcommands=(
         'list:List available personas'
@@ -154,18 +154,18 @@ _aictl_persona() {
             case $line[1] in
                 create)
                     _arguments \
-                        '--from=[Inherit from existing persona]:persona:_aictl_personas' \
-                        '--cluster=[Override current cluster]:cluster:_aictl_clusters'
+                        '--from=[Inherit from existing persona]:persona:_langop_personas' \
+                        '--cluster=[Override current cluster]:cluster:_langop_clusters'
                     ;;
                 show|edit|delete)
-                    _aictl_personas
+                    _langop_personas
                     ;;
             esac
             ;;
     esac
 }
 
-_aictl_tool() {
+_langop_tool() {
     local -a subcommands
     subcommands=(
         'list:List tools in current cluster'
@@ -186,18 +186,18 @@ _aictl_tool() {
         args)
             case $line[1] in
                 auth|test|delete)
-                    _aictl_tools
+                    _langop_tools
                     ;;
                 list)
                     _arguments \
-                        '--cluster=[Override current cluster]:cluster:_aictl_clusters'
+                        '--cluster=[Override current cluster]:cluster:_langop_clusters'
                     ;;
             esac
             ;;
     esac
 }
 
-_aictl_new() {
+_langop_new() {
     local -a types
     types=('tool:Generate a new tool project' 'agent:Generate a new agent project')
     _describe 'project type' types
@@ -205,28 +205,28 @@ _aictl_new() {
 
 # Helper functions for dynamic completion
 
-_aictl_clusters() {
+_langop_clusters() {
     local -a clusters
-    clusters=(${(f)"$(aictl cluster list 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v '^─' | grep -v '^NAME')"})
+    clusters=(${(f)"$(langop cluster list 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v '^─' | grep -v '^NAME')"})
     _describe 'cluster' clusters
 }
 
-_aictl_agents() {
+_langop_agents() {
     local -a agents
-    agents=(${(f)"$(aictl agent list 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v '^─' | grep -v '^NAME')"})
+    agents=(${(f)"$(langop agent list 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v '^─' | grep -v '^NAME')"})
     _describe 'agent' agents
 }
 
-_aictl_personas() {
+_langop_personas() {
     local -a personas
-    personas=(${(f)"$(aictl persona list 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v '^─' | grep -v '^NAME')"})
+    personas=(${(f)"$(langop persona list 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v '^─' | grep -v '^NAME')"})
     _describe 'persona' personas
 }
 
-_aictl_tools() {
+_langop_tools() {
     local -a tools
-    tools=(${(f)"$(aictl tool list 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v '^─' | grep -v '^NAME')"})
+    tools=(${(f)"$(langop tool list 2>/dev/null | tail -n +2 | awk '{print $1}' | grep -v '^─' | grep -v '^NAME')"})
     _describe 'tool' tools
 }
 
-_aictl "$@"
+_langop "$@"