ukiryu 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '092e272dd1abe46958fdb31f6b4b0d12cd72bbf3b88d4c6c4119165faf210fe3'
-  data.tar.gz: 22b4c54e212f7c84bbf6dc69dd352c3d55137fa711f712241f2c5a5769366953
+  metadata.gz: 72da5a25186dfa4f3b3b53d0503c46f76086aaa94e219523126f331f10ca88d0
+  data.tar.gz: 6fcd4fa7a7f1af0830a1d2ea75632f63ff5b8b1333bfc4ce6b565444cc263898
 SHA512:
-  metadata.gz: ac196302eda5c010de7849e693bba66a1a844bcbad125d21d4b95b6c97c7110f9c175b087b2820ae61f4d1a6cd951e90663ccbaaf90a189168ad77d900986552
-  data.tar.gz: 64a86f0d697b12742fbe4a9a9368c55cbbe743d37bbee6ae08f39d199d455f90efa1a43f801e61e303c516268268198a76ebf34cb3d9c5b95e1fd83a172bbe8f
+  metadata.gz: 264926ef984787a01fd48941daea277027fa14ae405c63e15b765464338e474ef78c7f3d98a81f41762a281b140139bf9c8d515e468bf3350b584476e5118db0
+  data.tar.gz: aa91036800ea42466283e46e05fffc47179cffe08d9340f246f5abb44d3bf9276742804ba61c8ad3e00acb384f9d5ef56b55a3e87cc2990e675f50811a1ab5ec

data/README.adoc

@@ -83,7 +83,7 @@ Without Ukiryu, CLI tools suffer from:
 === The Ukiryu Solution
 
 [cols="1,1,4"]
-|===|===
+|===
 |Problem |Traditional CLI |Ukiryu Solution
 
 |Argument fragility
@@ -107,18 +107,19 @@ Without Ukiryu, CLI tools suffer from:
 
 |Discovery friction
 |`tool --help` |`ukiryu describe tool command`
+
 |===
 
 === Why "OpenAPI for CLIs"?
 
-OpenAPI revolutionized REST APIs by:
+OpenAPI provides the following benefits for REST APIs by:
 
 1. **Standardizing** - Machine-readable schema definitions
 2. **Documenting** - Auto-generated interactive documentation
 3. **Type-Safe** - Request/response validation
 4. **Versioning** - Multiple API versions coexisting
 
-Ukiryu brings the same revolution to CLI tools:
+Ukiryu provides the same benefits for CLI tools by:
 
 * **Schema**: YAML profiles replace grepping --help
 * **Docs**: `ukiryu describe` replaces man pages
@@ -136,7 +137,8 @@ Ukiryu brings the same revolution to CLI tools:
 // What is Ukiryu?
 == What is Ukiryu?
 
-Ukiryu is a framework that turns CLI tools into well-defined, versioned APIs through declarative YAML profiles.
+Ukiryu is a framework that turns CLI tools into well-defined, versioned APIs
+through declarative YAML profiles.
 
 === Key Concepts
 
@@ -150,32 +152,32 @@ Ukiryu is a framework that turns CLI tools into well-defined, versioned APIs thr
 
 [source]
 ----
-┌─────────────────────────────────────────────────────────────────────┐
-│                                                                    │
+┌───────────────────────────────────────────────────────────────────┐
+│                                                                   │
 │  User Code (Ruby / CLI)                                           │
 │  ├─ tool.execute(:inkscape, { inputs: [...] })                    │
 │  └─ ukiryu exec inkscape export inputs=...                        │
-│                                                                    │
+│                                                                   │
 └─────────────────────────────┬─────────────────────────────────────┘
                               │
                               ▼
 ┌─────────────────────────────▼─────────────────────────────────────┐
-│  Ukiryu Framework                                                  │
-│  ├─ Register (loads YAML profiles)                                  │
-│  ├─ Tool (selects profile, detects version)                           │
-│  ├─ CommandBuilder (formats arguments for shell)                    │
-│  ├─ Executor (runs commands, captures output)                        │
-│  └─ Shell Layer (platform-specific quoting/escaping)                │
-│                                                                    │
+│  Ukiryu Framework                                                 │
+│  ├─ Register (loads YAML profiles)                                │
+│  ├─ Tool (selects profile, detects version)                       │
+│  ├─ CommandBuilder (formats arguments for shell)                  │
+│  ├─ Executor (runs commands, captures output)                     │
+│  └─ Shell Layer (platform-specific quoting/escaping)              │
+│                                                                   │
 └─────────────────────────────┬─────────────────────────────────────┘
                               │
                               ▼
 ┌─────────────────────────────▼─────────────────────────────────────┐
-│  YAML Tool Profiles (Declarative API Definition)                   │
-│  ├─ tools/inkscape/1.0.yaml (Modern Inkscape)                        │
-│  ├─ tools/inkscape/0.92.yaml (Legacy Inkscape)                       │
-│  └─ tools/imagemagick/7.1.yaml (ImageMagick 7.1)                   │
-└──────────────────────────────────────────────────────────────────────┘
+│  YAML Tool Profiles (Declarative API Definition)                  │
+│  ├─ tools/inkscape/1.0.yaml (Modern Inkscape)                     │
+│  ├─ tools/inkscape/0.92.yaml (Legacy Inkscape)                    │
+│  └─ tools/imagemagick/7.1.yaml (ImageMagick 7.1)                  │
+└───────────────────────────────────────────────────────────────────┘
 ----
 
 === Tool Profile Schema

data/lib/ukiryu/definition/definition_validator.rb

@@ -73,12 +73,6 @@ module Ukiryu
           errors = []
           warnings = []
 
-          # Debug: Check which tool is being validated
-          if ENV['DEBUG_SCHEMA_VALIDATION']
-            tool_name = definition['name'] || definition[:name] || 'unknown'
-            puts "DEBUG: Validating tool: #{tool_name}"
-          end
-
           # Basic structural validation (always available)
           structural_result = validate_structure(definition)
           errors.concat(structural_result[:errors])
@@ -88,9 +82,6 @@ module Ukiryu
           if schema_validation_available?
             schema = schema_path ? load_schema(schema_path) : find_and_load_schema
             if schema
-              if ENV['DEBUG_SCHEMA_VALIDATION']
-                puts "DEBUG: Schema loaded, proceeding with JSON Schema validation"
-              end
               schema_result = validate_against_schema(definition, schema)
               errors.concat(schema_result[:errors])
               warnings.concat(schema_result[:warnings])
@@ -221,65 +212,9 @@ module Ukiryu
           warnings = []
 
           begin
-            # Debug: Check data BEFORE stringify_keys
-            if ENV['DEBUG_SCHEMA_VALIDATION']
-              tool_name = definition['name'] || definition[:name] || 'unknown'
-              puts "DEBUG: validate_against_schema for tool: #{tool_name}"
-
-              # Check flags[0] before stringify
-              if definition['profiles'] && definition['profiles'][0] &&
-                 definition['profiles'][0]['commands'] &&
-                 definition['profiles'][0]['commands'][0] &&
-                 definition['profiles'][0]['commands'][0]['flags'] &&
-                 definition['profiles'][0]['commands'][0]['flags'][0]
-                flg0_before = definition['profiles'][0]['commands'][0]['flags'][0]
-                puts "DEBUG: Flag 0 BEFORE stringify: #{flg0_before.inspect}"
-                puts "DEBUG: Flag 0 name BEFORE stringify: #{flg0_before['name'].inspect}"
-                puts "DEBUG: Flag 0 name class BEFORE stringify: #{flg0_before['name'].class}"
-              end
-            end
-
             # Convert symbol keys to strings for JSON Schema validation
             stringified = stringify_keys(definition)
-            # Debug: Check if keys are strings after stringify_keys
-            if ENV['DEBUG_SCHEMA_VALIDATION']
-              puts "DEBUG: After stringify_keys, checking keys..."
-              puts "DEBUG: Top-level keys: #{stringified.keys.inspect}"
-              puts "DEBUG: Top-level key classes: #{stringified.keys.map(&:class).inspect}"
-
-              # Check options[0] and flags[0] if they exist
-              if stringified['profiles'] && stringified['profiles'][0] &&
-                 stringified['profiles'][0]['commands'] &&
-                 stringified['profiles'][0]['commands'][0]
-                cmd = stringified['profiles'][0]['commands'][0]
-
-                # Check options[0]
-                if cmd['options'] && cmd['options'][0]
-                  opt0 = cmd['options'][0]
-                  puts "DEBUG: Option 0 after stringify: #{opt0.inspect}"
-                  puts "DEBUG: Option 0 keys: #{opt0.keys.inspect}"
-                  puts "DEBUG: Option 0 name: #{opt0['name'].inspect}"
-                  puts "DEBUG: Option 0 name class: #{opt0['name'].class}"
-                end
-
-                # Check flags[0]
-                if cmd['flags'] && cmd['flags'][0]
-                  flg0 = cmd['flags'][0]
-                  puts "DEBUG: Flag 0 after stringify: #{flg0.inspect}"
-                  puts "DEBUG: Flag 0 keys: #{flg0.keys.inspect}"
-                  puts "DEBUG: Flag 0 name: #{flg0['name'].inspect}"
-                  puts "DEBUG: Flag 0 name class: #{flg0['name'].class}"
-                end
-
-                # Also check options[26] for grep
-                if cmd['options'] && cmd['options'][26]
-                  opt26 = cmd['options'][26]
-                  puts "DEBUG: Option 26 after stringify: #{opt26.inspect}"
-                  puts "DEBUG: Option 26 name: #{opt26['name'].inspect}"
-                end
-              end
-              puts "DEBUG: JSON::Schema version: #{JSON::Schema::VERSION rescue 'unknown'}"
-            end
+
             validation = JSON::Validator.fully_validate(schema, stringified, errors_as_objects: true)
 
             validation.each do |error|

data/lib/ukiryu/definition/discovery.rb

@@ -217,7 +217,7 @@ module Ukiryu
       def self.metadata_from_file(yaml_file, source_type)
         # Try to load just the name and version from YAML
         yaml_content = File.read(yaml_file)
-        data = YAML.safe_load(yaml_content, permitted_classes: [Symbol])
+        data = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
 
         return nil unless data.is_a?(Hash)
         return nil unless data['name']

data/lib/ukiryu/executable_locator.rb

@@ -2,6 +2,7 @@
 
 require_relative 'executor'
 require_relative 'platform'
+require_relative 'models/search_paths'
 
 module Ukiryu
   # Executable locator for finding tool executables
@@ -74,7 +75,7 @@ module Ukiryu
 
       # Normalize search paths to array format
       #
-      # @param search_paths [Array<String>, Models::SearchPaths] the search paths
+      # @param search_paths [Array<String>, Models::SearchPaths, Hash] the search paths
       # @param platform [Symbol] the platform
       # @return [Array<String>] normalized array of paths
       def normalize_search_paths(search_paths, platform)
@@ -83,6 +84,12 @@ module Ukiryu
         # If it's a SearchPaths model, get platform-specific paths
         return search_paths.for_platform(platform) || [] if search_paths.is_a?(Models::SearchPaths)
 
+        # If it's a Hash, extract platform-specific paths
+        if search_paths.is_a?(Hash)
+          platform_paths = search_paths[platform] || search_paths[platform.to_s]
+          return platform_paths || [] if platform_paths
+        end
+
         # Already an array
         search_paths
       end

data/lib/ukiryu/executor.rb

@@ -45,6 +45,11 @@ module Ukiryu
         cwd = options[:cwd]
         stdin = options[:stdin]
 
+        # Suppress thread warnings from Open3 (cosmetic IOError from stream closure)
+        # Open3's internal threads may raise IOError when streams close early
+        original_setting = Thread.report_on_exception
+        Thread.report_on_exception = false
+
         started_at = Time.now
         begin
           result = if stdin
@@ -55,6 +60,8 @@ module Ukiryu
         rescue Timeout::Error
           Time.now
           raise TimeoutError, "Command timed out after #{timeout} seconds: #{executable}"
+        ensure
+          Thread.report_on_exception = original_setting
         end
         finished_at = Time.now
 

data/lib/ukiryu/man_page_parser.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative 'platform'
+require_relative 'executor'
+require 'time'
+require 'date'
+
+module Ukiryu
+  # Man page date parser for extracting version information
+  #
+  # Parses man page `.Dd` macros to extract dates as version information.
+  # Used as fallback for system tools that don't support --version flags.
+  #
+  # @example Parse man page date
+  #   date = ManPageParser.parse_date('/usr/share/man/man1/xargs.1')
+  #   # => "2020-09-21"
+  module ManPageParser
+    class << self
+      # Parse date from man page
+      #
+      # Extracts the `.Dd` (date) macro from a man page and converts it to
+      # ISO 8601 format (YYYY-MM-DD).
+      #
+      # @param man_page_path [String] path to the man page file
+      # @return [String, nil] ISO 8601 date string or nil if not found
+      def parse_date(man_page_path)
+        return nil unless man_page_path
+        return nil unless File.exist?(man_page_path)
+
+        content = File.read(man_page_path, encoding: 'UTF-8')
+
+        # Find .Dd line
+        # Format: .Dd Month DD, YYYY or .Dd DD Month YYYY
+        dd_line = content.lines.find { |line| line =~ /^\.Dd\s+/ }
+
+        return nil unless dd_line
+
+        # Extract and parse date
+        extract_date_from_dd_line(dd_line)
+      rescue Errno::ENOENT, Errno::EACCES => e
+        # File not found or inaccessible - silent failure
+        nil
+      end
+
+      # Get man page path for a tool on current platform
+      #
+      # @param tool_name [String] the tool name
+      # @param paths [Hash] platform-specific path templates
+      # @return [String, nil] resolved man page path or nil
+      def resolve_man_page_path(tool_name, paths = {})
+        platform = Platform.current
+
+        # Get platform-specific path pattern
+        path_pattern = paths[platform]
+
+        return nil unless path_pattern
+
+        # Expand tool name placeholder if present
+        path_pattern.gsub('{tool}', tool_name)
+      end
+
+      # Parse date from multiple possible man page locations
+      #
+      # Tries multiple paths in order and returns the first successfully
+      # parsed date.
+      #
+      # @param possible_paths [Array<String>] list of possible man page paths
+      # @return [String, nil] ISO 8601 date string or nil if none found
+      def parse_from_fallback(possible_paths)
+        possible_paths.each do |path|
+          date = parse_date(path)
+          return date if date
+        end
+
+        nil
+      end
+
+      private
+
+      # Extract date from .Dd line
+      #
+      # Handles various man page date formats:
+      # - .Dd September 21, 2020
+      # - .Dd 21 September 2020
+      # - .Dd 2020-09-21
+      #
+      # @param dd_line [String] the .Dd line
+      # @return [String, nil] ISO 8601 date or nil
+      def extract_date_from_dd_line(dd_line)
+        # Remove .Dd prefix
+        date_str = dd_line.sub(/^\.Dd\s+/, '').strip
+
+        # Try parsing different formats
+        parsed = try_parse_date_formats(date_str)
+
+        parsed&.strftime('%Y-%m-%d')
+      end
+
+      # Try parsing various date formats
+      #
+      # @param date_str [String] the date string
+      # @return [Date, nil] parsed date or nil
+      def try_parse_date_formats(date_str)
+        # Format: "September 21, 2020" or "21 September 2020"
+        # Parse with Date.parse which handles many formats
+        Date.parse(date_str)
+      rescue ArgumentError, Date::Error
+        # Try regex-based extraction
+        extract_date_with_regex(date_str)
+      end
+
+      # Extract date using regex patterns
+      #
+      # @param date_str [String] the date string
+      # @return [Date, nil] parsed date or nil
+      def extract_date_with_regex(date_str)
+        # Match "Month DD, YYYY" or "DD Month YYYY" or "YYYY-MM-DD"
+        patterns = [
+          /(\w+)\s+(\d+),?\s+(\d{4})/,   # Month DD, YYYY
+          /(\d+)\s+(\w+)\s+(\d{4})/,      # DD Month YYYY
+          /(\d{4})-(\d{2})-(\d{2})/       # YYYY-MM-DD
+        ]
+
+        patterns.each do |pattern|
+          match = date_str.match(pattern)
+          next unless match
+
+          captures = match.captures
+
+          # Determine order based on capture count
+          if captures[0]&.length == 4 # First capture is year (YYYY-MM-DD)
+            year, month, day = captures
+            return Date.new(year.to_i, month.to_i, day.to_i)
+          elsif captures[2]&.length == 4 # Last capture is year
+            month_or_day, day_or_month, year = captures
+
+            # Check if first is month name or number
+            if month_or_day =~ /^\d+$/
+              # DD Month YYYY format
+              day, month_name, year = captures
+              month = month_name_to_number(month_name)
+              return Date.new(year.to_i, month, day.to_i) if month
+            else
+              # Month DD, YYYY format
+              month_name, day, year = captures
+              month = month_name_to_number(month_name)
+              return Date.new(year.to_i, month, day.to_i) if month
+            end
+          end
+        end
+
+        nil
+      end
+
+      # Convert month name to number
+      #
+      # @param month_name [String] the month name
+      # @return [Integer, nil] month number (1-12) or nil
+      def month_name_to_number(month_name)
+        months = {
+          'january' => 1, 'jan' => 1,
+          'february' => 2, 'feb' => 2,
+          'march' => 3, 'mar' => 3,
+          'april' => 4, 'apr' => 4,
+          'may' => 5,
+          'june' => 6, 'jun' => 6,
+          'july' => 7, 'jul' => 7,
+          'august' => 8, 'aug' => 8,
+          'september' => 9, 'sep' => 9, 'sept' => 9,
+          'october' => 10, 'oct' => 10,
+          'november' => 11, 'nov' => 11,
+          'december' => 12, 'dec' => 12
+        }
+
+        months[month_name.downcase]
+      end
+    end
+  end
+end

data/lib/ukiryu/models/version_detection.rb

@@ -4,6 +4,23 @@ require 'lutaml/model'
 
 module Ukiryu
   module Models
+    # Version detection method
+    #
+    # Single detection method in the fallback hierarchy
+    class VersionDetectionMethod < Lutaml::Model::Serializable
+      attribute :type, :string # 'command' or 'man_page'
+      attribute :command, :string
+      attribute :pattern, :string
+      attribute :paths, :hash # Platform-specific paths for man_page
+
+      yaml do
+        map_element 'type', to: :type
+        map_element 'command', to: :command
+        map_element 'pattern', to: :pattern
+        map_element 'paths', to: :paths
+      end
+    end
+
     # Version detection configuration
     #
     # @example Command-based version detection (GNU tools)
@@ -19,17 +36,27 @@ module Ukiryu
     #     pattern: 'macOS ([\d.]+)',
     #     source: 'man'
     #   )
+    #
+    # @example Fallback hierarchy with detection_methods array
+    #   vd = VersionDetection.new(
+    #     detection_methods: [
+    #       VersionDetectionMethod.new(type: 'command', command: '--version', pattern: '(\d+\.\d+)'),
+    #       VersionDetectionMethod.new(type: 'man_page', paths: { macos: '/usr/share/man/man1/xargs.1' })
+    #     ]
+    #   )
     class VersionDetection < Lutaml::Model::Serializable
       attribute :command, :string, collection: true, default: []
       attribute :pattern, :string
       attribute :modern_threshold, :string
       attribute :source, :string, default: 'command' # 'command' or 'man'
+      attribute :detection_methods, VersionDetectionMethod, collection: true, default: []
 
       yaml do
         map_element 'command', to: :command
         map_element 'pattern', to: :pattern
         map_element 'modern_threshold', to: :modern_threshold
         map_element 'source', to: :source
+        map_element 'detection_methods', to: :detection_methods
       end
 
       # Hash-like access for Base.detect_version compatibility

data/lib/ukiryu/models/version_info.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Models
+    # Version information with detection method tracking
+    #
+    # Represents a version value with metadata about how it was detected.
+    # Supports multiple detection methods (command, man_page, etc.) as a
+    # fallback hierarchy, NOT mutually exclusive types.
+    #
+    # @example Command-based version
+    #   VersionInfo.new(
+    #     value: '3.11',
+    #     method_used: :command,
+    #     available_methods: [:command]
+    #   )
+    #
+    # @example Man page fallback version
+    #   VersionInfo.new(
+    #     value: '2020-09-21',
+    #     method_used: :man_page,
+    #     available_methods: [:command, :man_page]
+    #   )
+    class VersionInfo
+      attr_reader :value, :method_used, :available_methods
+
+      # Initialize version info
+      #
+      # @param value [String] the version value (e.g., "3.11" or "2020-09-21")
+      # @param method_used [Symbol] the method that succeeded (:command, :man_page, etc.)
+      # @param available_methods [Array<Symbol>] all methods that were available
+      def initialize(value:, method_used:, available_methods: [])
+        @value = value
+        @method_used = method_used
+        @available_methods = available_methods
+      end
+
+      # Check if version was detected via command
+      #
+      # @return [Boolean] true if from command execution
+      def from_command?
+        method_used == :command
+      end
+
+      # Check if version was detected via man page
+      #
+      # @return [Boolean] true if from man page date
+      def from_man_page?
+        method_used == :man_page
+      end
+
+      # Display format with context
+      # Adds "(man page)" suffix only for display, not stored in data
+      #
+      # @return [String] formatted version string
+      def to_s
+        case method_used
+        when :command
+          value
+        when :man_page
+          "#{value} (man page)"
+        else
+          value
+        end
+      end
+
+      # Hash representation
+      #
+      # @return [Hash] hash with value, method, and available_methods
+      def to_h
+        {
+          value: value,
+          method: method_used,
+          available_methods: available_methods
+        }
+      end
+
+      # Equality comparison
+      #
+      # @param other [Object] the object to compare
+      # @return [Boolean] true if equal
+      def ==(other)
+        return false unless other.is_a?(VersionInfo)
+
+        value == other.value &&
+          method_used == other.method_used &&
+          available_methods == other.available_methods
+      end
+
+      # Inspect representation
+      #
+      # @return [String] inspect string
+      def inspect
+        "#<VersionInfo value=\"#{value}\" method=#{method_used}>"
+      end
+    end
+  end
+end

data/lib/ukiryu/register.rb

@@ -98,7 +98,7 @@ module Ukiryu
         # First try exact name match
         yaml_content = load_tool_yaml(name, options.merge(register_path: register_path))
         if yaml_content
-          hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol])
+          hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
           return ToolMetadata.from_hash(hash, tool_name: name.to_s, register_path: register_path) if hash
         end
 
@@ -162,7 +162,7 @@ module Ukiryu
         yaml_content = load_tool_yaml(name, options)
         return Models::ValidationResult.not_found(name.to_s) unless yaml_content
 
-        profile = YAML.safe_load(yaml_content, permitted_classes: [Symbol])
+        profile = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
         return Models::ValidationResult.invalid(name.to_s, ['Failed to parse YAML']) unless profile
 
         errors = SchemaValidator.validate_profile(profile, options)

data/lib/ukiryu/thor_ext.rb

@@ -183,7 +183,7 @@ module Ukiryu
     # @param error [Exception] the error to format
     # @return [String] the formatted error message
     def format_error_message(error)
-      message = error.message.to_s
+      message = error.message.to_s.dup
       return message if error.is_a?(Thor::Error) && !message.empty?
 
       # Add class prefix for non-Thor errors or empty messages

data/lib/ukiryu/tool.rb

@@ -13,6 +13,7 @@ require_relative 'version_detector'
 require_relative 'logger'
 require_relative 'tool_index'
 require_relative 'models/routing'
+require_relative 'errors'
 
 module Ukiryu
   # Tool wrapper class for external command-line tools
@@ -441,7 +442,17 @@ module Ukiryu
     #
     # @return [String, nil] the tool version
     def version
-      @version || detect_version
+      return @version if @version
+
+      info = detect_version
+      info&.to_s
+    end
+
+    # Get the tool version info (full metadata)
+    #
+    # @return [Models::VersionInfo, nil] the version info or nil
+    def version_info
+      @version_info ||= detect_version
     end
 
     # Get the definition source if loaded from non-register source
@@ -719,14 +730,23 @@ module Ukiryu
 
     # Detect tool version using VersionDetector
     #
-    # @return [String, nil] the detected version or nil if not detected
+    # Supports both legacy format (command/pattern) and new methods array.
+    # The methods array allows fallback hierarchy: try command first,
+    # then man page, etc.
+    #
+    # @return [Models::VersionInfo, nil] the version info or nil if not detected
     public
 
     def detect_version
       vd = @profile.version_detection
       return nil unless vd
 
-      # Only attempt version detection if command is configured
+      # Check for new detection_methods array format
+      if vd.respond_to?(:detection_methods) && vd.detection_methods && !vd.detection_methods.empty?
+        return detect_version_with_detection_methods(vd.detection_methods)
+      end
+
+      # Legacy format: command-based detection
       return nil if vd.command.nil? || vd.command.empty?
 
       # For man page detection, the executable is 'man' and command is the tool name
@@ -743,7 +763,7 @@ module Ukiryu
         command_args = vd.command
       end
 
-      VersionDetector.detect(
+      VersionDetector.detect_info(
         executable: executable,
         command: command_args,
         pattern: vd.pattern || /(\d+\.\d+)/,
@@ -752,6 +772,61 @@ module Ukiryu
       )
     end
 
+    # Detect version using detection_methods array with fallback hierarchy
+    #
+    # @param detection_methods [Array] array of method definitions from YAML
+    # @return [Models::VersionInfo, nil] version info or nil
+    def detect_version_with_detection_methods(detection_methods)
+      # Convert YAML detection_methods to format expected by VersionDetector
+      detector_methods = detection_methods.map do |m|
+        # Handle both Hash and Lutaml::Model objects
+        type = if m.respond_to?(:type)
+                 m.type
+               elsif m.is_a?(Hash)
+                 m[:type] || m['type']
+               end
+
+        if type == :man_page || type == 'man_page'
+          paths = if m.respond_to?(:paths)
+                    m.paths
+                  elsif m.is_a?(Hash)
+                    m[:paths] || m['paths']
+                  else
+                    {}
+                  end
+
+          {
+            type: :man_page,
+            paths: paths
+          }
+        else
+          command = if m.respond_to?(:command)
+                      m.command
+                    elsif m.is_a?(Hash)
+                      m[:command] || m['command']
+                    end
+
+          pattern = if m.respond_to?(:pattern)
+                      m.pattern
+                    elsif m.is_a?(Hash)
+                      m[:pattern] || m['pattern']
+                    end
+
+          {
+            type: :command,
+            command: command || '--version',
+            pattern: pattern || /(\d+\.\d+)/
+          }
+        end
+      end
+
+      VersionDetector.detect_with_methods(
+        executable: @executable,
+        methods: detector_methods,
+        shell: @shell
+      )
+    end
+
     # Check version compatibility with profile requirements
     #
     # @param mode [Symbol] check mode (:strict, :lenient, :probe)
@@ -773,7 +848,7 @@ module Ukiryu
       end
 
       # If installed version unknown, probe for it
-      installed = detect_version if !installed && mode == :probe
+      installed = detect_version&.to_s if !installed && mode == :probe
 
       # If still unknown, handle based on mode
       unless installed

data/lib/ukiryu/tool_index.rb

@@ -160,7 +160,7 @@ module Ukiryu
       # Scan all tool directories for metadata
       Dir.glob(File.join(tools_dir, '*', '*.yaml')).each do |file|
         # Load only the top-level keys (metadata) without full parsing
-        hash = YAML.safe_load(File.read(file), permitted_classes: [Symbol])
+        hash = YAML.safe_load(File.read(file), permitted_classes: [Symbol], aliases: true)
         next unless hash
 
         tool_name = File.basename(File.dirname(file))
@@ -197,7 +197,7 @@ module Ukiryu
       yaml_content = load_yaml_for_tool(tool_name)
       return nil unless yaml_content
 
-      hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol])
+      hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
       return nil unless hash
 
       ToolMetadata.from_hash(hash, tool_name: tool_name.to_s, register_path: register_path)

data/lib/ukiryu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ukiryu
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

data/lib/ukiryu/version_detector.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative 'executor'
+require_relative 'models/version_info'
+require_relative 'man_page_parser'
 
 module Ukiryu
   # Version detector for external CLI tools
@@ -10,25 +12,28 @@ module Ukiryu
   # - Regex pattern matching for version strings
   # - Proper shell handling for command execution
   # - Support for man-page based version detection (BSD/system tools)
+  # - Fallback hierarchy: try multiple methods, use first success
   #
   # @example Detecting version from command output (GNU tools)
-  #   version = VersionDetector.detect(
+  #   info = VersionDetector.detect(
   #     executable: '/usr/bin/ffmpeg',
   #     command: '-version',
   #     pattern: /version (\d+\.\d+)/,
   #     shell: :bash
   #   )
   #
-  # @example Detecting version from man page (BSD/system tools)
-  #   version = VersionDetector.detect(
-  #     executable: '/usr/bin/man',
-  #     command: ['man', 'find'],
-  #     pattern: /macOS ([\d.]+)/,
-  #     source: 'man'
+  # @example Detecting version with fallback hierarchy
+  #   info = VersionDetector.detect_with_methods(
+  #     executable: '/usr/bin/xargs',
+  #     methods: [
+  #       { type: :command, command: '--version', pattern: /xargs \(GNU findutils\) ([\d.]+)/ },
+  #       { type: :man_page, paths: { macos: '/usr/share/man/man1/xargs.1' } }
+  #     ],
+  #     shell: :bash
   #   )
   module VersionDetector
     class << self
-      # Detect the version of an external tool
+      # Detect the version of an external tool (legacy API)
       #
       # @param executable [String] the executable path
       # @param command [String, Array<String>] the version command (default: '--version')
@@ -37,6 +42,26 @@ module Ukiryu
       # @param source [String] the version source: 'command' (default) or 'man'
       # @return [String, nil] the detected version or nil if not found
       def detect(executable:, command: '--version', pattern: /(\d+\.\d+)/, shell: nil, source: 'command')
+        result = detect_info(
+          executable: executable,
+          command: command,
+          pattern: pattern,
+          shell: shell,
+          source: source
+        )
+
+        result&.value
+      end
+
+      # Detect version with full info (VersionInfo)
+      #
+      # @param executable [String] the executable path
+      # @param command [String, Array<String>] the version command (default: '--version')
+      # @param pattern [Regexp] the regex pattern to extract version
+      # @param shell [Symbol] the shell to use for execution
+      # @param source [String] the version source: 'command' (default) or 'man'
+      # @return [VersionInfo, nil] the version info or nil if not found
+      def detect_info(executable:, command: '--version', pattern: /(\d+\.\d+)/, shell: nil, source: 'command')
         # Return nil if executable is not found
         return nil if executable.nil? || executable.empty?
 
@@ -45,7 +70,7 @@ module Ukiryu
         # Normalize command to array
         command_args = command.is_a?(Array) ? command : [command]
 
-        result = Executor.execute(executable, command_args, shell: shell)
+        result = Executor.execute(executable, command_args, shell: shell, allow_failure: true)
 
         return nil unless result.success?
 
@@ -59,11 +84,83 @@ module Ukiryu
           # Get last 500 characters to catch the OS version at bottom
           tail = output[-500..] || output
           match = tail.match(pattern)
-          return match[1] if match
+          return Models::VersionInfo.new(
+            value: match[1],
+            method_used: :man_page,
+            available_methods: [:man_page]
+          ) if match
         end
 
         match = stdout.match(pattern) || stderr.match(pattern)
-        match[1] if match
+
+        return nil unless match
+
+        Models::VersionInfo.new(
+          value: match[1],
+          method_used: :command,
+          available_methods: [:command]
+        )
+      rescue StandardError
+        # Return nil on any error (command not found, execution error, etc.)
+        nil
+      end
+
+      # Detect version using multiple methods with fallback hierarchy
+      #
+      # Tries each method in order and returns the first successful result.
+      # Methods are NOT mutually exclusive - they work together as fallbacks.
+      #
+      # @param executable [String] the tool executable path
+      # @param methods [Array<Hash>] array of method definitions
+      # @param shell [Symbol] the shell to use
+      # @return [VersionInfo, nil] version info or nil if all methods fail
+      def detect_with_methods(executable:, methods:, shell: nil)
+        shell ||= Shell.detect
+
+        # Track available methods for VersionInfo
+        available_methods = methods.map { |m| m[:type] }.uniq
+
+        # Try each method in order
+        methods.each do |method|
+          case method[:type]
+          when :command
+            # Try command-based detection
+            info = detect_info(
+              executable: executable,
+              command: method[:command] || '--version',
+              pattern: method[:pattern] || /(\d+\.\d+)/,
+              shell: shell,
+              source: 'command'
+            )
+
+            return info if info
+
+          when :man_page
+            # Try man page date extraction
+            paths = method[:paths] || {}
+
+            # Resolve man page path for current platform
+            require_relative 'platform'
+            platform = Platform.detect
+            man_path = paths[platform] || paths[platform.to_s]
+
+            next unless man_path
+
+            # Parse date from man page
+            date_str = ManPageParser.parse_date(man_path)
+
+            next unless date_str
+
+            return Models::VersionInfo.new(
+              value: date_str,
+              method_used: :man_page,
+              available_methods: available_methods
+            )
+          end
+        end
+
+        # All methods failed
+        nil
       end
     end
   end

data/ukiryu.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.7.0'
 
   # Core dependencies
-  spec.add_dependency 'git', '~> 4.0'
+  spec.add_dependency 'git', '~> 3.0'
   spec.add_dependency 'lutaml-model', '~> 0.7'
   spec.add_dependency 'thor', '~> 1.0'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ukiryu
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Ribose Inc.
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: lutaml-model
   requirement: !ruby/object:Gem::Requirement
@@ -178,6 +178,7 @@ files:
 - lib/ukiryu/extractors/native_extractor.rb
 - lib/ukiryu/io.rb
 - lib/ukiryu/logger.rb
+- lib/ukiryu/man_page_parser.rb
 - lib/ukiryu/models.rb
 - lib/ukiryu/models/argument.rb
 - lib/ukiryu/models/argument_definition.rb
@@ -202,6 +203,7 @@ files:
 - lib/ukiryu/models/validation_result.rb
 - lib/ukiryu/models/version_compatibility.rb
 - lib/ukiryu/models/version_detection.rb
+- lib/ukiryu/models/version_info.rb
 - lib/ukiryu/options/base.rb
 - lib/ukiryu/options_builder.rb
 - lib/ukiryu/options_builder/formatter.rb