language-operator 0.1.31 → 0.1.35

data/lib/language_operator/type_coercion.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Type coercion system for task inputs and outputs
+  #
+  # Provides smart type coercion with automatic conversion for common cases
+  # and clear error messages when coercion is not possible. This enables
+  # flexible type handling while maintaining type safety.
+  #
+  # Supported types:
+  # - integer: Coerces String, Integer, Float to Integer
+  # - number: Coerces String, Integer, Float to Float
+  # - string: Coerces any value to String via to_s
+  # - boolean: Coerces String, Boolean to Boolean (explicit values only)
+  # - array: Strict validation (no coercion)
+  # - hash: Strict validation (no coercion)
+  # - any: No coercion, passes through any value
+  #
+  # @example Integer coercion
+  #   TypeCoercion.coerce("123", "integer")  # => 123
+  #   TypeCoercion.coerce(123, "integer")    # => 123
+  #   TypeCoercion.coerce("abc", "integer")  # raises ArgumentError
+  #
+  # @example Boolean coercion
+  #   TypeCoercion.coerce("true", "boolean")   # => true
+  #   TypeCoercion.coerce("1", "boolean")      # => true
+  #   TypeCoercion.coerce("false", "boolean")  # => false
+  #   TypeCoercion.coerce("maybe", "boolean")  # raises ArgumentError
+  #
+  # @example String coercion (never fails)
+  #   TypeCoercion.coerce(:symbol, "string")  # => "symbol"
+  #   TypeCoercion.coerce(123, "string")      # => "123"
+  #
+  # @example Strict validation
+  #   TypeCoercion.coerce([1, 2], "array")    # => [1, 2]
+  #   TypeCoercion.coerce({a: 1}, "array")    # raises ArgumentError
+  module TypeCoercion
+    # Coerce a value to the specified type
+    #
+    # @param value [Object] Value to coerce
+    # @param type [String] Target type (see COERCION_RULES for valid types)
+    # @return [Object] Coerced value
+    # @raise [ArgumentError] If coercion fails or type is unknown
+    #
+    # @example
+    #   TypeCoercion.coerce("345", "integer")  # => 345
+    #   TypeCoercion.coerce("true", "boolean") # => true
+    def self.coerce(value, type)
+      case type
+      when 'integer'
+        coerce_integer(value)
+      when 'number'
+        coerce_number(value)
+      when 'string'
+        coerce_string(value)
+      when 'boolean'
+        coerce_boolean(value)
+      when 'array'
+        validate_array(value)
+      when 'hash'
+        validate_hash(value)
+      when 'any'
+        value
+      else
+        raise ArgumentError, "Unknown type: #{type}"
+      end
+    end
+
+    # Coerce value to Integer
+    #
+    # Accepts: String, Integer, Float
+    # Coercion: Uses Ruby's Integer() method
+    # Errors: Cannot parse as integer
+    #
+    # @param value [Object] Value to coerce
+    # @return [Integer] Coerced integer
+    # @raise [ArgumentError] If coercion fails
+    #
+    # @example
+    #   coerce_integer("123")   # => 123
+    #   coerce_integer(123)     # => 123
+    #   coerce_integer(123.0)   # => 123
+    #   coerce_integer("abc")   # raises ArgumentError
+    def self.coerce_integer(value)
+      return value if value.is_a?(Integer)
+
+      Integer(value)
+    rescue ArgumentError, TypeError => e
+      raise ArgumentError, "Cannot coerce #{value.inspect} to integer: #{e.message}"
+    end
+
+    # Coerce value to Float (number)
+    #
+    # Accepts: String, Integer, Float
+    # Coercion: Uses Ruby's Float() method
+    # Errors: Cannot parse as number
+    #
+    # @param value [Object] Value to coerce
+    # @return [Float] Coerced number
+    # @raise [ArgumentError] If coercion fails
+    #
+    # @example
+    #   coerce_number("3.14")      # => 3.14
+    #   coerce_number(3)           # => 3.0
+    #   coerce_number(3.14)        # => 3.14
+    #   coerce_number("not a num") # raises ArgumentError
+    def self.coerce_number(value)
+      return value if value.is_a?(Numeric)
+
+      Float(value)
+    rescue ArgumentError, TypeError => e
+      raise ArgumentError, "Cannot coerce #{value.inspect} to number: #{e.message}"
+    end
+
+    # Coerce value to String
+    #
+    # Accepts: Any object with to_s method (all Ruby objects)
+    # Coercion: Uses to_s method
+    # Errors: Never (everything has to_s)
+    #
+    # @param value [Object] Value to coerce
+    # @return [String] Coerced string
+    #
+    # @example
+    #   coerce_string(:symbol)  # => "symbol"
+    #   coerce_string(123)      # => "123"
+    #   coerce_string(nil)      # => ""
+    def self.coerce_string(value)
+      value.to_s
+    end
+
+    # Coerce value to Boolean
+    #
+    # Accepts: Boolean, String (explicit values only)
+    # Coercion: Case-insensitive string matching
+    # Truthy: "true", "1", "yes", "t", "y"
+    # Falsy: "false", "0", "no", "f", "n"
+    # Errors: Ambiguous values (e.g., "maybe", "unknown")
+    #
+    # @param value [Object] Value to coerce
+    # @return [Boolean] Coerced boolean
+    # @raise [ArgumentError] If coercion is ambiguous
+    #
+    # @example
+    #   coerce_boolean(true)      # => true
+    #   coerce_boolean("true")    # => true
+    #   coerce_boolean("1")       # => true
+    #   coerce_boolean("yes")     # => true
+    #   coerce_boolean(false)     # => false
+    #   coerce_boolean("false")   # => false
+    #   coerce_boolean("0")       # => false
+    #   coerce_boolean("no")      # => false
+    #   coerce_boolean("maybe")   # raises ArgumentError
+    def self.coerce_boolean(value)
+      return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      # Only allow string values for coercion (not integers or other types)
+      raise ArgumentError, "Cannot coerce #{value.inspect} to boolean" unless value.is_a?(String)
+
+      str = value.strip.downcase
+      return true if %w[true 1 yes t y].include?(str)
+      return false if %w[false 0 no f n].include?(str)
+
+      raise ArgumentError, "Cannot coerce #{value.inspect} to boolean"
+    end
+
+    # Validate value is an Array (no coercion)
+    #
+    # Accepts: Array
+    # Coercion: None (strict validation)
+    # Errors: Not an array
+    #
+    # @param value [Object] Value to validate
+    # @return [Array] Validated array
+    # @raise [ArgumentError] If not an array
+    #
+    # @example
+    #   validate_array([1, 2, 3])  # => [1, 2, 3]
+    #   validate_array({a: 1})     # raises ArgumentError
+    def self.validate_array(value)
+      raise ArgumentError, "Expected array, got #{value.class}" unless value.is_a?(Array)
+
+      value
+    end
+
+    # Validate value is a Hash (no coercion)
+    #
+    # Accepts: Hash
+    # Coercion: None (strict validation)
+    # Errors: Not a hash
+    #
+    # @param value [Object] Value to validate
+    # @return [Hash] Validated hash
+    # @raise [ArgumentError] If not a hash
+    #
+    # @example
+    #   validate_hash({a: 1, b: 2})  # => {a: 1, b: 2}
+    #   validate_hash([1, 2])         # raises ArgumentError
+    def self.validate_hash(value)
+      raise ArgumentError, "Expected hash, got #{value.class}" unless value.is_a?(Hash)
+
+      value
+    end
+
+    # Coercion rules table
+    #
+    # @return [Hash] Mapping of types to their coercion behavior
+    # rubocop:disable Metrics/MethodLength
+    def self.coercion_rules
+      {
+        'integer' => {
+          accepts: 'String, Integer, Float',
+          method: 'Integer(value)',
+          errors: 'Cannot parse as integer'
+        },
+        'number' => {
+          accepts: 'String, Integer, Float',
+          method: 'Float(value)',
+          errors: 'Cannot parse as number'
+        },
+        'string' => {
+          accepts: 'Any object',
+          method: 'value.to_s',
+          errors: 'Never (everything has to_s)'
+        },
+        'boolean' => {
+          accepts: 'Boolean, String (explicit values)',
+          method: 'Pattern matching (true/1/yes/t/y or false/0/no/f/n)',
+          errors: 'Ambiguous values'
+        },
+        'array' => {
+          accepts: 'Array only',
+          method: 'No coercion (strict)',
+          errors: 'Not an array'
+        },
+        'hash' => {
+          accepts: 'Hash only',
+          method: 'No coercion (strict)',
+          errors: 'Not a hash'
+        },
+        'any' => {
+          accepts: 'Any value',
+          method: 'No coercion (pass-through)',
+          errors: 'Never'
+        }
+      }
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end

data/lib/language_operator/ux/base.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'tty-prompt'
+require 'pastel'
+require_relative '../cli/formatters/progress_formatter'
+
+module LanguageOperator
+  module Ux
+    # Base class for interactive user experience flows
+    #
+    # Provides common infrastructure for TTY-based interactive wizards
+    # including cluster context validation and standard UI helpers.
+    #
+    # @example Creating a new UX flow
+    #   class CreateModel < Base
+    #     def execute
+    #       show_welcome
+    #       # ... flow logic
+    #     end
+    #   end
+    #
+    # @example Using a UX flow
+    #   Ux::CreateModel.execute(ctx)
+    #
+    class Base
+      attr_reader :prompt, :pastel, :ctx
+
+      # Initialize the UX flow
+      #
+      # @param ctx [Object, nil] Cluster context (required unless overridden)
+      def initialize(ctx = nil)
+        @prompt = TTY::Prompt.new
+        @pastel = Pastel.new
+        @ctx = ctx
+
+        validate_cluster_context! if requires_cluster?
+      end
+
+      # Execute the UX flow
+      #
+      # Subclasses must override this method to implement their flow logic.
+      #
+      # @raise [NotImplementedError] if not overridden by subclass
+      def execute
+        raise NotImplementedError, "#{self.class.name} must implement #execute"
+      end
+
+      # Execute the UX flow as a class method
+      #
+      # @param ctx [Object, nil] Cluster context
+      # @return [Object] Result of execute method
+      def self.execute(ctx = nil)
+        new(ctx).execute
+      end
+
+      private
+
+      # Whether this flow requires a cluster context
+      #
+      # Subclasses can override to disable cluster requirement (e.g., Quickstart).
+      #
+      # @return [Boolean] true if cluster is required
+      def requires_cluster?
+        true
+      end
+
+      # Validate that a cluster context is available
+      #
+      # Exits with error if cluster is required but not provided.
+      def validate_cluster_context!
+        return unless requires_cluster?
+        return if ctx
+
+        CLI::Formatters::ProgressFormatter.error(
+          'No cluster selected. Run "aictl cluster add" first.'
+        )
+        exit 1
+      end
+    end
+  end
+end

data/lib/language_operator/ux/concerns/README.md

@@ -0,0 +1,155 @@
+# Ux::Concerns
+
+Reusable mixins for interactive UX flows.
+
+## Available Concerns
+
+### Headings
+
+Provides consistent formatting for headings, step indicators, and banners.
+
+```ruby
+class MyFlow < Ux::Base
+  include Concerns::Headings
+
+  def execute
+    heading('Welcome!', emoji: '🎉')
+    step_heading(1, 3, 'First Step')
+    subheading('Configuration')
+    separator
+  end
+end
+```
+
+**Methods:**
+- `heading(text, emoji: nil, width: 50)` - Display prominent heading with border
+- `step_heading(current, total, title, width: 50)` - Display step indicator
+- `subheading(text)` - Display simple subheading
+- `separator(width: 50, char: '─')` - Display separator line
+- `section(title, description: nil)` - Display section header with description
+
+### ProviderHelpers
+
+Common operations for LLM provider integration.
+
+```ruby
+class MyFlow < Ux::Base
+  include Concerns::ProviderHelpers
+
+  def execute
+    result = test_provider_connection(:anthropic, api_key: 'sk-...')
+    models = fetch_provider_models(:openai, api_key: 'sk-...')
+    info = provider_info(:anthropic)
+  end
+end
+```
+
+**Methods:**
+- `test_provider_connection(provider, api_key:, endpoint:)` - Test connection to provider
+- `fetch_provider_models(provider, api_key:, endpoint:)` - Fetch available models
+- `provider_info(provider)` - Get provider display info and documentation URLs
+
+**Supported Providers:**
+- `:anthropic` - Anthropic (Claude)
+- `:openai` - OpenAI (GPT)
+- `:openai_compatible` - OpenAI-compatible endpoints (Ollama, vLLM, LM Studio, etc)
+
+### InputValidation
+
+Common input validation and prompting helpers.
+
+```ruby
+class MyFlow < Ux::Base
+  include Concerns::InputValidation
+
+  def execute
+    url = ask_url('Enter endpoint URL:')
+    name = ask_k8s_name('Resource name:', default: 'my-resource')
+    email = ask_email('Your email:')
+    api_key = ask_secret('API key:')
+    port = ask_port('Port:', default: 8080)
+    confirmed = ask_yes_no('Continue?', default: true)
+  end
+end
+```
+
+**Methods:**
+- `ask_url(question, default:, required:)` - Prompt for URL with validation
+- `ask_k8s_name(question, default:)` - Prompt for Kubernetes resource name
+- `ask_email(question, default:)` - Prompt for email address
+- `ask_secret(question, required:)` - Prompt for masked input (API keys, passwords)
+- `ask_port(question, default:)` - Prompt for port number (1-65535)
+- `ask_yes_no(question, default:)` - Prompt for yes/no confirmation
+- `ask_select(question, choices, per_page:)` - Prompt for selection from list
+- `validate_k8s_name(name)` - Validate and normalize Kubernetes name
+- `validate_url(url)` - Validate URL format
+
+## Usage Guidelines
+
+### When to Use Concerns
+
+✅ **DO use concerns for:**
+- Common formatting patterns used across multiple flows
+- Repeated validation logic
+- Shared provider/API operations
+- Reusable UI components
+
+❌ **DON'T use concerns for:**
+- Flow-specific business logic
+- One-off operations
+- Complex state management
+
+### Naming Convention
+
+Concerns should be:
+- Named as adjectives or capabilities (e.g., `Headings`, `ProviderHelpers`)
+- Focused on a single responsibility
+- Well-documented with examples
+
+### Testing
+
+Each concern should have corresponding specs in `spec/language_operator/ux/concerns/`.
+
+## Creating New Concerns
+
+1. Create file in `lib/language_operator/ux/concerns/my_concern.rb`
+2. Define module under `LanguageOperator::Ux::Concerns`
+3. Add YARD documentation with examples
+4. Include in flows via `include Concerns::MyConcern`
+5. Add tests in `spec/language_operator/ux/concerns/my_concern_spec.rb`
+6. Update this README
+
+## Example: Creating a New Concern
+
+```ruby
+# lib/language_operator/ux/concerns/kubernetes_helpers.rb
+module LanguageOperator
+  module Ux
+    module Concerns
+      # Mixin for Kubernetes resource operations
+      module KubernetesHelpers
+        def resource_exists?(type, name)
+          ctx.client.get_resource(type, name, ctx.namespace)
+          true
+        rescue K8s::Error::NotFound
+          false
+        end
+      end
+    end
+  end
+end
+```
+
+Then use it:
+
+```ruby
+class CreateAgent < Base
+  include Concerns::KubernetesHelpers
+
+  def execute
+    if resource_exists?('LanguageAgent', 'my-agent')
+      puts "Agent already exists!"
+    end
+  end
+end
+```

data/lib/language_operator/ux/concerns/headings.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Ux
+    module Concerns
+      # Mixin for consistent heading and banner formatting in UX flows
+      #
+      # Provides helpers for creating section headers, step indicators,
+      # welcome banners, and separator lines.
+      #
+      # @example
+      #   class MyFlow < Base
+      #     include Concerns::Headings
+      #
+      #     def execute
+      #       heading('Welcome to My Flow', emoji: '🎉')
+      #       step_heading(1, 5, 'First Step')
+      #       # ... flow logic
+      #     end
+      #   end
+      module Headings
+        def title(text)
+          puts
+          puts pastel.bold.green("LANGUAGE OPERATOR v#{LanguageOperator::VERSION}")
+          puts pastel.dim("↪ #{text}")
+        end
+
+        # Display a prominent heading with optional emoji
+        #
+        # @param text [String] The heading text
+        # @param emoji [String, nil] Optional emoji to display
+        # @param width [Integer] Width of the banner (default: 50)
+        def heading(text, emoji: nil, width: 50)
+          border = "╭#{'─' * (width - 2)}╮"
+          bottom = "╰#{'─' * (width - 2)}╯"
+
+          display_text = emoji ? "#{text} #{emoji}" : text
+          padding = width - display_text.length - 4
+
+          puts
+          puts pastel.cyan(border)
+          puts "#{pastel.cyan('│')}  #{display_text}#{' ' * padding}#{pastel.cyan('│')}"
+          puts pastel.cyan(bottom)
+          puts
+        end
+
+        # Display a step heading with step number
+        #
+        # @param current [Integer] Current step number
+        # @param total [Integer] Total number of steps
+        # @param title [String] Step title
+        # @param width [Integer] Width of the separator line (default: 50)
+        def step_heading(current, total, title, width: 50)
+          puts
+          puts '─' * width
+          puts pastel.cyan("Step #{current}/#{total}: #{title}")
+          puts '─' * width
+          puts
+        end
+
+        # Display a simple subheading
+        #
+        # @param text [String] The subheading text
+        def subheading(text)
+          puts
+          puts pastel.bold(text)
+        end
+
+        # Display a separator line
+        #
+        # @param width [Integer] Width of the line (default: 50)
+        # @param char [String] Character to use for the line (default: '─')
+        def separator(width: 50, char: '─')
+          puts char * width
+        end
+
+        # Display a section header with description
+        #
+        # @param title [String] Section title
+        # @param description [String, nil] Optional description
+        def section(title, description: nil)
+          puts
+          puts pastel.cyan.bold(title)
+          puts pastel.dim(description) if description
+          puts
+        end
+      end
+    end
+  end
+end