ukiryu 0.1.0 → 0.1.1

data/lib/ukiryu/models/routing.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Models
+    # Represents a command routing table for hierarchical tools.
+    #
+    # Routing maps command names to their executable targets, enabling
+    # tools like git where `git remote` routes to `git-remote` executable.
+    #
+    # @example Basic routing
+    #   routing = Routing.new({ 'remote' => 'git-remote', 'branch' => 'git-branch' })
+    #   routing.resolve('remote') # => 'git-remote'
+    #
+    # @example Multi-level routing
+    #   routing = Routing.new({ 'remote' => 'git-remote' })
+    #   routing.child('remote').merge!({ 'add' => 'action' })
+    #   routing.resolve_path(['remote', 'add']) # => ['git-remote', 'action']
+    #
+    class Routing
+      # The routing table mapping command names to executables
+      #
+      # @return [Hash<String, String>]
+      attr_reader :table
+
+      # Parent routing table for multi-level hierarchies
+      #
+      # @return [Routing, nil]
+      attr_reader :parent
+
+      # Create a new Routing table
+      #
+      # @param table [Hash] routing table mapping command names to executables
+      # @param parent [Routing, nil] parent routing for multi-level hierarchies
+      #
+      # @example
+      #   Routing.new({ 'remote' => 'git-remote' })
+      #   Routing.new({ 'add' => 'action' }, parent_routing)
+      #
+      def initialize(table = {}, parent: nil)
+        @table = symbolize_keys(table)
+        @parent = parent
+        @children = {}
+      end
+
+      # Resolve a command name to its executable target
+      #
+      # @param command_name [String, Symbol] the command name to resolve
+      # @return [String, nil] the executable target or nil if not found
+      #
+      # @example
+      #   routing.resolve('remote') # => 'git-remote'
+      #   routing.resolve('unknown') # => nil
+      #
+      def resolve(command_name)
+        key = command_name.to_sym
+        @table[key] || @parent&.resolve(key)
+      end
+
+      # Resolve a path of command names to their executable targets
+      #
+      # @param path [Array<String, Symbol>] the command path to resolve
+      # @return [Array<String>] array of executable targets
+      #
+      # @example
+      #   routing.resolve_path(['remote', 'add']) # => ['git-remote', 'action']
+      #
+      def resolve_path(path)
+        return [] if path.empty?
+
+        # Resolve first level in this routing table
+        first_target = resolve(path.first)
+        return [] unless first_target
+
+        # If there are more levels, resolve them in child routing
+        if path.size > 1
+          child = child(path.first)
+          [first_target, *child.resolve_path(path[1..])]
+        else
+          [first_target]
+        end
+      end
+
+      # Check if a command exists in the routing table
+      #
+      # @param command_name [String, Symbol] the command name to check
+      # @return [Boolean] true if the command exists
+      #
+      # @example
+      #   routing.include?('remote') # => true
+      #   routing.include?('unknown') # => false
+      #
+      def include?(command_name)
+        key = command_name.to_sym
+        @table.key?(key) || @parent&.include?(key) || false
+      end
+
+      # Get a child routing table for a command
+      #
+      # Creates or returns the child routing for multi-level hierarchies.
+      #
+      # @param command_name [String, Symbol] the parent command name
+      # @return [Routing] the child routing table
+      #
+      # @example
+      #   routing.child('remote').merge!({ 'add' => 'action' })
+      #
+      def child(command_name)
+        key = command_name.to_sym
+        @children[key] ||= Routing.new(parent: self)
+      end
+
+      # Merge a hash into this routing table
+      #
+      # @param other [Hash] the routing entries to merge
+      # @return [self] returns self for chaining
+      #
+      # @example
+      #   routing.merge!({ 'branch' => 'git-branch' })
+      #
+      def merge!(other)
+        @table.merge!(symbolize_keys(other))
+        self
+      end
+
+      # Get all command names in this routing table
+      #
+      # @return [Array<String>] array of command names
+      #
+      # @example
+      #   routing.keys # => ['remote', 'branch', 'stash']
+      #
+      def keys
+        @table.keys.map(&:to_s).sort
+      end
+
+      # Check if the routing table is empty
+      #
+      # @return [Boolean] true if no routing entries
+      #
+      def empty?
+        @table.empty?
+      end
+
+      # Get the number of routing entries
+      #
+      # @return [Integer] number of entries
+      #
+      def size
+        @table.size
+      end
+
+      # Convert routing table to hash
+      #
+      # @return [Hash] the routing table as a hash
+      #
+      def to_h
+        @table.transform_keys(&:to_s)
+      end
+
+      # Check for circular references in routing hierarchy
+      #
+      # @return [Boolean] true if circular reference detected
+      #
+      def circular?
+        return false unless @parent
+
+        current = @parent
+        seen = { self => true }
+
+        while current
+          return true if seen.key?(current)
+
+          seen[current] = true
+          current = current.parent
+        end
+
+        false
+      end
+
+      # String representation
+      #
+      # @return [String] debug-friendly string representation
+      #
+      def inspect
+        parent_info = @parent ? "(parent: #{parent.object_id})" : ''
+        "#<#{self.class.name}:#{object_id}#{parent_info} #{@table.keys.inspect}>"
+      end
+
+      # String representation for debugging
+      #
+      # @return [String] routing table as formatted string
+      #
+      def to_s
+        return "(empty)" if @table.empty?
+
+        @table.map { |k, v| "#{k} => #{v}" }.join(', ')
+      end
+
+      private
+
+      # Symbolize hash keys
+      #
+      # @param hash [Hash] the hash to symbolize
+      # @return [Hash] hash with symbolized keys
+      #
+      def symbolize_keys(hash)
+        hash.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/ukiryu/models/search_paths.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  module Models
+    # Search paths configuration for finding tool executables
+    #
+    # @example
+    #   sp = SearchPaths.new
+    #   sp.macos = ['/opt/homebrew/bin/tool']
+    #   sp.linux = ['/usr/bin/tool']
+    class SearchPaths < Lutaml::Model::Serializable
+      attribute :macos, :string, collection: true, default: []
+      attribute :linux, :string, collection: true, default: []
+      attribute :windows, :string, collection: true, default: []
+      attribute :freebsd, :string, collection: true, default: []
+      attribute :openbsd, :string, collection: true, default: []
+      attribute :netbsd, :string, collection: true, default: []
+
+      yaml do
+        map_element 'macos', to: :macos
+        map_element 'linux', to: :linux
+        map_element 'windows', to: :windows
+        map_element 'freebsd', to: :freebsd
+        map_element 'openbsd', to: :openbsd
+        map_element 'netbsd', to: :netbsd
+      end
+
+      # Get search paths for a specific platform
+      #
+      # @param platform [Symbol] the platform
+      # @return [Array<String>] the search paths
+      def for_platform(platform)
+        send(platform) || []
+      end
+    end
+  end
+end

data/lib/ukiryu/models/success_response.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'arguments'
+require_relative 'command_info'
+require_relative 'output_info'
+require_relative 'execution_metadata'
+require_relative 'execution_report'
+
+module Ukiryu
+  module Models
+    # Successful CLI execution response
+    #
+    # Contains the complete result of a successful command execution
+    # structured into three phases: Request, Command, and Output.
+    # Optionally includes ExecutionReport with metrics when enabled.
+    class SuccessResponse < Lutaml::Model::Serializable
+      attribute :status, :string, default: 'success'
+      attribute :exit_code, :integer
+      attribute :request, Arguments
+      attribute :command, CommandInfo
+      attribute :output, OutputInfo
+      attribute :metadata, ExecutionMetadata
+      attribute :execution_report, ExecutionReport
+
+      yaml do
+        map_element 'status', to: :status
+        map_element 'exit_code', to: :exit_code
+        map_element 'request', to: :request
+        map_element 'command', to: :command
+        map_element 'output', to: :output
+        map_element 'metadata', to: :metadata
+        map_element 'execution_report', to: :execution_report
+      end
+
+      json do
+        map 'status', to: :status
+        map 'exit_code', to: :exit_code
+        map 'request', to: :request
+        map 'command', to: :command
+        map 'output', to: :output
+        map 'metadata', to: :metadata
+        map 'execution_report', to: :execution_report
+      end
+
+      # Create a SuccessResponse from an Executor::Result
+      #
+      # @param result [Executor::Result] the execution result
+      # @param params [Hash] the original parameters passed to the command
+      # @param command_definition [CommandDefinition] the command definition for context
+      # @param execution_report [ExecutionReport, nil] optional execution report with metrics
+      # @return [SuccessResponse] the response model
+      def self.from_result(result, params = {}, command_definition = nil, execution_report: nil)
+        request = Arguments.from_params(params, command_definition)
+
+        response = new(
+          status: 'success',
+          exit_code: result.status,
+          request: request,
+          command: CommandInfo.new(
+            executable: result.executable,
+            arguments: request, # Use the same structured arguments for the command
+            full_command: result.command_info.full_command,
+            shell: result.command_info.shell.to_s
+          ),
+          output: OutputInfo.new(
+            stdout: result.stdout,
+            stderr: result.error_output
+          ),
+          metadata: ExecutionMetadata.new(
+            started_at: result.started_at.iso8601,
+            finished_at: result.finished_at.iso8601,
+            duration_seconds: result.duration,
+            formatted_duration: result.metadata.formatted_duration
+          )
+        )
+
+        # Add execution report if provided
+        response.execution_report = execution_report if execution_report
+
+        response
+      end
+    end
+  end
+end

data/lib/ukiryu/models/tool_definition.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+require_relative 'platform_profile'
+require_relative 'version_detection'
+require_relative 'search_paths'
+require_relative 'components'
+
+module Ukiryu
+  module Models
+    # Tool definition loaded from YAML profile
+    #
+    # @example
+    #   tool = ToolDefinition.from_yaml(yaml_string)
+    #   profile = tool.compatible_profile
+    class ToolDefinition < Lutaml::Model::Serializable
+      attribute :ukiryu_schema, :string
+      attribute :self_uri, :string
+      attribute :name, :string
+      attribute :display_name, :string
+      attribute :homepage, :string
+      attribute :version, :string
+      attribute :implements, :string
+      attribute :aliases, :string, collection: true, default: []
+      attribute :timeout, :integer, default: 90
+      attribute :profiles, PlatformProfile, collection: true
+      attribute :version_detection, VersionDetection
+      attribute :search_paths, SearchPaths
+      attribute :components, Components  # Registry of reusable definitions
+
+      yaml do
+        map_element 'ukiryu_schema', to: :ukiryu_schema
+        map_element '$self', to: :self_uri
+        map_element 'name', to: :name
+        map_element 'display_name', to: :display_name
+        map_element 'homepage', to: :homepage
+        map_element 'version', to: :version
+        map_element 'implements', to: :implements
+        map_element 'aliases', to: :aliases
+        map_element 'timeout', to: :timeout
+        map_element 'profiles', to: :profiles
+        map_element 'version_detection', to: :version_detection
+        map_element 'search_paths', to: :search_paths
+        map_element 'components', to: :components
+      end
+
+      # Get compatible profile for current platform/shell
+      #
+      # @param platform [Symbol] the platform
+      # @param shell [Symbol] the shell
+      # @return [PlatformProfile, nil] the compatible profile
+      def compatible_profile(platform: nil, shell: nil)
+        require_relative '../platform'
+        require_relative '../shell'
+
+        platform ||= Platform.detect
+        shell ||= Shell.detect
+        return nil unless platform && shell
+
+        return nil if profiles.empty?
+
+        profiles.find do |p|
+          p.is_a?(PlatformProfile) && p.compatible?(platform.to_sym, shell.to_sym)
+        end
+      end
+
+      # Check if tool implements an interface
+      #
+      # @param interface_name [String, Symbol] the interface name
+      # @return [Boolean] true if implements
+      def implements?(interface_name)
+        implements == interface_name.to_s
+      end
+
+      # Check if tool is available on a platform
+      #
+      # @param platform [Symbol] the platform
+      # @return [Boolean] true if available
+      def available_on?(platform)
+        return true if profiles.empty?
+
+        profiles.any? { |p| p.is_a?(PlatformProfile) && p.supports_platform?(platform) }
+      end
+
+      # Resolve profile inheritance
+      #
+      # Merges parent profile commands into child profiles that have `inherits` set.
+      # The child profile's commands take precedence over parent commands.
+      #
+      # @return [self] returns self for chaining
+      def resolve_inheritance!
+        return self unless profiles
+
+        profiles.each do |profile|
+          next unless profile.inherits
+
+          # Find parent profile by name
+          parent_profile = profiles.find { |p| p.name == profile.inherits }
+          next unless parent_profile
+
+          # Merge parent commands into child (child takes precedence)
+          parent_commands = parent_profile.commands || []
+          child_commands = profile.commands || []
+
+          # Create a map of child commands by name for quick lookup
+          child_commands_map = child_commands.to_h { |c| [c.name, c] }
+
+          # Add parent commands that don't exist in child
+          merged_commands = child_commands.dup
+          parent_commands.each do |parent_cmd|
+            merged_commands << parent_cmd unless child_commands_map.key?(parent_cmd.name)
+          end
+
+          # Update profile commands and clear index so it rebuilds on next access
+          profile.commands = merged_commands
+          profile.clear_commands_index!
+        end
+
+        self
+      end
+
+      # Get the schema version
+      #
+      # @return [String, nil] the schema version (e.g., "1.0", "1.1", "1.2")
+      def schema_version
+        ukiryu_schema
+      end
+
+      # Get the self URI
+      #
+      # @return [String, nil] the self URI
+      def self_uri
+        @self_uri
+      end
+
+      # Check if a specific schema version is specified
+      #
+      # @param version [String] the version to check
+      # @return [Boolean] true if this is the schema version
+      def schema_version?(version)
+        ukiryu_schema == version
+      end
+    end
+  end
+end

data/lib/ukiryu/models/tool_metadata.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Ukiryu
+  class ToolMetadata
+    # Lightweight metadata model for tools
+    # Contains only the essential information needed for tool discovery
+    # without loading the full profile definition
+
+    attr_reader :name, :version, :display_name, :implements, :homepage,
+                :description, :aliases, :tool_name, :registry_path, :default_command
+
+    def initialize(name:, version:, display_name: nil, implements: nil,
+                   homepage: nil, description: nil, aliases: nil,
+                   tool_name: nil, registry_path: nil, default_command: nil)
+      @name = name
+      @version = version
+      @display_name = display_name
+      @implements = implements
+      @homepage = homepage
+      @description = description
+      @aliases = Array(aliases || [])
+      @tool_name = tool_name || name
+      @registry_path = registry_path
+      @default_command = default_command
+    end
+
+    # Check if this metadata matches an interface
+    #
+    # @param interface_name [Symbol, String] the interface to check
+    # @return [Boolean] true if this tool implements the interface
+    def implements?(interface_name)
+      @implements == interface_name.to_sym
+    end
+
+    # Get the primary command name for this tool
+    # Returns the default_command from YAML if set, otherwise the implements value,
+    # otherwise falls back to the tool name
+    #
+    # @return [Symbol, nil] the default command name
+    def default_command
+      @default_command || @implements || @name.to_sym
+    end
+
+    # String representation
+    #
+    # @return [String] description string
+    def to_s
+      "#{@display_name || @name} v#{@version}"
+    end
+
+    # Inspect
+    #
+    # @return [String] inspection string
+    def inspect
+      "#<#{self.class.name} name=#{@name.inspect} version=#{@version.inspect} implements=#{@implements.inspect}>"
+    end
+
+    # Class method to create from YAML hash
+    # Extracts only metadata fields from a full tool profile
+    #
+    # @param hash [Hash] the YAML profile hash
+    # @param tool_name [String] the tool name
+    # @param registry_path [String] the registry path
+    # @return [ToolMetadata] the metadata object
+    def self.from_hash(hash, tool_name:, registry_path: nil)
+      new(
+        name: tool_name,
+        version: hash['version'],
+        display_name: hash['display_name'],
+        implements: hash['implements']&.to_sym,
+        homepage: hash['homepage'],
+        description: hash['description'],
+        aliases: hash['aliases'],
+        default_command: hash['default_command'],
+        tool_name: tool_name,
+        registry_path: registry_path
+      )
+    end
+  end
+end

data/lib/ukiryu/models/validation_result.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Models
+    # Result of validating a tool profile against the schema
+    #
+    # Contains validation status and any errors found during validation.
+    class ValidationResult
+      attr_reader :tool_name, :valid, :errors
+
+      # Create a new validation result
+      #
+      # @param tool_name [String] the tool name that was validated
+      # @param valid [Boolean] whether validation passed
+      # @param errors [Array<String>] list of validation errors
+      def initialize(tool_name:, valid:, errors: [])
+        @tool_name = tool_name
+        @valid = valid
+        @errors = errors
+      end
+
+      # Create a valid result (no errors)
+      #
+      # @param tool_name [String] the tool name
+      # @return [ValidationResult] a valid result
+      def self.valid(tool_name)
+        new(tool_name: tool_name, valid: true, errors: [])
+      end
+
+      # Create an invalid result with errors
+      #
+      # @param tool_name [String] the tool name
+      # @param errors [Array<String>] list of validation errors
+      # @return [ValidationResult] an invalid result
+      def self.invalid(tool_name, errors)
+        new(tool_name: tool_name, valid: false, errors: errors)
+      end
+
+      # Create a result for a tool not found
+      #
+      # @param tool_name [String] the tool name
+      # @return [ValidationResult] a not found result
+      def self.not_found(tool_name)
+        new(tool_name: tool_name, valid: false, errors: ['Tool not found'])
+      end
+
+      # Get a human-readable status message
+      #
+      # @return [String] status message
+      def status_message
+        if valid?
+          "✓ Valid"
+        else
+          "✗ Invalid (#{errors.size} error#{errors.size == 1 ? '' : 's'})"
+        end
+      end
+
+      # Check if validation passed
+      #
+      # @return [Boolean] true if valid
+      def valid?
+        @valid
+      end
+
+      # Check if validation failed
+      #
+      # @return [Boolean] true if invalid
+      def invalid?
+        !@valid
+      end
+
+      # Check if tool was not found
+      #
+      # @return [Boolean] true if tool not found
+      def not_found?
+        @errors == ['Tool not found']
+      end
+    end
+  end
+end