ukiryu 0.1.1 → 0.1.3

data/docs/understanding/index.adoc

@@ -0,0 +1,20 @@
+---
+layout: default
+title: Understanding
+nav_order: 5
+has_children: true
+---
+
+= Understanding
+
+Deep dive into Ukiryu's architecture, design decisions, and internal mechanisms.
+
+// Overview
+== Overview
+
+This section covers the technical internals of Ukiryu:
+
+* link:/understanding/architecture[Architecture] - System design and components
+* link:/understanding/register[Register] - Profile loading and caching
+* link:/understanding/shell-layer[Shell Layer] - Platform and shell adaptation
+* link:/understanding/command-builder[Command Builder] - Argument construction

data/lib/ukiryu/cli.rb

@@ -15,6 +15,10 @@ require_relative 'cli_commands/version_command'
 require_relative 'cli_commands/system_command'
 require_relative 'cli_commands/validate_command'
 require_relative 'cli_commands/extract_command'
+require_relative 'cli_commands/definitions_command'
+require_relative 'cli_commands/cache_command'
+require_relative 'cli_commands/resolve_command'
+require_relative 'cli_commands/register_command'
 require_relative 'thor_ext'
 require_relative 'version'
 
@@ -29,74 +33,77 @@ module Ukiryu
     # Extend FriendlyCLI for better Thor behavior
     extend FriendlyCLI
 
-    # Set default registry path if not configured
+    # Set default register path if not configured
     def self.exit_on_failure?
       false
     end
 
     desc 'run-file REQUEST_FILE', 'Execute a Ukiryu Structured Execution Request from a YAML file'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     method_option :output, aliases: :o, desc: 'Output file for response (default: stdout)', type: :string
     method_option :format, aliases: :f, desc: 'Response format (yaml, json, table, raw)', type: :string, default: 'yaml'
     method_option :dry_run, aliases: :d, desc: 'Show execution request without executing', type: :boolean,
                             default: false
-    method_option :shell, desc: 'Shell to use for command execution (bash, zsh, fish, sh, powershell, cmd)', type: :string
+    method_option :shell, desc: 'Shell to use for command execution (bash, zsh, fish, sh, powershell, cmd)',
+                          type: :string
     def run_file(request_file)
       CliCommands::RunFileCommand.new(options).run(request_file)
     end
 
     desc 'exec TOOL [COMMAND] [KEY=VALUE ...]', 'Execute a tool command inline'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
+    method_option :definition, aliases: :d, desc: 'Path to tool definition file', type: :string
     method_option :format, aliases: :f, desc: 'Response format (yaml, json, table, raw)', type: :string, default: 'yaml'
     method_option :output, aliases: :o, desc: 'Output file for response (default: stdout)', type: :string
-    method_option :dry_run, aliases: :d, desc: 'Show execution request without executing', type: :boolean,
+    method_option :dry_run, aliases: :D, desc: 'Show execution request without executing', type: :boolean,
                             default: false
-    method_option :shell, desc: 'Shell to use for command execution (bash, zsh, fish, sh, powershell, cmd)', type: :string
+    method_option :shell, aliases: :s,
+                          desc: 'Shell to use for command execution (bash, zsh, fish, sh, powershell, cmd)', type: :string
     method_option :stdin, desc: 'Read input from stdin (pass to command)', type: :boolean, default: false
     method_option :raw, desc: 'Output raw stdout/stderr (for pipe composition)', type: :boolean, default: false
     def exec(tool_name, command_name = nil, *params)
       CliCommands::RunCommand.new(options).run(tool_name, command_name, *params)
     end
 
-    desc 'list', 'List all available tools in the registry'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    desc 'list', 'List all available tools in the register'
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     def list
       CliCommands::ListCommand.new(options).run
     end
 
-    desc 'info [TOOL]', 'Show detailed information about a tool (or general info if no tool specified)'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    desc 'info [TOOL]', 'Show detailed information about a tool'
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     method_option :all, desc: 'Show all implementations for interfaces', type: :boolean, default: false
     def info(tool_name = nil)
       if tool_name.nil?
-        # Show general info when no tool specified
-        show_general_info
+        # No tool specified - show help
+        help
       else
         CliCommands::InfoCommand.new(options).run(tool_name)
       end
     end
 
     desc 'commands TOOL', 'List all commands available for a tool'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     def commands(tool_name)
       CliCommands::CommandsCommand.new(options).run(tool_name)
     end
 
     desc 'opts TOOL [COMMAND]', 'Show options for a tool or specific command'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     def opts(tool_name, command_name = nil)
       CliCommands::OptsCommand.new(options).run(tool_name, command_name)
     end
 
     desc 'describe TOOL [COMMAND]', 'Show comprehensive documentation for a tool or specific command'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     method_option :format, aliases: :f, desc: 'Output format (text, yaml, json)', type: :string, default: 'text'
     def describe(tool_name, command_name = nil)
       CliCommands::DescribeCommand.new(options).run(tool_name, command_name)
     end
 
     desc 'system [SUBCOMMAND]', 'Show system information (shells, etc.)'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     def system(subcommand = nil)
       CliCommands::SystemCommand.new(options).run(subcommand)
     end
@@ -107,7 +114,7 @@ module Ukiryu
     end
 
     desc 'which IDENTIFIER', 'Show which tool implementation would be selected'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     method_option :platform, desc: 'Platform to check (macos, linux, windows)', type: :string
     method_option :shell, desc: 'Shell to check (bash, zsh, fish, sh, powershell, cmd)', type: :string
     def which(identifier)
@@ -115,16 +122,13 @@ module Ukiryu
     end
 
     desc 'config [ACTION] [KEY] [VALUE]', 'Manage configuration (list, get, set, unset)'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
+    method_option :register, aliases: :r, desc: 'Path to tool register', type: :string
     def config(action = 'list', key = nil, value = nil)
       CliCommands::ConfigCommand.new(options).run(action, key, value)
     end
 
-    desc 'validate [TOOL]', 'Validate tool profile(s) against schema'
-    method_option :registry, aliases: :r, desc: 'Path to tool registry', type: :string
-    def validate(tool_name = nil)
-      CliCommands::ValidateCommand.new(options).run(tool_name)
-    end
+    desc 'validate [COMMAND]', 'Validate tool definitions'
+    subcommand 'validate', CliCommands::ValidateCommand
 
     desc 'extract TOOL', 'Extract tool definition from an installed CLI tool'
     method_option :output, aliases: :o, desc: 'Output file for extracted definition', type: :string
@@ -134,41 +138,22 @@ module Ukiryu
       CliCommands::ExtractCommand.new(options).run(tool_name)
     end
 
-    private
-
-    # Show general information when no specific tool is requested
-    def show_general_info
-      require_relative 'shell'
-      require_relative 'runtime'
-      require_relative 'platform'
-
-      puts "Ukiryu v#{VERSION}"
-      puts ''
-      puts 'System Information:'
-      puts "  Platform: #{Platform.detect}"
-      puts "  Shell: #{Runtime.instance.shell}"
-      puts "  Ruby: #{RUBY_VERSION}"
-      puts ''
-      puts 'Available Shells:'
-      Shell.available_shells.each do |shell|
-        puts "  - #{shell}"
-      end
-      puts ''
-      puts 'Available Commands:'
-      puts '  list                    - List all available tools'
-      puts '  info TOOL               - Show detailed information about a tool'
-      puts '  which IDENTIFIER        - Show which tool implementation would be selected'
-      puts '  commands TOOL           - List all commands available for a tool'
-      puts '  opts TOOL [COMMAND]     - Show options for a tool or specific command'
-      puts '  describe TOOL [COMMAND] - Show comprehensive documentation'
-      puts '  config [ACTION]         - Manage configuration (list, get, set, unset)'
-      puts '  system [shells]         - Show system information (shells, etc.)'
-      puts '  exec ...                - Execute a tool command inline'
-      puts '  run-file ...            - Execute from a YAML file'
-      puts '  version                 - Show Ukiryu version'
-      puts ''
-      puts 'For more information on a specific command:'
-      puts '  ukiryu help COMMAND'
+    desc 'definitions [COMMAND]', 'Manage tool definitions'
+    subcommand 'definitions', CliCommands::DefinitionsCommand
+
+    desc 'cache [ACTION]', 'Manage definition cache'
+    subcommand 'cache', CliCommands::CacheCommand
+
+    desc 'resolve TOOL [VERSION]', 'Resolve which definition would be used for a tool'
+    def resolve(tool_name, version_constraint = nil)
+      CliCommands::ResolveCommand.new(options).run(tool_name, version_constraint)
+    end
+
+    desc 'register [SUBCOMMAND]', 'Manage the tool register'
+    method_option :force, aliases: :f, desc: 'Force re-clone the register', type: :boolean, default: false
+    method_option :verbose, aliases: :v, desc: 'Show verbose output', type: :boolean, default: false
+    def register(subcommand = nil)
+      CliCommands::RegisterCommand.new(options).run(subcommand, options)
     end
   end
 end

data/lib/ukiryu/cli_commands/base_command.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require_relative '../config'
+require_relative '../register'
 
 module Ukiryu
   module CliCommands
     # Base class for CLI commands
     #
     # Provides shared functionality for all CLI commands including
-    # registry setup, output formatting, and error handling.
+    # register setup, output formatting, and error handling.
     #
     # @abstract Subclasses must implement the `run` method
     class BaseCommand
@@ -31,14 +32,14 @@ module Ukiryu
         raise NotImplementedError, "#{self.class} must implement #run"
       end
 
-      # Setup the registry path
+      # Setup the register path
       #
-      # @param custom_path [String, nil] custom registry path
-      def setup_registry(custom_path = nil)
-        registry_path = custom_path || config.registry || default_registry_path
-        return unless registry_path && Dir.exist?(registry_path)
+      # @param custom_path [String, nil] custom register path
+      def setup_register(custom_path = nil)
+        register_path = custom_path || config.register || default_register_path
+        return unless register_path && Dir.exist?(register_path)
 
-        Registry.default_registry_path = registry_path
+        Register.default_register_path = register_path
       end
 
       # Apply CLI options to the Config instance
@@ -49,7 +50,7 @@ module Ukiryu
         cli_mappings = {
           format: 'yaml', # default format in Thor
           output: nil,
-          registry: nil,
+          register: nil,
           timeout: nil,
           shell: nil
         }
@@ -80,26 +81,14 @@ module Ukiryu
         config.set_cli_option(:dry_run, options[:dry_run])
       end
 
-      # Get the default registry path
+      # Get the default register path
       #
-      # @return [String, nil] the default registry path
-      def default_registry_path
-        # Try multiple approaches to find the registry
-        # Note: ENV and Config.registry are already checked by setup_registry
-
-        # 1. Try relative to gem location
-        gem_root = File.dirname(File.dirname(File.dirname(__FILE__)))
-        registry_path = File.join(gem_root, '..', 'register')
-        return File.expand_path(registry_path) if Dir.exist?(registry_path)
-
-        # 2. Try from current directory (development setup)
-        current = File.expand_path('../register', Dir.pwd)
-        return current if Dir.exist?(current)
-
-        # 3. Try from parent directory
-        parent = File.expand_path('../../register', Dir.pwd)
-        return parent if Dir.exist?(parent)
-
+      # @return [String, nil] the default register path from RegisterAutoManager
+      def default_register_path
+        # Use RegisterAutoManager to find or create the register
+        require_relative '../register_auto_manager'
+        RegisterAutoManager.register_path
+      rescue StandardError
         nil
       end
 

data/lib/ukiryu/cli_commands/cache_command.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative '../definition/definition_cache'
+
+module Ukiryu
+  module CliCommands
+    # Manage definition cache
+    #
+    # The cache command allows users to view and manage the definition cache.
+    class CacheCommand < Thor
+      class_option :verbose, type: :boolean, default: false
+      class_option :dry_run, type: :boolean, default: false
+
+      desc 'info', 'Show cache information'
+      def info
+        show_cache_info
+      end
+
+      desc 'stats', 'Show detailed cache statistics'
+      def stats
+        show_cache_stats
+      end
+
+      desc 'clear', 'Clear all cached definitions'
+      def clear
+        clear_cache
+      end
+
+      private
+
+      # Show cache information
+      def show_cache_info
+        cache = Ukiryu::Definition::DefinitionCache.instance
+        stats = cache.stats
+
+        say 'Definition Cache:', :cyan
+        say '', :clear
+
+        say "Status: #{stats[:size].positive? ? 'Active' : 'Empty'}", stats[:size].positive? ? :green : :dim
+        say "Entries: #{stats[:size]}", :white
+        say "TTL: #{stats[:ttl]} seconds", :white
+        say "Refresh Strategy: #{stats[:refresh_strategy]}", :white
+
+        return unless stats[:entries] && !stats[:entries].empty?
+
+        say '', :clear
+        say 'Cached Definitions:', :white
+        stats[:entries].each do |key|
+          say "  - #{key}", :dim
+        end
+      end
+
+      # Clear the cache
+      def clear_cache
+        cache = Ukiryu::Definition::DefinitionCache.instance
+
+        if options[:dry_run]
+          say 'Dry run: Would clear cache', :cyan
+          count = cache.stats[:size]
+          say "Entries to be cleared: #{count}", :white
+          return
+        end
+
+        count = cache.clear
+
+        say "✓ Cache cleared (#{count} entries)", :green
+      end
+
+      # Show cache statistics
+      def show_cache_stats
+        cache = Ukiryu::Definition::DefinitionCache.instance
+        stats = cache.stats
+
+        say 'Cache Statistics:', :cyan
+        say '', :clear
+
+        say "Total Entries: #{stats[:size]}", :white
+        say "TTL: #{stats[:ttl]} seconds (#{(stats[:ttl] / 60).round(1)} minutes)", :white
+        say "Refresh Strategy: #{stats[:refresh_strategy]}", :white
+        say '', :clear
+
+        return unless stats[:entries] && !stats[:entries].empty?
+
+        say 'Cached Keys:', :white
+        stats[:entries].each do |key|
+          entry = cache.get(key)
+          if entry
+            age = Time.now - entry.loaded_at
+            stale = entry.stale? ? ' (stale)' : ''
+            say "  - #{key}#{stale}", :white
+            say "    Age: #{age.round}s", :dim
+          else
+            say "  - #{key} (empty)", :dim
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ukiryu/cli_commands/commands_command.rb

@@ -11,11 +11,11 @@ module Ukiryu
       #
       # @param tool_name [String] the tool name
       def run(tool_name)
-        setup_registry
+        setup_register
 
         # Use find_by for interface-based discovery (ping -> ping_bsd/ping_gnu)
         tool = Tool.find_by(tool_name.to_sym)
-        error!("Tool not found: #{tool_name}\nAvailable tools: #{Registry.tools.sort.join(', ')}") unless tool
+        error!("Tool not found: #{tool_name}\nAvailable tools: #{Register.tools.sort.join(', ')}") unless tool
 
         tool_commands = tool.commands
         error! "No commands defined for #{tool_name}" unless tool_commands
@@ -73,9 +73,9 @@ module Ukiryu
         end
 
         # Show cli_flag if this is a flag-based action
-        if cmd.flag_action?
-          say "    Action flag: #{cmd.cli_flag}", :dim
-        end
+        return unless cmd.flag_action?
+
+        say "    Action flag: #{cmd.cli_flag}", :dim
       end
 
       # Display hierarchical commands with routing information
@@ -86,8 +86,8 @@ module Ukiryu
       def display_hierarchical_commands(tool, grouped)
         # Show routing table first
         if tool.routing?
-          say "  Routing table:", :dim
-          tool.routing.keys.each do |key|
+          say '  Routing table:', :dim
+          tool.routing.each_key do |key|
             target = tool.routing.resolve(key)
             say "    #{key} => #{target}", :dim
           end
@@ -96,7 +96,7 @@ module Ukiryu
 
         # Show top-level commands (no belongs_to)
         if grouped.key?(nil) && !grouped[nil].empty?
-          say "  Top-level commands:", :cyan
+          say '  Top-level commands:', :cyan
           grouped[nil].each do |cmd|
             display_command(cmd)
           end

data/lib/ukiryu/cli_commands/commands_command.rb.fixed

@@ -11,7 +11,7 @@ module Ukiryu
         #
         # @param tool_name [String] the tool name
       def run(tool_name)
-          setup_registry
+          setup_register
 
           tool = Tool.get(tool_name)
           tool_commands = tool.commands

data/lib/ukiryu/cli_commands/config_command.rb

@@ -2,6 +2,7 @@
 
 require_relative 'base_command'
 require_relative '../config'
+require_relative '../register_auto_manager'
 require 'yaml'
 require 'fileutils'
 
@@ -18,7 +19,7 @@ module Ukiryu
       # @param key [String, nil] the config key
       # @param value [String, nil] the config value
       def run(action = 'list', key = nil, value = nil)
-        setup_registry
+        setup_register
 
         case action
         when 'list'
@@ -41,8 +42,11 @@ module Ukiryu
         say 'Current configuration:', :cyan
         say '', :clear
 
+        # Get actual register info for better display
+        register_display = format_register_display
+
         config_data = {
-          'Registry' => config.registry || '(not set)',
+          'Register' => register_display,
           'Timeout' => format_config_value(config.timeout, '(no timeout)'),
           'Debug' => format_config_value(config.debug),
           'Dry run' => format_config_value(config.dry_run),
@@ -51,7 +55,7 @@ module Ukiryu
           'Format' => format_config_value(config.format),
           'Output' => format_config_value(config.output, '(stdout)'),
           'Search paths' => format_config_value(config.search_paths, '(not set)'),
-          'Use color' => format_config_value(config.use_color, '(auto-detect)')
+          'Use color' => format_config_value(config.use_color)
         }
 
         config_data.each do |k, v|
@@ -82,7 +86,7 @@ module Ukiryu
         say '', :clear
         say 'Environment variables:', :cyan
         env_vars = {
-          'UKIRYU_REGISTRY' => ENV['UKIRYU_REGISTRY'],
+          'UKIRYU_REGISTER' => ENV['UKIRYU_REGISTER'],
           'UKIRYU_TIMEOUT' => ENV['UKIRYU_TIMEOUT'],
           'UKIRYU_DEBUG' => ENV['UKIRYU_DEBUG'],
           'UKIRYU_DRY_RUN' => ENV['UKIRYU_DRY_RUN'],
@@ -111,7 +115,7 @@ module Ukiryu
         normalized_key = normalize_key(key)
 
         value = case normalized_key
-                when :registry then config.registry
+                when :register then config.register
                 when :timeout then config.timeout
                 when :debug then config.debug
                 when :dry_run then config.dry_run
@@ -122,7 +126,7 @@ module Ukiryu
                 when :search_paths then config.search_paths
                 when :use_color then config.use_color
                 else
-                  error! "Unknown config key: #{key}\nValid keys: registry, timeout, debug, dry_run, metrics, shell, format, output, search_paths, use_color"
+                  error! "Unknown config key: #{key}\nValid keys: register, timeout, debug, dry_run, metrics, shell, format, output, search_paths, use_color"
                 end
 
         say "#{key}: #{format_config_value(value, '(not set)')}", :white
@@ -206,7 +210,7 @@ module Ukiryu
         when :shell then config.shell = value
         when :format then config.format = value
         when :output then config.output = value
-        when :registry then config.registry = value
+        when :register then config.register = value
         when :search_paths then config.search_paths = value
         when :use_color then config.use_color = value
         end
@@ -221,6 +225,44 @@ module Ukiryu
         value.nil? ? default : value
       end
 
+      # Format register display showing actual register being used
+      #
+      # @return [String] formatted register display
+      def format_register_display
+        info = RegisterAutoManager.register_info
+
+        case info[:status]
+        when :ok
+          # Register exists and is valid
+          source_label = format_source_label(info[:source])
+          tools_count = info[:tools_count] ? " (#{info[:tools_count]} tools)" : ''
+          "#{info[:path]} [#{source_label}]#{tools_count}"
+        when :not_cloned, :not_found
+          # Register not cloned yet
+          '~/.ukiryu/register (not found - run: ukiryu register update)'
+        when :invalid
+          # Register exists but is invalid
+          "#{info[:path]} (invalid - run: ukiryu register update --force)"
+        else
+          '(unknown)'
+        end
+      end
+
+      # Format source label for display
+      #
+      # @param source [Symbol] the source symbol
+      # @return [String] formatted source label
+      def format_source_label(source)
+        case source
+        when :env
+          'env'
+        when :user
+          'user'
+        else
+          source.to_s
+        end
+      end
+
       # Ensure config directory exists
       def ensure_config_dir
         FileUtils.mkdir_p(CONFIG_DIR) unless Dir.exist?(CONFIG_DIR)