ukiryu 0.1.0

data/lib/ukiryu/platform.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  # Platform detection module
+  #
+  # Provides explicit platform detection with clear error messages.
+  # No automatic fallbacks - if platform cannot be determined, raises an error.
+  module Platform
+    class << self
+      # Detect the current platform
+      #
+      # @return [Symbol] :windows, :macos, or :linux
+      # @raise [UnsupportedPlatformError] if platform cannot be determined
+      def detect
+        if windows?
+          :windows
+        elsif macos?
+          :macos
+        elsif linux?
+          :linux
+        else
+          # Try to determine from RbConfig
+          host_os = RbConfig::CONFIG["host_os"]
+          case host_os
+          when /mswin|mingw|windows/i
+            :windows
+          when /darwin|mac os/i
+            :macos
+          when /linux/i
+            :linux
+          else
+            raise UnsupportedPlatformError, <<~ERROR
+              Unable to detect platform. Host OS: #{host_os}
+
+              Supported platforms: Windows, macOS, Linux
+
+              Please configure platform explicitly:
+                Ukiryu.configure do |config|
+                  config.platform = :linux # or :macos, :windows
+                end
+            ERROR
+          end
+        end
+      end
+
+      # Check if running on Windows
+      #
+      # @return [Boolean]
+      def windows?
+        Gem.win_platform? || RbConfig::CONFIG["host_os"] =~ /mswin|mingw|windows/i
+      end
+
+      # Check if running on macOS
+      #
+      # @return [Boolean]
+      def macos?
+        RbConfig::CONFIG["host_os"] =~ /darwin|mac os/i
+      end
+
+      # Check if running on Linux
+      #
+      # @return [Boolean]
+      def linux?
+        RbConfig::CONFIG["host_os"] =~ /linux/i
+      end
+
+      # Check if running on a Unix-like system (macOS or Linux)
+      #
+      # @return [Boolean]
+      def unix?
+        macos? || linux?
+      end
+
+      # Get the PATH environment variable as an array
+      # Handles different PATH separators on Windows (;) vs Unix (:)
+      #
+      # @return [Array<String>] array of directory paths
+      def executable_search_paths
+        @executable_search_paths ||= begin
+          path_sep = windows? ? ";" : ":"
+          (ENV["PATH"] || "").split(path_sep)
+        end
+      end
+
+      # Reset cached paths (primarily for testing)
+      #
+      # @api private
+      def reset_cache
+        @executable_search_paths = nil
+      end
+    end
+  end
+end

data/lib/ukiryu/registry.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "find"
+
+module Ukiryu
+  # YAML profile registry loader
+  #
+  # Loads tool definitions from YAML profiles in a registry directory.
+  class Registry
+    class << self
+      # Load all tool profiles from a registry directory
+      #
+      # @param path [String] the registry directory path
+      # @param options [Hash] loading options
+      # @option options [Boolean] :recursive search recursively (default: true)
+      # @option options [Boolean] :validate validate against schema (default: false)
+      # @return [Hash] loaded tools keyed by name
+      def load_from(path, options = {})
+        raise ProfileLoadError, "Registry path not found: #{path}" unless Dir.exist?(path)
+
+        tools = {}
+        recursive = options.fetch(:recursive, true)
+
+        pattern = recursive ? "**/*.yaml" : "*.yaml"
+        files = Dir.glob(File.join(path, "tools", pattern))
+
+        files.each do |file|
+          begin
+            profile = load_profile(file)
+            name = profile[:name]
+            tools[name] ||= []
+            tools[name] << profile
+          rescue => e
+            warn "Warning: Failed to load profile #{file}: #{e.message}"
+          end
+        end
+
+        tools
+      end
+
+      # Load a single profile file
+      #
+      # @param file [String] the path to the YAML file
+      # @return [Hash] the loaded profile
+      def load_profile(file)
+        content = File.read(file)
+        profile = YAML.safe_load(content, permitted_classes: [], permitted_symbols: [], aliases: true)
+
+        # Convert string keys to symbols for consistency
+        profile = symbolize_keys(profile)
+
+        # Resolve inheritance if present
+        resolve_inheritance(profile, file)
+
+        profile
+      end
+
+      # Load a specific tool by name
+      #
+      # @param name [String] the tool name
+      # @param options [Hash] loading options
+      # @option options [String] :version specific version to load
+      # @option options [String] :registry_path path to registry
+      # @return [Hash, nil] the tool profile or nil if not found
+      def load_tool(name, options = {})
+        registry_path = options[:registry_path] || @default_registry_path
+
+        raise ProfileLoadError, "Registry path not configured" unless registry_path
+
+        # Try version-specific directory first
+        version = options[:version]
+        if version
+          file = File.join(registry_path, "tools", name, "#{version}.yaml")
+          return load_profile(file) if File.exist?(file)
+        end
+
+        # Search in all matching files
+        pattern = File.join(registry_path, "tools", name, "*.yaml")
+        files = Dir.glob(pattern).sort
+
+        if files.empty?
+          # Try the old format (single file per tool)
+          file = File.join(registry_path, "tools", "#{name}.yaml")
+          return load_profile(file) if File.exist?(file)
+          return nil
+        end
+
+        # Return the latest version if version not specified
+        if version.nil?
+          # Sort by version and return the newest
+          sorted_files = files.sort_by { |f| Gem::Version.new(File.basename(f, ".yaml")) }
+          load_profile(sorted_files.last)
+        else
+          # Find specific version
+          version_file = files.find { |f| File.basename(f, ".yaml") == version }
+          version_file ? load_profile(version_file) : nil
+        end
+      end
+
+      # Set the default registry path
+      #
+      # @param path [String] the default registry path
+      def default_registry_path=(path)
+        @default_registry_path = path
+      end
+
+      # Get the default registry path
+      #
+      # @return [String, nil] the default registry path
+      def default_registry_path
+        @default_registry_path
+      end
+
+      # Get all available tool names
+      #
+      # @return [Array<String>] list of tool names
+      def tools
+        registry_path = @default_registry_path
+        return [] unless registry_path
+
+        tools_dir = File.join(registry_path, "tools")
+        return [] unless Dir.exist?(tools_dir)
+
+        # List all directories in tools/
+        Dir.glob(File.join(tools_dir, "*")).select do |path|
+          File.directory?(path)
+        end.map do |path|
+          File.basename(path)
+        end.sort
+      end
+
+      # Find the newest compatible version of a tool
+      #
+      # @param tool_name [String] the tool name
+      # @param options [Hash] search options
+      # @option options [String] :platform platform (default: auto-detect)
+      # @option options [String] :shell shell (default: auto-detect)
+      # @option options [String] :version_constraint version constraint
+      # @return [Hash, nil] the best matching profile or nil
+      def find_compatible_profile(tool_name, options = {})
+        profiles = load_tool_profiles(tool_name)
+        return nil if profiles.nil? || profiles.empty?
+
+        platform = options[:platform] || Platform.detect
+        shell = options[:shell] || Shell.detect
+        version = options[:version]
+
+        # Filter by platform and shell
+        candidates = profiles.select do |profile|
+          profile_platforms = profile[:platforms] || profile[:platform]
+          profile_shells = profile[:shells] || profile[:shell]
+
+          platform_match = profile_platforms.include?(platform) if profile_platforms
+          shell_match = profile_shells.include?(shell) if profile_shells
+
+          (platform_match || profile_platforms.nil?) && (shell_match || profile_shells.nil?)
+        end
+
+        # Further filter by version if specified
+        if version && !candidates.empty?
+          constraint = Gem::Requirement.new(version)
+          candidates.select! do |profile|
+            profile_version = profile[:version]
+            next true unless profile_version
+
+            constraint.satisfied_by?(Gem::Version.new(profile_version))
+          end
+        end
+
+        # Return the first matching profile (prefer newer versions)
+        candidates.first
+      end
+
+      private
+
+      # Load all profiles for a specific tool
+      def load_tool_profiles(name)
+        registry_path = @default_registry_path
+        return nil unless registry_path
+
+        pattern = File.join(registry_path, "tools", name, "*.yaml")
+        files = Dir.glob(pattern)
+
+        return nil if files.empty?
+
+        files.flat_map do |file|
+          begin
+            profile = load_profile(file)
+            profile[:_file_path] = file
+            profile
+          rescue => e
+            warn "Warning: Failed to load profile #{file}: #{e.message}"
+            []
+          end
+        end
+      end
+
+      # Resolve profile inheritance
+      #
+      # @param profile [Hash] the profile to resolve
+      # @param file_path [String] the path to the profile file
+      def resolve_inheritance(profile, file_path)
+        return unless profile[:profiles]
+
+        base_dir = File.dirname(file_path)
+
+        profile[:profiles].each do |p|
+          next unless p[:inherits]
+
+          parent_profile = find_parent_profile(p[:inherits], profile[:profiles], base_dir)
+          if parent_profile
+            # Merge parent into child (child takes precedence)
+            p.merge!(parent_profile) { |_, child_val, _| child_val }
+          end
+        end
+      end
+
+      # Find a parent profile within the same file
+      def find_parent_profile(name, profiles, _base_dir)
+        profiles.find { |p| p[:name] == name }
+      end
+
+      # Recursively convert string keys to symbols
+      #
+      # @param hash [Hash] the hash to convert
+      # @return [Hash] the hash with symbolized keys
+      def symbolize_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.transform_keys do |key|
+          key.is_a?(String) ? key.to_sym : key
+        end.transform_values do |value|
+          case value
+          when Hash
+            symbolize_keys(value)
+          when Array
+            value.map { |v| v.is_a?(Hash) ? symbolize_keys(v) : v }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ukiryu/schema_validator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+begin
+  require "json-schema"
+rescue LoadError
+  # json-schema is optional - only needed for schema validation
+end
+require "yaml"
+
+module Ukiryu
+  # Schema validator for YAML tool profiles
+  #
+  # Validates tool profile YAML files against JSON Schema definitions.
+  class SchemaValidator
+    class << self
+      # Validate a tool profile against the schema
+      #
+      # @param profile [Hash] the loaded profile hash
+      # @param options [Hash] validation options
+      # @option options [String] :schema_path path to schema file
+      # @option options [Boolean] :strict whether to use strict validation
+      # @return [Array<String>] list of validation errors (empty if valid)
+      def validate_profile(profile, options = {})
+        # Check if json-schema gem is available
+        unless defined?(JSON::Validator)
+          return ["json-schema gem not installed. Add 'json-schema' to Gemfile for schema validation."]
+        end
+
+        errors = []
+
+        # Load the schema
+        schema = load_schema(options[:schema_path])
+        return ["Failed to load schema"] unless schema
+
+        # Validate against JSON schema
+        begin
+          # JSON Schema library expects the data to be a hash
+          validation_errors = JSON::Validator.fully_validate(schema, profile, strict: options[:strict] || false)
+
+          # Convert errors to readable format
+          validation_errors.each do |error|
+            errors << format_schema_error(error)
+          end
+        rescue JSON::Schema::ValidationError => e
+          errors << "Schema validation error: #{e.message}"
+        end
+
+        errors
+      end
+
+      # Load and parse the JSON schema
+      #
+      # @param path [String, nil] path to schema file (optional)
+      # @return [Hash] the parsed schema
+      def load_schema(path = nil)
+        schema_path = path || default_schema_path
+        return nil unless schema_path && File.exist?(schema_path)
+
+        schema_content = File.read(schema_path)
+        parsed = YAML.safe_load(schema_content)
+
+        # Convert YAML schema to JSON schema format
+        # YAML schema uses $schema, definitions, etc.
+        convert_yaml_schema_to_json(parsed)
+      end
+
+      # Get the default schema path
+      #
+      # @return [String, nil] the default schema path
+      def default_schema_path
+        # Schema is in the sibling 'schema' directory at the same level as the gem
+        # From lib/ukiryu/, we go up to gem root, then to sibling schema/
+        gem_root = File.expand_path("../..", __dir__) # ukiryu gem root
+        schema_dir = File.expand_path("../schema", gem_root) # src/ukiryu/schema/
+        schema_file = File.join(schema_dir, "tool-profile.schema.yaml")
+        return schema_file if File.exist?(schema_file)
+
+        nil
+      end
+
+      private
+
+      # Convert YAML schema format to JSON schema format
+      #
+      # @param yaml_schema [Hash] the parsed YAML schema
+      # @return [Hash] the converted JSON schema
+      def convert_yaml_schema_to_json(yaml_schema)
+        # The YAML schema format is very similar to JSON schema
+        # Just need to ensure it has the right structure
+        yaml_schema
+      end
+
+      # Format a schema error for readability
+      #
+      # @param error [String] the raw error message
+      # @return [String] the formatted error
+      def format_schema_error(error)
+        error
+      end
+    end
+  end
+end

data/lib/ukiryu/shell/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Ukiryu
+  module Shell
+    # Base class for shell implementations
+    #
+    # Each shell implementation must provide:
+    # - name: Symbol identifying the shell
+    # - escape(string): Escape a string for this shell
+    # - quote(string): Quote an argument for this shell
+    # - format_path(path): Format a file path for this shell
+    # - env_var(name): Format an environment variable reference
+    # - join(executable, *args): Join executable and arguments into a command line
+    class Base
+      # Identify the shell
+      #
+      # @return [Symbol] the shell name
+      def name
+        raise NotImplementedError, "#{self.class} must implement #name"
+      end
+
+      # Escape a string for this shell
+      #
+      # @param string [String] the string to escape
+      # @return [String] the escaped string
+      def escape(string)
+        raise NotImplementedError, "#{self.class} must implement #escape"
+      end
+
+      # Quote an argument for this shell
+      #
+      # @param string [String] the string to quote
+      # @return [String] the quoted string
+      def quote(string)
+        raise NotImplementedError, "#{self.class} must implement #quote"
+      end
+
+      # Format a file path for this shell
+      #
+      # @param path [String] the file path
+      # @return [String] the formatted path
+      def format_path(path)
+        path
+      end
+
+      # Format an environment variable reference
+      #
+      # @param name [String] the variable name
+      # @return [String] the formatted reference
+      def env_var(name)
+        raise NotImplementedError, "#{self.class} must implement #env_var"
+      end
+
+      # Join executable and arguments into a command line
+      #
+      # @param executable [String] the executable path
+      # @param args [Array<String>] the arguments
+      # @return [String] the complete command line
+      def join(executable, *args)
+        raise NotImplementedError, "#{self.class} must implement #join"
+      end
+
+      # Format environment variables for command execution
+      #
+      # @param env_vars [Hash] environment variables to set
+      # @return [Hash] formatted environment variables
+      def format_environment(env_vars)
+        env_vars
+      end
+
+      # Get headless environment variables (e.g., DISPLAY="" for Unix)
+      #
+      # @return [Hash] environment variables for headless operation
+      def headless_environment
+        {}
+      end
+    end
+  end
+end

data/lib/ukiryu/shell/bash.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Ukiryu
+  module Shell
+    # Bash shell implementation
+    #
+    # Bash uses single quotes for literal strings and backslash for escaping.
+    # Environment variables are referenced with $VAR syntax.
+    class Bash < Base
+      def name
+        :bash
+      end
+
+      # Escape a string for Bash
+      # Single quotes are literal (no escaping inside), so we end the quote,
+      # add an escaped quote, and restart the quote.
+      #
+      # @param string [String] the string to escape
+      # @return [String] the escaped string
+      def escape(string)
+        string.to_s.gsub("'") { "'\\''" }
+      end
+
+      # Quote an argument for Bash
+      # Uses single quotes for literal strings
+      #
+      # @param string [String] the string to quote
+      # @return [String] the quoted string
+      def quote(string)
+        "'#{escape(string)}'"
+      end
+
+      # Format an environment variable reference
+      #
+      # @param name [String] the variable name
+      # @return [String] the formatted reference ($VAR)
+      def env_var(name)
+        "$#{name}"
+      end
+
+      # Join executable and arguments into a command line
+      #
+      # @param executable [String] the executable path
+      # @param args [Array<String>] the arguments
+      # @return [String] the complete command line
+      def join(executable, *args)
+        [executable, *args.map { |a| quote(a) }].join(" ")
+      end
+
+      # Get headless environment (disable DISPLAY on Unix)
+      #
+      # @return [Hash] environment variables for headless operation
+      def headless_environment
+        { "DISPLAY" => "" }
+      end
+    end
+  end
+end

data/lib/ukiryu/shell/cmd.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Ukiryu
+  module Shell
+    # Windows cmd.exe shell implementation
+    #
+    # cmd.exe uses caret (^) as the escape character and double quotes
+    # for strings containing spaces. Environment variables use %VAR% syntax.
+    class Cmd < Base
+      def name
+        :cmd
+      end
+
+      # Escape a string for cmd.exe
+      # Caret is the escape character for special characters: % ^ < > & |
+      #
+      # @param string [String] the string to escape
+      # @return [String] the escaped string
+      def escape(string)
+        string.to_s.gsub(/[%^<>&|]/) { "^$&" }
+      end
+
+      # Quote an argument for cmd.exe
+      # Uses double quotes for strings with spaces
+      #
+      # @param string [String] the string to quote
+      # @return [String] the quoted string
+      def quote(string)
+        if string.to_s =~ /[ \t]/
+          # Contains whitespace, use double quotes
+          # Note: cmd.exe doesn't escape quotes inside double quotes the same way
+          "\"#{string}\""
+        else
+          # No whitespace, escape special characters
+          escape(string)
+        end
+      end
+
+      # Format a file path for cmd.exe
+      # Convert forward slashes to backslashes
+      #
+      # @param path [String] the file path
+      # @return [String] the formatted path
+      def format_path(path)
+        path.to_s.gsub("/", "\\")
+      end
+
+      # Format an environment variable reference
+      #
+      # @param name [String] the variable name
+      # @return [String] the formatted reference (%VAR%)
+      def env_var(name)
+        "%#{name}%"
+      end
+
+      # Join executable and arguments into a command line
+      #
+      # @param executable [String] the executable path
+      # @param args [Array<String>] the arguments
+      # @return [String] the complete command line
+      def join(executable, *args)
+        [executable, *args.map { |a| quote(a) }].join(" ")
+      end
+
+      # cmd.exe doesn't need DISPLAY variable
+      #
+      # @return [Hash] empty hash (no headless environment needed)
+      def headless_environment
+        {}
+      end
+    end
+  end
+end

data/lib/ukiryu/shell/fish.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "bash"
+
+module Ukiryu
+  module Shell
+    # Fish shell implementation
+    #
+    # Fish uses similar quoting to Bash for most cases.
+    class Fish < Bash
+      def name
+        :fish
+      end
+    end
+  end
+end