language-operator 0.1.30 → 0.1.35

data/lib/language_operator/cli/commands/use.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'thor'
+require_relative '../base_command'
 require 'pastel'
 require_relative '../formatters/progress_formatter'
 require_relative '../../config/cluster_config'
@@ -9,37 +9,34 @@ module LanguageOperator
   module CLI
     module Commands
       # Switch cluster context command
-      class Use < Thor
+      class Use < BaseCommand
         desc 'use CLUSTER', 'Switch to a different cluster context'
         def self.exit_on_failure?
           true
         end
 
         def switch(cluster_name)
-          unless Config::ClusterConfig.cluster_exists?(cluster_name)
-            Formatters::ProgressFormatter.error("Cluster '#{cluster_name}' not found")
-            puts "\nAvailable clusters:"
-            Config::ClusterConfig.list_clusters.each do |cluster|
-              puts "  - #{cluster[:name]}"
+          handle_command_error('switch cluster') do
+            unless Config::ClusterConfig.cluster_exists?(cluster_name)
+              Formatters::ProgressFormatter.error("Cluster '#{cluster_name}' not found")
+              puts "\nAvailable clusters:"
+              Config::ClusterConfig.list_clusters.each do |cluster|
+                puts "  - #{cluster[:name]}"
+              end
+              exit 1
             end
-            exit 1
-          end
-
-          Config::ClusterConfig.set_current_cluster(cluster_name)
-          cluster = Config::ClusterConfig.get_cluster(cluster_name)
 
-          Formatters::ProgressFormatter.success("Switched to cluster '#{cluster_name}'")
+            Config::ClusterConfig.set_current_cluster(cluster_name)
+            cluster = Config::ClusterConfig.get_cluster(cluster_name)
 
-          pastel = Pastel.new
-          puts "\nCluster Details"
-          puts '----------------'
-          puts "Name: #{pastel.bold.white(cluster[:name])}"
-          puts "Namespace: #{pastel.bold.white(cluster[:namespace])}"
-        rescue StandardError => e
-          Formatters::ProgressFormatter.error("Failed to switch cluster: #{e.message}")
-          raise if ENV['DEBUG']
+            Formatters::ProgressFormatter.success("Switched to cluster '#{cluster_name}'")
 
-          exit 1
+            pastel = Pastel.new
+            puts "\nCluster Details"
+            puts '----------------'
+            puts "Name: #{pastel.bold.white(cluster[:name])}"
+            puts "Namespace: #{pastel.bold.white(cluster[:namespace])}"
+          end
         end
       end
     end

data/lib/language_operator/cli/formatters/code_formatter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'rouge'
-require 'pastel'
+require_relative '../helpers/pastel_helper'
 
 module LanguageOperator
   module CLI
@@ -9,6 +9,8 @@ module LanguageOperator
       # Formatter for displaying syntax-highlighted code in the terminal
       class CodeFormatter
         class << self
+          include Helpers::PastelHelper
+
           # Display Ruby code with syntax highlighting
           #
           # @param code_content [String] The Ruby code to display
@@ -68,12 +70,6 @@ module LanguageOperator
             puts highlighted
             puts
           end
-
-          private
-
-          def pastel
-            @pastel ||= Pastel.new
-          end
         end
       end
     end

data/lib/language_operator/cli/formatters/log_formatter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'pastel'
+require_relative '../helpers/pastel_helper'
 require 'json'
 require 'time'
 
@@ -10,6 +10,8 @@ module LanguageOperator
       # Formatter for displaying agent execution logs with color and icons
       class LogFormatter
         class << self
+          include Helpers::PastelHelper
+
           # Format a single log line from kubectl output
           #
           # @param line [String] Raw log line from kubectl (with [pod/container] prefix)
@@ -33,10 +35,6 @@ module LanguageOperator
 
           private
 
-          def pastel
-            @pastel ||= Pastel.new
-          end
-
           # Parse the kubectl prefix from the log line
           # Returns [prefix, content] or [nil, original_line]
           def parse_kubectl_prefix(line)

data/lib/language_operator/cli/formatters/progress_formatter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'tty-spinner'
-require 'pastel'
+require_relative '../helpers/pastel_helper'
 
 module LanguageOperator
   module CLI
@@ -9,6 +9,8 @@ module LanguageOperator
       # Beautiful progress output for CLI operations
       class ProgressFormatter
         class << self
+          include Helpers::PastelHelper
+
           def with_spinner(message, success_msg: nil, &block)
             spinner = TTY::Spinner.new("[:spinner] #{message}...", format: :dots, success_mark: pastel.green('✔'))
             spinner.auto_spin
@@ -40,12 +42,6 @@ module LanguageOperator
           def warn(message)
             puts "[#{pastel.yellow('⚠')}] #{message}"
           end
-
-          private
-
-          def pastel
-            @pastel ||= Pastel.new
-          end
         end
       end
     end

data/lib/language_operator/cli/formatters/status_formatter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/pastel_helper'
+
+module LanguageOperator
+  module CLI
+    module Formatters
+      # Unified formatter for status indicators across all commands
+      #
+      # Provides consistent colored status dots (●) for resource states
+      class StatusFormatter
+        extend Helpers::PastelHelper
+
+        # Format a status string with colored indicator
+        #
+        # @param status [String, Symbol] The status to format
+        # @return [String] Formatted status with colored dot
+        def self.format(status)
+          status_str = status.to_s
+
+          case status_str.downcase
+          when 'ready', 'running', 'active'
+            "#{pastel.green('●')} #{status_str}"
+          when 'pending', 'creating', 'synthesizing'
+            "#{pastel.yellow('●')} #{status_str}"
+          when 'failed', 'error'
+            "#{pastel.red('●')} #{status_str}"
+          when 'paused', 'stopped', 'suspended'
+            "#{pastel.dim('●')} #{status_str}"
+          else
+            "#{pastel.dim('●')} #{status_str}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/cli/formatters/table_formatter.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require 'tty-table'
-require 'pastel'
+require_relative '../helpers/pastel_helper'
+require_relative 'status_formatter'
 
 module LanguageOperator
   module CLI
@@ -9,6 +10,8 @@ module LanguageOperator
       # Table output for CLI list commands
       class TableFormatter
         class << self
+          include Helpers::PastelHelper
+
           def clusters(clusters)
             return ProgressFormatter.info('No clusters found') if clusters.empty?
 
@@ -20,7 +23,7 @@ module LanguageOperator
                 cluster[:agents] || 0,
                 cluster[:tools] || 0,
                 cluster[:models] || 0,
-                status_indicator(cluster[:status])
+                StatusFormatter.format(cluster[:status] || 'Unknown')
               ]
             end
 
@@ -36,7 +39,7 @@ module LanguageOperator
               [
                 agent[:name],
                 agent[:mode],
-                status_indicator(agent[:status]),
+                StatusFormatter.format(agent[:status]),
                 agent[:next_run] || 'N/A',
                 agent[:executions] || 0
               ]
@@ -58,7 +61,7 @@ module LanguageOperator
                   cluster_name,
                   agent[:name],
                   agent[:mode],
-                  status_indicator(agent[:status]),
+                  StatusFormatter.format(agent[:status]),
                   agent[:next_run] || 'N/A',
                   agent[:executions] || 0
                 ]
@@ -77,7 +80,7 @@ module LanguageOperator
               [
                 tool[:name],
                 tool[:type],
-                status_indicator(tool[:status]),
+                StatusFormatter.format(tool[:status]),
                 tool[:agents_using] || 0
               ]
             end
@@ -112,7 +115,7 @@ module LanguageOperator
                 model[:name],
                 model[:provider],
                 model[:model],
-                status_indicator(model[:status])
+                StatusFormatter.format(model[:status])
               ]
             end
 
@@ -133,7 +136,7 @@ module LanguageOperator
                 cluster[:agents] || 0,
                 cluster[:tools] || 0,
                 cluster[:models] || 0,
-                status_indicator(cluster[:status])
+                StatusFormatter.format(cluster[:status] || 'Unknown')
               ]
             end
 
@@ -148,30 +151,11 @@ module LanguageOperator
 
           private
 
-          def status_indicator(status)
-            case status&.downcase
-            when 'ready', 'running', 'active'
-              "#{pastel.green('●')} #{status}"
-            when 'pending', 'creating', 'synthesizing'
-              "#{pastel.yellow('●')} #{status}"
-            when 'failed', 'error'
-              "#{pastel.red('●')} #{status}"
-            when 'paused', 'stopped'
-              "#{pastel.dim('●')} #{status}"
-            else
-              "#{pastel.dim('●')} #{status || 'Unknown'}"
-            end
-          end
-
           def truncate(text, length)
             return text if text.nil? || text.length <= length
 
             "#{text[0...(length - 3)]}..."
           end
-
-          def pastel
-            @pastel ||= Pastel.new
-          end
         end
       end
     end

data/lib/language_operator/cli/helpers/pastel_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'pastel'
+
+module LanguageOperator
+  module CLI
+    module Helpers
+      # Shared module providing Pastel color functionality
+      # to CLI commands, formatters, and helpers.
+      #
+      # Usage:
+      #   include PastelHelper
+      #   puts pastel.green("Success!")
+      module PastelHelper
+        # Returns a memoized Pastel instance for colorizing terminal output
+        #
+        # @return [Pastel] Pastel instance
+        def pastel
+          @pastel ||= Pastel.new
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/cli/helpers/resource_dependency_checker.rb

@@ -50,24 +50,6 @@ module LanguageOperator
         def self.tool_usage_count(agents, tool_name)
           agents_using_tool(agents, tool_name).size
         end
-
-        # Count how many agents use a specific model
-        #
-        # @param agents [Array<Hash>] Array of agent resources
-        # @param model_name [String] Name of the model
-        # @return [Integer] Count of agents using this model
-        def self.model_usage_count(agents, model_name)
-          agents_using_model(agents, model_name).size
-        end
-
-        # Count how many agents use a specific persona
-        #
-        # @param agents [Array<Hash>] Array of agent resources
-        # @param persona_name [String] Name of the persona
-        # @return [Integer] Count of agents using this persona
-        def self.persona_usage_count(agents, persona_name)
-          agents_using_persona(agents, persona_name).size
-        end
       end
     end
   end

data/lib/language_operator/cli/main.rb

@@ -11,6 +11,7 @@ require_relative 'commands/tool'
 require_relative 'commands/model'
 require_relative 'commands/quickstart'
 require_relative 'commands/install'
+require_relative 'commands/system'
 require_relative 'formatters/progress_formatter'
 require_relative '../config/cluster_config'
 require_relative '../kubernetes/client'
@@ -88,6 +89,9 @@ module LanguageOperator
       desc 'model SUBCOMMAND ...ARGS', 'Manage language models'
       subcommand 'model', Commands::Model
 
+      desc 'system SUBCOMMAND ...ARGS', 'System commands for schema and metadata'
+      subcommand 'system', Commands::System
+
       desc 'quickstart', 'Interactive setup wizard for first-time users'
       def quickstart
         Commands::Quickstart.new.invoke(:start)

data/lib/language_operator/cli/wizards/quickstart_wizard.rb

@@ -413,7 +413,6 @@ module LanguageOperator
         end
 
         def create_model_resource(cluster_info, name, provider, model, api_key = nil, endpoint = nil)
-          # rubocop:disable Metrics/BlockLength
           Formatters::ProgressFormatter.with_spinner("Creating model '#{name}'") do
             k8s = Kubernetes::Client.new(
               kubeconfig: cluster_info[:kubeconfig],

data/lib/language_operator/client/config.rb

@@ -34,12 +34,13 @@ module LanguageOperator
         {
           'llm' => {
             'provider' => detect_provider_from_env,
-            'model' => ENV.fetch('LLM_MODEL') { default_model_from_env },
+            'model' => LanguageOperator::Config.get('LLM_MODEL', default: default_model_from_env),
             'endpoint' => parse_model_endpoint_from_env,
-            'api_key' => ENV.fetch('OPENAI_API_KEY') { ENV.fetch('ANTHROPIC_API_KEY', 'dummy-key-for-local-proxy') }
+            'api_key' => LanguageOperator::Config.get('OPENAI_API_KEY', 'ANTHROPIC_API_KEY',
+                                                      default: 'dummy-key-for-local-proxy')
           },
           'mcp_servers' => parse_mcp_servers_from_env,
-          'debug' => ENV['DEBUG'] == 'true'
+          'debug' => LanguageOperator::Config.get_bool('DEBUG', default: false)
         }
       end
 
@@ -49,15 +50,12 @@ module LanguageOperator
       #
       # @return [String, nil] Model endpoint URL
       def self.parse_model_endpoint_from_env
-        # Support MODEL_ENDPOINTS (operator sets this)
-        endpoints_env = ENV.fetch('MODEL_ENDPOINTS', nil)
-        if endpoints_env && !endpoints_env.empty?
-          # Take the first endpoint from comma-separated list
-          endpoints_env.split(',').first.strip
-        else
-          # Fallback to legacy OPENAI_ENDPOINT
-          ENV.fetch('OPENAI_ENDPOINT', nil)
-        end
+        # Support MODEL_ENDPOINTS (operator sets this) - take first from comma-separated list
+        endpoints = LanguageOperator::Config.get_array('MODEL_ENDPOINTS')
+        return endpoints.first unless endpoints.empty?
+
+        # Fallback to legacy OPENAI_ENDPOINT
+        LanguageOperator::Config.get('OPENAI_ENDPOINT')
       end
 
       # Load configuration with automatic fallback to environment variables
@@ -79,11 +77,11 @@ module LanguageOperator
       # @return [String] Provider name (openai_compatible, openai, or anthropic)
       # @raise [RuntimeError] If no API key or endpoint is found
       def self.detect_provider_from_env
-        if ENV['OPENAI_ENDPOINT'] || ENV['MODEL_ENDPOINTS']
+        if LanguageOperator::Config.set?('OPENAI_ENDPOINT', 'MODEL_ENDPOINTS')
           'openai_compatible'
-        elsif ENV['OPENAI_API_KEY']
+        elsif LanguageOperator::Config.set?('OPENAI_API_KEY')
           'openai'
-        elsif ENV['ANTHROPIC_API_KEY']
+        elsif LanguageOperator::Config.set?('ANTHROPIC_API_KEY')
           'anthropic'
         else
           raise 'No API key or endpoint found. Set OPENAI_ENDPOINT or MODEL_ENDPOINTS for local LLM, ' \
@@ -109,21 +107,22 @@ module LanguageOperator
       # @return [Array<Hash>] Array of MCP server configurations
       def self.parse_mcp_servers_from_env
         # Support both MCP_SERVERS (comma-separated) and legacy MCP_URL
-        servers_env = ENV.fetch('MCP_SERVERS', nil)
-        if servers_env && !servers_env.empty?
+        servers = LanguageOperator::Config.get_array('MCP_SERVERS')
+
+        if !servers.empty?
           # Parse comma-separated URLs
-          servers_env.split(',').map.with_index do |url, index|
+          servers.map.with_index do |url, index|
             {
               'name' => "default-tools-#{index}",
-              'url' => url.strip,
+              'url' => url,
               'transport' => 'streamable',
               'enabled' => true
             }
           end
-        elsif ENV['MCP_URL']
+        elsif (url = LanguageOperator::Config.get('MCP_URL'))
           [{
             'name' => 'default-tools',
-            'url' => ENV['MCP_URL'],
+            'url' => url,
             'transport' => 'streamable',
             'enabled' => true
           }]

data/lib/language_operator/config.rb

@@ -8,8 +8,9 @@ module LanguageOperator
   # - Key-to-env-var mappings
   # - Prefixes (e.g., SMTP_HOST from prefix: 'SMTP')
   # - Default values
-  # - Type conversion (string, integer, boolean, float)
+  # - Type conversion (string, integer, boolean, float, array)
   # - Required config validation
+  # - Multiple fallback keys
   #
   # @example Load SMTP configuration
   #   config = LanguageOperator::Config.load(
@@ -75,7 +76,8 @@ module LanguageOperator
     # Convert a string value to the specified type
     #
     # @param value [String, nil] Raw string value from environment
-    # @param type [Symbol] Target type (:string, :integer, :boolean, :float)
+    # @param type [Symbol] Target type (:string, :integer, :boolean, :float, :array)
+    # @param separator [String] Separator for array type (default: ',')
     # @return [Object] Converted value
     #
     # @example String conversion
@@ -92,7 +94,10 @@ module LanguageOperator
     #
     # @example Float conversion
     #   Config.convert_type('3.14', :float) # => 3.14
-    def self.convert_type(value, type)
+    #
+    # @example Array conversion
+    #   Config.convert_type('a,b,c', :array) # => ["a", "b", "c"]
+    def self.convert_type(value, type, separator: ',')
       return nil if value.nil?
 
       case type
@@ -104,6 +109,10 @@ module LanguageOperator
         value.to_f
       when :boolean
         %w[true 1 yes on].include?(value.to_s.downcase)
+      when :array
+        return [] if value.to_s.empty?
+
+        value.to_s.split(separator).map(&:strip).reject(&:empty?)
       else
         value
       end
@@ -134,5 +143,108 @@ module LanguageOperator
       validate_required!(config, required) unless required.empty?
       config
     end
+
+    # Get environment variable with multiple fallback keys
+    #
+    # @param keys [Array<String>] Environment variable names to try
+    # @param default [Object, nil] Default value if none found
+    # @return [String, nil] The first non-nil value or default
+    #
+    # @example
+    #   Config.get('SMTP_HOST', 'MAIL_HOST', default: 'localhost')
+    def self.get(*keys, default: nil)
+      keys.each do |key|
+        value = ENV.fetch(key.to_s, nil)
+        return value if value
+      end
+      default
+    end
+
+    # Get required environment variable with fallback keys
+    #
+    # @param keys [Array<String>] Environment variable names to try
+    # @return [String] The first non-nil value
+    # @raise [ArgumentError] If none of the keys are set
+    #
+    # @example
+    #   Config.require('DATABASE_URL', 'DB_URL')
+    def self.require(*keys)
+      value = get(*keys)
+      raise ArgumentError, "Missing required configuration: #{keys.join(' or ')}" unless value
+
+      value
+    end
+
+    # Get environment variable as integer
+    #
+    # @param keys [Array<String>] Environment variable names to try
+    # @param default [Integer, nil] Default value if none found
+    # @return [Integer, nil] The value converted to integer, or default
+    #
+    # @example
+    #   Config.get_int('MAX_WORKERS', default: 4)
+    def self.get_int(*keys, default: nil)
+      value = get(*keys)
+      return default if value.nil?
+
+      value.to_i
+    end
+
+    # Get environment variable as boolean
+    #
+    # Treats 'true', '1', 'yes', 'on' as true (case insensitive).
+    #
+    # @param keys [Array<String>] Environment variable names to try
+    # @param default [Boolean] Default value if none found
+    # @return [Boolean] The value as boolean
+    #
+    # @example
+    #   Config.get_bool('USE_TLS', 'ENABLE_TLS', default: true)
+    def self.get_bool(*keys, default: false)
+      value = get(*keys)
+      return default if value.nil?
+
+      %w[true 1 yes on].include?(value.to_s.downcase)
+    end
+
+    # Get environment variable as array (split by separator)
+    #
+    # @param keys [Array<String>] Environment variable names to try
+    # @param default [Array] Default value if none found
+    # @param separator [String] Character to split on (default: ',')
+    # @return [Array<String>] The value split into array
+    #
+    # @example
+    #   Config.get_array('ALLOWED_HOSTS', separator: ',')
+    def self.get_array(*keys, default: [], separator: ',')
+      value = get(*keys)
+      return default if value.nil? || value.empty?
+
+      value.split(separator).map(&:strip).reject(&:empty?)
+    end
+
+    # Check if environment variable is set (even if empty string)
+    #
+    # @param keys [Array<String>] Environment variable names to check
+    # @return [Boolean] True if any key is set
+    #
+    # @example
+    #   Config.set?('DEBUG', 'VERBOSE')
+    def self.set?(*keys)
+      keys.any? { |key| ENV.key?(key.to_s) }
+    end
+
+    # Get all environment variables matching a prefix
+    #
+    # @param prefix [String] Prefix to match
+    # @return [Hash<String, String>] Hash with prefix removed from keys
+    #
+    # @example
+    #   Config.with_prefix('DATABASE_')
+    #   # Returns { 'URL' => '...', 'POOL_SIZE' => '5' } for DATABASE_URL and DATABASE_POOL_SIZE
+    def self.with_prefix(prefix)
+      ENV.select { |key, _| key.start_with?(prefix) }
+         .transform_keys { |key| key.sub(prefix, '') }
+    end
   end
 end

data/lib/language_operator/constants.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  # Shared constants used across the Language Operator gem
+  module Constants
+    # Agent execution modes with their aliases
+    # Primary modes are the canonical forms used in CRD schemas
+    # Aliases are accepted for backwards compatibility and convenience
+    EXECUTION_MODES = {
+      autonomous: %w[autonomous interactive].freeze,
+      scheduled: %w[scheduled event-driven].freeze,
+      reactive: %w[reactive http webhook].freeze
+    }.freeze
+
+    # Primary (canonical) execution modes for schema definitions
+    PRIMARY_MODES = %w[autonomous scheduled reactive].freeze
+
+    # All valid mode strings (primary + aliases)
+    ALL_MODE_ALIASES = EXECUTION_MODES.values.flatten.freeze
+
+    # Normalizes a mode string to its primary canonical form
+    #
+    # @param mode_string [String] The mode string to normalize
+    # @return [String] The canonical primary mode
+    # @raise [ArgumentError] if the mode string is not recognized
+    #
+    # @example
+    #   Constants.normalize_mode('interactive') # => 'autonomous'
+    #   Constants.normalize_mode('webhook')     # => 'reactive'
+    #   Constants.normalize_mode('scheduled')   # => 'scheduled'
+    def self.normalize_mode(mode_string)
+      return nil if mode_string.nil?
+
+      mode_string = mode_string.to_s.downcase.strip
+
+      EXECUTION_MODES.each do |primary, aliases|
+        return primary.to_s if aliases.include?(mode_string)
+      end
+
+      raise ArgumentError, "Unknown execution mode: #{mode_string}. " \
+                           "Valid modes: #{ALL_MODE_ALIASES.join(', ')}"
+    end
+
+    # Validates that a mode string is recognized
+    #
+    # @param mode_string [String] The mode string to validate
+    # @return [Boolean] true if valid, false otherwise
+    def self.valid_mode?(mode_string)
+      return false if mode_string.nil?
+
+      ALL_MODE_ALIASES.include?(mode_string.to_s.downcase.strip)
+    end
+  end
+end