ukiryu 0.1.7 → 0.2.0

data/lib/ukiryu/shell/powershell.rb

@@ -2,6 +2,7 @@
 
 require 'open3'
 require 'timeout'
+require 'tempfile'
 
 module Ukiryu
   module Shell
@@ -42,11 +43,25 @@ module Ukiryu
       end
 
       # Escape a string for PowerShell
-      # Backtick is the escape character for: ` $ "
+      # - Single quotes are escaped by doubling them (for single-quoted strings)
+      # - Backtick, dollar, and double quotes are escaped with backtick (for double-quoted strings)
+      #
+      # Note: This method escapes for single-quoted strings by default since we use
+      # single quotes for arguments to prevent parameter binding issues.
       #
       # @param string [String] the string to escape
       # @return [String] the escaped string
       def escape(string)
+        # For single-quoted strings, escape single quotes by doubling them
+        string.to_s.gsub("'", "''")
+      end
+
+      # Escape a string for double-quoted PowerShell strings
+      # Used for executable paths which need double quotes
+      #
+      # @param string [String] the string to escape
+      # @return [String] the escaped string
+      def escape_for_double_quotes(string)
         string.to_s.gsub(/[`"$]/) { "`#{::Regexp.last_match(0)}" }
       end
 
@@ -58,6 +73,8 @@ module Ukiryu
       # to be stripped (e.g., -sDEVICE=pdfwrite becomes =pdfwrite).
       # To prevent this, we must quote all arguments starting with -.
       #
+      # Also, arguments containing $ must be quoted to prevent variable expansion.
+      #
       # @param string [String] the string to check
       # @return [Boolean] true if quoting is needed
       def needs_quoting?(string)
@@ -67,26 +84,25 @@ module Ukiryu
         # PowerShell-specific: arguments starting with - must be quoted
         # to prevent PowerShell's parameter binder from stripping the prefix
         return true if str.start_with?('-')
+        # PowerShell-specific: arguments containing $ must be quoted
+        # to prevent variable expansion
+        return true if str.include?('$')
 
         false
       end
 
       # Quote an argument for PowerShell
-      # Uses single quotes for literal strings
-      # Uses double quotes for executable paths (works in both cmd.exe and PowerShell)
+      # Uses double quotes for all arguments to prevent PowerShell's parameter
+      # binder from stripping dash prefixes. Double quotes work consistently
+      # across both the call operator (&) and Start-Process.
       #
       # @param string [String] the string to quote
-      # @param for_exe [Boolean] true if quoting for executable path
+      # @param for_exe [Boolean] true if quoting for executable path (same behavior)
       # @return [String] the quoted string
       def quote(string, for_exe: false)
-        if for_exe
-          # For executable paths, use double quotes which work in both cmd.exe and PowerShell
-          # This is needed because Ruby's Open3 uses cmd.exe on Windows, not PowerShell
-          "\"#{string}\""
-        else
-          # For arguments, use single quotes for literal strings
-          "'#{escape(string)}'"
-        end
+        # Always use double quotes - this prevents PowerShell's parameter binder
+        # from stripping dash prefixes in all contexts (call operator, Start-Process)
+        "\"#{escape_for_double_quotes(string)}\""
       end
 
       # Format an environment variable reference
@@ -97,6 +113,18 @@ module Ukiryu
         "$ENV:#{name}"
       end
 
+      # Format a file path for PowerShell on Windows
+      #
+      # Returns the path unchanged. Quoting for paths with spaces is handled
+      # by the quote method, which wraps paths in double quotes with proper
+      # escaping.
+      #
+      # @param path [String] the file path
+      # @return [String] the formatted path
+      def format_path(path)
+        path.to_s
+      end
+
       # Join executable and arguments into a command line
       # Uses smart quoting: only quote arguments that need it
       #
@@ -107,12 +135,20 @@ module Ukiryu
       # @param args [Array<String>] the arguments
       # @return [String] the complete command line
       def join(executable, *args)
-        # Debug logging for Ruby 4.0 CI
+        # Debug logging for CI - helps identify where prefix stripping might occur
         if ENV['UKIRYU_DEBUG_EXECUTABLE']
           warn "[UKIRYU DEBUG PowerShell#join] executable: #{executable.inspect}"
           warn "[UKIRYU DEBUG PowerShell#join] args: #{args.inspect}"
           warn "[UKIRYU DEBUG PowerShell#join] args.size: #{args.size}"
           warn "[UKIRYU DEBUG PowerShell#join] args.class: #{args.class}"
+          args.each_with_index do |a, i|
+            warn "[UKIRYU DEBUG PowerShell#join] args[#{i}]: #{a.inspect} (#{a.class})"
+            # Check for nested arrays which would cause stringification issues
+            if a.is_a?(Array)
+              warn "[UKIRYU DEBUG PowerShell#join] WARNING: args[#{i}] is a NESTED ARRAY!"
+              warn "[UKIRYU DEBUG PowerShell#join] This will be converted to string: #{a.to_s.inspect}"
+            end
+          end
         end
 
         # Quote executable if it needs quoting (e.g., contains spaces)
@@ -161,9 +197,12 @@ module Ukiryu
 
       # Execute a command using PowerShell
       #
-      # Uses PowerShell's -Command flag to execute the command string.
-      # The executable and arguments are quoted individually and passed to
-      # PowerShell's call operator &.
+      # On Windows: Uses cmd /c to execute commands. This provides more predictable
+      # quoting behavior than PowerShell's Start-Process for native executables
+      # with arguments containing spaces.
+      #
+      # On Unix: Uses the call operator (&) since PowerShell on Unix doesn't have
+      # the parameter binding issues that Windows PowerShell has.
       #
       # @param executable [String] the executable path
       # @param args [Array<String>] command arguments
@@ -173,33 +212,72 @@ module Ukiryu
       # @return [Hash] execution result with :status, :stdout, :stderr keys
       # @raise [Timeout::Error] if command times out
       def execute_command(executable, args, env, timeout, cwd = nil)
-        # Build the command with proper quoting for each element
-        # Use double quotes for PowerShell -Command (works better than single quotes)
-        exe_quoted = %("#{escape(executable)}")
-
-        # Quote each argument based on needs_quoting?
-        # Note: We do NOT add special handling for -Command/-File here because
-        # this method builds a PowerShell script string (using the & call operator),
-        # not a command line for the shell. The -Command/-File handling in join()
-        # is for when building command lines where PowerShell's parameter binder
-        # would interpret -prefixed arguments.
-        args_quoted = args.map do |a|
-          if needs_quoting?(a)
-            %("#{escape(a)}")
-          else
-            a
+        # Debug logging for CI - helps identify where prefix stripping might occur
+        if ENV['UKIRYU_DEBUG_EXECUTABLE']
+          warn "[UKIRYU DEBUG PowerShell#execute_command] executable: #{executable.inspect}"
+          warn "[UKIRYU DEBUG PowerShell#execute_command] args: #{args.inspect}"
+          warn "[UKIRYU DEBUG PowerShell#execute_command] args.class: #{args.class}"
+          args.each_with_index do |a, i|
+            warn "[UKIRYU DEBUG PowerShell#execute_command] args[#{i}]: #{a.inspect} (#{a.class})"
+            # Check for nested arrays which would cause stringification issues
+            warn "[UKIRYU DEBUG PowerShell#execute_command] WARNING: args[#{i}] is a NESTED ARRAY!" if a.is_a?(Array)
+          end
+        end
+
+        # Build the command line with proper quoting
+        if Platform.windows?
+          # On Windows: Use PowerShell call operator with single quotes for all arguments
+          # Single quotes are completely literal in PowerShell - no parameter binding issues
+          # This works for both paths with spaces and without spaces
+          exe_normalized = executable.to_s.gsub('/', '\\')
+          exe_escaped = exe_normalized.gsub("'", "''")
+
+          args_escaped = args.map do |a|
+            arg_str = a.to_s.gsub('/', '\\')
+            if arg_str.start_with?('-')
+              # Arguments starting with - must be single-quoted to prevent PowerShell's
+              # parameter binder from stripping the prefix (e.g., -sDEVICE=pdfwrite -> =pdfwrite)
+              escaped = arg_str.gsub("'", "''")
+              "'#{escaped}'"
+            elsif arg_str.include?('$') || arg_str.include?('`')
+              # Use single quotes for arguments with $ or ` to prevent expansion
+              escaped = arg_str.gsub("'", "''")
+              "'#{escaped}'"
+            elsif arg_str.include?(' ') || arg_str.include?('"')
+              # Use single quotes for spaces or quotes (completely literal)
+              escaped = arg_str.gsub("'", "''")
+              "'#{escaped}'"
+            else
+              arg_str
+            end
+          end
+
+          # Propagate exit code from external command using $LASTEXITCODE
+        else
+          # On Unix: Use the call operator directly with single quotes
+          # Single quotes are completely literal in PowerShell (no variable expansion)
+          exe_escaped = executable.to_s.gsub("'", "''")
+
+          args_escaped = args.map do |a|
+            arg_str = a.to_s
+            # Quote arguments that contain special PowerShell characters or
+            # start with dash (to prevent parameter binding)
+            if arg_str.include?(' ') || arg_str.start_with?('-') || arg_str.include?('$') || arg_str.include?('`') || arg_str.include?(';')
+              # Use single quotes for completely literal strings
+              escaped = arg_str.gsub("'", "''")
+              "'#{escaped}'"
+            else
+              arg_str
+            end
           end
+
+          # Propagate exit code from external command using $LASTEXITCODE
         end
+        full_command = ["'#{exe_escaped}'", *args_escaped].join(' ')
+        warn "[UKIRYU DEBUG PowerShell#execute_command] full_command: #{full_command.inspect}" if ENV['UKIRYU_DEBUG_EXECUTABLE']
+        ps_command = "& #{full_command}; exit $LASTEXITCODE"
 
-        # Build PowerShell command: & "executable" "arg1" "arg2" ...
-        # Append "; exit $LASTEXITCODE" to properly propagate exit codes from
-        # the invoked command/program back through the PowerShell wrapper
-        ps_command_base = if args_quoted.empty?
-                            "& #{exe_quoted}"
-                          else
-                            "& #{exe_quoted} #{args_quoted.join(' ')}"
-                          end
-        ps_command = "#{ps_command_base}; exit $LASTEXITCODE"
+        warn "[UKIRYU DEBUG PowerShell#execute_command] ps_command:\n#{ps_command}" if ENV['UKIRYU_DEBUG_EXECUTABLE']
 
         # Convert Environment to Hash ONLY at Open3 call site
         env_hash = environment_to_h(env)
@@ -228,9 +306,7 @@ module Ukiryu
 
       # Execute a command with stdin input using PowerShell
       #
-      # Uses PowerShell's -Command flag to execute the command string.
-      # The executable and arguments are quoted individually and passed to
-      # PowerShell's call operator &.
+      # Uses platform-specific execution with stdin redirection.
       #
       # @param executable [String] the executable path
       # @param args [Array<String>] command arguments
@@ -241,78 +317,91 @@ module Ukiryu
       # @return [Hash] execution result with :status, :stdout, :stderr keys
       # @raise [Timeout::Error] if command times out
       def execute_command_with_stdin(executable, args, env, timeout, cwd, stdin_data)
-        # Build the command with proper quoting for each element
-        # Use double quotes for PowerShell -Command (works better than single quotes)
-        exe_quoted = %("#{escape(executable)}")
-
-        # Quote each argument based on needs_quoting?
-        # Note: We do NOT add special handling for -Command/-File here because
-        # this method builds a PowerShell script string (using the & call operator),
-        # not a command line for the shell. The -Command/-File handling in join()
-        # is for when building command lines where PowerShell's parameter binder
-        # would interpret -prefixed arguments.
-        args_quoted = args.map do |a|
-          if needs_quoting?(a)
-            %("#{escape(a)}")
-          else
-            a
+        # Write stdin to temp file for redirection
+        stdin_file = Tempfile.new('ukiryu_stdin')
+        begin
+          if stdin_data.is_a?(IO)
+            IO.copy_stream(stdin_data, stdin_file)
+          elsif stdin_data.is_a?(String)
+            stdin_file.write(stdin_data)
           end
-        end
+          stdin_file.close
 
-        # Build PowerShell command: & "executable" "arg1" "arg2" ...
-        # Append "; exit $LASTEXITCODE" to properly propagate exit codes from
-        # the invoked command/program back through the PowerShell wrapper
-        ps_command_base = if args_quoted.empty?
-                            "& #{exe_quoted}"
-                          else
-                            "& #{exe_quoted} #{args_quoted.join(' ')}"
-                          end
-        ps_command = "#{ps_command_base}; exit $LASTEXITCODE"
+          stdin_path = stdin_file.path
 
-        # Convert Environment to Hash ONLY at Open3 call site
-        env_hash = environment_to_h(env)
+          if Platform.windows?
+            # On Windows: Use PowerShell call operator with single quotes for all arguments
+            # Single quotes are completely literal in PowerShell - no parameter binding issues
+            # This works for both paths with spaces and without spaces
+            exe_normalized = executable.to_s.gsub('/', '\\')
+            exe_escaped = exe_normalized.gsub("'", "''")
 
-        # Execute using PowerShell's -Command flag
-        Timeout.timeout(timeout) do
-          execution = lambda do
-            Open3.popen3(env_hash, powershell_command, '-NoLogo', '-Command',
-                         ps_command) do |stdin, stdout, stderr, wait_thr|
-              # Write stdin data
-              begin
-                if stdin_data.is_a?(IO)
-                  IO.copy_stream(stdin_data, stdin)
-                elsif stdin_data.is_a?(String)
-                  stdin.write(stdin_data)
-                end
-              rescue Errno::EPIPE
-                # Process closed stdin early
-              ensure
-                stdin.close
+            args_escaped = args.map do |a|
+              arg_str = a.to_s.gsub('/', '\\')
+              if arg_str.start_with?('-')
+                # Arguments starting with - must be single-quoted to prevent PowerShell's
+                # parameter binder from stripping the prefix (e.g., -sDEVICE=pdfwrite -> =pdfwrite)
+                escaped = arg_str.gsub("'", "''")
+                "'#{escaped}'"
+              elsif arg_str.include?('$') || arg_str.include?('`')
+                # Use single quotes for arguments with $ or ` to prevent expansion
+                escaped = arg_str.gsub("'", "''")
+                "'#{escaped}'"
+              elsif arg_str.include?(' ') || arg_str.include?('"')
+                # Use single quotes for spaces or quotes (completely literal)
+                escaped = arg_str.gsub("'", "''")
+                "'#{escaped}'"
+              else
+                arg_str
+              end
+            end
+
+            # Propagate exit code from external command using $LASTEXITCODE
+          else
+            # On Unix: Use the call operator with stdin redirection
+            # Single quotes are completely literal in PowerShell (no variable expansion)
+            exe_escaped = executable.to_s.gsub("'", "''")
+
+            args_escaped = args.map do |a|
+              arg_str = a.to_s
+              # Quote arguments that contain special PowerShell characters or
+              # start with dash (to prevent parameter binding)
+              if arg_str.include?(' ') || arg_str.start_with?('-') || arg_str.include?('$') || arg_str.include?('`') || arg_str.include?(';')
+                escaped = arg_str.gsub("'", "''")
+                "'#{escaped}'"
+              else
+                arg_str
               end
+            end
 
-              # Read output
-              out = stdout.read
-              err = stderr.read
+            # Use Get-Content to read stdin file and pipe to command
+            # Propagate exit code from external command using $LASTEXITCODE
+          end
+          full_command = ["'#{exe_escaped}'", *args_escaped].join(' ')
+          ps_command = "Get-Content '#{stdin_path.gsub("'", "''")}' | & #{full_command}; exit $LASTEXITCODE"
 
-              # Wait for process to complete
-              status = wait_thr.value
+          env_hash = environment_to_h(env)
 
+          Timeout.timeout(timeout) do
+            execution = lambda do
+              stdout, stderr, status = Open3.capture3(env_hash, powershell_command, '-NoLogo', '-Command', ps_command)
               {
                 status: Ukiryu::Executor.extract_status(status),
-                stdout: out,
-                stderr: err
+                stdout: stdout,
+                stderr: stderr
               }
             end
-          end
 
-          if cwd
-            Dir.chdir(cwd) { execution.call }
-          else
-            execution.call
+            if cwd
+              Dir.chdir(cwd) { execution.call }
+            else
+              execution.call
+            end
           end
+        ensure
+          stdin_file.unlink
         end
       rescue Timeout::Error, Timeout::ExitException
-        # Re-raise with context
         raise Timeout::Error, "Command timed out after #{timeout}s: #{executable}"
       end
     end

data/lib/ukiryu/shell/sh.rb

@@ -20,7 +20,10 @@ module Ukiryu
         result = `type #{command_name} 2>/dev/null`
         return nil unless result
 
-        { definition: result.strip, target: ::Regexp.last_match(1) } if result =~ /^#{command_name} is aliased to `(.*)'`$/
+        if result =~ /^#{command_name} is aliased to `(.*)'`$/
+          { definition: result.strip,
+            target: ::Regexp.last_match(1) }
+        end
         nil
       end
 

data/lib/ukiryu/shell.rb

@@ -25,6 +25,7 @@ module Ukiryu
     autoload :Tcsh, 'ukiryu/shell/tcsh'
     autoload :PowerShell, 'ukiryu/shell/powershell'
     autoload :Cmd, 'ukiryu/shell/cmd'
+    autoload :InstanceCache, 'ukiryu/shell/instance_cache'
 
     # Platform-grouped shell types (new schema v1)
     PLATFORM_GROUPS = %i[unix windows powershell].freeze
@@ -56,6 +57,47 @@ module Ukiryu
       powershell: %i[powershell pwsh]
     }.freeze
 
+    # Shell registry for custom shells
+    # @api private
+    class Registry
+      class << self
+        def shells
+          @shells ||= {}
+        end
+
+        # Register a custom shell class
+        #
+        # @param name [Symbol] the shell name
+        # @param shell_class [Class] the shell class (must inherit from Shell::Base)
+        # @raise [ArgumentError] if shell_class is not a Shell::Base subclass
+        def register(name, shell_class)
+          raise ArgumentError, 'Shell class must inherit from Ukiryu::Shell::Base' unless shell_class.ancestors.include?(Base)
+
+          shells[name.to_sym] = shell_class
+        end
+
+        # Lookup a shell class by name
+        #
+        # @param name [Symbol] the shell name
+        # @return [Class, nil] the shell class or nil if not registered
+        def lookup(name)
+          shells[name.to_sym]
+        end
+
+        # Get all registered shell names
+        #
+        # @return [Array<Symbol>] list of registered shell names
+        def registered_shells
+          shells.keys
+        end
+
+        # Clear all registered shells (mainly for testing)
+        def clear
+          @shells = nil
+        end
+      end
+    end
+
     class << self
       # Get or set the current shell (for explicit configuration)
       attr_writer :current_shell
@@ -94,7 +136,10 @@ module Ukiryu
       def platform_group_for(shell_sym)
         return shell_sym if PLATFORM_GROUPS.include?(shell_sym)
 
-        raise ArgumentError, "Unknown shell: #{shell_sym}. Valid shells: #{VALID_SHELLS.join(', ')}" unless SHELL_TO_PLATFORM.key?(shell_sym)
+        unless SHELL_TO_PLATFORM.key?(shell_sym)
+          raise ArgumentError,
+                "Unknown shell: #{shell_sym}. Valid shells: #{VALID_SHELLS.join(', ')}"
+        end
 
         SHELL_TO_PLATFORM[shell_sym]
       end
@@ -231,7 +276,11 @@ module Ukiryu
       # @return [Class] the shell class
       # @raise [UnknownShellError] if shell class not found
       def class_for(name)
-        # Platform groups map to their representative shell classes
+        # Check registry first (for custom shells)
+        registered = Registry.lookup(name)
+        return registered if registered
+
+        # Built-in shells
         case name
         when :unix
           Bash # Most common Unix shell, all Unix shells share the same quoting rules
@@ -260,6 +309,15 @@ module Ukiryu
         end
       end
 
+      # Register a custom shell class
+      #
+      # @param name [Symbol] the shell name
+      # @param shell_class [Class] the shell class (must inherit from Shell::Base)
+      # @raise [ArgumentError] if shell_class is not a Shell::Base subclass
+      def register(name, shell_class)
+        Registry.register(name, shell_class)
+      end
+
       private
 
       # Detect shell on Windows

data/lib/ukiryu/tool/command_resolution.rb

@@ -92,7 +92,8 @@ module Ukiryu
         args = build_args(action, params)
 
         # Execute with the routed executable, passing tool_name and command_name for exit code lookups
-        execute_with_config(resolution[:executable], args, action, params, execution_timeout: execution_timeout, stdin: stdin)
+        execute_with_config(resolution[:executable], args, action, params, execution_timeout: execution_timeout,
+                                                                           stdin: stdin)
       end
 
       # Execute a command with root-path notation (for hierarchical tools)

data/lib/ukiryu/tool/executable_discovery.rb

@@ -22,16 +22,15 @@ module Ukiryu
         # Use executable_name from command profile, falling back to profile name
         executable_name = @command_profile.executable_name || @profile.name
 
-        # Debug logging for Windows CI
-        if ENV['UKIRYU_DEBUG_EXECUTABLE'] || (Platform.windows? && ENV['CI'])
-          warn "[UKIRYU DEBUG] Tool: #{@profile.name}"
-          warn "[UKIRYU DEBUG] Command profile executable_name: #{@command_profile.executable_name.inspect}"
-          warn "[UKIRYU DEBUG] Profile name: #{@profile.name.inspect}"
-          warn "[UKIRYU DEBUG] Resolved executable_name: #{executable_name.inspect}"
-          warn "[UKIRYU DEBUG] Profile aliases: #{@profile.aliases.inspect}"
-          warn "[UKIRYU DEBUG] Shell: #{@shell.inspect}"
-          warn "[UKIRYU DEBUG] Platform: #{@platform.inspect}"
-        end
+        # Debug logging for executable discovery
+        Logger.debug("Tool: #{@profile.name}", category: :executable)
+        Logger.debug("Command profile executable_name: #{@command_profile.executable_name.inspect}",
+                     category: :executable)
+        Logger.debug("Profile name: #{@profile.name.inspect}", category: :executable)
+        Logger.debug("Resolved executable_name: #{executable_name.inspect}", category: :executable)
+        Logger.debug("Profile aliases: #{@profile.aliases.inspect}", category: :executable)
+        Logger.debug("Shell: #{@shell.inspect}", category: :executable)
+        Logger.debug("Platform: #{@platform.inspect}", category: :executable)
 
         result = ::Ukiryu::ExecutableLocator.find_with_info(
           tool_name: executable_name,
@@ -39,11 +38,11 @@ module Ukiryu
           platform: @platform
         )
 
-        if result && (ENV['UKIRYU_DEBUG_EXECUTABLE'] || (Platform.windows? && ENV['CI']))
-          warn "[UKIRYU DEBUG] Found executable: #{result[:path]}"
-          warn "[UKIRYU DEBUG] Discovery source: #{result[:info].source.inspect}"
-        elsif !result && (ENV['UKIRYU_DEBUG_EXECUTABLE'] || (Platform.windows? && ENV['CI']))
-          warn '[UKIRYU DEBUG] EXECUTABLE NOT FOUND!'
+        if result
+          Logger.debug("Found executable: #{result[:path]}", category: :executable)
+          Logger.debug("Discovery source: #{result[:info].source.inspect}", category: :executable)
+        else
+          Logger.debug('EXECUTABLE NOT FOUND!', category: :executable)
         end
 
         return nil unless result