ukiryu 0.1.6 → 0.2.0

data/lib/ukiryu/register.rb

@@ -1,109 +1,153 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require 'git'
+require 'fileutils'
+require 'pathname'
 require_relative 'utils'
 require_relative 'models/interface'
 require_relative 'models/implementation_index'
 require_relative 'models/implementation_version'
-require_relative 'register_auto_manager'
 
 module Ukiryu
-  # YAML profile register loader
+  # Represents a collection of tool definitions
   #
-  # Provides access to tool definitions from YAML profiles in a register directory.
-  # Supports lazy loading: metadata can be loaded without full profile parsing.
+  # A Register is a directory containing tool profiles in YAML format.
+  # It handles:
+  # - Discovery (env variable, dev path, user clone)
+  # - Auto-cloning from GitHub
+  # - Loading tool definitions
+  # - Validation
+  #
+  # @example Getting the default register
+  #   register = Ukiryu::Register.default
+  #   register.tool_names  # => ['ghostscript', 'imagemagick', ...]
+  #
+  # @example Using a specific path
+  #   register = Ukiryu::Register.at('/path/to/register')
+  #
+  # @api private - This is an internal class. Developers use Tool.get()
   #
-  # Features:
-  # - Cached version listings to avoid repeated glob operations
-  # - Automatic cache invalidation when register path changes
-  # - Automatic register cloning to ~/.ukiryu/register if not configured
   class Register
+    # GitHub repository URL for the register
+    REMOTE_URL = 'https://github.com/ukiryu/register'
+
+    # Default local directory for user clone
+    DEFAULT_USER_PATH = '~/.ukiryu/register'
+
+    # @return [String] the filesystem path to the register
+    attr_reader :path
+
+    # @return [Symbol] how the register was discovered (:env, :dev, :user, :manual)
+    attr_reader :source
+
+    # Error raised when register operations fail
+    class Error < StandardError; end
+
+    # Error raised when register cannot be found or cloned
+    class NotFoundError < Error; end
+
+    # Error raised when cloning fails
+    class CloneError < Error; end
+
     class << self
-      # Set the default register path
+      # Get the default register instance
+      #
+      # Auto-discovers the register using this priority:
+      # 1. UKIRYU_REGISTER environment variable
+      # 2. Development register (sibling to gem source)
+      # 3. User clone at ~/.ukiryu/register (auto-clones if needed)
       #
-      # @param path [String] the default register path
+      # @return [Register] the default register instance
+      def default
+        @default ||= discover
+      end
 
-      # Get the default register path
+      # Create a register at a specific path
       #
-      # @return [String, nil] the default register path
-      attr_accessor :default_register_path
+      # @param path [String] the filesystem path
+      # @return [Register] a new register instance
+      def at(path)
+        new(File.expand_path(path), source: :manual)
+      end
 
-      # Reset the version cache (mainly for testing)
-      def reset_version_cache
-        @version_cache = nil
-        @register_cache_key = nil
+      # Reset the cached default register (mainly for testing)
+      def reset_default
+        @default = nil
       end
 
-      # Get all available tool names
-      # Only returns tools that have an index.yaml (new architecture)
+      # Check if a default register exists (without auto-cloning)
       #
-      # @return [Array<String>] list of tool names
-      def tools
-        register_path = effective_register_path
-        return [] unless register_path
+      # @return [Boolean] true if a register can be found
+      def exists?
+        path = resolve_path_without_clone
+        path && Dir.exist?(path) && valid_structure?(path)
+      end
 
-        tools_dir = File.join(register_path, 'tools')
-        return [] unless Dir.exist?(tools_dir)
+      # ===== BACKWARD COMPATIBILITY =====
+      # These class methods delegate to the default instance for backward compatibility
 
-        # List all directories that have an index.yaml file
-        Dir.glob(File.join(tools_dir, '*', 'index.yaml')).map do |index_file|
-          File.basename(File.dirname(index_file))
-        end.sort
+      # @deprecated Use Register.default.path instead
+      def default_register_path
+        default.path
       end
 
-      # Get available versions for a tool (cached) - DEPRECATED, kept for compatibility
-      #
-      # @param name [String, Symbol] the tool name
-      # @param register_path [String, nil] the register path
-      # @return [Hash] mapping of version filename to version string
+      # @deprecated Use ENV['UKIRYU_REGISTER'] = path; Register.reset_default instead
+      def default_register_path=(path)
+        ENV['UKIRYU_REGISTER'] = path
+        reset_default
+      end
+
+      # @deprecated Use Register.reset_default instead
+      def reset_version_cache
+        reset_default
+      end
+
+      # @deprecated Use Register.default.tool_names instead
+      def tools
+        default.tool_names
+      end
+
+      # @deprecated Use Register.default.list_versions instead
       def list_versions(name, register_path: nil)
-        register_path ||= effective_register_path
-        return {} unless register_path
-
-        # For new architecture, load the index and get versions
-        index = load_implementation_index(name, register_path: register_path)
-        return {} unless index
-
-        # Extract versions from all implementations
-        # Return a hash mapping version strings to full file paths
-        versions = {}
-        index.implementations.each do |impl|
-          impl_name = impl[:name] || impl['name']
-          impl_versions = impl[:versions] || impl['versions']
-          next unless impl_versions
-
-          impl_versions.each do |version_spec|
-            equals = version_spec[:equals] || version_spec['equals']
-            file = version_spec[:file] || version_spec['file']
-            next unless equals && file
-
-            # Build full path: tools/tool_name/implementation_name/file.yaml
-            full_path = File.join(register_path, 'tools', name.to_s, impl_name.to_s, file)
-            versions[full_path] = equals
-          end
-        end
+        register = register_path ? at(register_path) : default
+        register.list_versions(name)
+      end
 
-        versions
+      # @deprecated Use Register.default.load_tool_yaml instead
+      def load_tool_yaml(name, options = {})
+        register = options[:register_path] ? at(options[:register_path]) : default
+        register.load_tool_yaml(name, version: options[:version])
       end
 
-      # Load tool metadata only (lightweight, without full parsing)
-      # This is much faster than loading the full definition when only metadata is needed
-      #
-      # Supports both exact name lookup and interface-based discovery
-      #
-      # @param name [String, Symbol] the tool name or interface name
-      # @param options [Hash] loading options
-      # @option options [String] :version specific version to load
-      # @option options [String] :register_path path to register
-      # @return [ToolMetadata, nil] the tool metadata or nil if not found
-      def load_tool_metadata(name, options = {})
-        register_path = options[:register_path] || effective_register_path
+      # @deprecated Use Register.default.load_implementation_index instead
+      def load_implementation_index(tool_name, options = {})
+        register = options[:register_path] ? at(options[:register_path]) : default
+        register.load_implementation_index(tool_name)
+      end
+
+      # @deprecated Use Register.default.load_implementation_version instead
+      def load_implementation_version(tool_name, implementation_name, file_path, options = {})
+        register = options[:register_path] ? at(options[:register_path]) : default
+        register.load_implementation_version(tool_name, implementation_name, file_path)
+      end
 
+      # @deprecated Use Register.default.load_interface instead
+      def load_interface(path, options = {})
+        register = options[:register_path] ? at(options[:register_path]) : default
+        register.load_interface(path)
+      end
+
+      # @deprecated Use Register.default methods instead
+      def load_tool_metadata(name, options = {})
         # First try exact name match
-        yaml_content = load_tool_yaml(name, options.merge(register_path: register_path))
+        yaml_content = load_tool_yaml(name, options)
         if yaml_content
           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
+          if hash
+            return ToolMetadata.from_hash(hash, tool_name: name.to_s,
+                                                register_path: options[:register_path] || default.path)
+          end
         end
 
         # If not found, try interface-based discovery using ToolIndex
@@ -113,8 +157,7 @@ module Ukiryu
         result = index.find_by_interface(name.to_sym)
         return result if result
 
-        # Try interface name with common version suffix (e.g., imagemagick/1.0)
-        # This handles tools where the interface is defined with version suffix
+        # Try interface name with common version suffix
         name_str = name.to_s
         [:"#{name_str}/1.0", :"#{name_str}/1", :"v#{name_str}/1.0"].each do |versioned_interface|
           result = index.find_by_interface(versioned_interface)
@@ -124,57 +167,7 @@ module Ukiryu
         nil
       end
 
-      # Load tool YAML file content (for lutaml-model parsing)
-      #
-      # @param name [String, Symbol] the tool name
-      # @param options [Hash] loading options
-      # @option options [String] :version specific version to load
-      # @option options [String] :register_path path to register
-      # @return [String, nil] the YAML content or nil if not found
-      def load_tool_yaml(name, options = {})
-        register_path = options[:register_path] || effective_register_path
-
-        return nil unless register_path
-
-        # Convert to string for path operations
-        name_str = name.to_s
-
-        # Try version-specific directory first
-        version = options[:version]
-        if version
-          file = File.join(register_path, 'tools', name_str, "#{version}.yaml")
-          return File.read(file) if File.exist?(file)
-        end
-
-        # Use cached version list if available
-        versions = list_versions(name_str, register_path: register_path)
-
-        if versions.empty?
-          # Try the old format (single file per tool)
-          file = File.join(register_path, 'tools', "#{name_str}.yaml")
-          return File.read(file) if File.exist?(file)
-
-          return nil
-        end
-
-        # Return specific version if requested
-        if version
-          version_file = versions.keys.find { |f| File.basename(f, '.yaml') == version }
-          return version_file ? File.read(version_file) : nil
-        end
-
-        # Return the latest version (already sorted from scan_tool_versions)
-        File.read(versions.keys.last)
-      end
-
-      # Validate a tool profile against the schema
-      #
-      # @param name [String, Symbol] the tool name
-      # @param options [Hash] validation options
-      # @option options [String] :version specific version to validate
-      # @option options [String] :register_path path to register
-      # @option options [String] :schema_path path to schema file
-      # @return [ValidationResult] the validation result
+      # @deprecated Use Register.default.validate methods instead
       def validate_tool(name, options = {})
         yaml_content = load_tool_yaml(name, options)
         return Models::ValidationResult.not_found(name.to_s) unless yaml_content
@@ -190,145 +183,393 @@ module Ukiryu
         end
       end
 
-      # Validate all tool profiles in the register
-      #
-      # @param options [Hash] validation options
-      # @option options [String] :register_path path to register
-      # @option options [String] :schema_path path to schema file
-      # @return [Array<ValidationResult>] list of validation results
+      # @deprecated Use Register.default.validate methods instead
       def validate_all_tools(options = {})
         tools.map do |tool_name|
           validate_tool(tool_name, options)
         end
       end
 
-      # Load an Interface by path (e.g., "gzip/1.0")
+      private
+
+      # Discover and create the default register
       #
-      # @param path [String] the interface path (e.g., "gzip/1.0")
-      # @param options [Hash] loading options
-      # @option options [String] :register_path path to register
-      # @return [Models::Interface, nil] the interface or nil if not found
-      def load_interface(path, options = {})
-        register_path = options[:register_path] || effective_register_path
-        return nil unless register_path
+      # @return [Register] the discovered register
+      def discover
+        path, source = discover_path
+        raise NotFoundError, 'No register found and auto-clone failed' unless path
+
+        register = new(path, source: source)
+        register.ensure_exists!
+        register
+      end
 
-        file = File.join(register_path, 'interfaces', "#{path}.yaml")
-        return nil unless File.exist?(file)
+      # Discover the register path without auto-cloning
+      #
+      # @return [Array<String, Symbol>, nil] path and source, or nil
+      def discover_path
+        # 1. Check UKIRYU_REGISTER environment variable
+        env_path = ENV['UKIRYU_REGISTER']
+        return [env_path, :env] if env_path && Dir.exist?(env_path)
+
+        # 2. Check development register (sibling to gem source)
+        dev_path = calculate_dev_path
+        return [dev_path.to_s, :dev] if dev_path&.exist?
+
+        # 3. Use user clone (may need to be created)
+        user_path = File.expand_path(DEFAULT_USER_PATH)
+        return [user_path, :user] if Dir.exist?(user_path) && valid_structure?(user_path)
+
+        # 4. Return user path for auto-clone
+        [user_path, :user]
+      end
+
+      # Resolve path without triggering auto-clone
+      #
+      # @return [String, nil] the path or nil
+      def resolve_path_without_clone
+        env_path = ENV['UKIRYU_REGISTER']
+        return env_path if env_path && Dir.exist?(env_path)
+
+        dev_path = calculate_dev_path
+        return dev_path.to_s if dev_path&.exist?
 
-        yaml_content = File.read(file)
-        hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
-        return nil unless hash
+        user_path = File.expand_path(DEFAULT_USER_PATH)
+        return user_path if Dir.exist?(user_path) && valid_structure?(user_path)
 
-        Models::Interface.from_hash(symbolize_keys(hash))
+        nil
       end
 
-      # Load an ImplementationIndex by tool name
+      # Calculate the development register path
       #
-      # @param tool_name [String, Symbol] the tool name
-      # @param options [Hash] loading options
-      # @option options [String] :register_path path to register
-      # @return [Models::ImplementationIndex, nil] the index or nil if not found
-      def load_implementation_index(tool_name, options = {})
-        register_path = options[:register_path] || effective_register_path
+      # @return [Pathname, nil] the dev path or nil
+      def calculate_dev_path
+        this_file = Pathname.new(__FILE__).realpath
+        # lib/ukiryu/register.rb -> ../../../register
+        this_file.parent.parent.parent.join('register')
+      rescue StandardError
+        nil
+      end
 
-        if ENV['UKIRYU_DEBUG_EXECUTABLE']
-          warn "[UKIRYU DEBUG Register.load_implementation_index] tool_name=#{tool_name}"
-          warn "[UKIRYU DEBUG] register_path = #{register_path.inspect}"
-        end
+      # Check if a path has valid register structure
+      #
+      # @param path [String] the path to check
+      # @return [Boolean] true if valid
+      def valid_structure?(path)
+        return false unless path && Dir.exist?(path)
 
-        return nil unless register_path
+        tools_dir = File.join(path, 'tools')
+        return false unless Dir.exist?(tools_dir)
 
-        file = File.join(register_path, 'tools', tool_name.to_s, 'index.yaml')
-        if ENV['UKIRYU_DEBUG_EXECUTABLE']
-          warn "[UKIRYU DEBUG] index file = #{file.inspect}"
-          warn "[UKIRYU DEBUG] File exists? #{File.exist?(file)}"
-        end
-        return nil unless File.exist?(file)
+        # Must have at least one tool definition
+        Dir.glob(File.join(tools_dir, '*', '*.yaml')).any?
+      end
+    end
+
+    # Initialize a new Register
+    #
+    # @param path [String] the filesystem path
+    # @param source [Symbol] how the register was discovered
+    def initialize(path, source: :unknown)
+      @path = path
+      @source = source
+      @version_cache = {}
+    end
 
-        yaml_content = File.read(file)
-        hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
-        return nil unless hash
+    # Check if the register exists on disk
+    #
+    # @return [Boolean] true if the register directory exists
+    def exists?
+      Dir.exist?(path)
+    end
 
-        # Symbolize string keys recursively
-        symbolized_hash = symbolize_keys(hash)
-        Models::ImplementationIndex.from_hash(symbolized_hash)
+    # Check if the register has valid structure
+    #
+    # @return [Boolean] true if valid
+    def valid?
+      self.class.send(:valid_structure?, path)
+    end
+
+    # Ensure the register exists, cloning if necessary
+    #
+    # @raise [CloneError] if cloning fails
+    def ensure_exists!
+      return if exists? && valid?
+
+      clone!
+    end
+
+    # Clone the register from GitHub
+    #
+    # @raise [CloneError] if cloning fails
+    def clone!
+      raise CloneError, "Register already exists at #{path}" if exists? && valid?
+
+      parent_dir = File.dirname(path)
+      FileUtils.mkdir_p(parent_dir) unless Dir.exist?(parent_dir)
+
+      print "Cloning register from #{REMOTE_URL}..." if $stdout.tty?
+
+      begin
+        Git.clone(REMOTE_URL, path, quiet: true)
+      rescue Git::Error => e
+        FileUtils.rm_rf(path) if Dir.exist?(path)
+        raise CloneError, clone_error_message(e)
       end
 
-      # Load an ImplementationVersion by tool, implementation, and file path
-      #
-      # @param tool_name [String, Symbol] the tool name
-      # @param implementation_name [String, Symbol] the implementation name (e.g., "gnu")
-      # @param file_path [String] the file path relative to implementation directory
-      # @param options [Hash] loading options
-      # @option options [String] :register_path path to register
-      # @return [Models::ImplementationVersion, nil] the implementation version or nil if not found
-      def load_implementation_version(tool_name, implementation_name, file_path, options = {})
-        register_path = options[:register_path] || effective_register_path
+      puts 'done' if $stdout.tty?
+
+      raise CloneError, 'Register clone validation failed' unless valid?
+    end
 
-        if ENV['UKIRYU_DEBUG_EXECUTABLE']
-          warn "[UKIRYU DEBUG Register.load_implementation_version] tool=#{tool_name}, impl=#{implementation_name}, file=#{file_path}"
-          warn "[UKIRYU DEBUG] register_path = #{register_path.inspect}"
+    # Update the register (git pull)
+    #
+    # @raise [Error] if update fails
+    def update!
+      return clone! unless exists?
+
+      begin
+        null_dev = RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ ? 'NUL' : '/dev/null'
+        old_redirect = ENV['GIT_REDIRECT_STDERR']
+        ENV['GIT_REDIRECT_STDERR'] = null_dev
+
+        print 'Updating register...' if $stdout.tty?
+        git = Git.open(path)
+        git.pull
+        puts 'done' if $stdout.tty?
+      ensure
+        if old_redirect
+          ENV['GIT_REDIRECT_STDERR'] = old_redirect
+        else
+          ENV.delete('GIT_REDIRECT_STDERR')
         end
+      end
+    rescue Git::Error => e
+      raise Error, "Failed to update register: #{e.message}"
+    end
 
-        return nil unless register_path
+    # Get list of all tool names in this register
+    #
+    # @return [Array<String>] sorted list of tool names
+    def tool_names
+      tools_dir = File.join(path, 'tools')
+      return [] unless Dir.exist?(tools_dir)
 
-        file = File.join(register_path, 'tools', tool_name.to_s, implementation_name.to_s, file_path)
-        if ENV['UKIRYU_DEBUG_EXECUTABLE']
-          warn "[UKIRYU DEBUG] Loading from file: #{file.inspect}"
-          warn "[UKIRYU DEBUG] File exists? #{File.exist?(file)}"
-        end
-        return nil unless File.exist?(file)
+      Dir.glob(File.join(tools_dir, '*', 'index.yaml')).map do |index_file|
+        File.basename(File.dirname(index_file))
+      end.sort
+    end
+
+    # Check if a tool exists in this register
+    #
+    # @param name [String, Symbol] the tool name
+    # @return [Boolean] true if the tool exists
+    def tool?(name)
+      index_file = File.join(path, 'tools', name.to_s, 'index.yaml')
+      File.exist?(index_file)
+    end
+
+    # Load the implementation index for a tool
+    #
+    # @param tool_name [String, Symbol] the tool name
+    # @return [Models::ImplementationIndex, nil] the index or nil
+    def load_implementation_index(tool_name)
+      file = File.join(path, 'tools', tool_name.to_s, 'index.yaml')
+      return nil unless File.exist?(file)
 
-        yaml_content = File.read(file)
-        hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
-        return nil unless hash
+      yaml_content = File.read(file)
+      hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
+      return nil unless hash
+
+      Models::ImplementationIndex.from_hash(symbolize_keys(hash))
+    end
+
+    # Load a specific implementation version
+    #
+    # @param tool_name [String, Symbol] the tool name
+    # @param impl_name [String, Symbol] the implementation name
+    # @param file_path [String] the file path relative to implementation directory
+    # @return [Models::ImplementationVersion, nil] the version or nil
+    def load_implementation_version(tool_name, impl_name, file_path)
+      file = File.join(path, 'tools', tool_name.to_s, impl_name.to_s, file_path)
+      return nil unless File.exist?(file)
+
+      yaml_content = File.read(file)
+      hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
+      return nil unless hash
+
+      Models::ImplementationVersion.from_hash(symbolize_keys(hash))
+    end
 
-        Models::ImplementationVersion.from_hash(symbolize_keys(hash))
+    # Load raw YAML content for a tool
+    #
+    # @param name [String, Symbol] the tool name
+    # @param version [String, nil] specific version (optional)
+    # @return [String, nil] the YAML content or nil
+    def load_tool_yaml(name, version: nil)
+      name_str = name.to_s
+
+      # Try version-specific file first
+      if version
+        file = File.join(path, 'tools', name_str, "#{version}.yaml")
+        return File.read(file) if File.exist?(file)
       end
 
-      private
+      # Get versions from index
+      versions = list_versions(name_str)
+      return load_legacy_tool_yaml(name_str) if versions.empty?
 
-      # Get the effective register path
-      #
-      # Returns the manually set path if available, otherwise uses
-      # RegisterAutoManager to get or create the default path.
-      #
-      # @return [String, nil] the register path, or nil if unavailable
-      def effective_register_path
-        # If manually set, use that
-        return @default_register_path if @default_register_path
-
-        # Otherwise, use RegisterAutoManager (auto-clone if needed)
-        # Use :: to reference top-level Ukiryu namespace
-        auto_path = ::Ukiryu::RegisterAutoManager.register_path
-        warn "[UKIRYU DEBUG] Using RegisterAutoManager path: #{auto_path.inspect}" if ENV['UKIRYU_DEBUG_EXECUTABLE']
-        auto_path
+      # Return specific version or latest
+      if version
+        version_file = versions.keys.find { |f| File.basename(f, '.yaml') == version }
+        return version_file ? File.read(version_file) : nil
       end
 
-      # Recursively symbolize hash keys
-      #
-      # @param hash [Hash] the hash to symbolize
-      # @return [Hash] hash with symbolized keys
-      def symbolize_keys(hash)
-        Utils.symbolize_keys(hash)
+      File.read(versions.keys.last)
+    end
+
+    # Load an interface definition
+    #
+    # @param interface_path [String] the interface path (e.g., "gzip/1.0")
+    # @return [Models::Interface, nil] the interface or nil
+    def load_interface(interface_path)
+      file = File.join(path, 'interfaces', "#{interface_path}.yaml")
+      return nil unless File.exist?(file)
+
+      yaml_content = File.read(file)
+      hash = YAML.safe_load(yaml_content, permitted_classes: [Symbol], aliases: true)
+      return nil unless hash
+
+      Models::Interface.from_hash(symbolize_keys(hash))
+    end
+
+    # List available versions for a tool
+    #
+    # @param tool_name [String, Symbol] the tool name
+    # @return [Hash] mapping of full file path to version string
+    def list_versions(tool_name)
+      index = load_implementation_index(tool_name)
+      return {} unless index
+
+      versions = {}
+      index.implementations.each do |impl|
+        impl_name = impl[:name] || impl['name']
+        impl_versions = impl[:versions] || impl['versions']
+        next unless impl_versions
+
+        impl_versions.each do |version_spec|
+          equals = version_spec[:equals] || version_spec['equals']
+          file = version_spec[:file] || version_spec['file']
+          next unless equals && file
+
+          full_path = File.join(path, 'tools', tool_name.to_s, impl_name.to_s, file)
+          versions[full_path] = equals
+        end
       end
 
-      # Scan tool versions and sort by Gem::Version
-      #
-      # @param name [String] the tool name
-      # @param register_path [String] the register path
-      # @return [Hash] mapping of version filename to Gem::Version
-      def scan_tool_versions(name, register_path)
-        pattern = File.join(register_path, 'tools', name.to_s, '*.yaml')
-        files = Dir.glob(pattern)
-
-        # Sort files by Gem::Version for proper version ordering
-        files.sort_by { |f| Gem::Version.new(File.basename(f, '.yaml')) }
-             .each_with_object({}) { |file, hash| hash[file] = Gem::Version.new(File.basename(file, '.yaml')) }
-      rescue ArgumentError
-        # If version parsing fails, return unsorted files
-        files.each_with_object({}) { |file, hash| hash[file] = File.basename(file, '.yaml') }
+      versions
+    end
+
+    # Get information about this register
+    #
+    # @return [Hash] register information
+    def info
+      {
+        path: path,
+        source: source,
+        exists: exists?,
+        valid: valid?,
+        tools_count: tool_names.count,
+        git_info: git_info
+      }
+    end
+
+    private
+
+    # Load legacy single-file tool YAML
+    #
+    # @param name [String] the tool name
+    # @return [String, nil] the YAML content or nil
+    def load_legacy_tool_yaml(name)
+      file = File.join(path, 'tools', "#{name}.yaml")
+      File.read(file) if File.exist?(file)
+    end
+
+    # Get git information for this register
+    #
+    # @return [Hash, nil] git info or nil
+    def git_info
+      git_dir = File.join(path, '.git')
+      return nil unless Dir.exist?(git_dir)
+
+      null_dev = RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ ? 'NUL' : '/dev/null'
+      old_redirect = ENV['GIT_REDIRECT_STDERR']
+      ENV['GIT_REDIRECT_STDERR'] = null_dev
+
+      git = Git.open(path)
+      log = git.log(1).to_a
+
+      {
+        branch: git.current_branch,
+        commit: log.first&.sha&.[](0..7),
+        last_update: log.first&.date && Time.at(log.first.date.to_i)
+      }
+    rescue Git::Error, IOError, Errno::ENOENT
+      nil
+    ensure
+      if old_redirect
+        ENV['GIT_REDIRECT_STDERR'] = old_redirect
+      else
+        ENV.delete('GIT_REDIRECT_STDERR')
+      end
+    end
+
+    # Generate a helpful error message for clone failures
+    #
+    # @param error [Git::Error] the error
+    # @return [String] the error message
+    def clone_error_message(error)
+      msg = error.message.to_s
+
+      if msg.include?('cannot find') || msg.include?('not found') || msg.include?('path specified')
+        <<~ERROR
+          Failed to clone register: #{msg}
+
+          This error usually means git is not in PATH or the target directory is not accessible.
+
+          To fix this:
+            1. Verify git is installed and in PATH: git --version
+            2. On Windows, ensure Git for Windows is installed from https://git-scm.com
+            3. Or set UKIRYU_REGISTER to use a local register path
+
+          Example (Windows):
+            set UKIRYU_REGISTER=C:\\path\\to\\register
+
+          Example (Unix):
+            export UKIRYU_REGISTER=/path/to/register
+        ERROR
+      else
+        <<~ERROR
+          Failed to clone register from #{REMOTE_URL}: #{msg}
+
+          To fix this:
+            1. Check your internet connection
+            2. Verify git is installed: git --version
+            3. Manually clone: git clone #{REMOTE_URL} #{path}
+            4. Or set UKIRYU_REGISTER to use a local register path
+
+          Example:
+            export UKIRYU_REGISTER=/path/to/register
+        ERROR
       end
     end
+
+    # Recursively symbolize hash keys
+    #
+    # @param hash [Hash] the hash to symbolize
+    # @return [Hash] hash with symbolized keys
+    def symbolize_keys(hash)
+      Utils.symbolize_keys(hash)
+    end
   end
 end