ukiryu 0.1.6 → 0.2.0

data/lib/ukiryu/tool.rb

@@ -2,6 +2,7 @@
 
 require_relative 'tool_cache'
 require_relative 'tool_finder'
+require_relative 'tool/loader'
 
 module Ukiryu
   # Tool wrapper class for external command-line tools
@@ -44,48 +45,13 @@ module Ukiryu
       end
 
       # Try loading a tool using the new ImplementationIndex architecture
-      # Returns nil if the tool doesn't use the new architecture
+      # Delegates to Tool::Loader module
       #
       # @param name [String, Symbol] the tool name
       # @param options [Hash] loading options
       # @return [Tool, nil] the tool instance or nil if not using new architecture
       def load_with_implementation_index(name, options = {})
-        require_relative 'version_scheme_resolver'
-
-        # Try to load ImplementationIndex
-        index = Register.load_implementation_index(name, options)
-        return nil unless index
-
-        # Load Interface
-        interface = Register.load_interface(index.interface, options)
-        return nil unless interface
-
-        # Detect implementation and version
-        impl_spec = detect_implementation_and_version(index, name, options)
-        return nil unless impl_spec
-
-        # Load ImplementationVersion
-        impl_version = Register.load_implementation_version(
-          name,
-          impl_spec[:implementation_name],
-          impl_spec[:file],
-          options
-        )
-        return nil unless impl_version
-
-        # Convert to old ToolDefinition format for compatibility
-        profile = convert_to_tool_definition(
-          name,
-          interface,
-          impl_version,
-          impl_spec[:implementation_name],
-          impl_spec[:version], # Pass detected version
-          options
-        )
-        return nil unless profile
-
-        # Create tool instance
-        new(profile, options)
+        Loader.load_with_implementation_index(name, options)
       end
 
       # Detect implementation and version from ImplementationIndex
@@ -129,11 +95,13 @@ module Ukiryu
             # Prefer implementation-level default, then version-level default, then last version
             impl_default = impl[:default] || impl['default']
             version_spec = if impl_default
-                            # Find version spec matching the implementation default
-                            versions.find { |v| v[:file] == impl_default || v['file'] == impl_default } || versions.last
+                             # Find version spec matching the implementation default
+                             versions.find do |v|
+                               v[:file] == impl_default || v['file'] == impl_default
+                             end || versions.last
                            else
-                            versions.find { |v| v[:default] || v['default'] } || versions.last
-                          end
+                             versions.find { |v| v[:default] || v['default'] } || versions.last
+                           end
             return {
               implementation_name: impl[:name] || impl['name'],
               version: nil,
@@ -162,11 +130,11 @@ module Ukiryu
         # Prefer implementation-level default, then version-level default, then last version
         impl_default = impl[:default] || impl['default']
         default_spec = if impl_default
-                        # Find version spec matching the implementation default
-                        versions.find { |v| v[:file] == impl_default || v['file'] == impl_default } || versions.last
+                         # Find version spec matching the implementation default
+                         versions.find { |v| v[:file] == impl_default || v['file'] == impl_default } || versions.last
                        else
-                        versions.find { |v| v[:default] || v['default'] } || versions.last
-                      end
+                         versions.find { |v| v[:default] || v['default'] } || versions.last
+                       end
         {
           implementation_name: impl[:name] || impl['name'],
           version: nil,
@@ -260,14 +228,14 @@ module Ukiryu
 
         versions.each do |version_spec|
           range_type = if version_spec[:equals]
-  :equals
+                         :equals
                        elsif version_spec[:before]
-  :before
+                         :before
                        elsif version_spec[:after]
-  :after
+                         :after
                        else
-  version_spec[:between] ? :between : nil
-end
+                         version_spec[:between] ? :between : nil
+                       end
 
           next unless range_type
 
@@ -301,7 +269,8 @@ end
       # @param implementation_name [String] implementation name
       # @param options [Hash] options
       # @return [ToolDefinition] converted tool definition
-      def convert_to_tool_definition(tool_name, interface, impl_version, implementation_name, detected_version, options = {})
+      def convert_to_tool_definition(tool_name, interface, impl_version, implementation_name, detected_version,
+                                     options = {})
         require_relative 'models/tool_definition'
         require_relative 'models/platform_profile'
 
@@ -316,13 +285,13 @@ end
         # Build ToolDefinition from execution profile
         # Note: implements must be an array for the v2 model
         # Only append implementation name for non-default implementations
-        specific_tool_name = if implementation_name && implementation_name != 'default'
-                               "#{tool_name}_#{implementation_name}"
-                             else
-                               tool_name
-                             end
+        if implementation_name && implementation_name != 'default'
+          "#{tool_name}_#{implementation_name}"
+        else
+          tool_name
+        end
         # Use detected version if available, otherwise fall back to YAML version
-        version = detected_version || impl_version.version
+        detected_version || impl_version.version
         # Build ToolDefinition from execution profile
         # Note: implements must be an array for the v2 model
         # Only append implementation name for non-default implementations
@@ -377,11 +346,11 @@ end
       # @return [Hash] profile hash
       def convert_profile_to_hash(profile, actions)
         # Handle both Hash and ExecutionProfile objects
+        actions_hash = actions || {}
+        commands_array = convert_actions_to_array(actions_hash)
         if profile.is_a?(Hash)
           # Use the actions parameter (interface.actions), not profile[:actions]
-          actions_hash = actions || {}
           # Convert actions hash to array format expected by ToolDefinition
-          commands_array = convert_actions_to_array(actions_hash)
           {
             'name' => profile[:name] || profile['name'],
             'display_name' => profile[:display_name] || profile['display_name'],
@@ -392,8 +361,6 @@ end
             'commands' => commands_array
           }
         else
-          actions_hash = actions || {}
-          commands_array = convert_actions_to_array(actions_hash)
           {
             'name' => profile.name,
             'display_name' => profile.display_name,
@@ -441,25 +408,25 @@ end
         # If profile has commands, merge them with interface actions
         # If profile has no commands, use interface actions directly
         command_definitions = if profile_commands.nil? || profile_commands.empty?
-          # No profile commands - use interface actions directly
-          interface_commands_hash.map do |_cmd_name, cmd_hash|
-            convert_hash_to_command_definition(cmd_hash)
-          end
+                                # No profile commands - use interface actions directly
+                                interface_commands_hash.map do |_cmd_name, cmd_hash|
+                                  convert_hash_to_command_definition(cmd_hash)
+                                end
                               else
-          # Profile has commands - merge with interface actions
-          profile_commands.map do |cmd_hash|
-            # Command name may be specified as 'name' or 'subcommand' field
-            cmd_name = cmd_hash[:name] || cmd_hash['name'] || cmd_hash[:subcommand] || cmd_hash['subcommand']
-            # Merge profile command data with interface action data
-            interface_cmd = interface_commands_hash[cmd_name]
-            merged_cmd_hash = if interface_cmd
-                                # Deep merge: profile data takes precedence
-                                deep_merge_hashes(interface_cmd, cmd_hash)
-                              else
-                                cmd_hash
-                              end
-            convert_hash_to_command_definition(merged_cmd_hash)
-          end
+                                # Profile has commands - merge with interface actions
+                                profile_commands.map do |cmd_hash|
+                                  # Command name may be specified as 'name' or 'subcommand' field
+                                  cmd_name = cmd_hash[:name] || cmd_hash['name'] || cmd_hash[:subcommand] || cmd_hash['subcommand']
+                                  # Merge profile command data with interface action data
+                                  interface_cmd = interface_commands_hash[cmd_name]
+                                  merged_cmd_hash = if interface_cmd
+                                                      # Deep merge: profile data takes precedence
+                                                      deep_merge_hashes(interface_cmd, cmd_hash)
+                                                    else
+                                                      cmd_hash
+                                                    end
+                                  convert_hash_to_command_definition(merged_cmd_hash)
+                                end
                               end
 
         # Create PlatformProfile
@@ -501,7 +468,7 @@ end
           warn "[UKIRYU DEBUG build_command_definition] cmd.name: #{cmd_hash['name'] || cmd_hash[:name]}"
           warn "[UKIRYU DEBUG build_command_definition] post_options_data: #{post_options_data.inspect}"
           warn "[UKIRYU DEBUG build_command_definition] post_options_data.class: #{post_options_data.class}" if post_options_data
-          if post_options_data && post_options_data.is_a?(Array)
+          if post_options_data.is_a?(Array)
             post_options_data.first(2).each do |opt|
               warn "[UKIRYU DEBUG build_command_definition] post_option: #{opt.inspect}"
             end
@@ -563,7 +530,8 @@ end
                                    when 'inputs' then 'arguments'
                                    else nested_key.to_s
                                    end
-                      command_def[target_key.to_sym] = nested_value unless [:signature, 'signature'].include?(nested_key)
+                      command_def[target_key.to_sym] = nested_value unless [:signature,
+                                                                            'signature'].include?(nested_key)
                     end
                   else
                     command_def[key] = value
@@ -587,6 +555,7 @@ end
       # @option options [String] :register_path path to tool profiles
       # @option options [Symbol] :platform platform to use
       # @option options [Symbol] :shell shell to use
+      # @raise [Ukiryu::Errors::ToolNotFoundError] if tool is not found
       # @return [Tool] the tool instance
       def get(name, options = {})
         # Check cache first
@@ -602,6 +571,31 @@ end
         tool
       end
 
+      # Find a tool by name, returning nil if not found.
+      #
+      # This is a non-raising alternative to {.get} for cases where
+      # tool absence is expected and should be handled gracefully.
+      #
+      # @param name [String, Symbol] the tool name
+      # @param options [Hash] initialization options
+      # @option options [String] :register_path path to tool profiles
+      # @option options [Symbol] :platform platform to use
+      # @option options [Symbol] :shell shell to use
+      # @return [Tool, nil] the tool instance or nil if not found
+      #
+      # @example
+      #   tool = Ukiryu::Tool.find(:imagemagick)
+      #   if tool
+      #     tool.execute(:convert, inputs: ["image.png"])
+      #   else
+      #     puts "ImageMagick not available"
+      #   end
+      def find(name, options = {})
+        get(name, options)
+      rescue Ukiryu::Errors::ToolNotFoundError
+        nil
+      end
+
       # Find a tool by name, alias, or interface
       #
       # Searches for a tool that matches the given identifier by:
@@ -1000,9 +994,7 @@ end
       # Normalize params to hash with symbol keys
       params = normalize_params(params)
 
-      if ENV['UKIRYU_DEBUG_EXECUTABLE']
-        warn "[UKIRYU DEBUG execute_simple] params (after normalize): #{params.inspect}"
-      end
+      warn "[UKIRYU DEBUG execute_simple] params (after normalize): #{params.inspect}" if ENV['UKIRYU_DEBUG_EXECUTABLE']
 
       # Extract stdin parameter if present (special parameter, not passed to command)
       stdin = params.delete(:stdin)
@@ -1034,10 +1026,10 @@ end
                                # Use command-specific executable if profile explicitly allows it
                                # This is determined by checking if the command has standalone_executable: true
                                allows_standalone = if command.respond_to?(:standalone_executable?)
-                                                   command.standalone_executable?
+                                                     command.standalone_executable?
                                                    else
-                                                   false
-                                                 end
+                                                     false
+                                                   end
 
                                same_dir_as_exec = allows_standalone &&
                                                   File.executable?(exe_path) &&

data/lib/ukiryu/tool_index.rb

@@ -3,6 +3,8 @@
 # Lazy load ToolMetadata only when needed
 autoload :ToolMetadata, File.expand_path('models/tool_metadata', __dir__)
 
+require_relative 'models/semantic_version'
+
 module Ukiryu
   # Index for fast tool lookup by interface and alias
   #
@@ -12,20 +14,27 @@ module Ukiryu
   # - Register change detection via mtime
   #
   # Built once and cached for the lifetime of the process.
+  # Thread-safe for concurrent access.
   #
   # @api private
   class ToolIndex
+    @mutex = Mutex.new
+
     class << self
-      # Get the singleton instance
+      # Get the singleton instance (thread-safe)
       #
       # @return [ToolIndex] the index instance
       def instance
-        @instance ||= new
+        @mutex.synchronize do
+          @instance ||= new
+        end
       end
 
       # Reset the index (mainly for testing)
       def reset
-        @instance = nil
+        @mutex.synchronize do
+          @instance = nil
+        end
       end
 
       # Get all tools in the index (class method delegating to instance)
@@ -41,13 +50,13 @@ module Ukiryu
     # @param register_path [String, nil] the path to the tool register
     def initialize(register_path: nil)
       @register_path = register_path || Ukiryu::Register.default_register_path
+      @mutex = Mutex.new
 
-      if ENV['UKIRYU_DEBUG_EXECUTABLE']
-        warn '[UKIRYU DEBUG ToolIndex#initialize] called'
-        warn "[UKIRYU DEBUG] param register_path = #{register_path.inspect}"
-        warn "[UKIRYU_DEBUG] Ukiryu::Register.default_register_path = #{Ukiryu::Register.default_register_path.inspect}"
-        warn "[UKIRYU DEBUG] @register_path = #{@register_path.inspect}"
-      end
+      Logger.debug('ToolIndex#initialize called', category: :executable)
+      Logger.debug("param register_path = #{register_path.inspect}", category: :executable)
+      Logger.debug("Ukiryu::Register.default_register_path = #{Ukiryu::Register.default_register_path.inspect}",
+                   category: :executable)
+      Logger.debug("@register_path = #{@register_path.inspect}", category: :executable)
 
       @interface_to_tools = {} # interface => [tool_names]
       @alias_to_tool = {}      # alias => [tool_names] (multiple tools can share an alias)
@@ -64,16 +73,18 @@ module Ukiryu
     def find_by_interface(interface_name)
       build_index_if_needed
 
-      tool_names = @interface_to_tools[interface_name]
-      return nil unless tool_names
+      @mutex.synchronize do
+        tool_names = @interface_to_tools[interface_name]
+        return nil unless tool_names
 
-      # Try each tool implementing this interface until we find one that loads
-      tool_names.each do |tool_name|
-        metadata = load_metadata_for_tool(tool_name)
-        return metadata if metadata
-      end
+        # Try each tool implementing this interface until we find one that loads
+        tool_names.each do |tool_name|
+          metadata = load_metadata_for_tool(tool_name)
+          return metadata if metadata
+        end
 
-      nil
+        nil
+      end
     end
 
     # Find all tools that implement an interface
@@ -83,7 +94,9 @@ module Ukiryu
     def find_all_by_interface(interface_name)
       build_index_if_needed
 
-      @interface_to_tools[interface_name] || []
+      @mutex.synchronize do
+        @interface_to_tools[interface_name] || []
+      end
     end
 
     # Find tool by alias
@@ -96,20 +109,22 @@ module Ukiryu
     def find_by_alias(alias_name)
       build_index_if_needed
 
-      candidates = @alias_to_tool[alias_name.to_sym]
-      return nil unless candidates
+      @mutex.synchronize do
+        candidates = @alias_to_tool[alias_name.to_sym]
+        return nil unless candidates
 
-      # If only one tool has this alias, return it directly
-      return candidates.first if candidates.one?
+        # If only one tool has this alias, return it directly
+        return candidates.first if candidates.one?
 
-      # Multiple tools have this alias - select by platform compatibility
-      runtime = Ukiryu::Runtime.instance
-      platform = runtime.platform
-      shell = runtime.shell
+        # Multiple tools have this alias - select by platform compatibility
+        runtime = Ukiryu::Runtime.instance
+        platform = runtime.platform
+        shell = runtime.shell
 
-      candidates.find do |tool_name|
-        tool_compatible?(tool_name, platform: platform, shell: shell)
-      end || candidates.first
+        candidates.find do |tool_name|
+          tool_compatible?(tool_name, platform: platform, shell: shell)
+        end || candidates.first
+      end
     end
 
     # Check if a tool is compatible with the given platform and shell
@@ -165,31 +180,45 @@ module Ukiryu
     #
     # @return [Boolean] true if rebuild is needed
     def stale?
-      return true unless @built
+      @mutex.synchronize do
+        return true unless @built
 
-      current_cache_key = build_cache_key
-      @cache_key != current_cache_key
+        current_cache_key = build_cache_key
+        @cache_key != current_cache_key
+      end
     end
 
     # Update the register path
     #
     # @param new_path [String] the new register path
     def register_path=(new_path)
-      return if @register_path == new_path
-
-      @register_path = new_path
-      @built = false # Rebuild index with new path
-      @cache_key = nil
-      @interface_to_tools = {}
-      @alias_to_tool = {}
-      @compatibility_cache = {}
+      @mutex.synchronize do
+        return if @register_path == new_path
+
+        @register_path = new_path
+        @built = false # Rebuild index with new path
+        @cache_key = nil
+        @interface_to_tools = {}
+        @alias_to_tool = {}
+        @compatibility_cache = {}
+      end
     end
 
     private
 
-    # Build index only if needed (lazy loading)
+    # Build index only if needed (lazy loading) - thread-safe
     def build_index_if_needed
-      build_index if stale?
+      @mutex.synchronize do
+        build_index if stale_without_lock?
+      end
+    end
+
+    # Check if stale without acquiring lock (must be called within synchronized block)
+    def stale_without_lock?
+      return true unless @built
+
+      current_cache_key = build_cache_key
+      @cache_key != current_cache_key
     end
 
     # Build cache key for register change detection
@@ -216,12 +245,11 @@ module Ukiryu
     def register_path
       path = @register_path || Ukiryu::Register.default_register_path
 
-      if ENV['UKIRYU_DEBUG_EXECUTABLE']
-        warn '[UKIRYU DEBUG ToolIndex#register_path] called'
-        warn "[UKIRYU DEBUG] @register_path = #{@register_path.inspect}"
-        warn "[UKIRYU DEBUG] Ukiryu::Register.default_register_path = #{Ukiryu::Register.default_register_path.inspect}"
-        warn "[UKIRYU DEBUG] returning = #{path.inspect}"
-      end
+      Logger.debug('ToolIndex#register_path called', category: :executable)
+      Logger.debug("@register_path = #{@register_path.inspect}", category: :executable)
+      Logger.debug("Ukiryu::Register.default_register_path = #{Ukiryu::Register.default_register_path.inspect}",
+                   category: :executable)
+      Logger.debug("returning = #{path.inspect}", category: :executable)
 
       path
     end
@@ -231,10 +259,8 @@ module Ukiryu
     def build_index
       current_path = register_path
 
-      if ENV['UKIRYU_DEBUG_EXECUTABLE']
-        warn '[UKIRYU DEBUG ToolIndex#build_index] called'
-        warn "[UKIRYU DEBUG] current_path = #{current_path.inspect}"
-      end
+      Logger.debug('ToolIndex#build_index called', category: :executable)
+      Logger.debug("current_path = #{current_path.inspect}", category: :executable)
 
       return unless current_path
 
@@ -328,15 +354,17 @@ module Ukiryu
 
     # Load YAML content for a specific tool
     #
+    # Version selection is based on the `version:` field inside YAML content,
+    # NOT the filename. This ensures the content is the source of truth.
+    #
     # @param tool_name [Symbol, String] the tool name
     # @return [String, nil] the YAML content
     def load_yaml_for_tool(tool_name)
       current_path = register_path
 
-      if ENV['UKIRYU_DEBUG_EXECUTABLE']
-        warn "[UKIRYU DEBUG ToolIndex#load_yaml_for_tool] tool_name=#{tool_name}"
-        warn "[UKIRYU DEBUG] current_path = #{current_path.inspect}"
-      end
+      Logger.debug("ToolIndex#load_yaml_for_tool tool_name=#{tool_name}",
+                   category: :executable)
+      Logger.debug("current_path = #{current_path.inspect}", category: :executable)
 
       return nil unless current_path
 
@@ -354,19 +382,56 @@ module Ukiryu
         # Prefer 'default' variant if present
         next unless File.basename(variant_dir) == 'default'
 
-        files = Dir.glob(File.join(variant_dir, '*.yaml')).sort
-        return File.read(files.last) if files.any?
+        files = Dir.glob(File.join(variant_dir, '*.yaml'))
+        return select_latest_version_by_content(files) if files.any?
 
         # Fall back to any variant directory
-        files = Dir.glob(File.join(variant_dir, '*.yaml')).sort
-        return File.read(files.last) if files.any?
+        files = Dir.glob(File.join(variant_dir, '*.yaml'))
+        return select_latest_version_by_content(files) if files.any?
       end
 
       # Fallback: direct YAML files in tool directory (legacy structure)
-      files = Dir.glob(File.join(tool_dir, '*.yaml')).sort
-      files.last ? File.read(files.last) : nil
+      files = Dir.glob(File.join(tool_dir, '*.yaml'))
+      files.any? ? select_latest_version_by_content(files) : nil
     rescue StandardError
       nil
     end
+
+    # Select the latest version file by reading version from YAML CONTENT.
+    #
+    # This is the correct approach: version comes from the `version:` field
+    # inside the YAML file, NOT from the filename. The content is the
+    # source of truth.
+    #
+    # @param files [Array<String>] list of YAML file paths
+    # @return [String, nil] content of the file with the highest version
+    def select_latest_version_by_content(files)
+      return nil if files.empty?
+      return File.read(files.first) if files.size == 1
+
+      # Build a map of version (from content) => file content
+      versions_to_content = {}
+
+      files.each do |file|
+        content = File.read(file)
+        hash = YAML.safe_load(content, permitted_classes: [Symbol], aliases: true)
+        next unless hash
+
+        version_string = hash['version']
+        next unless version_string
+
+        version = Models::SemanticVersion.new(version_string)
+        versions_to_content[version] = content
+      rescue StandardError => e
+        # Skip files that can't be parsed
+        Logger.warn("Failed to parse version from #{file}: #{e.message}")
+      end
+
+      # Return content of the highest version
+      return nil if versions_to_content.empty?
+
+      latest_version = versions_to_content.keys.max
+      versions_to_content[latest_version]
+    end
   end
 end

data/lib/ukiryu/tools/base.rb

@@ -259,7 +259,8 @@ module Ukiryu
         args = build_args(command_def, params)
 
         # Find executable using ExecutableFinder
-        executable = Ukiryu::ExecutableFinder.find_executable(self.class.tool_definition.name.to_s, self.class.tool_definition)
+        executable = Ukiryu::ExecutableFinder.find_executable(self.class.tool_definition.name.to_s,
+                                                              self.class.tool_definition)
 
         # Get shell
         shell_sym = Ukiryu::Runtime.instance.shell
@@ -425,7 +426,8 @@ module Ukiryu
 
         cmd = vd.command
 
-        executable = Ukiryu::ExecutableFinder.find_executable(self.class.tool_definition.name.to_s, self.class.tool_definition)
+        executable = Ukiryu::ExecutableFinder.find_executable(self.class.tool_definition.name.to_s,
+                                                              self.class.tool_definition)
         return nil unless executable
 
         shell_sym = Ukiryu::Runtime.instance.shell