ukiryu 0.1.0 → 0.1.1

data/lib/ukiryu/models/arguments.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'argument'
+
+module Ukiryu
+  module Models
+    # Structured command arguments
+    #
+    # Contains the structured arguments passed to a command execution.
+    # Each argument has a name, value, and type.
+    class Arguments < Lutaml::Model::Serializable
+      attribute :options, Argument, collection: true, initialize_empty: true
+      attribute :flags, :string, collection: true, default: []
+      attribute :positional, Argument, collection: true, initialize_empty: true
+
+      yaml do
+        map_element 'options', to: :options
+        map_element 'flags', to: :flags
+        map_element 'positional', to: :positional
+      end
+
+      json do
+        map 'options', to: :options
+        map 'flags', to: :flags
+        map 'positional', to: :positional
+      end
+
+      # Create Arguments from a hash of parameters
+      #
+      # @param params [Hash] the parameters hash
+      # @param command_definition [CommandDefinition] the command definition for context
+      # @return [Arguments] the arguments model
+      def self.from_params(params, command_definition = nil)
+        options_arr = []
+        flags_arr = []
+        positional_arr = []
+
+        params.each do |key, value|
+          # Determine argument type based on command definition or heuristics
+          arg_type = determine_argument_type(key, value, command_definition)
+
+          case arg_type
+          when :flag
+            # Boolean flags
+            flags_arr << key.to_s if value
+          when :option
+            # Named options with values
+            options_arr << Argument.new(name: key.to_s, value: stringify_value(value), type: 'option')
+          when :positional
+            # Positional arguments
+            positional_arr << Argument.new(name: key.to_s, value: stringify_value(value), type: 'positional')
+          end
+        end
+
+        # Set arrays directly to ensure proper serialization
+        args = new
+        args.options = options_arr unless options_arr.empty?
+        args.flags = flags_arr unless flags_arr.empty?
+        args.positional = positional_arr unless positional_arr.empty?
+
+        args
+      end
+
+      # Determine the type of an argument
+      #
+      # @param key [Symbol] the argument key
+      # @param value [Object] the argument value
+      # @param command_definition [CommandDefinition] the command definition
+      # @return [Symbol] :option, :flag, or :positional
+      def self.determine_argument_type(key, value, command_definition)
+        # Check command definition if available
+        if command_definition
+          flag_def = command_definition.flags&.find { |f| f.name.to_sym == key }
+          return :flag if flag_def
+
+          option_def = command_definition.options&.find { |o| o.name.to_sym == key }
+          return :option if option_def
+
+          arg_def = command_definition.arguments&.find { |a| a.name.to_sym == key }
+          return :positional if arg_def
+        end
+
+        # Fall back to heuristics
+        if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          :flag
+        elsif value.is_a?(Array)
+          # Arrays are typically options (like inputs)
+          :option
+        else
+          :option
+        end
+      end
+
+      # Convert a value to string for serialization
+      #
+      # @param value [Object] the value
+      # @return [String] string representation
+      def self.stringify_value(value)
+        case value
+        when Array
+          value.map(&:to_s).join(', ')
+        when Symbol, Integer, Float, TrueClass, FalseClass
+          value.to_s
+        when NilClass
+          ''
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/ukiryu/models/command_definition.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'option_definition'
+require_relative 'flag_definition'
+require_relative 'argument_definition'
+require_relative 'env_var_definition'
+require_relative 'exit_codes'
+
+module Ukiryu
+  module Models
+    # Command definition for a tool
+    #
+    # @example
+    #   cmd = CommandDefinition.new(
+    #     name: 'convert',
+    #     description: 'Convert image format',
+    #     options: [OptionDefinition.new(...)],
+    #     flags: [FlagDefinition.new(...)]
+    #   )
+    class CommandDefinition < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :description, :string
+      attribute :usage, :string
+      attribute :subcommand, :string
+      attribute :execution_mode, :string
+      attribute :belongs_to, :string  # Parent command this action belongs to
+      attribute :cli_flag, :string    # CLI flag for this action (e.g., '-d' for delete)
+      attribute :aliases, :string, collection: true, default: []
+
+      # Collections of model objects (lutaml-model handles serialization automatically)
+      attribute :options, OptionDefinition, collection: true
+      attribute :flags, FlagDefinition, collection: true
+      attribute :arguments, ArgumentDefinition, collection: true
+      attribute :post_options, OptionDefinition, collection: true
+      attribute :env_vars, EnvVarDefinition, collection: true
+      attribute :exit_codes, ExitCodes  # Exit code definitions for this command
+
+      yaml do
+        map_element 'name', to: :name
+        map_element 'description', to: :description
+        map_element 'usage', to: :usage
+        map_element 'subcommand', to: :subcommand
+        map_element 'options', to: :options
+        map_element 'flags', to: :flags
+        map_element 'arguments', to: :arguments
+        map_element 'post_options', to: :post_options
+        map_element 'env_vars', to: :env_vars
+        map_element 'exit_codes', to: :exit_codes
+        map_element 'execution_mode', to: :execution_mode
+        map_element 'belongs_to', to: :belongs_to
+        map_element 'cli_flag', to: :cli_flag
+        map_element 'aliases', to: :aliases
+      end
+
+      # Check if this command/action belongs to a parent command
+      #
+      # @return [Boolean] true if belongs_to is set
+      def belongs_to_command?
+        !belongs_to.nil? && !belongs_to.empty?
+      end
+
+      # Check if this action is expressed as a flag
+      #
+      # @return [Boolean] true if cli_flag is set
+      def flag_action?
+        !cli_flag.nil? && !cli_flag.empty?
+      end
+
+      # Get an option by name using indexed O(1) lookup
+      #
+      # @param name [String, Symbol] the option name
+      # @return [OptionDefinition, nil] the option
+      def option(name)
+        return nil unless options
+
+        build_options_index unless @options_index_built
+        @options_index[name.to_s]
+      end
+
+      # Get a flag by name using indexed O(1) lookup
+      #
+      # @param name [String, Symbol] the flag name
+      # @return [FlagDefinition, nil] the flag
+      def flag(name)
+        return nil unless flags
+
+        build_flags_index unless @flags_index_built
+        @flags_index[name.to_s]
+      end
+
+      # Get an argument by name using indexed O(1) lookup
+      #
+      # @param name [String, Symbol] the argument name
+      # @return [ArgumentDefinition, nil] the argument
+      def argument(name)
+        return nil unless arguments
+
+        build_arguments_index unless @arguments_index_built
+        @arguments_index[name.to_s]
+      end
+
+      # Get the last argument
+      #
+      # @return [ArgumentDefinition, nil] the last argument
+      def last_argument
+        return nil unless arguments
+
+        arguments.find { |a| a.is_a?(ArgumentDefinition) && a.last? }
+      end
+
+      # Get regular arguments (not last)
+      #
+      # @return [Array<ArgumentDefinition>] regular arguments sorted by position
+      def regular_arguments
+        return [] unless arguments
+
+        args = arguments.select { |a| a.is_a?(ArgumentDefinition) }
+        args.reject(&:last?).sort_by(&:numeric_position)
+      end
+
+      # Check if command has a subcommand
+      #
+      # @return [Boolean] true if has subcommand
+      def has_subcommand?
+        !subcommand.nil? && !subcommand.empty?
+      end
+
+      # Clear all indexes
+      #
+      # Call this if collections are modified after initial loading
+      #
+      # @api private
+      def clear_indexes!
+        @options_index = nil
+        @options_index_built = false
+        @flags_index = nil
+        @flags_index_built = false
+        @arguments_index = nil
+        @arguments_index_built = false
+      end
+
+      private
+
+      # Build the options index hash for O(1) lookup
+      #
+      # @api private
+      def build_options_index
+        return unless options
+
+        @options_index = options.to_h { |o| [o.name, o] }
+        @options_index_built = true
+      end
+
+      # Build the flags index hash for O(1) lookup
+      #
+      # @api private
+      def build_flags_index
+        return unless flags
+
+        @flags_index = flags.to_h { |f| [f.name, f] }
+        @flags_index_built = true
+      end
+
+      # Build the arguments index hash for O(1) lookup
+      #
+      # @api private
+      def build_arguments_index
+        return unless arguments
+
+        @arguments_index = arguments.to_h { |a| [a.name, a] }
+        @arguments_index_built = true
+      end
+    end
+  end
+end

data/lib/ukiryu/models/command_info.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'arguments'
+
+module Ukiryu
+  module Models
+    # Command execution information
+    #
+    # Contains details about the executed command including
+    # the executable path, structured arguments, full command string, and shell used.
+    class CommandInfo < Lutaml::Model::Serializable
+      attribute :executable, :string
+      attribute :executable_name, :string
+      attribute :tool_name, :string  # Name of the tool being executed
+      attribute :arguments, Arguments
+      attribute :full_command, :string
+      attribute :shell, :string
+
+      yaml do
+        map_element 'executable', to: :executable
+        map_element 'executable_name', to: :executable_name
+        map_element 'tool_name', to: :tool_name
+        map_element 'arguments', to: :arguments
+        map_element 'full_command', to: :full_command
+        map_element 'shell', to: :shell
+      end
+
+      json do
+        map 'executable', to: :executable
+        map 'arguments', to: :arguments
+        map 'full_command', to: :full_command
+        map 'shell', to: :shell
+      end
+    end
+  end
+end

data/lib/ukiryu/models/components.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'option_definition'
+require_relative 'flag_definition'
+require_relative 'argument_definition'
+require_relative 'exit_codes'
+
+module Ukiryu
+  module Models
+    # Components registry for reusable definitions
+    #
+    # Enables sharing common option/argument/flag/exit_codes definitions
+    # across commands through `$ref` references.
+    #
+    # @example
+    #   components = Components.new(
+    #     options: { 'verbose' => OptionDefinition.new(...) },
+    #     flags: { 'help' => FlagDefinition.new(...) }
+    #   )
+    class Components < Lutaml::Model::Serializable
+      attribute :options, :hash, default: {}
+      attribute :flags, :hash, default: {}
+      attribute :arguments, :hash, default: {}
+      attribute :exit_codes, ExitCodes
+
+      yaml do
+        map_element 'options', to: :options
+        map_element 'flags', to: :flags
+        map_element 'arguments', to: :arguments
+        map_element 'exit_codes', to: :exit_codes
+      end
+
+      # Get an option by name
+      #
+      # @param name [String, Symbol] the option name
+      # @return [OptionDefinition, nil] the option definition
+      def option(name)
+        @options&.dig(name.to_s)
+      end
+
+      # Get a flag by name
+      #
+      # @param name [String, Symbol] the flag name
+      # @return [FlagDefinition, nil] the flag definition
+      def flag(name)
+        @flags&.dig(name.to_s)
+      end
+
+      # Get an argument by name
+      #
+      # @param name [String, Symbol] the argument name
+      # @return [ArgumentDefinition, nil] the argument definition
+      def argument(name)
+        @arguments&.dig(name.to_s)
+      end
+
+      # Check if a reference can be resolved
+      #
+      # @param ref [String] the reference path (e.g., '#/components/options/verbose')
+      # @return [Boolean] true if the reference can be resolved
+      def can_resolve?(ref)
+        return false unless ref =~ %r{^#/components/(options|flags|arguments|exit_codes)/(.+)$}
+
+        type = Regexp.last_match(1)
+        name = Regexp.last_match(2)
+
+        case type
+        when 'options'
+          @options&.key?(name)
+        when 'flags'
+          @flags&.key?(name)
+        when 'arguments'
+          @arguments&.key?(name)
+        when 'exit_codes'
+          !@exit_codes.nil?
+        else
+          false
+        end
+      end
+
+      # Resolve a reference path to a component
+      #
+      # @param ref [String] the reference path (e.g., '#/components/options/verbose')
+      # @return [Object, nil] the component or nil if not found
+      def resolve(ref)
+        return nil unless ref =~ %r{^#/components/(options|flags|arguments|exit_codes)/(.+)$}
+
+        type = Regexp.last_match(1)
+        name = Regexp.last_match(2)
+
+        case type
+        when 'options'
+          option(name)
+        when 'flags'
+          flag(name)
+        when 'arguments'
+          argument(name)
+        when 'exit_codes'
+          @exit_codes
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ukiryu/models/env_var_definition.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  module Models
+    # Environment variable definition for a command
+    #
+    # @example
+    #   env_var = EnvVarDefinition.new(
+    #     name: 'DISPLAY',
+    #     env_var: 'DISPLAY',
+    #     value: '',
+    #     platforms: [:linux, :macos]
+    #   )
+    class EnvVarDefinition < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :env_var, :string
+      attribute :value, :string
+      attribute :platforms, :string, collection: true, default: []
+
+      yaml do
+        map_element 'name', to: :name
+        map_element 'env_var', to: :env_var
+        map_element 'value', to: :value
+        map_element 'platforms', to: :platforms
+      end
+    end
+  end
+end

data/lib/ukiryu/models/error_response.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  module Models
+    # Error CLI execution response
+    #
+    # Contains error information when a command execution fails.
+    class ErrorResponse < Lutaml::Model::Serializable
+      attribute :status, :string, default: 'error'
+      attribute :exit_code, :integer, default: 1
+      attribute :error, :string
+
+      yaml do
+        map_element 'status', to: :status
+        map_element 'exit_code', to: :exit_code
+        map_element 'error', to: :error
+      end
+
+      json do
+        map 'status', to: :status
+        map 'exit_code', to: :exit_code
+        map 'error', to: :error
+      end
+
+      # Create an ErrorResponse from an error message
+      #
+      # @param message [String] the error message
+      # @param exit_code [Integer] the exit code (default: 1)
+      # @return [ErrorResponse] the response model
+      def self.from_message(message, exit_code: 1)
+        new(
+          status: 'error',
+          exit_code: exit_code,
+          error: message
+        )
+      end
+    end
+  end
+end

data/lib/ukiryu/models/execution_metadata.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  module Models
+    # Execution metadata
+    #
+    # Contains timing and duration information about command execution.
+    class ExecutionMetadata < Lutaml::Model::Serializable
+      attribute :started_at, :string
+      attribute :finished_at, :string
+      attribute :duration_seconds, :float
+      attribute :formatted_duration, :string
+
+      yaml do
+        map_element 'started_at', to: :started_at
+        map_element 'finished_at', to: :finished_at
+        map_element 'duration_seconds', to: :duration_seconds
+        map_element 'formatted_duration', to: :formatted_duration
+      end
+
+      json do
+        map 'started_at', to: :started_at
+        map 'finished_at', to: :finished_at
+        map 'duration_seconds', to: :duration_seconds
+        map 'formatted_duration', to: :formatted_duration
+      end
+    end
+  end
+end